diff --git a/docs/cpp/void-cpp.md b/docs/cpp/void-cpp.md index b9a5cbeae78..9d991fdb273 100644 --- a/docs/cpp/void-cpp.md +++ b/docs/cpp/void-cpp.md @@ -1,20 +1,20 @@ --- description: "Learn more about: void (C++)" title: "void (C++)" -ms.date: "11/04/2016" +ms.date: 10/15/2021 f1_keywords: ["void_cpp"] helpviewer_keywords: ["void keyword [C++]", "functions [C++], void", "pointers, void"] ms.assetid: d203edba-38e6-4056-8b89-011437351057 --- # void (C++) -When used as a function return type, the **`void`** keyword specifies that the function does not return a value. When used for a function's parameter list, **`void`** specifies that the function takes no parameters. When used in the declaration of a pointer, **`void`** specifies that the pointer is "universal." +When used as a function return type, the **`void`** keyword specifies that the function doesn't return a value. When used for a function's parameter list, **`void`** specifies that the function takes no parameters. When used in the declaration of a pointer, **`void`** specifies that the pointer is "universal." -If a pointer's type is **void\***, the pointer can point to any variable that is not declared with the **`const`** or **`volatile`** keyword. A **void\*** pointer cannot be dereferenced unless it is cast to another type. A **void\*** pointer can be converted into any other type of data pointer. +If a pointer's type is `void*`, the pointer can point to any variable that's not declared with the **`const`** or **`volatile`** keyword. A `void*` pointer can't be dereferenced unless it's cast to another type. A `void*` pointer can be converted into any other type of data pointer. -A **`void`** pointer can point to a function, but not to a class member in C++. +In C++, a **`void`** pointer can point to a free function (a function that's not a member of a class), or to a static member function, but not to a non-static member function. -You cannot declare a variable of type **`void`**. +You can't declare a variable of type **`void`**. ## Example @@ -32,5 +32,5 @@ int main() { ## See also -[Keywords](../cpp/keywords-cpp.md)
+[Keywords](../cpp/keywords-cpp.md)\ [Built-in types](../cpp/fundamental-types-cpp.md) diff --git a/docs/mfc/codesnippet/CPP/cfindreplacedialog-class_5.cpp b/docs/mfc/codesnippet/CPP/cfindreplacedialog-class_5.cpp index 26178006389..e10e6c27fe2 100644 --- a/docs/mfc/codesnippet/CPP/cfindreplacedialog-class_5.cpp +++ b/docs/mfc/codesnippet/CPP/cfindreplacedialog-class_5.cpp @@ -20,8 +20,6 @@ LRESULT CMyRichEditView::OnFindReplace(WPARAM wparam, LPARAM lparam) _T("FindString"), csFindString)); VERIFY(AfxGetApp()->WriteProfileString(AfxGetApp()->m_pszAppName, _T("ReplaceString"), csReplaceString)); - - VERIFY(pDlg->DestroyWindow()); } } diff --git a/docs/mfc/reference/cfindreplacedialog-class.md b/docs/mfc/reference/cfindreplacedialog-class.md index 9594abe4fb0..4b105896919 100644 --- a/docs/mfc/reference/cfindreplacedialog-class.md +++ b/docs/mfc/reference/cfindreplacedialog-class.md @@ -239,10 +239,6 @@ BOOL IsTerminating() const; Nonzero if the user has decided to terminate the dialog box; otherwise 0. -### Remarks - -If this function returns nonzero, you should call the `DestroyWindow` member function of the current dialog box and set any dialog box pointer variable to NULL. Optionally, you can also store the find/replace text last entered and use it to initialize the next find/replace dialog box. - ### Example See the example for [CFindReplaceDialog::GetFindString](#getfindstring). diff --git a/docs/standard-library/choose-enum.md b/docs/standard-library/choose-enum.md index f871988cba5..c0306545e37 100644 --- a/docs/standard-library/choose-enum.md +++ b/docs/standard-library/choose-enum.md @@ -38,7 +38,7 @@ If a `local_time` specifies a time during this "extra" hour, it isn't clear how **Nonexistent conversion error** -When converting from standard time to daylight saving time, a different problem can arise. During the transition from standard time to daylight saving time in the spring, clocks move ahead an hour. The skipped hour disappears, so even though it appears that we've added an hour to the time, by "springing forward" an hour, the hour following the transition is effectively removed. +When converting from standard time to daylight saving time, a different problem can arise. During the transition from standard time to daylight saving time in the spring, clocks move ahead an hour. The skipped hour disappears, so even though it appears we've added an hour to the time, by "springing forward" an hour, the hour following the transition is effectively removed. Consider the change to daylight saving time in New York, which happens on the second Sunday in March at 2am. At 2am, the clock transitions to daylight savings time and now reads 3:00am. If the `local_time` being converted is 2:30am, for example, that time is during the period that was "removed" and so is "nonexistent", resulting in a [`nonexistent_local_time`](nonexistent-local-time.md#example-nonexistent_local_time) exception. diff --git a/docs/standard-library/chrono-functions.md b/docs/standard-library/chrono-functions.md index 2d98a313ea3..52f3dcb0d5c 100644 --- a/docs/standard-library/chrono-functions.md +++ b/docs/standard-library/chrono-functions.md @@ -1,9 +1,9 @@ --- description: "Learn more about: functions" title: " functions" -ms.date: 10/06/2021 -f1_keywords: ["chrono/std::duration_cast", "chrono/std::time_point_cast", "chrono/std::chrono::duration_cast", "chrono/std::chrono::time_point_cast", "chrono/std::chrono::from_stream", "chrono/std::chrono::abs", "chrono/std::chrono::floor", "chrono/std::chrono::ceil", "chrono/std::chrono::round", "chrono/std::chrono::is_am", "chrono/std::chrono::is_pm", "chrono/std::chrono::make12", "chrono/std::chrono::make24", "chrono/std::chrono::get_leap_second_info", "chrono/std::chrono::get_tzdb", "chrono/std::chrono::get_tzdb_list", "chrono/std::chrono::locate_zone", "chrono/std::chrono::current_zone", "chrono/std::chrono::reload_tzdb", "chrono/std::chrono::remote_version"] -helpviewer_keywords: ["std::duration_cast function", "std::time_point_cast function", "std::chrono::duration_cast function", "std::chrono::time_point_cast function", "std::chrono::from_stream function", "std::chrono::floor function", "std::chrono::ceil function", "std::chrono::round function", "std::chrono::is_am function", "std::chrono::is_pm function", "std::chrono::make12 function", "std::chrono::make24 function", "std::chrono::get_leap_second_info function", "std::chrono::get_tzdb function", "std::chrono::get_tzdb_list function", "std::chrono::locate_zone function", "std::chrono::current_zone function", "std::chrono::reload_tzdb function", "std::chrono::remote_version function"] +ms.date: 10/15/2021 +f1_keywords: ["chrono/std::duration_cast", "chrono/std::time_point_cast", "chrono/std::chrono::clock_cast", "chrono/std::chrono::duration_cast", "chrono/std::chrono::time_point_cast", "chrono/std::chrono::from_stream", "chrono/std::chrono::abs", "chrono/std::chrono::floor", "chrono/std::chrono::ceil", "chrono/std::chrono::round", "chrono/std::chrono::is_am", "chrono/std::chrono::is_pm", "chrono/std::chrono::make12", "chrono/std::chrono::make24", "chrono/std::chrono::get_leap_second_info", "chrono/std::chrono::get_tzdb", "chrono/std::chrono::get_tzdb_list", "chrono/std::chrono::locate_zone", "chrono/std::chrono::current_zone", "chrono/std::chrono::reload_tzdb", "chrono/std::chrono::remote_version"] +helpviewer_keywords: ["std::duration_cast function", "std::time_point_cast function", "std::chrono::clock_cast", "std::chrono::duration_cast function", "std::chrono::time_point_cast function", "std::chrono::from_stream function", "std::chrono::floor function", "std::chrono::ceil function", "std::chrono::round function", "std::chrono::is_am function", "std::chrono::is_pm function", "std::chrono::make12 function", "std::chrono::make24 function", "std::chrono::get_leap_second_info function", "std::chrono::get_tzdb function", "std::chrono::get_tzdb_list function", "std::chrono::locate_zone function", "std::chrono::current_zone function", "std::chrono::reload_tzdb function", "std::chrono::remote_version function"] --- # `` functions @@ -120,6 +120,83 @@ Returns the smallest time point representable using `ToDuration` that's greater `ceil` doesn't participate in overload resolution unless the `ToDuration` type is an instance of a [`duration`](../standard-library/duration-class.md). +## `clock_cast` + +Converts a [`time_point`](time-point-class.md) for one clock to an equivalent `time_point` for another clock. + +### Syntax + +```cpp +template +auto clock_cast(const time_point& t); // C++ 20 +``` + +### Parameters + +*`DestClock`*\ +The clock type to convert the `time_point` to. + +*`Duration`*\ +The [`duration`](duration-class.md) of the `SourceClock`, or one that you specify. + +*`SourceClock`*\ +The clock type that the `time_point` to convert is based on. + +*`t`*\ +The `time_point` to convert. + +### Return value + +A [`time_point`](time-point-class.md) equivalent to **`t`**, but specific to `DestClock`. + +### Remarks + +The parameters `SourceClock` and `Duration` can be inferred via class template argument deduction when not explicitly passed. For example, given `clock_cast(file_clock::now())`, `SourceClock` is deduced to be `file_clock`, and `Duration` is deduced to be `file_clock::duration`. + +From the following list of well-formed clock conversions, the one that requires the fewest conversion steps to get from the `SourceClock` to the `DestClock` is selected. + +```cpp +clock_time_conversion{}(t) + +clock_time_conversion{}( + clock_time_conversion{}(t)) + +clock_time_conversion{}( + clock_time_conversion{}(t)) + +clock_time_conversion{}( + clock_time_conversion{}( + clock_time_conversion{}(t))) + +clock_time_conversion{}( + clock_time_conversion{}( + clock_time_conversion{}(t))) +``` + +For more information about what `clock_time_conversion` does, see [`clock_time_conversion` struct](clock-time-conversion-struct.md). + +### Example `clock_cast` + +```cpp +// compile using: /std:c++latest +#include +#include + +using namespace std::chrono; + +int main() +{ + utc_clock::time_point t = clock_cast(file_clock::now()); + std::cout << t; + + return 0; +} +``` + +```output +2021-10-11 22:58:17.8540720 +``` + ## `current_zone` Gets the current time zone object. diff --git a/docs/standard-library/chrono.md b/docs/standard-library/chrono.md index ad124958be7..26b5c0e8300 100644 --- a/docs/standard-library/chrono.md +++ b/docs/standard-library/chrono.md @@ -1,7 +1,7 @@ --- description: "Learn more about: " title: "" -ms.date: 09/30/2021 +ms.date: 10/13/2021 f1_keywords: ["", "chrono/std::chrono::nanoseconds", "chrono/std::chrono::minutes", "chrono/std::chrono::seconds", "chrono/std::chrono::hours", "chrono/std::chrono::milliseconds", "chrono/std::chrono::microseconds"] --- @@ -70,7 +70,10 @@ In the Microsoft C++ implementation, `steady_clock::time_point` is now a `typede | [`sys_info`](sys-info-struct.md) | Provides a low-level interface to time zone information about the result of converting a `sys_time` to a `local_time`. | | [`time_zone` class](time-zone-class.md) | All time zone transitions for a specific geographic area. | | [`time_zone_link` class](time-zone-link-class.md) | An alternative name for a `time_zone`. | +| [`tzdb` struct](tzdb-struct.md) | Represents a copy of the time zone database. | +| [`tzdb_list` class](tzdb-list-class.md) | A singleton list of time zone databases. | | [`zoned_time` class](zoned-time-class.md) | A pairing of a [`time_zone`](time-zone-class.md) and a [`time_point`](time-point-class.md) with a specified precision. | +| [`zoned_traits` struct](zoned-traits-struct.md) | Used to associate a different default time zone with a `zoned_time`, and optionally map a custom name to that default time zone. | **Exceptions** @@ -85,6 +88,7 @@ In the Microsoft C++ implementation, `steady_clock::time_point` is now a `typede |--|--| | [`ceil(duration)`](chrono-functions.md#std-chrono-ceil-duration) | Returns the `ceil` of a `duration` object as a specified type. | | [`ceil(time_point)`](chrono-functions.md#std-chrono-ceil-time-point) | Returns the `ceil` of a `time_point` object as a specified type. | +| [`clock_cast`](chrono-functions.md#std-chrono-clock-cast) | Converts a [`time_point`](time-point-class.md) from one clock to an equivalent `time_point` for another clock. | | [`duration_cast`](chrono-functions.md#std-chrono-duration-cast) | Casts a `duration` object to a specified type. | | [`floor(duration)`](chrono-functions.md#std-chrono-floor-duration) | Returns the `floor` of a `duration` object as a specified type. | | [`floor(time_point)`](chrono-functions.md#std-chrono-floor-time-point) | Returns the `floor` of a `time_point` object as a specified type. | @@ -104,8 +108,8 @@ In the Microsoft C++ implementation, `steady_clock::time_point` is now a `typede | Name | Description | |--|--| | [`current_zone`](chrono-functions.md#std-chrono-current-zone) | Gets the current time zone. | -| [`get_tzdb_list`](chrono-functions.md#std-chrono-get-tzdb-list) | Gets the list of time zone database entries. | | [`get_tzdb`](chrono-functions.md#std-chrono-get-tzdb) | Gets the first time zone database entry. | +| [`get_tzdb_list`](chrono-functions.md#std-chrono-get-tzdb-list) | Gets the list of time zone database entries. | | [`reload_tzdb`](chrono-functions.md#std-chrono-reload-tzdb) | Gets an updated time zone database entry. | | [`remote_version`](chrono-functions.md#std-chrono-remote-version) | Checks for an updated time zone database entry. | @@ -163,6 +167,7 @@ For more information about ratio types that are used in the following typedefs, | Name | Description | |--|--| +| [`clock_time_conversion`](clock-time-conversion-struct.md) | A trait that specifies how to convert a [`time_point`](time-point-class.md) from one clock to another. | | [is_clock](is-clock-struct.md) | Check if a type is a clock. | | [treat_as_floating_point](treat-as-floating-point-structure.md) | Check if a `duration` can be converted to another `duration` that has a different tick period. | @@ -185,7 +190,7 @@ For more information about ratio types that are used in the following typedefs, | `nanoseconds operator "" ns(unsigned long long Val)` | Specifies nanoseconds as an integral value. | | `duration operator "" ns(long double Val)` | Specifies nanoseconds as a floating-point value. | -The following examples show how to use `` literals. +The following examples show how to use `` literals: ```cpp constexpr auto day = 24h; diff --git a/docs/standard-library/clock-time-conversion-struct.md b/docs/standard-library/clock-time-conversion-struct.md new file mode 100644 index 00000000000..ac13ace42c9 --- /dev/null +++ b/docs/standard-library/clock-time-conversion-struct.md @@ -0,0 +1,157 @@ +--- +description: "Learn more about clock_conversion trait" +title: "clock_conversion struct" +ms.date: 10/12/2021 +f1_keywords: ["chrono/std::clock_conversion"] +helpviewer_keywords: ["std::chrono [C++], clock_conversion"] +--- + +# `clock_time_conversion` struct + +A trait that specifies how to convert a [`time_point`](time-point-class.md) from one type of clock to another, while maintaining the equivalent point in time. + +## Syntax + +```cpp +// C++20 +1) template struct clock_time_conversion {}; +2) template struct clock_time_conversion; +3) template<> struct clock_time_conversion; +4) template<> struct clock_time_conversion; +5) template<> struct clock_time_conversion; +6) template<> struct clock_time_conversion; +7) template struct clock_time_conversion; +8) template struct clock_time_conversion; +9) template struct clock_time_conversion; +10) template struct clock_time_conversion; +``` + +### Template parameters + +*`Clock`*\ +A clock type to convert from/to. + +*`Dest`*\ +The clock type to convert to. + +*`Source`*\ +The clock type to convert from. + +The traits provide the following conversions: + +1\) An empty struct that is defined only so that it can be specialized.\ +2-4\) Identity conversions. Returns the same clock you pass in.\ +5-6\) Converting between `sys_time` and `utc_time` calls `utc_clock::to_sys` or `utc_clock::from_sys` depending on the direction of the conversion.\ +7-8\) Converting between `sys_time` and the specified clock, when the specified clock supports `to_sys` and `from_sys`, results in a call to `Clock::to_sys` or `Clock::from_sys`, depending on the direction of the conversion.\ +9-10\) Converting between `utc_time`and the specified clock, when the specified clock supports `from_utc` and `to_sys`, results in a call to `Clock::to_utc` or `Clock::from_utc`, depending on the direction of the conversion. + +## Members + +|Name|Description| +|----------|-----------------| +| [`operator ()`](#op_parens) | Converts a `time_point` from one clock to another. | + +## Remarks + +You usually won't use this trait directly in your code. It's used by the [`clock_cast`](chrono-functions.md#std-chrono-clock-cast) conversion function. + +## Requirements + +**Header:** \<`chrono`> + +**Namespace:** `std` + +**Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) + +## `operator()` + +Converts a `time_point` from one clock type to another while maintaining the equivalent point in time. + +### Syntax + +```cpp +1) +template +time_point operator()(const time_point& t) const; + +2) +template +sys_time operator()(const sys_time & t) const; + +3) +template +utc_time operator()(const utc_time& t) const; + +4) +template +sys_time operator()(const utc_time& t) const; + +5) +template +utc_time operator()(const sys_time& t) const; +``` + +### Parameters + +**`t`** +The `time_point` to convert. + +### Return value + +1-3\) Identity conversions. No conversion. Returns `t` without any changes.\ +4\) Returns `utc_clock::to_sys(t)`.\ +5\) Returns` utc_clock::from_sys(t)`. + +### Deduction guides + +The following deduction guides are provided for `template operator()`: + +```cpp +1) +template auto operator()(const sys_time& t) const + -> decltype(Clock::from_sys(t)); + +2) +template auto operator()(const time_point& t) const + -> decltype(Clock::to_sys(t)); + +3) +template auto operator()(const utc_time& t) const + -> decltype(Clock::from_utc(t)); + +4) +template auto operator()(const time_point& t) const + -> decltype(Clock::to_utc(t)); +``` + +1\) Participates in overload resolution only when `Clock` supports `from_sys()` and returns `time_point`.\ +2\) Participates in overload resolution only when `Clock` supports `to_sys()` and returns `sys_time`.\ +3\) Participates in overload resolution only when `Clock` supports `from_utc()` and returns `time_point`.\ +4\) Participates in overload resolution only when `Clock` supports `to_utc()` and returns `utc_time`. + +## Example: `clock_time_conversion` + +```cpp +#include +#include + +using namespace std::chrono; + +int main() +{ + auto sd = sys_days{ 2021y / July / 26 }; + auto time = clock_time_conversion{}(sd); + std::cout << time << "\n"; + return 0; +} +``` + +```output +2021-07-26 00:00:00 +``` + +## See also + +[``](chrono.md)\ +[`clock_cast`](chrono-functions.md#std-chrono-clock-cast)\ +[Header Files Reference](cpp-standard-library-header-files.md) diff --git a/docs/standard-library/day-class.md b/docs/standard-library/day-class.md index 28b6a50c98c..26120059e64 100644 --- a/docs/standard-library/day-class.md +++ b/docs/standard-library/day-class.md @@ -12,7 +12,7 @@ Represents a day of the month. For example, the 25th day of the month. ## Syntax ```cpp -class day; // c++ 20 +class day; // C++ 20 ``` ## Remarks diff --git a/docs/standard-library/duration-class.md b/docs/standard-library/duration-class.md index c78c38abc29..c84e5572e17 100644 --- a/docs/standard-library/duration-class.md +++ b/docs/standard-library/duration-class.md @@ -1,14 +1,16 @@ --- description: "Learn more about: duration Class" title: "duration Class" -ms.date: 10/07/2021 +ms.date: 10/12/2021 f1_keywords: ["chrono/std::chrono::duration", "chrono/std::chrono::duration::duration", "chrono/std::chrono::duration::count", "chrono/std::chrono::duration::max", "chrono/std::chrono::duration::min", "chrono/std::chrono::duration::zero"] helpviewer_keywords: ["std::chrono [C++], duration"] --- # `duration` class -Describes a type that holds a *time interval*, which is the number of ticks over a time unit. For example, five minutes is five ticks, with each tick a minute apart. 42 seconds is 42 ticks, with each tick a second apart. +Measures a time span such as one minute, two hours, ten milliseconds, and so on. + +A `duration` holds a *time interval*, which is the number of ticks over a time unit. For example, five minutes is five ticks, with each tick a minute apart. 42 seconds is 42 ticks, with each tick a second apart. ## Syntax diff --git a/docs/standard-library/local-info-struct.md b/docs/standard-library/local-info-struct.md index 695c19bb3f0..f890d1dd4c7 100644 --- a/docs/standard-library/local-info-struct.md +++ b/docs/standard-library/local-info-struct.md @@ -14,10 +14,6 @@ Provides a low-level interface to time zone information about the result of conv struct local_info; ``` -## Remarks - -Provides a low-level interface to time zone information about the result of converting a `local_time` to a `sys_time`. - ## Members |Function|Description| @@ -56,7 +52,7 @@ The result can be one of the following values: ### Remarks -For information about how `first` and `second` are set based on `result`, see [`first`, `second`](#firstsecond). +For information about how `first` and `second` are set based on `result`, see the following section about [`first`, `second`](#firstsecond). ## `first`, `second` diff --git a/docs/standard-library/toc.yml b/docs/standard-library/toc.yml index 0a98b5bd8bb..10ef23ae748 100644 --- a/docs/standard-library/toc.yml +++ b/docs/standard-library/toc.yml @@ -152,6 +152,8 @@ href: ambiguous-local-time.md - name: choose enum href: choose-enum.md + - name: clock_time_conversion struct + href: clock-time-conversion-struct.md - name: common_type struct href: common-type-structure.md - name: day class @@ -178,7 +180,7 @@ href: leap-second-info-struct.md - name: local_info struct href: local-info-struct.md - - name: local_t + - name: local_t struct href: local_t.md - name: month class href: month-class.md @@ -208,6 +210,10 @@ href: time-zone-link-class.md - name: treat_as_floating_point struct href: treat-as-floating-point-structure.md + - name: tzdb struct + href: tzdb-struct.md + - name: tzcb_list class + href: tzdb-list-class.md - name: utc_clock class href: utc-clock-class.md - name: weekday class @@ -230,6 +236,8 @@ href: year-month-weekday-last-class.md - name: zoned_time class href: zoned-time-class.md + - name: zoned_traits struct + href: zoned-traits-struct.md - name: href: cinttypes.md - name: diff --git a/docs/standard-library/tzdb-list-class.md b/docs/standard-library/tzdb-list-class.md new file mode 100644 index 00000000000..c980ebaee9b --- /dev/null +++ b/docs/standard-library/tzdb-list-class.md @@ -0,0 +1,119 @@ +--- +description: "Learn more about: tzdb_list class" +title: "tzdb_list struct" +ms.date: 10/13/2021 +f1_keywords: ["chrono/std::chrono::tzdb_list", "chrono/std::chrono::tzdb_list::front", "chrono/std::chrono::tzdb_list::erase_after", "chrono/std::chrono::tzdb_list::begin", "chrono/std::chrono::tzdb_list::cbegin", "chrono/std::chrono::tzdb_list::end", "chrono/std::chrono::tzdb_list::cend"] +--- +# `tzdb_list` class + +A list of time zone databases. + +## Syntax + +```cpp +class tzdb_list; // C++ 20 +``` + +## Remarks + +You can't construct a `tzdb_list`. To get one, call [`get_tzdb_list()`](chrono-functions.md#std-chrono-get-tzdb-list). + +You can't use copy assignment with a `tzdb_list` as `operator=` is deleted. + +`tzdb_list` is a singleton. + +## Member functions + +|Function|Description| +|---------|-------------| +|[`begin`, `cbegin`](#begin)| Get an iterator to the start of the list of `tzdb` objects.| +|[`end`, `cend`](#end)| Get an iterator past the end of the list of `tzdb` objects. | +|[`erase_after`](#erase_after)| Erase the `tzdb` that immediately follows the element pointed to by the passed in iterator.| +|[`front`](#front)| Get the first element in the list of `tzdb` objects. | + +## Member types + +|Member type|Description| +|---------|-------------| +|`class const_iterator` | A constant iterator of type `tzdb`.| + +## `begin`, `cbegin` + +Gets an iterator that points to the start of the list. + +```cpp +const_iterator begin() const noexcept; // C++20 +const_iterator cbegin() const noexcept; // C++20 +``` + +### Return value + +An iterator pointing to the first `tzdb` in the list. + +## `end`, `cend` + +Get an iterator past the end of the list. + +```cpp +const_iterator end() const noexcept; // C++20 +const_iterator cend() const noexcept; // C++20) +``` + +### Return value + +An iterator pointing past the end of the last `tzdb` in the list. + +### Remarks + +Because the returned iterator points past the end of the list, it shouldn't be dereferenced. Instead, use it to compare when you've reached the end of the list. + +## `front` + +Gets the first [`tzdb`](tzdb-struct.md) in the list. + +```cpp +const tzdb& front() const noexcept; // C++20 +``` + +### Return value + +The first time zone database in the list. + +### Remarks + +You can simultaneously call this function and [`reload_tzdb`](chrono-functions.md#std-chrono-reload-tzdb) without risk of a race condition. + +## `erase_after` + +Erase the `tzdb` that follows the element pointed to by the passed-in iterator. + +```cpp +const_iterator erase_after(const_iterator p); +``` + +### Parameters + +*`p`*\ +An iterator that points to the element before the one to erase. + +### Return value + +An iterator following the erased `tzdb`. If there isn't an element following the erased `tzdb`, then `end()` + +### Remarks + +It isn't possible to erase the first element in the list. + +## Requirements + +**Header:** `` + +**Namespace:** `std::chrono` + +**Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) + +## See also + +[``](chrono.md)\ +[`tzdb` struct](tzdb-struct.md)\ +[Header Files Reference](cpp-standard-library-header-files.md) \ No newline at end of file diff --git a/docs/standard-library/tzdb-struct.md b/docs/standard-library/tzdb-struct.md new file mode 100644 index 00000000000..76617218c72 --- /dev/null +++ b/docs/standard-library/tzdb-struct.md @@ -0,0 +1,179 @@ +--- +description: "Learn more about: tzdb struct" +title: "tzdb struct" +ms.date: 10/15/2021 +f1_keywords: ["chrono/std::chrono::tzdb", "chrono/std::chrono::tzdb::leap_seconds", "chrono/std::chrono::tzdb::links", "chrono/std::chrono::tzdb::version", "chrono/std::chrono::tzdb::zones"] +helpviewer_keywords: ["std::chrono [C++], tzdb"] + +--- +# `tzdb` struct + +Represents a copy of the time zone database. + +## Syntax + +```cpp +struct tzdb; // C++ 20 +``` + +## Remarks + +Represents a copy of the IANA (Internet Assigned Numbers Authority) time zone database. The database contains information about each time zone and its history of local time adjustments. For more information about the database, see [Time Zone Database](https://data.iana.org/time-zones/tz-link.html). + +## Members + +|Member|Description| +|---------|-------------| +|`leap_seconds`| A sorted `vector`. A [`leap_second`](leap-second-class.md) provides a history of when leap seconds were added in the past. | +|`links`| A sorted `vector`. A [time_zone_link](time-zone-link-class.md) provides the alternate name for a given time zone. | +|`version`| A `std::string` containing the database version. | +|`zones`| A sorted `vector`. A [`time_zone`](time-zone-class.md) has the full history of time zone rules for a particular area. | + +For an example of how to use these members, see [Example: `leap_seconds`, `links`, `zones`](#example-leap_seconds-links-zones) near the end of this topic. + +## Member functions + +|Name|Description| +|------|------| +| [`current_zone`](#currentzone) | Gets the local time zone. | +| [`locate_zone`](#locatezone) | Gets the specified time zone. | + +## `current_zone` + +Gets the computer's local time zone. + +```cpp +time_zone* current_zone() const; // C++20 +``` + +### Return value + +A pointer to the [`time_zone`](time-zone-class.md) that represents the local time zone of the computer. + +### Example: `current_zone` + +This example demonstrates getting the current time zone. + +```cpp +// compile using: /std:c++latest +#include +#include + +using namespace std::chrono; + +int main() +{ + auto& db = get_tzdb(); + std::cout << "Current zone: " << db.current_zone()->name(); + + return 0; +} +``` + +```output +Current zone: America/Los_Angeles +``` + +## `locate_zone` + +Gets the specified time zone. + +```cpp +const time_zone* locate_zone(string_view name) const; +``` + +### Example: `locate_zone` + +This example demonstrates getting a time zone by name. + +```cpp +// compile using: /std:c++latest +#include +#include + +using namespace std::chrono; + +int main() +{ + auto& db = get_tzdb(); + std::cout << "Locate zone : " << db.locate_zone("America/New_York")->name() << "\n"; + + return 0; +} +``` + +```output +Locate zone : America/New_York +``` + +## Example: `leap_seconds, links, zones` + +This example demonstrates using various `tzdb` data members. + +```cpp +// compile using: /std:c++latest +#include +#include + +using namespace std::chrono; + +int main() +{ + std::cout << "Leap seconds:\n"; + std::for_each(db.leap_seconds.begin(), db.leap_seconds.end(), + [](const leap_second& ls) + { + std::cout << ls.date() << "\n"; + }); + + std::cout << "Links:\n"; + std::for_each(db.links.begin(), db.links.end(), + [](const time_zone_link& l) + { + std::cout << "Name: " << l.name() << "\t\tTarget:" << l.target() << '\n'; + }); + + std::cout << "\nTime Zone descriptions:\n"; + std::for_each(db.zones.begin(), db.zones.end(), + [](const time_zone& z) + { + std::cout << "Zone: " << z.name() << "\n"; + }); + + return 0; +} +``` + +```output +Leap seconds: +1972-07-01 00:00:00 +1973-01-01 00:00:00 +1974-01-01 00:00:00 +... +Links: +Name: ACT Target:Australia/Darwin +Name: AET Target:Australia/Sydney +Name: AGT Target:America/Buenos_Aires +Name: ART Target:Africa/Cairo +... +Time Zone descriptions: +Zone: Africa/Abidjan +Zone: Africa/Accra +Zone: Africa/Addis_Ababa +... +``` + +## Requirements + +**Header:** `` + +**Namespace:** `std::chrono` + +**Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) + +## See also + +[``](chrono.md)\ +[`tzdb_list`](tzdb-list-class.md)\ +[`time_zone_link`](time-zone-link-class.md)\ +[Header Files Reference](cpp-standard-library-header-files.md) \ No newline at end of file diff --git a/docs/standard-library/zoned-time-class.md b/docs/standard-library/zoned-time-class.md index 140917b7634..d20840fdb08 100644 --- a/docs/standard-library/zoned-time-class.md +++ b/docs/standard-library/zoned-time-class.md @@ -1,20 +1,20 @@ --- description: "Learn more about: zoned_time class" title: "zoned_time class" -ms.date: 09/20/2021 +ms.date: 10/11/2021 f1_keywords: ["chrono/std::chrono::zoned_time::get_info", "chrono/std::chrono::zoned_time::get_local_time", "chrono/std::chrono::zoned_time::get_sys_time", "chrono/std::chrono::zoned_time::get_time_zone","chrono/std::chrono::zoned_time:operator=", "chrono/std::chrono::zoned_time:operator local_time", "chrono/std::chrono::zoned_time:operator sys_time"] helpviewer_keywords: ["std::chrono [C++], zoned_time class", "std::chrono::zoned_time::get_info function", "std::chrono::zoned_time::get_local_time function", "std::chrono::zoned_time::get_sys_time function", "std::chrono::zoned_time::get_time_zone function"] --- # `zoned_time` class -A `zoned_time` is a pairing of a [`time_zone`](time-zone-class.md) and a [`time_point`](time-point-class.md). +A `zoned_time` is a pairing of a [`time_zone`](time-zone-class.md) and a [`time_point`](time-point-class.md). It gives a `time_point` meaning within a specific time zone. ## Syntax ```cpp template -class zoned_time ; // Since C++20 +class zoned_time ; // C++20 ``` ## Remarks @@ -47,6 +47,7 @@ Microsoft C++ supports the `zoned_time` class starting in Visual Studio 2019 ver | Name | Description | |--|--| +| `zoned_seconds` | A synonym for `zoned_time;`| | `zoned_time::duration` | A duration measured in seconds. It's a synonym for `common_type_t;` | ## Requirements @@ -101,33 +102,33 @@ A `zoned_time` copied to construct a new `zoned_time`. A [`time_zone`](time-zone-class.md) that is `std::move(z)`'d into the constructed `zoned_time`. *`zt`*\ -A `zoned_time` pointer to a that is `std::move(z)`'d into the constructed `zoned_time`. +A `zoned_time` pointer that is `std::move(zt)`'d into the constructed `zoned_time`. ### Remarks -1) Initializes the time zone with `traits::default_zone()`, and default constructs the time point. -2) The default copy constructor. -3) Initializes the time zone with `std::move(z)`, and default constructs the time point. -4) Initializes the time zone with `traits::default_zone()`, and the time with `st`. -5) Initializes the time zone with `traits::locate_zone(name)` and default constructs the time point. -6) Initializes the time zone with `std::move(z)`, and the time by converting `tp` as though by `z->to_sys(tp)`. -7) Initializes the time zone with `std::move(z)`, and the time as though by `z->to_sys(tp, c)`. See [`choose` enum](choose-enum.md) for how `c` affects the time. -8) Initializes the time zone with `std::move(z)`, and the time with `st`. -9) Equivalent to construction with `{traits::locate_zone(name), tp}`. -10) Equivalent to construction with `{traits::locate_zone(name), tp, c}`. -11) Equivalent to construction with `{traits::locate_zone(name), st}`. -12) Equivalent to construction with `{traits::locate_zone(name), y}`. -13) Equivalent to construction with `{traits::locate_zone(name), y, c}`. The `choose` parameter, `c`, has no effect. -14) Initializes the time zone from `y`'s time zone and time point. -15) Initializes the time zone with `std::move(z)` and the time from `y`'s time point. -16) Equivalent to construction with `{z, y}`. The `choose` parameter, `c`, has no effect. +1\) Initializes the time zone with `traits::default_zone()`, and default constructs the time point.\ +2\) The default copy constructor.\ +3\) Initializes the time zone with `std::move(z)`, and default constructs the time point.\ +4\) Initializes the time zone with `traits::default_zone()`, and the time with `st`.\ +5\) Initializes the time zone with `traits::locate_zone(name)` and default constructs the time point.\ +6\) Initializes the time zone with `std::move(z)`, and the time by converting `tp` as though by `z->to_sys(tp)`.\ +7\) Initializes the time zone with `std::move(z)`, and the time as though by `z->to_sys(tp, c)`. See [`choose` enum](choose-enum.md) for how the parameter `c` affects the outcome.\ +8\) Initializes the time zone with `std::move(z)`, and the time with `st`.\ +9\) Equivalent to construction with `{traits::locate_zone(name), tp}`.\ +10\) Equivalent to construction with `{traits::locate_zone(name), tp, c}`.\ +11\) Equivalent to construction with `{traits::locate_zone(name), st}`.\ +12\) Equivalent to construction with `{traits::locate_zone(name), y}`.\ +13\) Equivalent to construction with `{traits::locate_zone(name), y, c}`. The `choose` parameter, `c`, has no effect.\ +14\) Initializes the time zone from `y`'s time zone and time point.\ +15\) Initializes the time zone with `std::move(z)` and the time from `y`'s time point.\ +16\) Equivalent to construction with `{z, y}`. The `choose` parameter, `c`, has no effect. > [!NOTE] -> `zoned_time` doesn't have a move constructor. Trying to move it results in a copy using the defaulted copy constructor. +> `zoned_time` doesn't have a move constructor. Trying to move it results in a copy using the default copy constructor. -## Example: construct a `zoned_time` +### Example: construct a `zoned_time` -The following shows how to create a `zoned_time` instance for the time zone "Antartica/Casey", on 9/15/2021 at 4:45pm: +The following shows how to create a `zoned_time` instance for the time zone `"Antartica/Casey"`, on 9/15/2021 at 4:45pm: ```cpp // compile using: /std:c++latest @@ -188,7 +189,6 @@ begin: 2020-10-03 16:01:00, end: 32767-12-31 23:59:59, offset: 39600s, save: 0mi Gets a `local_time` that represents the local time given this `zoned_time`'s time zone and time point. - ```cpp local_time get_local_time() const; ``` @@ -221,7 +221,7 @@ int main() ## `get_sys_time` -Gets the time stored in the `zoned_time` in terms of the [`system_clock`](system-clock-structure.md). +Gets the time stored in the `zoned_time` for the [`system_clock`](system-clock-structure.md). ```cpp sys_time get_sys_time() const; @@ -340,9 +340,9 @@ int main() ### Remarks -1) The default copy assignment operator. Copies (doesn't move) the stored [`time_point`](time-point-class.md) and [time_zone](time-zone-class.md) pointer from the other `zoned_time` into this `zoned_time`. -2) Assigns `st` to the [`time_point`](time-point-class.md) in this `zoned_time`. After the assignment, `*this->get_sys_time() == st;` -3) Converts `lt` (a `local_time`) to a `sys_time`. It does this essentially as `timeZone->to_sys(lt)`, and assigns the result to the [`time_point`] in this `zoned_time`. After the assignment, `*this->get_local_time() == lt;` +1\) The default copy assignment operator. Copies (doesn't move) the stored [`time_point`](time-point-class.md) and [time_zone](time-zone-class.md) pointer from the other `zoned_time` into this `zoned_time`. +2\) Assigns `st` to the [`time_point`](time-point-class.md) in this `zoned_time`. After the assignment, `*this->get_sys_time() == st;` +3\) Converts `lt` (a `local_time`) to a `sys_time`. It does this essentially as `timeZone->to_sys(lt)`, and assigns the result to the [`time_point`] in this `zoned_time`. After the assignment, `*this->get_local_time() == lt;` ## `operator local_time` @@ -419,4 +419,5 @@ int main() [``](chrono.md)\ [`time_point`](time-point-class.md)\ [`time_zone`](time-zone-class.md)\ +[`zoned_traits` struct](zoned-traits-struct.md)\ [Header files reference](./cpp-standard-library-header-files.md) \ No newline at end of file diff --git a/docs/standard-library/zoned-traits-struct.md b/docs/standard-library/zoned-traits-struct.md new file mode 100644 index 00000000000..0b64e15f370 --- /dev/null +++ b/docs/standard-library/zoned-traits-struct.md @@ -0,0 +1,157 @@ +--- +description: "Learn more about: zoned_traits struct" +title: "zoned_traits struct" +ms.date: 10/15/2021 +f1_keywords: ["chrono/std::chrono::zoned_traits::get_info", "chrono/std::chrono::zoned_traits::default_zone", "chrono/std::chrono::zoned_traits::locate_zone"] +helpviewer_keywords: ["std::chrono [C++], zoned_traits struct", "std::chrono::zoned_traits::default_zone function", "std::chrono::zoned_traits::locate_zone function"] +--- + +# `zoned_traits` struct + +Allows you to associate a different default time zone with a `zoned_time`, and optionally map a custom name to a time zone. + +## Syntax + +```cpp +1) +template +struct zoned_traits {}; // C++20 + +2) +template <> +struct zoned_traits; // C++20 +``` + +### Parameters + +1\) `T` - A pointer to a type that provides a custom `time_zone`.\ +2\) When you don't provide the `time_zone*` template argument, this specialization provides `const std::chrono::time_zone*`, which defaults to the UTC time zone. + +## Remarks + +The pointer to the type that you supply doesn't have to provide the static functions `default_zone()` or `locate_zone()`. But if it doesn't, the `zoned_time` constructors won't be considered during overload resolution. + +Microsoft C++ supports `zoned_traits` starting in Visual Studio 2019 version 16.10. + +## Members + +|Name|Description| +|-|-| +|[`default_zone`](#default_zone) | Gets the `time_zone` pointer for the default time zone.| +|[`locate_zone`](#locate_zone) | Gets the `time_zone` pointer for the specified time zone. | + +## Requirements + +**Header:** `` + +**Namespace:** `std::chrono` + +**Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) + +## `default_zone` + +Gets the [`time_zone`](time-zone-class.md) for the default time zone. For more information about how this works, see the code [example](#example-zoned_traits) at the end of this topic. + +```cpp +static const time_zone* default_zone(); +``` + +### Return value + +If the template argument isn't provided, then the template specialization provides `zoned_traits`, which returns the UTC time zone. Otherwise, it returns the default time zone provided by the template argument `T`. + +## `locate_zone` + +Returns the [`time_zone`](time-zone-class.md) pointer for the specified time zone. For more information about how this works, see the code [example](#example-zoned_traits) at the end of this topic. + +```cpp +static const time_zone* locate_zone(string_view name); +``` + +### Template parameters + +*`name`*\ +The name of the time zone to locate. For example, `"UTC"`. + +### Return value + +If you constructed a `zoned_traits` without providing the template argument of a custom time zone pointer, then the return value is `std::chrono::locate_zone(name)`. Otherwise, it returns the value of `locate_zone()` as defined in the template argument `T`. + +## Example: `zoned_traits` + +This following example shows how to use `zoned_traits` to supply a custom default time zone. + +First, `CustomTimeZonePtr` is defined, which provides the pointer to the custom time zone type via `operator->()`. + +Then, a `zoned_traits` is declared in which `default_zone` is defined to return the custom default time zone. In this case, the South Pole. + +In the example, `zoned_traits::locate_zone()` passes the specified time zone name to `std::chrono::locate_zone()`. This function is where you could map a custom time zone name to another time zone. + +Finally, `stdZT` is defined, which uses the standard `time_zone` pointer because it doesn't provide a template argument, so the specialization is used that provides `const std::chrono::time_zone*`. + +Run this example to see the `zoned_time` use the custom, and then the standard, `time_zone` pointer. + +```cpp +// compile using: /std:c++latest +#include +#include + +using namespace std::chrono; + +struct CustomTimeZonePtr +{ + CustomTimeZonePtr() {} + CustomTimeZonePtr(const time_zone* tz) : tzptr(tz) {} + + const time_zone* operator->() const + { + return tzptr; + } + +private: + const time_zone* tzptr; +}; + +template <> +struct zoned_traits +{ + static const CustomTimeZonePtr default_zone() + { + return CustomTimeZonePtr{ locate_zone("Antarctica/South_Pole") }; + } + + static const CustomTimeZonePtr locate_zone(std::string_view name) + { + // Here you can provide your own mapping between the name + // parameter and another time zone before passing it to locate_zone() + return CustomTimeZonePtr{ std::chrono::locate_zone(name) }; + } +}; + +int main() +{ + std::cout << "-- Custom time zone pointer with specialized zoned_traits and different default zone behavior --\n"; + zoned_time myZT; + std::cout << myZT.get_info() << "\n"; + + std::cout << "-- Built-in time zone pointer with standard zoned_traits --\n"; + zoned_time stdZT; + std::cout << stdZT.get_info() << "\n"; + + return 0; +} +``` + +```output +-- Custom time zone pointer with specialized zoned_traits and different default zone behavior -- +begin: 1945-12-31 12:00:00, end: 1974-11-02 14:00:00, offset: 43200s, save: 0min, abbrev: GMT+12 +-- Built-in time zone pointer with standard zoned_traits -- +begin: -32767-01-01 00:00:00, end: 32767-12-31 23:59:59, offset: 0s, save: 0min, abbrev: UTC +``` + +## See also + +[``](chrono.md)\ +[`time_zone`](time-zone-class.md)\ +[`zoned_time` class](zoned-time-class.md)\ +[Header files reference](./cpp-standard-library-header-files.md) \ No newline at end of file