From 5bcc9a6e7d8baead144aeb3f90718458c6c8d05f Mon Sep 17 00:00:00 2001 From: RigelNana <809239189@qq.com> Date: Tue, 2 Dec 2025 01:24:32 +0800 Subject: [PATCH] feat: [chrono] add day/month/year/duration and some small funcs --- src/content/docs/cpp/library/chrono.mdx | 524 ++++++++++++++++++ src/content/docs/cpp/library/chrono/_meta.yml | 1 + .../library/chrono/ambiguous_local_time.mdx | 184 ++++++ .../docs/cpp/library/chrono/choose.mdx | 49 ++ .../docs/cpp/library/chrono/clock_cast.mdx | 63 +++ .../library/chrono/clock_time_conversion.mdx | 321 +++++++++++ .../docs/cpp/library/chrono/current_zone.mdx | 71 +++ src/content/docs/cpp/library/chrono/day.mdx | 124 +++++ .../docs/cpp/library/chrono/day/_meta.yml | 1 + .../docs/cpp/library/chrono/day/day.mdx | 35 ++ .../docs/cpp/library/chrono/day/formatter.mdx | 41 ++ .../cpp/library/chrono/day/from_stream.mdx | 43 ++ .../docs/cpp/library/chrono/day/hash.mdx | 30 + .../docs/cpp/library/chrono/day/ok.mdx | 60 ++ .../cpp/library/chrono/day/operator_arith.mdx | 78 +++ .../library/chrono/day/operator_arith_2.mdx | 102 ++++ .../cpp/library/chrono/day/operator_cmp.mdx | 77 +++ .../library/chrono/day/operator_inc_dec.mdx | 97 ++++ .../cpp/library/chrono/day/operator_ltlt.mdx | 85 +++ .../library/chrono/day/operator_unsigned.mdx | 49 ++ .../docs/cpp/library/chrono/duration.mdx | 331 +++++++++++ .../cpp/library/chrono/duration/_meta.yml | 1 + .../docs/cpp/library/chrono/duration/abs.mdx | 92 +++ .../docs/cpp/library/chrono/duration/ceil.mdx | 123 ++++ .../cpp/library/chrono/duration/count.mdx | 72 +++ .../cpp/library/chrono/duration/duration.mdx | 116 ++++ .../library/chrono/duration/duration_cast.mdx | 126 +++++ .../cpp/library/chrono/duration/floor.mdx | 96 ++++ .../docs/cpp/library/chrono/duration/max.mdx | 104 ++++ .../docs/cpp/library/chrono/duration/min.mdx | 57 ++ .../cpp/library/chrono/duration/round.mdx | 106 ++++ .../docs/cpp/library/chrono/duration/zero.mdx | 77 +++ .../docs/cpp/library/chrono/hour_fun.mdx | 143 +++++ .../docs/cpp/library/chrono/is_clock.mdx | 126 +++++ .../docs/cpp/library/chrono/last_spec.mdx | 55 ++ .../docs/cpp/library/chrono/locate_zone.mdx | 52 ++ src/content/docs/cpp/library/chrono/month.mdx | 128 +++++ .../docs/cpp/library/chrono/month/_meta.yml | 1 + .../cpp/library/chrono/month/formatter.mdx | 49 ++ .../cpp/library/chrono/month/from_stream.mdx | 43 ++ .../docs/cpp/library/chrono/month/hash.mdx | 30 + .../docs/cpp/library/chrono/month/month.mdx | 35 ++ .../docs/cpp/library/chrono/month/ok.mdx | 55 ++ .../library/chrono/month/operator_arith.mdx | 95 ++++ .../library/chrono/month/operator_arith_2.mdx | 103 ++++ .../cpp/library/chrono/month/operator_cmp.mdx | 61 ++ .../library/chrono/month/operator_inc_dec.mdx | 115 ++++ .../library/chrono/month/operator_ltlt.mdx | 72 +++ .../chrono/month/operator_unsigned.mdx | 52 ++ .../library/chrono/nonexistent_local_time.mdx | 186 +++++++ .../docs/cpp/library/chrono/operator_d.mdx | 99 ++++ .../docs/cpp/library/chrono/operator_h.mdx | 114 ++++ .../docs/cpp/library/chrono/operator_min.mdx | 115 ++++ .../docs/cpp/library/chrono/operator_ms.mdx | 112 ++++ .../docs/cpp/library/chrono/operator_ns.mdx | 112 ++++ .../docs/cpp/library/chrono/operator_s.mdx | 122 ++++ .../cpp/library/chrono/operator_slash.mdx | 215 +++++++ .../docs/cpp/library/chrono/operator_us.mdx | 112 ++++ .../docs/cpp/library/chrono/operator_y.mdx | 97 ++++ src/content/docs/cpp/library/chrono/parse.mdx | 199 +++++++ .../chrono/treat_as_floating_point.mdx | 101 ++++ .../cpp/library/chrono/tzdb_functions.mdx | 76 +++ src/content/docs/cpp/library/chrono/year.mdx | 148 +++++ .../docs/cpp/library/chrono/year/_meta.yml | 1 + .../cpp/library/chrono/year/formatter.mdx | 41 ++ .../cpp/library/chrono/year/from_stream.mdx | 43 ++ .../docs/cpp/library/chrono/year/hash.mdx | 30 + .../docs/cpp/library/chrono/year/is_leap.mdx | 62 +++ .../docs/cpp/library/chrono/year/max.mdx | 47 ++ .../docs/cpp/library/chrono/year/min.mdx | 47 ++ .../docs/cpp/library/chrono/year/ok.mdx | 76 +++ .../library/chrono/year/operator_arith.mdx | 87 +++ .../library/chrono/year/operator_arith_2.mdx | 105 ++++ .../cpp/library/chrono/year/operator_cmp.mdx | 69 +++ .../library/chrono/year/operator_inc_dec.mdx | 107 ++++ .../cpp/library/chrono/year/operator_int.mdx | 54 ++ .../cpp/library/chrono/year/operator_ltlt.mdx | 83 +++ .../cpp/library/chrono/year/operator_sign.mdx | 60 ++ .../docs/cpp/library/chrono/year/year.mdx | 67 +++ .../docs/cpp/library/chrono/zoned_traits.mdx | 81 +++ 80 files changed, 7419 insertions(+) create mode 100644 src/content/docs/cpp/library/chrono.mdx create mode 100644 src/content/docs/cpp/library/chrono/_meta.yml create mode 100644 src/content/docs/cpp/library/chrono/ambiguous_local_time.mdx create mode 100644 src/content/docs/cpp/library/chrono/choose.mdx create mode 100644 src/content/docs/cpp/library/chrono/clock_cast.mdx create mode 100644 src/content/docs/cpp/library/chrono/clock_time_conversion.mdx create mode 100644 src/content/docs/cpp/library/chrono/current_zone.mdx create mode 100644 src/content/docs/cpp/library/chrono/day.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/_meta.yml create mode 100644 src/content/docs/cpp/library/chrono/day/day.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/formatter.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/from_stream.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/hash.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/ok.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/operator_arith.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/operator_arith_2.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/operator_cmp.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/operator_inc_dec.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/operator_ltlt.mdx create mode 100644 src/content/docs/cpp/library/chrono/day/operator_unsigned.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/_meta.yml create mode 100644 src/content/docs/cpp/library/chrono/duration/abs.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/ceil.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/count.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/duration.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/duration_cast.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/floor.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/max.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/min.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/round.mdx create mode 100644 src/content/docs/cpp/library/chrono/duration/zero.mdx create mode 100644 src/content/docs/cpp/library/chrono/hour_fun.mdx create mode 100644 src/content/docs/cpp/library/chrono/is_clock.mdx create mode 100644 src/content/docs/cpp/library/chrono/last_spec.mdx create mode 100644 src/content/docs/cpp/library/chrono/locate_zone.mdx create mode 100644 src/content/docs/cpp/library/chrono/month.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/_meta.yml create mode 100644 src/content/docs/cpp/library/chrono/month/formatter.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/from_stream.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/hash.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/month.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/ok.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/operator_arith.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/operator_arith_2.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/operator_cmp.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/operator_inc_dec.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/operator_ltlt.mdx create mode 100644 src/content/docs/cpp/library/chrono/month/operator_unsigned.mdx create mode 100644 src/content/docs/cpp/library/chrono/nonexistent_local_time.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_d.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_h.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_min.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_ms.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_ns.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_s.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_slash.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_us.mdx create mode 100644 src/content/docs/cpp/library/chrono/operator_y.mdx create mode 100644 src/content/docs/cpp/library/chrono/parse.mdx create mode 100644 src/content/docs/cpp/library/chrono/treat_as_floating_point.mdx create mode 100644 src/content/docs/cpp/library/chrono/tzdb_functions.mdx create mode 100644 src/content/docs/cpp/library/chrono/year.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/_meta.yml create mode 100644 src/content/docs/cpp/library/chrono/year/formatter.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/from_stream.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/hash.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/is_leap.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/max.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/min.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/ok.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/operator_arith.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/operator_arith_2.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/operator_cmp.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/operator_inc_dec.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/operator_int.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/operator_ltlt.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/operator_sign.mdx create mode 100644 src/content/docs/cpp/library/chrono/year/year.mdx create mode 100644 src/content/docs/cpp/library/chrono/zoned_traits.mdx diff --git a/src/content/docs/cpp/library/chrono.mdx b/src/content/docs/cpp/library/chrono.mdx new file mode 100644 index 00000000..01cc4562 --- /dev/null +++ b/src/content/docs/cpp/library/chrono.mdx @@ -0,0 +1,524 @@ +--- +title: Date and time utilities +--- + +import { CppHeader } from "@components/header"; +import { Desc, DescItem, DescList } from "@components/desc-list"; +import { FeatureTestMacro, FeatureTestMacroValue } from "@components/feature-test-macro"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; +import DocLink from "@components/DocLink.astro"; + +C++ includes support for two types of time manipulation: + +- The `chrono` library, a flexible collection of types that track time with varying degrees of precision (e.g. `std::chrono::time_point`). +- C-style date and time library (e.g. `std::time`). + +## Chrono library + +The `chrono` library defines threefive main types as well as utility functions and common typedefs: +- clocks +- time points +- durations + +- calendar dates +- time zone information + + +### Clocks + +A clock consists of a starting point (or epoch) and a tick rate. For example, a clock may have an epoch of January 1, 1970 and tick every second. C++ defines several clock types: + + + + Defined in header + + + Defined in namespace `std::chrono` + + + + `system_clock` + + wall clock time from the system-wide realtime clock + + + + `steady_clock` + + monotonic clock that will never be adjusted + + + + `high_resolution_clock` + + the clock with the shortest tick period available + + + + `is_clock` + + determines if a type is a Clock + + + + `utc_clock` + + Clock for Coordinated Universal Time (UTC) + + + + `tai_clock` + + Clock for International Atomic Time (TAI) + + + + `gps_clock` + + Clock for GPS time + + + + `file_clock` + + Clock used for file time + + + + `local_t` + + pseudo-clock representing local time + + + +### Time point + +A time point is a duration of time that has passed since the epoch of a specific clock. + + + + Defined in header + + + Defined in namespace `std::chrono` + + + + `time_point` + + a point in time + + + + `clock_time_conversion` + + traits class defining how to convert time points of one clock to another + + + + `clock_cast` + + convert time points of one clock to another + + + +### Duration + +A duration consists of a span of time, defined as some number of ticks of some time unit. For example, "42 seconds" could be represented by a duration consisting of 42 ticks of a 1-second time unit. + + + + Defined in header + + + Defined in namespace `std::chrono` + + + + `duration` + + a time interval + + + +### Time of day + +`hh_mm_ss` splits a duration representing time elapsed since midnight into hours, minutes, seconds, and fractional seconds, as applicable. It is primarily a formatting tool. + + + + Defined in header + + + Defined in namespace `std::chrono` + + + + `hh_mm_ss` + + represents a time of day + + + + `is_am` / `is_pm` / `make12` / `make24` + + translates a 12h/24h format time of day + + + +### Calendar + + + + Defined in header + + + Defined in namespace `std::chrono` + + + + `last_spec` + + tag class indicating the last day or weekday in a month + + + + `day` + + represents a day of a month + + + + `month` + + represents a month of a year + + + + `year` + + represents a year in the Gregorian calendar + + + + `weekday` + + represents a day of the week in the Gregorian calendar + + + + `weekday_indexed` + + represents the n-th weekday of a month + + + + `weekday_last` + + represents the last weekday of a month + + + + `month_day` + + represents a specific day of a specific month + + + + `month_day_last` + + represents the last day of a specific month + + + + `month_weekday` + + represents the n-th weekday of a specific month + + + + `month_weekday_last` + + represents the last weekday of a specific month + + + + `year_month` + + represents a specific year and month + + + + `year_month_day` + + represents a specific year, month, and day + + + + `year_month_day_last` + + represents the last day of a specific year and month + + + + `year_month_weekday` + + represents the n-th weekday of a specific year and month + + + + `year_month_weekday_last` + + represents the last weekday of a specific year and month + + + + `operator/` + + conventional syntax for Gregorian calendar date creation + + + +### Time zone + + + + Defined in header + + + Defined in namespace `std::chrono` + + + + `tzdb` + + describes a copy of the IANA time zone database + + + + `tzdb_list` + + represents a linked list of tzdb + + + + `get_tzdb` / `get_tzdb_list` / `reload_tzdb` / `remote_version` + + accesses and controls the global time zone database information + + + + `locate_zone` + + locates a time_zone based on its name + + + + `current_zone` + + returns the current time_zone + + + + `time_zone` + + represents a time zone + + + + `sys_info` + + represents information about a time zone at a particular time point + + + + `local_info` + + represents information about a local time to UNIX time conversion + + + + `choose` + + selects how an ambiguous local time should be resolved + + + + `zoned_traits` + + traits class for time zone pointers used by zoned_time + + + + `zoned_time` + + represents a time zone and a time point + + + + `leap_second` + + contains information about a leap second insertion + + + + `leap_second_info` + + leap second insertion information + + + + `get_leap_second_info` + + obtains leap second insertion information from a utc_time object + + + + `time_zone_link` + + represents an alternative name for a time zone + + + + `nonexistent_local_time` + + exception thrown to report that a local time is nonexistent + + + + `ambiguous_local_time` + + exception thrown to report that a local time is ambiguous + + + +### Literals + + + + Defined in header + + + Defined in inline namespace `std::literals::chrono_literals` + + + + `operator""y` + + a `std::chrono::year` literal representing a particular year + + + + `operator""d` + + a `std::chrono::day` literal representing a day of a month + + + + `operator""h` + + a `std::chrono::duration` literal representing hours + + + + `operator""min` + + a `std::chrono::duration` literal representing minutes + + + + `operator""s` + + a `std::chrono::duration` literal representing seconds + + + + `operator""ms` + + a `std::chrono::duration` literal representing milliseconds + + + + `operator""us` + + a `std::chrono::duration` literal representing microseconds + + + + `operator""ns` + + a `std::chrono::duration` literal representing nanoseconds + + + +### Chrono I/O + + + + Defined in header + + + Defined in namespace `std::chrono` + + + + `parse` + + parses a chrono object from a stream + + + +## Notes + + + + Rounding functions for `std::chrono::duration` and `std::chrono::time_point` + + + `constexpr` for all the member functions of `std::chrono::duration` and `std::chrono::time_point` + + + [Calendars](#calendar) and [Time zones](#time-zone) + + + Hashing support for `std::chrono` value classes + + + +## C-style date and time library + +Also provided are the C-style date and time functions, such as `std::time_t`, `std::difftime`, and `CLOCKS_PER_SEC`. + +## Example + +Measures and displays an execution time of a function call. + +```cpp +#include +#include + +long Fibonacci(unsigned n) +{ + return n < 2 ? n : Fibonacci(n - 1) + Fibonacci(n - 2); +} + +int main() +{ + const auto start{std::chrono::steady_clock::now()}; + const auto fb{Fibonacci(42)}; + const auto end{std::chrono::steady_clock::now()}; + const std::chrono::duration elapsed_seconds{end - start}; + + std::cout << "Fibonacci(42): " << fb << "\nElapsed time: "; +// std::cout << elapsed_seconds.count() << "s\n"; // Before C++20 + std::cout << elapsed_seconds << '\n'; // C++20's chrono::duration operator<< +} +``` + +Possible output: + +``` +Fibonacci(42): 267914296 +Elapsed time: 0.791429s +``` diff --git a/src/content/docs/cpp/library/chrono/_meta.yml b/src/content/docs/cpp/library/chrono/_meta.yml new file mode 100644 index 00000000..75b32826 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/_meta.yml @@ -0,0 +1 @@ +label: Date and time library \ No newline at end of file diff --git a/src/content/docs/cpp/library/chrono/ambiguous_local_time.mdx b/src/content/docs/cpp/library/chrono/ambiguous_local_time.mdx new file mode 100644 index 00000000..a85f816a --- /dev/null +++ b/src/content/docs/cpp/library/chrono/ambiguous_local_time.mdx @@ -0,0 +1,184 @@ +--- +title: std::chrono::ambiguous_local_time +cppdoc: + keys: ["cpp.chrono.ambiguous_local_time"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + class ambiguous_local_time; + ``` + + + + 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`). + + +## Member functions + + + + `(constructor)` + constructs the exception object + + + `operator=` + replaces the exception object + + + `what` + returns the explanatory string + + + +## std::chrono::ambiguous_local_time::ambiguous_local_time + + + + + ```cpp + template< class Duration > + ambiguous_local_time( const std::chrono::local_time& tp, + const std::chrono::local_info& i ); + ``` + + + + The explanatory string returned by `what()` is equivalent to that produced by `os.str()` after the following code: + + ```cpp + 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`. + + + + + + ```cpp + ambiguous_local_time( const ambiguous_local_time& other ) noexcept; + ``` + + + + Copy constructor. If `*this` and `other` both have dynamic type `std::chrono::ambiguous_local_time` then `std::strcmp(what(), other.what()) == 0`. + + +### Parameters + + + + the time point for which conversion was attempted + + + a `std::chrono::local_info` describing the result of the conversion attempt + + + another `ambiguous_local_time` to copy + + + +### Exceptions + +May throw `std::bad_alloc`. + +### 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_local_time::operator= + + + + + ```cpp + ambiguous_local_time& operator=( const ambiguous_local_time& other ) noexcept; + ``` + + + + Assigns the contents with those of `other`. If `*this` and `other` both have dynamic type `std::chrono::ambiguous_local_time` then `std::strcmp(what(), other.what()) == 0` after assignment. + + +### Parameters + + + + another exception object to assign with + + + +### Return value + +`*this` + +## std::chrono::ambiguous_local_time::what + + + + + ```cpp + virtual const char* what() const noexcept; + ``` + + + + Returns the explanatory string. + + +### Parameters + +(none) + +### 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. + +### Notes + +Implementations are allowed but not required to override `what()`. + +## Inherited from std::runtime_error + +Inherited from `std::exception`. + +### Member functions + + + + `what` + returns an explanatory string + + + +## See also + + + + + `nonexistent_local_time` + + exception thrown to report that a local time is nonexistent + + diff --git a/src/content/docs/cpp/library/chrono/choose.mdx b/src/content/docs/cpp/library/chrono/choose.mdx new file mode 100644 index 00000000..9514222b --- /dev/null +++ b/src/content/docs/cpp/library/chrono/choose.mdx @@ -0,0 +1,49 @@ +--- +title: std::chrono::choose +cppdoc: + keys: ["cpp.chrono.choose"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + enum class choose { + earliest, + 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. + + +## See also + + + + + `zoned_time::zoned_time` + + constructs a `zoned_time` + + + + `time_zone::to_sys` + + converts a `local_time` in this time zone to a `sys_time` + + diff --git a/src/content/docs/cpp/library/chrono/clock_cast.mdx b/src/content/docs/cpp/library/chrono/clock_cast.mdx new file mode 100644 index 00000000..7c4273a5 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/clock_cast.mdx @@ -0,0 +1,63 @@ +--- +title: std::chrono::clock_cast +cppdoc: + keys: ["cpp.chrono.clock_cast"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class Dest, class Source, class Duration > + auto clock_cast( const std::chrono::time_point& t ); + ``` + + + + 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. + + +## Return value + +The result of the conversion, determined as described above. + +## Example + +```cpp +// Example code here +``` + +## See also + + + + + `clock_time_conversion` + + traits class defining how to convert time points of one clock to another + + diff --git a/src/content/docs/cpp/library/chrono/clock_time_conversion.mdx b/src/content/docs/cpp/library/chrono/clock_time_conversion.mdx new file mode 100644 index 00000000..7c1e1c55 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/clock_time_conversion.mdx @@ -0,0 +1,321 @@ +--- +title: std::chrono::clock_time_conversion +cppdoc: + keys: ["cpp.chrono.clock_time_conversion"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class Dest, class Source > + 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: + + + + + + ```cpp + template< class Clock > + struct clock_time_conversion; + ``` + + + + Identity conversion: `operator()` returns a copy of the argument. + + + + + + ```cpp + template<> + struct clock_time_conversion; + ``` + + + + Identity conversion: `operator()` returns a copy of the argument. + + + + + + ```cpp + template<> + struct clock_time_conversion; + ``` + + + + Identity conversion: `operator()` returns a copy of the argument. + + + + + + ```cpp + template<> + struct clock_time_conversion; + ``` + + + + Conversions between `std::chrono::sys_time` and `std::chrono::utc_time`: `operator()` calls `std::chrono::utc_clock::to_sys`. + + + + + + ```cpp + template<> + struct clock_time_conversion; + ``` + + + + Conversions between `std::chrono::sys_time` and `std::chrono::utc_time`: `operator()` calls `std::chrono::utc_clock::from_sys`. + + + + + + ```cpp + template< class Clock > + struct clock_time_conversion; + ``` + + + + Conversions to and from `std::chrono::sys_time` when `Clock` supports `from_sys` and `to_sys`: `operator()` calls `Clock::from_sys`. + + + + + + ```cpp + template< class Clock > + struct clock_time_conversion; + ``` + + + + Conversions to and from `std::chrono::sys_time` when `Clock` supports `from_sys` and `to_sys`: `operator()` calls `Clock::to_sys`. + + + + + + ```cpp + template< class Clock > + struct clock_time_conversion; + ``` + + + + Conversions to and from `std::chrono::utc_time` when `Clock` supports `from_utc` and `to_utc`: `operator()` calls `Clock::from_utc`. + + + + + + ```cpp + template< class Clock > + struct clock_time_conversion; + ``` + + + + Conversions to and from `std::chrono::utc_time` when `Clock` supports `from_utc` and `to_utc`: `operator()` calls `Clock::to_utc`. + + +## 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() + + + + + ```cpp + // member of specialization (1) + template< class Duration > + std::chrono::time_point + operator()( const std::chrono::time_point& t ) const; + ``` + + + + Identity conversion. Returns `t` unchanged. + + + + + + ```cpp + // member of specialization (2) + template< class Duration > + std::chrono::sys_time + operator()( const std::chrono::sys_time& t ) const; + ``` + + + + Identity conversion. Returns `t` unchanged. + + + + + + ```cpp + // member of specialization (3) + template< class Duration > + std::chrono::utc_time + operator()( const std::chrono::utc_time& t ) const; + ``` + + + + Identity conversion. Returns `t` unchanged. + + + + + + ```cpp + // member of specialization (4) + template< class Duration > + std::chrono::sys_time + operator()( const std::chrono::utc_time& t ) const; + ``` + + + + Returns `std::chrono::utc_clock::to_sys(t)`. + + + + + + ```cpp + // member of specialization (5) + template< class Duration > + std::chrono::utc_time + operator()( const std::chrono::sys_time& t ) const; + ``` + + + + Returns `std::chrono::utc_clock::from_sys(t)`. + + + + + + ```cpp + // member of specialization (6) + template< class Duration > + auto operator()( const std::chrono::sys_time& t ) const + -> decltype(Clock::from_sys(t)); + ``` + + + + 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`. + + + + + + ```cpp + // member of specialization (7) + template< class Duration > + auto operator()( const std::chrono::time_point& t ) const + -> decltype(Clock::to_sys(t)); + ``` + + + + 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`. + + + + + + ```cpp + // member of specialization (8) + template< class Duration > + auto operator()( const std::chrono::utc_time& t ) const + -> decltype(Clock::from_utc(t)); + ``` + + + + 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`. + + + + + + ```cpp + // member of specialization (9) + template< class Duration > + auto operator()( const std::chrono::time_point& t ) const + -> decltype(Clock::to_utc(t)); + ``` + + + + 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`. + + +### Parameters + + + + time point to convert + + + +### 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)`. + +## See also + + + + + `clock_cast` + + convert time points of one clock to another + + diff --git a/src/content/docs/cpp/library/chrono/current_zone.mdx b/src/content/docs/cpp/library/chrono/current_zone.mdx new file mode 100644 index 00000000..a937c951 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/current_zone.mdx @@ -0,0 +1,71 @@ +--- +title: std::chrono::current_zone +cppdoc: + keys: ["cpp.chrono.current_zone"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + const std::chrono::time_zone* current_zone(); + ``` + + + + Convenience function for obtaining local time zone from the time zone database. Equivalent to `std::chrono::get_tzdb().current_zone()`. + + +## Exceptions + +`std::runtime_error` if this is the first reference to the time zone database and the time zone database cannot be initialized. + +## Notes + +A call to this function that is the first reference to the time zone database will cause it to be initialized. + +## Example + +```cpp +#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'; +} +``` + +Possible output: + +``` +2021-09-13 19:46:42.249182012 MAGT +``` + +## See also + + + + + `tzdb::current_zone` + + locates the current time zone + + + + `get_tzdb` / `get_tzdb_list` / `reload_tzdb` / `remote_version` + + accesses and controls the global time zone database information + + diff --git a/src/content/docs/cpp/library/chrono/day.mdx b/src/content/docs/cpp/library/chrono/day.mdx new file mode 100644 index 00000000..1b8826ba --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day.mdx @@ -0,0 +1,124 @@ +--- +title: std::chrono::day +cppdoc: + keys: ["cpp.chrono.day"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + class day; + ``` + + + + 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*. + + +## Member functions + + + + + `(constructor)` + + constructs a `day` + + + + `operator++` / `operator--` + + increments or decrements the day + + + + `operator+=` / `operator-=` + + adds or subtracts a number of days + + + + `operator unsigned` + + retrieves the stored day value + + + + `ok` + + checks if the stored day value is in the normal range + + + +## Non-member functions + + + + + `operator==` / `operator<=>` + + compares two `day` values + + + + `operator+` / `operator-` + + performs arithmetic on `day`s + + + + `operator<<` + + outputs a `day` into a stream + + + + `from_stream` + + parses a `day` from a stream according to the provided format + + + +## Helper classes + + + + + `std::formatter` + + formatting support for `day` + + + + `std::hash` + + hash support for `std::chrono::day` + + + +## Literals + + + + Defined in inline namespace `std::literals::chrono_literals` + + + + `operator""d` + + a `std::chrono::day` literal representing a day of a month + + diff --git a/src/content/docs/cpp/library/chrono/day/_meta.yml b/src/content/docs/cpp/library/chrono/day/_meta.yml new file mode 100644 index 00000000..817cb70d --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/_meta.yml @@ -0,0 +1 @@ +label: std::chrono::day \ No newline at end of file diff --git a/src/content/docs/cpp/library/chrono/day/day.mdx b/src/content/docs/cpp/library/chrono/day/day.mdx new file mode 100644 index 00000000..4241b43d --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/day.mdx @@ -0,0 +1,35 @@ +--- +title: std::chrono::day::day +cppdoc: + keys: ["cpp.chrono.day.day"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + day() = default; + ``` + + + + + ```cpp + constexpr explicit day( unsigned d ) noexcept; + ``` + + + + 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/src/content/docs/cpp/library/chrono/day/formatter.mdx b/src/content/docs/cpp/library/chrono/day/formatter.mdx new file mode 100644 index 00000000..7d65c381 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/formatter.mdx @@ -0,0 +1,41 @@ +--- +title: std::formatter +cppdoc: + keys: ["cpp.chrono.day.formatter"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT > + struct formatter; + ``` + + + + Specialization of `std::formatter` that defines formatting rules for a `std::chrono::day`. + + The `std::formatter` specialization is usually not directly accessed, but is used through formatting functions. + + +## See also + + + + + `std::format` + + stores formatted representation of the arguments in a new string + + diff --git a/src/content/docs/cpp/library/chrono/day/from_stream.mdx b/src/content/docs/cpp/library/chrono/day/from_stream.mdx new file mode 100644 index 00000000..e9426af6 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/from_stream.mdx @@ -0,0 +1,43 @@ +--- +title: std::chrono::from_stream (std::chrono::day) +cppdoc: + keys: ["cpp.chrono.day.from_stream"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT, class Traits, class Alloc = std::allocator > + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* fmt, + std::chrono::day& d, + std::basic_string* abbrev = nullptr, + std::chrono::minutes* offset = nullptr ); + ``` + + + + Parses a `day` from the stream `is` according to the format string `fmt`. + + +## See also + + + + + `std::chrono::parse` + + parses a `chrono` object from a stream + + diff --git a/src/content/docs/cpp/library/chrono/day/hash.mdx b/src/content/docs/cpp/library/chrono/day/hash.mdx new file mode 100644 index 00000000..698ca4df --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/hash.mdx @@ -0,0 +1,30 @@ +--- +title: std::hash +cppdoc: + keys: ["cpp.chrono.day.hash"] + revision: + since: C++26 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template<> + struct std::hash; + ``` + + + + The template specialization of `std::hash` for `std::chrono::day` allows users to obtain hashes of objects of type `std::chrono::day`. + + The specialization is enabled, and `operator()` of this specialization is `noexcept`. + diff --git a/src/content/docs/cpp/library/chrono/day/ok.mdx b/src/content/docs/cpp/library/chrono/day/ok.mdx new file mode 100644 index 00000000..820bf6d6 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/ok.mdx @@ -0,0 +1,60 @@ +--- +title: std::chrono::day::ok +cppdoc: + keys: ["cpp.chrono.day.ok"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr bool ok() const noexcept; + ``` + + + + Checks if the day value stored in `*this` is in the valid range, i.e., \[1, 31\]. + + +## Return value + +`true` if the day value stored in `*this` is in the range \[1, 31\]. Otherwise `false`. + +## Example + +```cpp +#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() {} +``` + +## See also + + + + + `operator unsigned` + + retrieves the stored day value + + diff --git a/src/content/docs/cpp/library/chrono/day/operator_arith.mdx b/src/content/docs/cpp/library/chrono/day/operator_arith.mdx new file mode 100644 index 00000000..0de9f31c --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/operator_arith.mdx @@ -0,0 +1,78 @@ +--- +title: std::chrono::day::operator+=, operator-= +cppdoc: + keys: ["cpp.chrono.day.operator_arith"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::day& operator+=( const std::chrono::days& d ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::day& operator-=( const std::chrono::days& d ) noexcept; + ``` + + + + Adds or subtracts `d.count()` days from the day value. + + 1. Equivalent to `*this = *this + d;`. + 2. Equivalent to `*this = *this - d;`. + + +## Return value + +A reference to this `day` after modification. + +## Notes + +If the result would be outside the range \[0, 255\], the actual stored value is unspecified. + +## Example + +```cpp +#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)); +} +``` + +## See also + + + + + `operator++` / `operator--` + + increments or decrements the day + + + + `operator+` / `operator-` + + performs arithmetic on `day`s + + diff --git a/src/content/docs/cpp/library/chrono/day/operator_arith_2.mdx b/src/content/docs/cpp/library/chrono/day/operator_arith_2.mdx new file mode 100644 index 00000000..6ded6a21 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/operator_arith_2.mdx @@ -0,0 +1,102 @@ +--- +title: operator+, operator- (std::chrono::day) +cppdoc: + keys: ["cpp.chrono.day.operator_arith_2"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::day operator+( const std::chrono::day& d, + const std::chrono::days& ds ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::day operator+( const std::chrono::days& ds, + const std::chrono::day& d ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::day operator-( const std::chrono::day& d, + const std::chrono::days& ds ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::days operator-( const std::chrono::day& x, + const std::chrono::day& y ) 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`. + + +## 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)))` + +## Notes + +1-3) If the result would be outside the range \[0, 255\], the actual stored value is unspecified. + +## Example + +```cpp +#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)); +} +``` + +## See also + + + + + `operator++` / `operator--` + + increments or decrements the day + + + + `operator+=` / `operator-=` + + adds or subtracts a number of days + + diff --git a/src/content/docs/cpp/library/chrono/day/operator_cmp.mdx b/src/content/docs/cpp/library/chrono/day/operator_cmp.mdx new file mode 100644 index 00000000..191642b4 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/operator_cmp.mdx @@ -0,0 +1,77 @@ +--- +title: operator==, <=> (std::chrono::day) +cppdoc: + keys: ["cpp.chrono.day.operator_cmp"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr bool operator==( const std::chrono::day& x, + const std::chrono::day& y ) noexcept; + ``` + + + + + ```cpp + constexpr std::strong_ordering operator<=>( const std::chrono::day& x, + 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. + + +## Return value + +1) `unsigned(x) == unsigned(y)` +2) `unsigned(x) <=> unsigned(y)` + +## Example + +```cpp +#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) + ); +} +``` + +**Possible output:** + +``` +x is less than y +``` diff --git a/src/content/docs/cpp/library/chrono/day/operator_inc_dec.mdx b/src/content/docs/cpp/library/chrono/day/operator_inc_dec.mdx new file mode 100644 index 00000000..bc8532f9 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/operator_inc_dec.mdx @@ -0,0 +1,97 @@ +--- +title: std::chrono::day::operator++, operator-- +cppdoc: + keys: ["cpp.chrono.day.operator_inc_dec"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::day& operator++() noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::day operator++( int ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::day& operator--() noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::day operator--( int ) noexcept; + ``` + + + + Adds or subtracts 1 from the day value. + + 1,2) Performs `*this += std::chrono::days{1};`. + 3,4) Performs `*this -= std::chrono::days{1};`. + + +## Parameters + +(none) + +## Return value + +1,3) A reference to this `day` after modification. +2,4) A copy of the `day` made before modification. + +## Notes + +If the result would be outside the range \[0, 255\], the actual stored value is unspecified. + +## Example + +```cpp +#include +#include + +int main() +{ + std::chrono::day d{15}; + + ++d; + assert(d == std::chrono::day(16)); + + --d; + assert(d == std::chrono::day(15)); +} +``` + +## See also + + + + + `operator+=` / `operator-=` + + adds or subtracts a number of days + + + + `operator+` / `operator-` + + performs arithmetic on `day`s + + diff --git a/src/content/docs/cpp/library/chrono/day/operator_ltlt.mdx b/src/content/docs/cpp/library/chrono/day/operator_ltlt.mdx new file mode 100644 index 00000000..f62ae481 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/operator_ltlt.mdx @@ -0,0 +1,85 @@ +--- +title: operator<< (std::chrono::day) +cppdoc: + keys: ["cpp.chrono.day.operator_ltlt"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT, class Traits > + std::basic_ostream& + 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 + + ```cpp + 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`. + + +## Return value + +`os` + +## Example + +```cpp +#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'; +} +``` + +**Possible output:** + +``` +31 +07 +42 is not a valid day +00 is not a valid day +``` + +## See also + + + + + `std::format` + + stores formatted representation of the arguments in a new string + + + + `std::formatter` + + formatting support for `day` + + diff --git a/src/content/docs/cpp/library/chrono/day/operator_unsigned.mdx b/src/content/docs/cpp/library/chrono/day/operator_unsigned.mdx new file mode 100644 index 00000000..45e8c7fd --- /dev/null +++ b/src/content/docs/cpp/library/chrono/day/operator_unsigned.mdx @@ -0,0 +1,49 @@ +--- +title: std::chrono::day::operator unsigned +cppdoc: + keys: ["cpp.chrono.day.operator_unsigned"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr explicit operator unsigned() const noexcept; + ``` + + + + Returns the day value stored in `*this`. + + +## Return value + +The day value stored in `*this`. + +## Example + +```cpp +#include +#include + +int main() +{ + constexpr std::chrono::day d{15}; + constexpr unsigned day = static_cast(d); + std::cout << "The day is: " << day << '\n'; +} +``` + +**Output:** + +``` +The day is: 15 +``` diff --git a/src/content/docs/cpp/library/chrono/duration.mdx b/src/content/docs/cpp/library/chrono/duration.mdx new file mode 100644 index 00000000..bce71ebb --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration.mdx @@ -0,0 +1,331 @@ +--- +title: std::chrono::duration +cppdoc: + keys: ["cpp.chrono.duration"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList, DescItem } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; +import { FeatureTestMacro, FeatureTestMacroValue } from "@components/feature-test-macro"; + +Defined in header . + + + + + ```cpp + template< + class Rep, + class Period = std::ratio<1> + > class duration; + ``` + + + + 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 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 point, then the `duration` can represent fractions of ticks. `Period` is included as part of the duration's type, and is only used when converting between different durations. + + +## Member types + +| Member type | Definition | +|---|---| +| `rep` | `Rep`, an arithmetic type, or a class emulating an arithmetic type, representing the number of ticks | +| `period` | `Period``typename Period::type`, a `std::ratio` representing the tick period (i.e. the number of second's fractions per tick) | + +## Member functions + + + + + `(constructor)` + + constructs new duration + + + + `operator=` + + assigns the contents + + + + `count` + + returns the count of ticks + + + + `zero` + + returns the special duration value zero + + + + `min` + + returns the special duration value min + + + + `max` + + returns the special duration value max + + + + `operator+` / `operator-` + + implements unary + and unary - + + + + `operator++` / `operator--` + + increments or decrements the tick count + + + + `operator+=` / `operator-=` / `operator*=` / `operator/=` / `operator%=` + + implements compound assignment between two durations + + + +## Non-member functions + + + + + `operator+` / `operator-` / `operator*` / `operator/` / `operator%` + + implements arithmetic operations with durations as arguments + + + + `operator==` / `operator!=` / `operator<` / `operator<=` / `operator>` / `operator>=` / `operator<=>` + + compares two durations + + + + `duration_cast` + + converts a duration to another, with a different tick interval + + + + `floor` + + converts a duration to another, rounding down + + + + `ceil` + + converts a duration to another, rounding up + + + + `round` + + converts a duration to another, rounding to nearest, ties to even + + + + `abs` + + obtains the absolute value of the duration + + + + `operator<<` + + performs stream output on a duration + + + + `from_stream` + + parses a duration from a stream according to the provided format + + + +## Helper types + +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`** | `std::chrono::duration>` | +| **`std::chrono::weeks`** | `std::chrono::duration>` | +| **`std::chrono::months`** | `std::chrono::duration>` | +| **`std::chrono::years`** | `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 `days` (the average length of a Gregorian year). `months` is equal to 30.436875 `days` (exactly 1/12 of `years`). + + +## Helper classes + + + + + `std::common_type` + + specializes the `std::common_type` trait + + + + `std::chrono::treat_as_floating_point` + + indicates that a duration is convertible to duration with different tick period + + + + `std::chrono::duration_values` + + constructs zero, min, and max values of a tick count type + + + + `std::formatter` + + formatting support for `duration` + + + + `std::hash` + + hash support for `std::chrono::duration` + + + +## Literals + + + + Defined in inline namespace `std::literals::chrono_literals` + + + + `operator""h` + + a `std::chrono::duration` literal representing hours + + + + `operator""min` + + a `std::chrono::duration` literal representing minutes + + + + `operator""s` + + a `std::chrono::duration` literal representing seconds + + + + `operator""ms` + + a `std::chrono::duration` literal representing milliseconds + + + + `operator""us` + + a `std::chrono::duration` literal representing microseconds + + + + `operator""ns` + + a `std::chrono::duration` literal representing nanoseconds + + + + +Note: the literal suffixes `d` and `y` do not refer to `days` and `years` but to `std::chrono::day` and `std::chrono::year`, respectively. + + +## 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. + + + + User-defined literals for time types + + + +## Example + +This example shows how to define several custom duration types and convert between types: + +```cpp +#include +#include + +using namespace std::chrono_literals; + +template +using mul = std::ratio_multiply; + +int main() +{ + 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"; + + // 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"; + // alternative to duration_cast: + std::cout << 1s / 1min << " 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"; +} +``` + +**Output:** + +``` +1 second is: +1000 milliseconds +1000000 microseconds +1000000000 nanoseconds +0 minutes +0 minutes +0.82672 microfortnights +0.316887 nanocenturies +24 frames at 24fps +``` diff --git a/src/content/docs/cpp/library/chrono/duration/_meta.yml b/src/content/docs/cpp/library/chrono/duration/_meta.yml new file mode 100644 index 00000000..7654e8b2 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/_meta.yml @@ -0,0 +1 @@ +label: std::chrono::duration \ No newline at end of file diff --git a/src/content/docs/cpp/library/chrono/duration/abs.mdx b/src/content/docs/cpp/library/chrono/duration/abs.mdx new file mode 100644 index 00000000..154dd0bd --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/abs.mdx @@ -0,0 +1,92 @@ +--- +title: std::chrono::abs (std::chrono::duration) +cppdoc: + keys: ["cpp.chrono.duration.abs"] + revision: + since: C++17 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class Rep, class Period > + constexpr std::chrono::duration abs( 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`. + + +## Parameters + +| Parameter | Description | +|---|---| +| `d` | duration | + +## Return value + +Absolute value of `d`. + +## Possible implementation + +```cpp +template::is_signed>> +constexpr std::chrono::duration abs(std::chrono::duration d) +{ + return d >= d.zero() ? +d : -d; +} +``` + +## Example + +```cpp +#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'; +} +``` + +**Output:** + +``` +abs(+3min) = 3 +abs(-3min) = 3 +``` + +## See also + + + + + `operator+` / `operator-` + + implements unary + and unary - + + + + `std::abs` / `std::labs` / `std::llabs` + + computes absolute value of an integral value + + diff --git a/src/content/docs/cpp/library/chrono/duration/ceil.mdx b/src/content/docs/cpp/library/chrono/duration/ceil.mdx new file mode 100644 index 00000000..902b8c72 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/ceil.mdx @@ -0,0 +1,123 @@ +--- +title: std::chrono::ceil (std::chrono::duration) +cppdoc: + keys: ["cpp.chrono.duration.ceil"] + revision: + since: C++17 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class ToDuration, class Rep, class Period > + constexpr ToDuration ceil( const std::chrono::duration& 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`. + + +## Parameters + +| Parameter | Description | +|---|---| +| `d` | duration to convert | + +## Return value + +`d` rounded up to a duration of type `ToDuration`. + +## Possible implementation + +```cpp +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; +} +``` + +## Example + +```cpp +#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"; +} +``` + +**Output:** + +``` +ceil(+2.4min) = +3min +ceil(-2.4min) = -2min +ceil(+0.0min) = +0min +``` + +## See also + + + + + `duration_cast` + + converts a duration to another, with a different tick interval + + + + `floor` + + converts a duration to another, rounding down + + + + `round` + + converts a duration to another, rounding to nearest, ties to even + + + + `ceil` (time_point) + + converts a time_point to another, rounding up + + + + `std::ceil` + + nearest integer not less than the given value + + diff --git a/src/content/docs/cpp/library/chrono/duration/count.mdx b/src/content/docs/cpp/library/chrono/duration/count.mdx new file mode 100644 index 00000000..6c7aae2e --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/count.mdx @@ -0,0 +1,72 @@ +--- +title: std::chrono::duration::count +cppdoc: + keys: ["cpp.chrono.duration.count"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr rep count() const; + ``` + + + + Returns the number of ticks for this duration. + + +## Parameters + +(none) + +## Return value + +The number of ticks for this duration. + +## Example + +```cpp +#include +#include + +int main() +{ + std::chrono::milliseconds ms{3}; // 3 milliseconds + // 6000 microseconds constructed from 3 milliseconds + 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"; +} +``` + +**Output:** + +``` +3 ms duration has 3 ticks +6000 us duration has 6000 ticks +3.5 30Hz duration has 3.5 ticks +``` + +## See also + + + + + `duration_cast` + + converts a duration to another, with a different tick interval + + diff --git a/src/content/docs/cpp/library/chrono/duration/duration.mdx b/src/content/docs/cpp/library/chrono/duration/duration.mdx new file mode 100644 index 00000000..2f255718 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/duration.mdx @@ -0,0 +1,116 @@ +--- +title: std::chrono::duration::duration +cppdoc: + keys: ["cpp.chrono.duration.duration"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr duration() = default; + ``` + + + + + ```cpp + duration( const duration& ) = default; + ``` + + + + + ```cpp + template< class Rep2 > + constexpr explicit duration( const Rep2& r ); + ``` + + + + + ```cpp + template< class Rep2, class Period2 > + constexpr duration( const duration& d ); + ``` + + + + Constructs a new `duration` from one of several optional data sources. + + 1. The default constructor. + 2. The copy constructor. + 3. Constructs a duration with `r` ticks. This constructor only participates in overload resolution if all following conditions are satisfied: + - `is_convertible::value` is `true`. + - Any of the following conditions is satisfied (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): + - `std::chrono::treat_as_floating_point::value` is `true`. + - `std::chrono::treat_as_floating_point::value` is `false`. + 4. Constructs a duration by converting `d` to an appropriate period and tick count, as if by `std::chrono::duration_cast(d).count()`. This constructor only participates in overload resolution if no overflow is induced in the conversion, and any of the following conditions is satisfied (either the duration uses floating-point ticks, or `Period2` is exactly divisible by `Period`): + - `std::chrono::treat_as_floating_point::value` is `true`. + - All following conditions are satisfied: + - `std::ratio_divide::den` is `1`. + - `std::chrono::treat_as_floating_point::value` is `false`. + + +## Parameters + +| Parameter | Description | +|---|---| +| `r` | a tick count | +| `d` | a duration to copy from | + +## Example + +The following code shows several examples (both valid and invalid) of how to construct durations: + +```cpp +#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 | +|---|---|---|---| +| LWG 2094 | C++11 | for overload (4), `std::ratio_divide::num` might overflow when evaluating `std::ratio_divide::den` | overload (4) does not participate in overload resolution in this case | +| LWG 3050 | C++11 | convertibility constraint used non-const xvalue | use const lvalues instead | + +## See also + + + + + `operator=` + + assigns the contents + + diff --git a/src/content/docs/cpp/library/chrono/duration/duration_cast.mdx b/src/content/docs/cpp/library/chrono/duration/duration_cast.mdx new file mode 100644 index 00000000..e73bef9b --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/duration_cast.mdx @@ -0,0 +1,126 @@ +--- +title: std::chrono::duration_cast +cppdoc: + keys: ["cpp.chrono.duration.duration_cast"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class ToDuration, class Rep, class Period > + constexpr ToDuration duration_cast( const std::chrono::duration& d ); + ``` + + + + Converts a `std::chrono::duration` to a duration of different type `ToDuration`. + + The function only participates in overload resolution if `ToDuration` is a specialization of `std::chrono::duration`. + + +## Parameters + +| Parameter | Description | +|---|---| +| `d` | duration to convert | + +## Return value + +`d` converted to a duration of type `ToDuration`. + +## Notes + +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, as if by `static_cast`, to the result type only when finished. + +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 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. + +## Example + +This example measures the execution time of a function. + +```cpp +#include +#include +#include +#include + +void f() +{ + std::this_thread::sleep_for(std::chrono::seconds(1)); +} + +int main() +{ + const auto t1 = std::chrono::high_resolution_clock::now(); + f(); + 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"; +} +``` + +**Possible output:** + +``` +f() took 1000.14ms, or 1000ms (whole milliseconds), or 1000000us (whole microseconds) +``` + +## See also + + + + + `std::chrono::duration` + + a time interval + + + + `time_point_cast` + + converts a time point to another time point on the same clock, with a different duration + + + + `floor` + + converts a duration to another, rounding down + + + + `ceil` + + converts a duration to another, rounding up + + + + `round` + + converts a duration to another, rounding to nearest, ties to even + + diff --git a/src/content/docs/cpp/library/chrono/duration/floor.mdx b/src/content/docs/cpp/library/chrono/duration/floor.mdx new file mode 100644 index 00000000..60eb6e92 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/floor.mdx @@ -0,0 +1,96 @@ +--- +title: std::chrono::floor (std::chrono::duration) +cppdoc: + keys: ["cpp.chrono.duration.floor"] + revision: + since: C++17 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class ToDuration, class Rep, class Period > + constexpr ToDuration floor( const std::chrono::duration& 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`. + + +## Parameters + +| Parameter | Description | +|---|---| +| `d` | duration to convert | + +## Return value + +`d` rounded down to a duration of type `ToDuration`. + +## Possible implementation + +```cpp +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; +} +``` + +## See also + + + + + `duration_cast` + + converts a duration to another, with a different tick interval + + + + `ceil` + + converts a duration to another, rounding up + + + + `round` + + converts a duration to another, rounding to nearest, ties to even + + + + `floor` (time_point) + + converts a time_point to another, rounding down + + + + `std::floor` + + nearest integer not greater than the given value + + diff --git a/src/content/docs/cpp/library/chrono/duration/max.mdx b/src/content/docs/cpp/library/chrono/duration/max.mdx new file mode 100644 index 00000000..63da75b6 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/max.mdx @@ -0,0 +1,104 @@ +--- +title: std::chrono::duration::max +cppdoc: + keys: ["cpp.chrono.duration.max"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + static constexpr duration max(); + ``` + + + ```cpp + static constexpr duration max() noexcept; + ``` + + + + Returns a duration with the largest possible value. + + If the representation `rep` of the duration requires some other implementation to return a maximum-length duration, `std::chrono::duration_values` can be specialized to return the desired value. + + +## Parameters + +(none) + +## Return value + +`duration(std::chrono::duration_values::max())` + +## Example + +```cpp +#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"; +} +``` + +**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. +``` + +## See also + + + + + `zero` + + returns the special duration value zero + + + + `min` + + returns the special duration value min + + diff --git a/src/content/docs/cpp/library/chrono/duration/min.mdx b/src/content/docs/cpp/library/chrono/duration/min.mdx new file mode 100644 index 00000000..1477c32f --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/min.mdx @@ -0,0 +1,57 @@ +--- +title: std::chrono::duration::min +cppdoc: + keys: ["cpp.chrono.duration.min"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + static constexpr duration min(); + ``` + + + ```cpp + static constexpr duration min() noexcept; + ``` + + + + Returns a duration with the lowest possible value. + + If the representation `rep` of the duration requires some other implementation to return a minimum-length duration, `std::chrono::duration_values` can be specialized to return the desired value. + + +## Parameters + +(none) + +## Return value + +`duration(std::chrono::duration_values::min())` + +## See also + + + + + `zero` + + returns the special duration value zero + + + + `max` + + returns the special duration value max + + diff --git a/src/content/docs/cpp/library/chrono/duration/round.mdx b/src/content/docs/cpp/library/chrono/duration/round.mdx new file mode 100644 index 00000000..db02e057 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/round.mdx @@ -0,0 +1,106 @@ +--- +title: std::chrono::round (std::chrono::duration) +cppdoc: + keys: ["cpp.chrono.duration.round"] + revision: + since: C++17 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class ToDuration, class Rep, class Period > + constexpr ToDuration round( const std::chrono::duration& 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`. + + +## Parameters + +| Parameter | Description | +|---|---| +| `d` | duration to convert | + +## Return value + +`d` rounded to the nearest duration of type `ToDuration`, rounding to even in halfway cases. + +## Possible implementation + +```cpp +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; +} +``` + +## See also + + + + + `duration_cast` + + converts a duration to another, with a different tick interval + + + + `floor` + + converts a duration to another, rounding down + + + + `ceil` + + converts a duration to another, rounding up + + + + `round` (time_point) + + converts a time_point to another, rounding to nearest, ties to even + + + + `std::round` + + nearest integer, rounding away from zero in halfway cases + + diff --git a/src/content/docs/cpp/library/chrono/duration/zero.mdx b/src/content/docs/cpp/library/chrono/duration/zero.mdx new file mode 100644 index 00000000..ca049b04 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/duration/zero.mdx @@ -0,0 +1,77 @@ +--- +title: std::chrono::duration::zero +cppdoc: + keys: ["cpp.chrono.duration.zero"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + static constexpr duration zero(); + ``` + + + ```cpp + static constexpr duration zero() noexcept; + ``` + + + + Returns a zero-length duration. + + If the representation `rep` of the duration requires some other implementation to return a zero-length duration, `std::chrono::duration_values` can be specialized to return the desired value. + + +## Parameters + +(none) + +## Return value + +Returns `duration(std::chrono::duration_values::zero())`. + +## Example + +```cpp +#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() {} +``` + +## See also + + + + + `min` + + returns the special duration value min + + + + `max` + + returns the special duration value max + + diff --git a/src/content/docs/cpp/library/chrono/hour_fun.mdx b/src/content/docs/cpp/library/chrono/hour_fun.mdx new file mode 100644 index 00000000..a3558b64 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/hour_fun.mdx @@ -0,0 +1,143 @@ +--- +title: std::chrono::is_am, is_pm, make12, make24 +cppdoc: + keys: ["cpp.chrono.is_am", "cpp.chrono.is_pm", "cpp.chrono.make12", "cpp.chrono.make24"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr bool is_am( const std::chrono::hours& h ) noexcept; + ``` + + + + Detects whether the 24-hour format time is a.m. (*ante meridiem*, before midday). + + + + + + ```cpp + constexpr bool is_pm( const std::chrono::hours& h ) noexcept; + ``` + + + + Detects whether the 24-hour format time is p.m. (*post meridiem*, after midday). + + + + + + ```cpp + constexpr std::chrono::hours make12( const std::chrono::hours& h ) noexcept; + ``` + + + + Returns the 12-hour equivalent of a 24-hour format time. + + + + + + ```cpp + constexpr std::chrono::hours make24( const std::chrono::hours& h, + bool is_pm ) noexcept; + ``` + + + + Returns the 24-hour equivalent of a 12-hour format time `h`, where `is_pm` determines whether the time is p.m. + + +These functions aid in translating between a 12-hour format time of day, and a 24-hour format time of day. + +## Parameters + + + + 12-hour or 24-hour format time to detect + + + whether the 12-hour format time is p.m. + + + +## 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. + +## Example + +```cpp +#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"; + } +} +``` + +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/src/content/docs/cpp/library/chrono/is_clock.mdx b/src/content/docs/cpp/library/chrono/is_clock.mdx new file mode 100644 index 00000000..9b2c02ea --- /dev/null +++ b/src/content/docs/cpp/library/chrono/is_clock.mdx @@ -0,0 +1,126 @@ +--- +title: std::chrono::is_clock +cppdoc: + keys: ["cpp.chrono.is_clock"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class T > + 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 `is_clock` or `is_clock_v`, the behavior is undefined. + + +## Template parameters + + + + a type to check + + + +## Helper variable template + + + + + ```cpp + template< class T > + constexpr bool is_clock_v = is_clock::value; + ``` + + + + +## Inherited from std::integral_constant + + + + `value` + `true` if `T` satisfies the Clock requirements, `false` otherwise + + + `operator bool` + converts the object to `bool`, returns `value` + + + `operator()` + returns `value` + + + `value_type` + `bool` + + + `type` + `std::integral_constant` + + + +## Possible implementation + +```cpp +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; // type is not checked + T::now(); // return type is not checked + } +struct is_clock : std::true_type {}; +``` + +## Notes + +If `T` otherwise meets the Clock requirements, but `T::is_steady` is not of type `const bool`, or `T::now()` is not of type `T::time_point`, the result of `is_clock_v` is unspecified. + +## Example + +```cpp +#include +#include + +static_assert +( + std::chrono::is_clock_v and + not std::chrono::is_clock_v> +); + +int main() {} +``` diff --git a/src/content/docs/cpp/library/chrono/last_spec.mdx b/src/content/docs/cpp/library/chrono/last_spec.mdx new file mode 100644 index 00000000..2e5d58ae --- /dev/null +++ b/src/content/docs/cpp/library/chrono/last_spec.mdx @@ -0,0 +1,55 @@ +--- +title: std::chrono::last_spec, std::chrono::last +cppdoc: + keys: ["cpp.chrono.last_spec", "cpp.chrono.last"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + struct last_spec + { + explicit last_spec() = default; + }; + ``` + + + + + ```cpp + inline constexpr last_spec last{}; + ``` + + + + `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). + + +## Example + +```cpp +#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/src/content/docs/cpp/library/chrono/locate_zone.mdx b/src/content/docs/cpp/library/chrono/locate_zone.mdx new file mode 100644 index 00000000..b6771888 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/locate_zone.mdx @@ -0,0 +1,52 @@ +--- +title: std::chrono::locate_zone +cppdoc: + keys: ["cpp.chrono.locate_zone"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + const std::chrono::time_zone* locate_zone( std::string_view tz_name ); + ``` + + + + Convenience function for locating a time zone in the time zone database. Equivalent to `std::chrono::get_tzdb().locate_zone(tz_name)`. + + +## 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. + +## Notes + +A call to this function that is the first reference to the time zone database will cause it to be initialized. + +## See also + + + + + `tzdb::locate_zone` + + locates a time zone with the given name + + + + `get_tzdb` / `get_tzdb_list` / `reload_tzdb` / `remote_version` + + accesses and controls the global time zone database information + + diff --git a/src/content/docs/cpp/library/chrono/month.mdx b/src/content/docs/cpp/library/chrono/month.mdx new file mode 100644 index 00000000..fcb89e37 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month.mdx @@ -0,0 +1,128 @@ +--- +title: std::chrono::month +cppdoc: + keys: ["cpp.chrono.month"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + class month; + ``` + + + + + ```cpp + inline constexpr std::chrono::month January{1}; + inline constexpr std::chrono::month February{2}; + inline constexpr std::chrono::month March{3}; + inline constexpr std::chrono::month April{4}; + inline constexpr std::chrono::month May{5}; + inline constexpr std::chrono::month June{6}; + inline constexpr std::chrono::month July{7}; + inline constexpr std::chrono::month August{8}; + inline constexpr std::chrono::month September{9}; + inline constexpr std::chrono::month October{10}; + inline constexpr std::chrono::month November{11}; + inline constexpr std::chrono::month December{12}; + ``` + + + + 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*. + + +## Member functions + + + + + `(constructor)` + + constructs a `month` + + + + `operator++` / `operator--` + + increments or decrements the month + + + + `operator+=` / `operator-=` + + adds or subtracts a number of months + + + + `operator unsigned` + + retrieves the stored month value + + + + `ok` + + checks if the stored month value is in the normal range + + + +## Non-member functions + + + + + `operator==` / `operator<=>` + + compares two `month` values + + + + `operator+` / `operator-` + + performs arithmetic on `month`s + + + + `operator<<` + + outputs a `month` into a stream + + + + `from_stream` + + parses a `month` from a stream according to the provided format + + + +## Helper classes + + + + + `std::formatter` + + formatting support for `month` + + + + `std::hash` + + hash support for `std::chrono::month` + + diff --git a/src/content/docs/cpp/library/chrono/month/_meta.yml b/src/content/docs/cpp/library/chrono/month/_meta.yml new file mode 100644 index 00000000..5eb18492 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/_meta.yml @@ -0,0 +1 @@ +label: std::chrono::month \ No newline at end of file diff --git a/src/content/docs/cpp/library/chrono/month/formatter.mdx b/src/content/docs/cpp/library/chrono/month/formatter.mdx new file mode 100644 index 00000000..15c87750 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/formatter.mdx @@ -0,0 +1,49 @@ +--- +title: std::formatter +cppdoc: + keys: ["cpp.chrono.month.formatter"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT > + struct formatter; + ``` + + + + Specialization of `std::formatter` that defines formatting rules for a `std::chrono::month`. + + The `std::formatter` specialization is usually not directly accessed, but is used through formatting functions. + + +## 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 | `formatter` used the global locale or passed locale | default `"C"` locale is used when **L** is absent | + +## See also + + + + + `std::format` + + stores formatted representation of the arguments in a new string + + diff --git a/src/content/docs/cpp/library/chrono/month/from_stream.mdx b/src/content/docs/cpp/library/chrono/month/from_stream.mdx new file mode 100644 index 00000000..fcb38301 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/from_stream.mdx @@ -0,0 +1,43 @@ +--- +title: std::chrono::from_stream (std::chrono::month) +cppdoc: + keys: ["cpp.chrono.month.from_stream"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT, class Traits, class Alloc = std::allocator > + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* fmt, + std::chrono::month& m, + std::basic_string* abbrev = nullptr, + std::chrono::minutes* offset = nullptr ); + ``` + + + + Parses a `month` from the stream `is` according to the format string `fmt`. + + +## See also + + + + + `std::chrono::parse` + + parses a `chrono` object from a stream + + diff --git a/src/content/docs/cpp/library/chrono/month/hash.mdx b/src/content/docs/cpp/library/chrono/month/hash.mdx new file mode 100644 index 00000000..1bc22edf --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/hash.mdx @@ -0,0 +1,30 @@ +--- +title: std::hash +cppdoc: + keys: ["cpp.chrono.month.hash"] + revision: + since: C++26 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template<> + struct std::hash; + ``` + + + + The template specialization of `std::hash` for `std::chrono::month` allows users to obtain hashes of objects of type `std::chrono::month`. + + The specialization is enabled, and `operator()` of this specialization is `noexcept`. + diff --git a/src/content/docs/cpp/library/chrono/month/month.mdx b/src/content/docs/cpp/library/chrono/month/month.mdx new file mode 100644 index 00000000..63891ff8 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/month.mdx @@ -0,0 +1,35 @@ +--- +title: std::chrono::month::month +cppdoc: + keys: ["cpp.chrono.month.month"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + month() = default; + ``` + + + + + ```cpp + constexpr explicit month( unsigned m ) noexcept; + ``` + + + + 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/src/content/docs/cpp/library/chrono/month/ok.mdx b/src/content/docs/cpp/library/chrono/month/ok.mdx new file mode 100644 index 00000000..fefabdda --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/ok.mdx @@ -0,0 +1,55 @@ +--- +title: std::chrono::month::ok +cppdoc: + keys: ["cpp.chrono.month.ok"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr bool ok() const noexcept; + ``` + + + + Checks if the month value stored in `*this` is in the valid range, i.e., \[1, 12\]. + + +## Return value + +`true` if the month value stored in `*this` is in the range \[1, 12\]. Otherwise `false`. + +## Example + +```cpp +#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"; + } +} +``` + +**Output:** + +``` +6: month is valid +0: month is invalid +16: month is invalid +``` diff --git a/src/content/docs/cpp/library/chrono/month/operator_arith.mdx b/src/content/docs/cpp/library/chrono/month/operator_arith.mdx new file mode 100644 index 00000000..a455243f --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/operator_arith.mdx @@ -0,0 +1,95 @@ +--- +title: std::chrono::month::operator+=, operator-= +cppdoc: + keys: ["cpp.chrono.month.operator_arith"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::month& operator+=( const std::chrono::months& m ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::month& operator-=( const 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;`. + + +## Return value + +A reference to this `month` after modification. + +## Notes + +After a call to one of these functions, `ok()` is always `true` if no overflow occurred during the operation. + +## Example + +```cpp +#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'; +} +``` + +**Output:** + +``` +true true true true true true +``` + +## See also + + + + + `operator++` / `operator--` + + increments or decrements the month + + + + `operator+` / `operator-` + + performs arithmetic on `month`s + + diff --git a/src/content/docs/cpp/library/chrono/month/operator_arith_2.mdx b/src/content/docs/cpp/library/chrono/month/operator_arith_2.mdx new file mode 100644 index 00000000..63977a7b --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/operator_arith_2.mdx @@ -0,0 +1,103 @@ +--- +title: operator+, operator- (std::chrono::month) +cppdoc: + keys: ["cpp.chrono.month.operator_arith_2"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::month operator+( const std::chrono::month& m, + const std::chrono::months& ms ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::month operator+( const std::chrono::months& ms, + const std::chrono::month& m ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::month operator-( const std::chrono::month& m, + const std::chrono::months& ms ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::months operator-( const std::chrono::month& m1, + 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. + + +## 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`. + +## 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). + +## Example + +```cpp +#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)); +} +``` + +## See also + + + + + `operator++` / `operator--` + + increments or decrements the month + + + + `operator+=` / `operator-=` + + adds or subtracts a number of months + + diff --git a/src/content/docs/cpp/library/chrono/month/operator_cmp.mdx b/src/content/docs/cpp/library/chrono/month/operator_cmp.mdx new file mode 100644 index 00000000..746333dc --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/operator_cmp.mdx @@ -0,0 +1,61 @@ +--- +title: operator==, <=> (std::chrono::month) +cppdoc: + keys: ["cpp.chrono.month.operator_cmp"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr bool operator==( const std::chrono::month& x, + const std::chrono::month& y ) noexcept; + ``` + + + + + ```cpp + constexpr std::strong_ordering operator<=>( const std::chrono::month& x, + 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. + + +## Return value + +1) `unsigned(x) == unsigned(y)` +2) `unsigned(x) <=> unsigned(y)` + +## Example + +```cpp +#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/src/content/docs/cpp/library/chrono/month/operator_inc_dec.mdx b/src/content/docs/cpp/library/chrono/month/operator_inc_dec.mdx new file mode 100644 index 00000000..0d355873 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/operator_inc_dec.mdx @@ -0,0 +1,115 @@ +--- +title: std::chrono::month::operator++, operator-- +cppdoc: + keys: ["cpp.chrono.month.operator_inc_dec"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::month& operator++() noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::month operator++( int ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::month& operator--() noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::month operator--( int ) noexcept; + ``` + + + + 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};`. + + +## Parameters + +(none) + +## Return value + +1,3) A reference to this `month` after modification. +2,4) A copy of the `month` made before modification. + +## Notes + +After a call to one of these functions, `ok()` is always `true`. + +## Example + +```cpp +#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'; +} +``` + +**Output:** + +``` +1 +12 +``` + +## See also + + + + + `operator+=` / `operator-=` + + adds or subtracts a number of months + + + + `operator+` / `operator-` + + performs arithmetic on `month`s + + diff --git a/src/content/docs/cpp/library/chrono/month/operator_ltlt.mdx b/src/content/docs/cpp/library/chrono/month/operator_ltlt.mdx new file mode 100644 index 00000000..d9f61b1e --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/operator_ltlt.mdx @@ -0,0 +1,72 @@ +--- +title: operator<< (std::chrono::month) +cppdoc: + keys: ["cpp.chrono.month.operator_ltlt"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT, class Traits > + std::basic_ostream& + 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 + + ```cpp + 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`. + + +## Return value + +`os` + +## 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 | + +## See also + + + + + `std::format` + + stores formatted representation of the arguments in a new string + + + + `std::formatter` + + formatting support for `month` + + diff --git a/src/content/docs/cpp/library/chrono/month/operator_unsigned.mdx b/src/content/docs/cpp/library/chrono/month/operator_unsigned.mdx new file mode 100644 index 00000000..a664fb02 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/month/operator_unsigned.mdx @@ -0,0 +1,52 @@ +--- +title: std::chrono::month::operator unsigned +cppdoc: + keys: ["cpp.chrono.month.operator_unsigned"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr explicit operator unsigned() const noexcept; + ``` + + + + Returns the month value stored in `*this`. + + +## Return value + +The month value stored in `*this`. + +## Example + +```cpp +#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'; +} +``` + +**Output:** + +``` +The month is: 6 +September is: 9 +``` diff --git a/src/content/docs/cpp/library/chrono/nonexistent_local_time.mdx b/src/content/docs/cpp/library/chrono/nonexistent_local_time.mdx new file mode 100644 index 00000000..da72bea2 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/nonexistent_local_time.mdx @@ -0,0 +1,186 @@ +--- +title: std::chrono::nonexistent_local_time +cppdoc: + keys: ["cpp.chrono.nonexistent_local_time"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + class nonexistent_local_time; + ``` + + + + 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`). + + +## Member functions + + + + `(constructor)` + constructs the exception object + + + `operator=` + replaces the exception object + + + `what` + returns the explanatory string + + + +## std::chrono::nonexistent_local_time::nonexistent_local_time + + + + + ```cpp + template< class Duration > + nonexistent_local_time( const std::chrono::local_time& tp, + const std::chrono::local_info& i ); + ``` + + + + The explanatory string returned by `what()` is equivalent to that produced by `os.str()` after the following code: + + ```cpp + 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`. + + + + + + ```cpp + nonexistent_local_time( const nonexistent_local_time& other ) noexcept; + ``` + + + + Copy constructor. If `*this` and `other` both have dynamic type `std::chrono::nonexistent_local_time` then `std::strcmp(what(), other.what()) == 0`. + + +### Parameters + + + + the time point for which conversion was attempted + + + a `std::chrono::local_info` describing the result of the conversion attempt + + + another `nonexistent_local_time` to copy + + + +### Exceptions + +May throw `std::bad_alloc`. + +### 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_local_time::operator= + + + + + ```cpp + nonexistent_local_time& operator=( const nonexistent_local_time& other ) noexcept; + ``` + + + + Assigns the contents with those of `other`. If `*this` and `other` both have dynamic type `std::chrono::nonexistent_local_time` then `std::strcmp(what(), other.what()) == 0` after assignment. + + +### Parameters + + + + another exception object to assign with + + + +### Return value + +`*this` + +## std::chrono::nonexistent_local_time::what + + + + + ```cpp + virtual const char* what() const noexcept; + ``` + + + + Returns the explanatory string. + + +### Parameters + +(none) + +### 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. + +### Notes + +Implementations are allowed but not required to override `what()`. + +## Inherited from std::runtime_error + +Inherited from `std::exception`. + +### Member functions + + + + `what` + returns an explanatory string + + + +## See also + + + + + `ambiguous_local_time` + + exception thrown to report that a local time is ambiguous + + diff --git a/src/content/docs/cpp/library/chrono/operator_d.mdx b/src/content/docs/cpp/library/chrono/operator_d.mdx new file mode 100644 index 00000000..71189559 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_d.mdx @@ -0,0 +1,99 @@ +--- +title: std::literals::chrono_literals::operator""d +cppdoc: + keys: ["cpp.chrono.operator_d"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::day operator ""d( unsigned long long d ) noexcept; + ``` + + + + Forms a `std::chrono::day` literal representing a day of the month in the calendar. + + +## Parameters + + + + the day value + + + +## Return value + +A `std::chrono::day` storing `d`. If `d > 255`, the stored value is unspecified. + +## Possible implementation + +```cpp +constexpr std::chrono::day operator ""d(unsigned long long d) noexcept +{ + return std::chrono::day(d); +} +``` + +## 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. + +## Example + +```cpp +#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 +} +``` + +Possible output: + +``` +42 42 is not a valid day +0 00 is not a valid day +42 42 is not a valid day +``` + +## See also + + + + + `day::day` + + constructs a `day` + + + + `day::operator unsigned` + + retrieves the stored day value + + diff --git a/src/content/docs/cpp/library/chrono/operator_h.mdx b/src/content/docs/cpp/library/chrono/operator_h.mdx new file mode 100644 index 00000000..0ec8e6ab --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_h.mdx @@ -0,0 +1,114 @@ +--- +title: std::literals::chrono_literals::operator""h +cppdoc: + keys: ["cpp.chrono.operator_h"] + revision: + since: C++14 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::hours + operator""h( unsigned long long hrs ); + ``` + + + + Integer literal, returns exactly `std::chrono::hours(hrs)`. + + + + + + ```cpp + constexpr std::chrono::duration> + operator""h( long double hrs ); + ``` + + + + Floating-point literal, returns a floating-point duration equivalent to `std::chrono::hours`. + + +Forms a `std::chrono::duration` literal representing hours. + +## Parameters + + + + the number of hours + + + +## Return value + +The `std::chrono::duration` literal. + +## Possible implementation + +```cpp +constexpr std::chrono::hours operator""h(unsigned long long h) +{ + return std::chrono::hours(h); +} + +constexpr std::chrono::duration> operator""h(long double h) +{ + return std::chrono::duration>(h); +} +``` + +## 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. + +## Example + +```cpp +#include +#include + +int main() +{ + using namespace std::chrono_literals; + auto day = 24h; + auto halfhour = 0.5h; + std::cout << "one day is " << day.count() << " hours (" << day << ")\n" + << "half an hour is " << halfhour.count() << " hours (" + << halfhour << ")\n"; +} +``` + +Output: + +``` +one day is 24 hours (24h) +half an hour is 0.5 hours (0.5h) +``` + +## See also + + + + + `duration::duration` + + constructs new duration + + diff --git a/src/content/docs/cpp/library/chrono/operator_min.mdx b/src/content/docs/cpp/library/chrono/operator_min.mdx new file mode 100644 index 00000000..3b118777 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_min.mdx @@ -0,0 +1,115 @@ +--- +title: std::literals::chrono_literals::operator""min +cppdoc: + keys: ["cpp.chrono.operator_min"] + revision: + since: C++14 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr chrono::minutes + operator""min( unsigned long long mins ); + ``` + + + + Integer literal, returns exactly `std::chrono::minutes(mins)`. + + + + + + ```cpp + constexpr chrono::duration> + operator""min( long double mins ); + ``` + + + + Floating-point literal, returns a floating-point duration equivalent to `std::chrono::minutes`. + + +Forms a `std::chrono::duration` literal representing minutes. + +## Parameters + + + + the number of minutes + + + +## Return value + +The `std::chrono::duration` literal. + +## Possible implementation + +```cpp +constexpr std::chrono::minutes operator""min(unsigned long long m) +{ + return std::chrono::minutes(m); +} +constexpr std::chrono::duration> operator""min(long double m) +{ + return std::chrono::duration> (m); +} +``` + +## 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. + +## Example + +```cpp +#include +#include + +int main() +{ + using namespace std::chrono_literals; + auto lesson = 45min; + auto halfmin = 0.5min; + std::cout << "One lesson is " << lesson.count() << " minutes" + " (" << lesson << ")\n" + << "Half a minute is " << halfmin.count() << " minutes" + " (" << halfmin << ")\n"; +} +``` + +Output: + +``` +One lesson is 45 minutes (45min) +Half a minute is 0.5 minutes (0.5min) +``` + +## See also + + + + + `duration::duration` + + constructs new duration + + diff --git a/src/content/docs/cpp/library/chrono/operator_ms.mdx b/src/content/docs/cpp/library/chrono/operator_ms.mdx new file mode 100644 index 00000000..d9f60215 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_ms.mdx @@ -0,0 +1,112 @@ +--- +title: std::literals::chrono_literals::operator""ms +cppdoc: + keys: ["cpp.chrono.operator_ms"] + revision: + since: C++14 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::milliseconds + operator""ms( unsigned long long ms ); + ``` + + + + Integer literal, returns exactly `std::chrono::milliseconds(ms)`. + + + + + + ```cpp + constexpr std::chrono::duration + operator""ms( long double ms ); + ``` + + + + Floating-point literal, returns a floating-point duration equivalent to `std::chrono::milliseconds`. + + +Forms a `std::chrono::duration` literal representing milliseconds. + +## Parameters + + + + the number of milliseconds + + + +## Return value + +The `std::chrono::duration` literal. + +## Possible implementation + +```cpp +constexpr std::chrono::milliseconds operator""ms(unsigned long long ms) +{ + return std::chrono::milliseconds(ms); +} +constexpr std::chrono::duration operator""ms(long double ms) +{ + return std::chrono::duration(ms); +} +``` + +## 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. + +## Example + +```cpp +#include +#include + +int main() +{ + 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"; +} +``` + +Output: + +``` +250ms = 250 milliseconds +1000ms = 1000 milliseconds +``` + +## See also + + + + + `duration::duration` + + constructs new duration + + diff --git a/src/content/docs/cpp/library/chrono/operator_ns.mdx b/src/content/docs/cpp/library/chrono/operator_ns.mdx new file mode 100644 index 00000000..37cc48f8 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_ns.mdx @@ -0,0 +1,112 @@ +--- +title: std::literals::chrono_literals::operator""ns +cppdoc: + keys: ["cpp.chrono.operator_ns"] + revision: + since: C++14 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::nanoseconds + operator""ns( unsigned long long nsec ); + ``` + + + + Integer literal, returns exactly `std::chrono::nanoseconds(nsec)`. + + + + + + ```cpp + constexpr std::chrono::duration + operator""ns( long double nsec ); + ``` + + + + Floating-point literal, returns a floating-point duration equivalent to `std::chrono::nanoseconds`. + + +Forms a `std::chrono::duration` literal representing nanoseconds. + +## Parameters + + + + the number of nanoseconds + + + +## Return value + +The `std::chrono::duration` literal. + +## Possible implementation + +```cpp +constexpr std::chrono::nanoseconds operator""ns(unsigned long long ns) +{ + return std::chrono::nanoseconds(ns); +} +constexpr std::chrono::duration operator""ns(long double ns) +{ + return std::chrono::duration(ns); +} +``` + +## 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. + +## Example + +```cpp +#include +#include + +int main() +{ + 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"; +} +``` + +Output: + +``` +250ns = 250 nanoseconds +1000ns = 1000 nanoseconds +``` + +## See also + + + + + `duration::duration` + + constructs new duration + + diff --git a/src/content/docs/cpp/library/chrono/operator_s.mdx b/src/content/docs/cpp/library/chrono/operator_s.mdx new file mode 100644 index 00000000..326c8502 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_s.mdx @@ -0,0 +1,122 @@ +--- +title: std::literals::chrono_literals::operator""s +cppdoc: + keys: ["cpp.chrono.operator_s"] + revision: + since: C++14 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::seconds + operator""s( unsigned long long secs ); + ``` + + + + Integer literal, returns exactly `std::chrono::seconds(secs)`. + + + + + + ```cpp + constexpr std::chrono::duration + operator""s( long double secs ); + ``` + + + + Floating-point literal, returns a floating-point duration equivalent to `std::chrono::seconds`. + + +Forms a `std::chrono::duration` literal representing seconds. + +## Parameters + + + + the number of seconds + + + +## Return value + +The `std::chrono::duration` literal. + +## Possible implementation + +```cpp +constexpr std::chrono::seconds operator""s(unsigned long long s) +{ + return std::chrono::seconds(s); +} +constexpr std::chrono::duration operator""s(long double s) +{ + return std::chrono::duration(s); +} +``` + +## 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. + +`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 two-character string. + +## Example + +```cpp +#include +#include + +int main() +{ + 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"; +} +``` + +Output: + +``` +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. +``` + +## See also + + + + + `duration::duration` + + constructs new duration + + diff --git a/src/content/docs/cpp/library/chrono/operator_slash.mdx b/src/content/docs/cpp/library/chrono/operator_slash.mdx new file mode 100644 index 00000000..aa67e990 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_slash.mdx @@ -0,0 +1,215 @@ +--- +title: std::chrono::operator/ (calendar) +cppdoc: + keys: ["cpp.chrono.operator_slash"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + +These `operator/` overloads provide a conventional syntax for the creation of proleptic Gregorian calendar dates. + +For creation of a full date, any of the following three orders are accepted: +- *year/month/day*, +- *month/day/year*, +- *day/month/year*. + +In each case *day* can replaced with one of: +- `std::chrono::last`, for the last day of the month; +- `weekday[i]`, for the *i*th *weekday* of the month; +- `weekday[std::chrono::last]`, for the last *weekday* of the month. + +A plain integer is accepted if its meaning is unambiguous from the types of other operands: `2005y/4/5` is allowed, but `5/April/2005` is not. + +Partial-date types (`year_month`, `month_day`, etc.) can be created by not applying the second `operator/` in any of the three orders. + +## year_month + + + + + ```cpp + constexpr auto operator/( const std::chrono::year& y, + const std::chrono::month& m ) noexcept + -> std::chrono::year_month; + ``` + + + + Returns `std::chrono::year_month(y, m)`. + + + + + + ```cpp + constexpr auto operator/( const std::chrono::year& y, int m ) noexcept + -> std::chrono::year_month; + ``` + + + + Returns `std::chrono::year_month(y, std::chrono::month(m))`. + + +## month_day + + + + + ```cpp + constexpr auto operator/( const std::chrono::month& m, + const std::chrono::day& d ) noexcept + -> std::chrono::month_day; + ``` + + + + Returns `std::chrono::month_day(m, d)`. + + + + + + ```cpp + constexpr auto operator/( const std::chrono::month& m, int d ) noexcept + -> std::chrono::month_day; + ``` + + + + Returns `std::chrono::month_day(m, std::chrono::day(d))`. + + + + + + ```cpp + constexpr auto operator/( int m, const std::chrono::day& d ) noexcept + -> std::chrono::month_day; + ``` + + + + Returns `std::chrono::month_day(std::chrono::month(m), d)`. + + + + + + ```cpp + constexpr auto operator/( const std::chrono::day& d, + const std::chrono::month& m ) noexcept + -> std::chrono::month_day; + ``` + + + + Returns `std::chrono::month_day(m, d)`. + + + + + + ```cpp + constexpr auto operator/( const std::chrono::day& d, int m ) noexcept + -> std::chrono::month_day; + ``` + + + + Returns `std::chrono::month_day(std::chrono::month(m), d)`. + + +## month_day_last + + + + + ```cpp + constexpr auto operator/( const std::chrono::month& m, + std::chrono::last_spec ) noexcept + -> std::chrono::month_day_last; + ``` + + + + Returns `std::chrono::month_day_last(m)`. + + + + + + ```cpp + constexpr auto operator/( int m, std::chrono::last_spec ) noexcept + -> std::chrono::month_day_last; + ``` + + + + Returns `std::chrono::month_day_last(std::chrono::month(m))`. + + + + + + ```cpp + constexpr auto operator/( std::chrono::last_spec, + const std::chrono::month& m ) noexcept + -> std::chrono::month_day_last; + ``` + + + + Returns `std::chrono::month_day_last(m)`. + + + + + + ```cpp + constexpr auto operator/( std::chrono::last_spec, int m ) noexcept + -> std::chrono::month_day_last; + ``` + + + + Returns `std::chrono::month_day_last(std::chrono::month(m))`. + + +## Example + +```cpp +#include +using namespace std::chrono; + +constexpr auto ym{2021y/8}; +static_assert(ym == year_month(year(2021), August)); + +constexpr auto md{9/15d}; +static_assert(md == month_day(September, day(15))); + +constexpr auto mdl{October/last}; +static_assert(mdl == month_day_last(month(10))); + +constexpr auto mw{11/Monday[3]}; +static_assert(mw == month_weekday(November, Monday[3])); + +constexpr auto mwdl{December/Sunday[last]}; +static_assert(mwdl == month_weekday_last(month(12), weekday_last(Sunday))); + +// Those 3 year/month/day orders that people actually use on this planet and beyond: +constexpr auto ymd{year(2021)/January/day(23)}; +static_assert(ymd == month{1}/23/2021); +static_assert(ymd == day{23}/1/2021); +static_assert(ymd == year_month_day(2021y, month(January), 23d)); + +int main() {} +``` diff --git a/src/content/docs/cpp/library/chrono/operator_us.mdx b/src/content/docs/cpp/library/chrono/operator_us.mdx new file mode 100644 index 00000000..e388e6e1 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_us.mdx @@ -0,0 +1,112 @@ +--- +title: std::literals::chrono_literals::operator""us +cppdoc: + keys: ["cpp.chrono.operator_us"] + revision: + since: C++14 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::microseconds + operator""us( unsigned long long us ); + ``` + + + + Integer literal, returns exactly `std::chrono::microseconds(us)`. + + + + + + ```cpp + constexpr std::chrono::duration + operator""us( long double us ); + ``` + + + + Floating-point literal, returns a floating-point duration equivalent to `std::chrono::microseconds`. + + +Forms a `std::chrono::duration` literal representing microseconds. + +## Parameters + + + + the number of microseconds + + + +## Return value + +The `std::chrono::duration` literal. + +## Possible implementation + +```cpp +constexpr std::chrono::microseconds operator""us(unsigned long long us) +{ + return std::chrono::microseconds(us); +} +constexpr std::chrono::duration operator""us(long double us) +{ + return std::chrono::duration(us); +} +``` + +## 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. + +## Example + +```cpp +#include +#include + +int main() +{ + using namespace std::chrono_literals; + auto d1 = 250us; + std::chrono::microseconds d2 = 1ms; + std::cout << d1 << " = " << d1.count() << " microseconds\n" + << 1ms << " = " << d2.count() << " microseconds\n"; +} +``` + +Output: + +``` +250us = 250 microseconds +1ms = 1000 microseconds +``` + +## See also + + + + + `duration::duration` + + constructs new duration + + diff --git a/src/content/docs/cpp/library/chrono/operator_y.mdx b/src/content/docs/cpp/library/chrono/operator_y.mdx new file mode 100644 index 00000000..ebaa709f --- /dev/null +++ b/src/content/docs/cpp/library/chrono/operator_y.mdx @@ -0,0 +1,97 @@ +--- +title: std::literals::chrono_literals::operator""y +cppdoc: + keys: ["cpp.chrono.operator_y"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr std::chrono::year operator""y( unsigned long long y ) noexcept; + ``` + + + + Forms a `std::chrono::year` literal representing a year in the proleptic Gregorian calendar. + + +## Parameters + + + + the year value + + + +## Return value + +A `std::chrono::year` initialized from `int(y)`. If `y` is not in the range \[-32767, 32767\], the stored value is unspecified. + +## Possible implementation + +```cpp +constexpr std::chrono::year operator""y(unsigned long long y) noexcept +{ + return std::chrono::year(static_cast(y)); +} +``` + +## 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. + +## Example + +```cpp +#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 +} +``` + +Possible output: + +``` +2020 2020 +-220 -0220 +3000 3000 +-32768 -32768 is not a valid year +42 0042 +``` + +## See also + + + + + `year::year` + + constructs a `year` + + diff --git a/src/content/docs/cpp/library/chrono/parse.mdx b/src/content/docs/cpp/library/chrono/parse.mdx new file mode 100644 index 00000000..b8d5f4ab --- /dev/null +++ b/src/content/docs/cpp/library/chrono/parse.mdx @@ -0,0 +1,199 @@ +--- +title: std::chrono::parse +cppdoc: + keys: ["cpp.chrono.parse"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import { ParamDoc, ParamDocList } from "@components/param-doc"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT, class Parsable > + /* unspecified */ parse( const CharT* fmt, Parsable& tp ); + ``` + + + + 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 `from_stream(is, fmt, tp)`. + + + + + + ```cpp + template< class CharT, class Traits, class Alloc, class Parsable > + /* unspecified */ parse( const std::basic_string& fmt, + Parsable& tp ); + ``` + + + + Returns an object `manip` of unspecified type such that, given a `std::basic_istream` object `is`, the expression `is >> manip` calls `from_stream(is, fmt.c_str(), tp)`. + + + + + + ```cpp + template< class CharT, class Traits, class Alloc, class Parsable > + /* unspecified */ parse( const CharT* fmt, Parsable& tp, + std::basic_string& abbrev ); + ``` + + + + Returns an object `manip` of unspecified type such that, given a `std::basic_istream` object `is`, the expression `is >> manip` calls `from_stream(is, fmt, tp, std::addressof(abbrev))`. + + + + + + ```cpp + template< class CharT, class Traits, class Alloc, class Parsable > + /* unspecified */ parse( const std::basic_string& fmt, + Parsable& tp, + std::basic_string& abbrev ); + ``` + + + + Returns an object `manip` of unspecified type such that, given a `std::basic_istream` object `is`, the expression `is >> manip` calls `from_stream(is, fmt.c_str(), tp, std::addressof(abbrev))`. + + + + + + ```cpp + template< class CharT, class Parsable > + /* unspecified */ parse( const CharT* fmt, Parsable& tp, + 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(is, fmt, tp, static_cast*>(nullptr), &offset)`. + + + + + + ```cpp + template< class CharT, class Traits, class Alloc, class Parsable > + /* unspecified */ parse( const std::basic_string& fmt, + Parsable& tp, 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(is, fmt.c_str(), tp, static_cast*>(nullptr), &offset)`. + + + + + + ```cpp + template< class CharT, class Traits, class Alloc, class Parsable > + /* unspecified */ parse( const CharT* fmt, Parsable& tp, + 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(is, fmt, tp, std::addressof(abbrev), &offset)`. + + + + + + ```cpp + template< class CharT, class Traits, class Alloc, class Parsable > + /* unspecified */ parse( const std::basic_string& fmt, + Parsable& tp, + 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(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. + +## Parameters + + + + a format string (see below) + + + object to hold the parse result + + + string to hold the time zone abbreviation or name corresponding to the `%Z` specifier + + + 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. + +## Example + +```cpp +// Example code here +``` + +## Defect 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 type sequences were missing | added | + +## See also + + + + + `from_stream` (sys_time) + + parses a sys_time from a stream according to the provided format + + + + `from_stream` (utc_time) + + parses a utc_time from a stream according to the provided format + + + + `std::get_time` + + parses a date/time value of specified format + + diff --git a/src/content/docs/cpp/library/chrono/treat_as_floating_point.mdx b/src/content/docs/cpp/library/chrono/treat_as_floating_point.mdx new file mode 100644 index 00000000..f9d770ce --- /dev/null +++ b/src/content/docs/cpp/library/chrono/treat_as_floating_point.mdx @@ -0,0 +1,101 @@ +--- +title: std::chrono::treat_as_floating_point +cppdoc: + keys: ["cpp.chrono.treat_as_floating_point"] + revision: + since: C++11 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class Rep > + struct treat_as_floating_point : std::is_floating_point {}; + ``` + + + + The `std::chrono::treat_as_floating_point` trait helps determine if a duration can be converted to another duration with a different tick period. + + Implicit conversions between two durations normally depends on the tick period of the durations. However, implicit conversions can happen regardless of tick period if `std::chrono::treat_as_floating_point::value` is `true`. + + +## Helper variable template + + + + + ```cpp + template< class Rep > + constexpr bool treat_as_floating_point_v = treat_as_floating_point::value; + ``` + + + + +## Specializations + +`std::chrono::treat_as_floating_point` may be specialized for program-defined types. + +## Example + +```cpp +#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"; + 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 << "Timing stats:\n"; + + std::cout << " Time in milliseconds, using default rep: " + << i_ms.count() << '\n'; + + std::cout << " Time in milliseconds, using floating point rep: " + << f_ms.count() << '\n'; +} +``` + +Possible output: + +``` +Running some timed piece of code... +Timing stats: + Time in milliseconds, using default rep: 2 + Time in milliseconds, using floating point rep: 2.57307 +``` diff --git a/src/content/docs/cpp/library/chrono/tzdb_functions.mdx b/src/content/docs/cpp/library/chrono/tzdb_functions.mdx new file mode 100644 index 00000000..70fea8e3 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/tzdb_functions.mdx @@ -0,0 +1,76 @@ +--- +title: std::chrono::get_tzdb_list, get_tzdb, remote_version, reload_tzdb +cppdoc: + keys: ["cpp.chrono.get_tzdb_list", "cpp.chrono.get_tzdb", "cpp.chrono.remote_version", "cpp.chrono.reload_tzdb"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + std::chrono::tzdb_list& get_tzdb_list(); + ``` + + + + 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. + + + + + + ```cpp + const std::chrono::tzdb& get_tzdb(); + ``` + + + + Returns a reference to the first `std::chrono::tzdb` object held by the `tzdb_list` singleton. Equivalent to `std::chrono::get_tzdb_list().front()`. + + + + + + ```cpp + std::string remote_version(); + ``` + + + + Returns a string containing the latest remote database version. + + + + + + ```cpp + const std::chrono::tzdb& reload_tzdb(); + ``` + + + + 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. + + +These functions provide access to the program-wide time zone database. + +## Exceptions + +1. `std::runtime_error` if for any reason a reference to a `tzdb_list` containing one or more valid `tzdb` cannot be returned. + +## 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/src/content/docs/cpp/library/chrono/year.mdx b/src/content/docs/cpp/library/chrono/year.mdx new file mode 100644 index 00000000..42a49744 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year.mdx @@ -0,0 +1,148 @@ +--- +title: std::chrono::year +cppdoc: + keys: ["cpp.chrono.year"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + class year; + ``` + + + + The class `year` represents a year in the proleptic Gregorian calendar. Its range is \[-32767, 32767\]. + + `year` is a *TriviallyCopyable* *StandardLayoutType*. + + +## Member functions + + + + + `(constructor)` + + constructs a `year` + + + + `operator++` / `operator--` + + increments or decrements the year + + + + `operator+=` / `operator-=` + + adds or subtracts a number of years + + + + `operator+` / `operator-` + + applies unary operators to year + + + + `is_leap` + + determines if the year is a leap year + + + + `operator int` + + retrieves the year value + + + + `ok` + + checks if the stored year value is in the valid range + + + + `min` + + returns the smallest possible year + + + + `max` + + returns the largest possible year + + + +## Non-member functions + + + + + `operator==` / `operator<=>` + + compares two `year` values + + + + `operator+` / `operator-` + + performs arithmetic on `year`s + + + + `operator<<` + + outputs a `year` into a stream + + + + `from_stream` + + parses a `year` from a stream according to the provided format + + + +## Helper classes + + + + + `std::formatter` + + formatting support for `year` + + + + `std::hash` + + hash support for `std::chrono::year` + + + +## Literals + + + + Defined in inline namespace `std::literals::chrono_literals` + + + + `operator""y` + + a `std::chrono::year` literal representing a particular year + + diff --git a/src/content/docs/cpp/library/chrono/year/_meta.yml b/src/content/docs/cpp/library/chrono/year/_meta.yml new file mode 100644 index 00000000..a544ae12 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/_meta.yml @@ -0,0 +1 @@ +label: std::chrono::year \ No newline at end of file diff --git a/src/content/docs/cpp/library/chrono/year/formatter.mdx b/src/content/docs/cpp/library/chrono/year/formatter.mdx new file mode 100644 index 00000000..54d40036 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/formatter.mdx @@ -0,0 +1,41 @@ +--- +title: std::formatter +cppdoc: + keys: ["cpp.chrono.year.formatter"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT > + struct formatter; + ``` + + + + Specialization of `std::formatter` that defines formatting rules for a `std::chrono::year`. + + The `std::formatter` specialization is usually not directly accessed, but is used through formatting functions. + + +## See also + + + + + `std::format` + + stores formatted representation of the arguments in a new string + + diff --git a/src/content/docs/cpp/library/chrono/year/from_stream.mdx b/src/content/docs/cpp/library/chrono/year/from_stream.mdx new file mode 100644 index 00000000..b0ebdf1a --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/from_stream.mdx @@ -0,0 +1,43 @@ +--- +title: std::chrono::from_stream (std::chrono::year) +cppdoc: + keys: ["cpp.chrono.year.from_stream"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT, class Traits, class Alloc = std::allocator > + std::basic_istream& + from_stream( std::basic_istream& is, const CharT* fmt, + std::chrono::year& y, + std::basic_string* abbrev = nullptr, + std::chrono::minutes* offset = nullptr ); + ``` + + + + Parses a `year` from the stream `is` according to the format string `fmt`. + + +## See also + + + + + `std::chrono::parse` + + parses a `chrono` object from a stream + + diff --git a/src/content/docs/cpp/library/chrono/year/hash.mdx b/src/content/docs/cpp/library/chrono/year/hash.mdx new file mode 100644 index 00000000..c1beb829 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/hash.mdx @@ -0,0 +1,30 @@ +--- +title: std::hash +cppdoc: + keys: ["cpp.chrono.year.hash"] + revision: + since: C++26 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template<> + struct std::hash; + ``` + + + + The template specialization of `std::hash` for `std::chrono::year` allows users to obtain hashes of objects of type `std::chrono::year`. + + The specialization is enabled, and `operator()` of this specialization is `noexcept`. + diff --git a/src/content/docs/cpp/library/chrono/year/is_leap.mdx b/src/content/docs/cpp/library/chrono/year/is_leap.mdx new file mode 100644 index 00000000..753d300d --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/is_leap.mdx @@ -0,0 +1,62 @@ +--- +title: std::chrono::year::is_leap +cppdoc: + keys: ["cpp.chrono.year.is_leap"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr bool is_leap() const noexcept; + ``` + + + + 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. + + +## Return value + +`true` if `*this` represents a leap year, otherwise `false`. + +## Example + +```cpp +#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"; + } +} +``` + +**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/src/content/docs/cpp/library/chrono/year/max.mdx b/src/content/docs/cpp/library/chrono/year/max.mdx new file mode 100644 index 00000000..8d18c949 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/max.mdx @@ -0,0 +1,47 @@ +--- +title: std::chrono::year::max +cppdoc: + keys: ["cpp.chrono.year.max"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + static constexpr year max() noexcept; + ``` + + + + Returns the largest possible `year`, that is, `std::chrono::year(32767)`. + + +## Return value + +`std::chrono::year(32767)` + +## Example + +```cpp +#include +#include + +int main() +{ + std::cout << "The maximum year is: " << (int)std::chrono::year::max() << '\n'; +} +``` + +**Output:** + +``` +The maximum year is: 32767 +``` diff --git a/src/content/docs/cpp/library/chrono/year/min.mdx b/src/content/docs/cpp/library/chrono/year/min.mdx new file mode 100644 index 00000000..7603262d --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/min.mdx @@ -0,0 +1,47 @@ +--- +title: std::chrono::year::min +cppdoc: + keys: ["cpp.chrono.year.min"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + static constexpr std::chrono::year min() noexcept; + ``` + + + + Returns the smallest possible `year`, that is, `std::chrono::year(-32767)`. + + +## Return value + +`std::chrono::year(-32767)` + +## Example + +```cpp +#include +#include + +int main() +{ + std::cout << "The minimum year is: " << (int)std::chrono::year::min() << '\n'; +} +``` + +**Output:** + +``` +The minimum year is: -32767 +``` diff --git a/src/content/docs/cpp/library/chrono/year/ok.mdx b/src/content/docs/cpp/library/chrono/year/ok.mdx new file mode 100644 index 00000000..1874e12a --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/ok.mdx @@ -0,0 +1,76 @@ +--- +title: std::chrono::year::ok +cppdoc: + keys: ["cpp.chrono.year.ok"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr bool ok() const noexcept; + ``` + + + + Checks if the year value stored in `*this` is in the valid range, i.e., \[-32767, 32767\]. + + +## Return value + +`true` if the year value stored in `*this` is in the range \[-32767, 32767\]. Otherwise `false`. + +## Possible implementation + +```cpp +class Year +{ + short year_; // exposition-only + +public: + + bool ok() const noexcept { return year_ != std::numeric_limits::min(); } + + /*...*/ +}; +``` + +## Example + +```cpp +#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'; + } +} +``` + +**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/src/content/docs/cpp/library/chrono/year/operator_arith.mdx b/src/content/docs/cpp/library/chrono/year/operator_arith.mdx new file mode 100644 index 00000000..cedb00da --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/operator_arith.mdx @@ -0,0 +1,87 @@ +--- +title: std::chrono::year::operator+=, operator-= +cppdoc: + keys: ["cpp.chrono.year.operator_arith"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::year& operator+=( const std::chrono::years& y ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::year& operator-=( const std::chrono::years& y ) noexcept; + ``` + + + + Adds or subtracts `y.count()` years from the year value. + + 1. Equivalent to `*this = *this + y;`. + 2. Equivalent to `*this = *this - y;`. + + +## Return value + +A reference to this `year` after modification. + +## Notes + +If the result would be outside the range \[-32767, 32767\], the actual stored value is unspecified. + +## Example + +```cpp +#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'; +} +``` + +**Output:** + +``` +true true +``` + +## See also + + + + + `operator++` / `operator--` + + increments or decrements the year + + + + `operator+` / `operator-` + + performs arithmetic on `year`s + + diff --git a/src/content/docs/cpp/library/chrono/year/operator_arith_2.mdx b/src/content/docs/cpp/library/chrono/year/operator_arith_2.mdx new file mode 100644 index 00000000..1da9648e --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/operator_arith_2.mdx @@ -0,0 +1,105 @@ +--- +title: operator+, operator- (std::chrono::year) +cppdoc: + keys: ["cpp.chrono.year.operator_arith_2"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::year operator+( const std::chrono::year& y, + const std::chrono::years& ys ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::year operator+( const std::chrono::years& ys, + const std::chrono::year& y ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::year operator-( const std::chrono::year& y, + const std::chrono::years& ys ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::years operator-( const std::chrono::year& y1, + 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`. + + +## 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))` + +## 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(1)`, which represents 365.2425 days, not 365 days. + +## Example + +```cpp +#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)); +} +``` + +## See also + + + + + `operator++` / `operator--` + + increments or decrements the month + + + + `operator+=` / `operator-=` + + adds or subtracts a number of months + + diff --git a/src/content/docs/cpp/library/chrono/year/operator_cmp.mdx b/src/content/docs/cpp/library/chrono/year/operator_cmp.mdx new file mode 100644 index 00000000..d17c448c --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/operator_cmp.mdx @@ -0,0 +1,69 @@ +--- +title: operator==, <=> (std::chrono::year) +cppdoc: + keys: ["cpp.chrono.year.operator_cmp"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + constexpr bool operator==( const std::chrono::year& x, + const std::chrono::year& y ) noexcept; + ``` + + + + + ```cpp + constexpr std::strong_ordering operator<=>( const std::chrono::year& x, + 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. + + +## Return value + +1) `int(x) == int(y)` +2) `int(x) <=> int(y)` + +## Example + +```cpp +#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)); +} +``` + +**Output:** + +``` +true +``` diff --git a/src/content/docs/cpp/library/chrono/year/operator_inc_dec.mdx b/src/content/docs/cpp/library/chrono/year/operator_inc_dec.mdx new file mode 100644 index 00000000..30cec62a --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/operator_inc_dec.mdx @@ -0,0 +1,107 @@ +--- +title: std::chrono::year::operator++, operator-- +cppdoc: + keys: ["cpp.chrono.year.operator_inc_dec"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::year& operator++() noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::year operator++( int ) noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::year& operator--() noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::year operator--( int ) noexcept; + ``` + + + + Adds or subtracts 1 from the year value. + + 1,2) Performs `*this += std::chrono::years{1};`. + 3,4) Performs `*this -= std::chrono::years{1};`. + + +## Parameters + +(none) + +## Return value + +1,3) A reference to this `year` after modification. +2,4) A copy of the `year` made before modification. + +## Notes + +If the result would be outside the range \[-32767, 32767\], the actual stored value is unspecified. + +## Example + +```cpp +#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'; +} +``` + +**Possible output:** + +``` +true true +-32768 +``` + +## See also + + + + + `operator+=` / `operator-=` + + adds or subtracts a number of years + + + + `operator+` / `operator-` + + performs arithmetic on `year`s + + diff --git a/src/content/docs/cpp/library/chrono/year/operator_int.mdx b/src/content/docs/cpp/library/chrono/year/operator_int.mdx new file mode 100644 index 00000000..8330c6a5 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/operator_int.mdx @@ -0,0 +1,54 @@ +--- +title: std::chrono::year::operator int +cppdoc: + keys: ["cpp.chrono.year.operator_int"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr explicit operator int() const noexcept; + ``` + + + + Returns the year value stored in `*this`. + + +## Return value + +The year value stored in `*this`. + +## Example + +```cpp +#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'; +} +``` + +**Possible output:** + +``` +The year is: 2020 +This year is: 2023 +``` diff --git a/src/content/docs/cpp/library/chrono/year/operator_ltlt.mdx b/src/content/docs/cpp/library/chrono/year/operator_ltlt.mdx new file mode 100644 index 00000000..43fc97e4 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/operator_ltlt.mdx @@ -0,0 +1,83 @@ +--- +title: operator<< (std::chrono::year) +cppdoc: + keys: ["cpp.chrono.year.operator_ltlt"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template< class CharT, class Traits > + std::basic_ostream& + 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 + + ```cpp + 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`. + + +## Return value + +`os` + +## Example + +```cpp +#include +#include + +int main() +{ + constexpr std::chrono::year y1{2020}, y2{-020}, y3{98304}; + std::cout << y1 << '\n' + << y2 << '\n' + << y3 << '\n'; +} +``` + +**Possible output:** + +``` +2020 +-0016 +-32768 is not a valid year +``` + +## See also + + + + + `std::format` + + stores formatted representation of the arguments in a new string + + + + `std::formatter` + + formatting support for `year` + + diff --git a/src/content/docs/cpp/library/chrono/year/operator_sign.mdx b/src/content/docs/cpp/library/chrono/year/operator_sign.mdx new file mode 100644 index 00000000..0fb90459 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/operator_sign.mdx @@ -0,0 +1,60 @@ +--- +title: std::chrono::year::operator+, operator- +cppdoc: + keys: ["cpp.chrono.year.operator_sign"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + constexpr std::chrono::year operator+() noexcept; + ``` + + + + + ```cpp + constexpr std::chrono::year operator-() noexcept; + ``` + + + + 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`. + + +## Return value + +1) `*this` +2) `std::chrono::year(-int(*this))` + +## Example + +```cpp +#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'; +} +``` + +**Output:** + +``` +The year 2020 negated is -2020 +``` diff --git a/src/content/docs/cpp/library/chrono/year/year.mdx b/src/content/docs/cpp/library/chrono/year/year.mdx new file mode 100644 index 00000000..2370d1af --- /dev/null +++ b/src/content/docs/cpp/library/chrono/year/year.mdx @@ -0,0 +1,67 @@ +--- +title: std::chrono::year::year +cppdoc: + keys: ["cpp.chrono.year.year"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + + + + + ```cpp + year() = default; + ``` + + + + + ```cpp + constexpr explicit year( int y ) noexcept; + ``` + + + + 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. + + +## Example + +```cpp +#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"; +} +``` + +**Output:** + +``` +There are 15891 leap years in the range [-32767, 32767]. +``` diff --git a/src/content/docs/cpp/library/chrono/zoned_traits.mdx b/src/content/docs/cpp/library/chrono/zoned_traits.mdx new file mode 100644 index 00000000..0dc6ce42 --- /dev/null +++ b/src/content/docs/cpp/library/chrono/zoned_traits.mdx @@ -0,0 +1,81 @@ +--- +title: std::chrono::zoned_traits +cppdoc: + keys: ["cpp.chrono.zoned_traits"] + revision: + since: C++20 +--- + +import { CppHeader } from "@components/header"; +import { Decl, DeclDoc } from "@components/decl-doc"; +import { Desc, DescList } from "@components/desc-list"; +import Missing from "@components/Missing.astro"; +import { Revision, RevisionBlock } from "@components/revision"; + +Defined in header . + + + + + ```cpp + template < class TimeZonePtr > + struct zoned_traits { }; + ``` + + + + Primary template is empty. + + + + + + ```cpp + template <> + 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. + + +## Member functions + +### std::chrono::zoned_traits\::default_zone + + + + + ```cpp + static const std::chrono::time_zone* default_zone(); + ``` + + + + Returns a time zone pointer for the default time zone (UTC). + + +#### Return value + +`std::chrono::locate_zone("UTC")`. + +### std::chrono::zoned_traits\::locate_zone + + + + + ```cpp + static const std::chrono::time_zone* locate_zone(std::string_view name); + ``` + + + + Returns the time zone pointer for the time zone designated by `name`. + + +#### Return value + +`std::chrono::locate_zone(name)`.