Skip to content

Commit be63209

Browse files
TaojunshenTylerMSFTColin Robertsonkylereedmsftweijiechai
authored
10/11/2021 AM Publish (MicrosoftDocs#3828)
* add new classes: ambiguous_local_time & nonexistent_local_time * acrolinx * fix links * finish descriptions * fix more links * smoothing out * proofing * add some better linking * tune description * update descriptions * needed to update local-info-struct.md to reflect changes to descriptions for nonexistent and ambiguous * add chrono functions * rounding out duration links * Add documentation for IntelliSense linter for C++ (MicrosoftDocs#3821) * Add first draft of linter check documentation * WIP overview. Signed-off-by: Kyle Reed <kylereed@microsoft.com> * Update toc. First draft of the linter overview. * Add screenshots, move files, code samples are stand-alone. Signed-off-by: Kyle Reed <kylereed@microsoft.com> * Style and Acrolinx grammar checker pass * Add missing Options cues for checks * Update to use latest option names Co-authored-by: 3836425+corob-msft@users.noreply.github.com <corob@microsoft.com> * connecting duration up to it's non-member pieces and doing some general updates * fix links * cleanup * Split out VS2019 content for linter (#3824) * Update working-with-project-properties.md * cleanup * cleanup * cleanup * cleanup * cleanup * cleanup * cleanup Co-authored-by: TylerMSFT <Tyler.Whitney@microsoft.com> Co-authored-by: Colin Robertson <corob@microsoft.com> Co-authored-by: Kyle Reed <kylereed@microsoft.com> Co-authored-by: Chai Wei Jie <chai_weijie@hotmail.com> Co-authored-by: PRMerger19 <prmrgr19@microsoft.com> Co-authored-by: Laura Brenner <90344170+laurabren@users.noreply.github.com> Co-authored-by: Courtney Wales <62625502+Court72@users.noreply.github.com>
1 parent 589cc8f commit be63209

16 files changed

Lines changed: 609 additions & 177 deletions

‎docs/build/working-with-project-properties.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ Has the syntax `%(name)`. For a file, an item macro applies only to that file—
6666

6767
### User-defined macros
6868

69-
You can create *user-defined macros* to use as variables in project builds. For example, you could create a user-defined macro that provides a value to a custom build step or a custom build tool. A user-defined macro is a name/value pair. In a project file, use the **$(**<em>name</em>**)** notation to access the value.
69+
You can create *user-defined macros* to use as variables in project builds. For example, you could create a user-defined macro that provides a value to a custom build step or a custom build tool. A user-defined macro is a name/value pair. In a project file, use the `$(name)` notation to access the value.
7070

7171
A user-defined macro is stored in a property sheet. If your project does not already contain a property sheet, you can create one by following the steps under [Share or reuse Visual Studio project settings](create-reusable-property-configurations.md).
7272

@@ -78,7 +78,7 @@ A user-defined macro is stored in a property sheet. If your project does not alr
7878

7979
1. In the dialog box, specify a name and value for the macro. Optionally, select the **Set this macro as an environment variable in the build environment** check box.
8080

81-
## <a name="property_editor">Property Editor</a>
81+
## <a name="property_editor"></a> Property Editor
8282

8383
You can use the Property Editor to modify certain string properties and select macros as values. To access the Property Editor, select a property on a property page and then choose the down arrow button on the right. If the drop-down list contains **\<Edit>**, then you can choose it to display the Property Editor for that property.
8484

‎docs/standard-library/ambiguous-local-time.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
description: "Learn more about: ambiguous_local_time class"
3+
title: "ambiguous_local_time class"
4+
ms.date: 10/08/2021
5+
f1_keywords: ["chrono/std::chrono::ambiguous_local_time", "chrono/std::chrono::ambiguous_local_time::what"]
6+
helpviewer_keywords: ["std::chrono [C++], ambiguous_local_time"]
7+
---
8+
9+
# `ambiguous_local_time` class
10+
11+
This exception is thrown when attempting to convert a `local_time` to a `sys_time` and the result can be one of two times and neither `choose::earliest` or `choose::latest` was specified to settle the ambiguity.
12+
13+
## Syntax
14+
15+
```cpp
16+
class ambiguous_local_time : public runtime_error; // C++ 20
17+
```
18+
19+
## Remarks
20+
21+
During the transition from daylight saving time to standard time in the fall, clocks essentially gain an extra hour. This can be confusing because doesn't the transition to standard time mean losing an hour? By falling back an hour, the hour before the transition will be repeated after the clock adjusts for standard time. Consider the change to standard time in New York, which happens on the first Sunday in November at 2:00am. First, 1:00am goes by. At 2am, the clock transitions to standard time, so now it's 1:00am again. That means the time between 1am and 2am will be "repeated", effectively adding an hour.
22+
23+
If a `local_time` specifies a time during this "extra" hour, it isn't clear how to convert it. Should the converted time be treated as the "first" time that hour happens, or the "second"? If the enum [`choose`](choose-enum.md) isn't specified to indicate which it should be, you'll get an [`ambiguous_local_time`](ambiguous-local-time.md) exception.
24+
25+
This problem doesn't exist when converting from standard time to daylight saving time. In that case, a different problem can arise. See [`nonexistent_local_time`](nonexistent-local-time.md) for details.
26+
27+
The following example shows an ambiguous conversion.
28+
29+
## Example: `ambiguous_local_time`
30+
31+
```cpp
32+
#include <chrono>
33+
#include <iostream>
34+
35+
using namespace std::chrono;
36+
37+
int main()
38+
{
39+
try
40+
{
41+
// The following will throw an exception because converting 1:30am local time to system time could be interpreted as either
42+
// 1:30 AM EDT or 1:30 AM EST. Which to choose isn't specified for the conversion, so an ambiguous_local_time
43+
// exception is thrown.
44+
auto zt = zoned_time{"America/New_York", local_days{Sunday[1]/November/2016} + 1h + 30min};
45+
} catch (const ambiguous_local_time& e)
46+
{
47+
std::cout << e.what() << '\n';
48+
}
49+
return 0;
50+
}
51+
```
52+
53+
```output
54+
2016-11-06 01:30:00 is ambiguous. It could be
55+
2016-11-06 01:30:00 EDT == 2016-11-06 05:30:00 UTC or
56+
2016-11-06 01:30:00 EST == 2016-11-06 06:30:00 UTC
57+
```
58+
59+
## Members
60+
61+
|Name|Description|
62+
|----------|-----------------|
63+
| [Constructor](#ctor) | Construct an `ambiguous_local_time`. |
64+
| [`what`](#what) | Gets a string that describes the nature of the ambiguity. |
65+
66+
## Requirements
67+
68+
**Header:** `<chrono>` (since C++20)
69+
70+
**Namespace:** `std::chrono`
71+
72+
**Compiler Option:** [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md)
73+
74+
## <a name="ctor"></a> Constructors
75+
76+
Constructs a `ambiguous_local_time`.
77+
78+
```cpp
79+
template<class Duration>
80+
ambiguous_local_time(const local_time<Duration>& tp, const local_info& i);
81+
```
82+
83+
### Parameters
84+
85+
*`tp`*\
86+
The `local_time` that couldn't be converted.
87+
88+
*`i`*\
89+
Information about the attempted conversion. See [`local_info`](local-info-struct.md) for details.
90+
91+
### Remarks
92+
93+
You typically won't create this exception. It's thrown by functions that convert a `local_time` to a `sys_time`.
94+
95+
## <a name="what"></a> `what`
96+
97+
Gets a string describing the details of the ambiguity.
98+
99+
```cpp
100+
[nodiscard] virtual const char* what() const noexcept;
101+
```
102+
103+
### Return value
104+
105+
A string describing the ambiguity. For example:
106+
107+
```output
108+
2016-11-06 01:30:00 is ambiguous. It could be
109+
2016-11-06 01:30:00 EDT == 2016-11-06 05:30:00 UTC or
110+
2016-11-06 01:30:00 EST == 2016-11-06 06:30:00 UTC
111+
```
112+
113+
## See also
114+
115+
[`<chrono>`](../standard-library/chrono.md)\
116+
[`to_sys` ](month-day-class.md)\
117+
[`nonexistent_local_time`](nonexistent-local-time.md)\
118+
[Header Files Reference](cpp-standard-library-header-files.md)

‎docs/standard-library/choose-enum.md‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
title: "choose enum"
33
description: "enum used to specify how to handle ambiguous or nonexistent local times when resolving a time in a time zone"
4-
ms.date: 09/16/2021
4+
ms.date: 10/08/2021
55
f1_keywords: ["chrono/std::choose"]
66
helpviewer_keywords: ["std::choose"]
77
---
88

99
# `choose` enum
1010

11-
Used with [`time_zone`](time-zone-class.md) and [`zoned_time`](zoned-time-class.md) to indicate how to handle ambiguous or nonexistent local times when resolving a time in a time zone.
11+
Used with [`time_zone`](time-zone-class.md) and [`zoned_time`](zoned-time-class.md) to indicate how to handle an ambiguous or nonexistent `local_time` to `sys_time` conversion.
1212

1313
## Syntax
1414

@@ -23,13 +23,24 @@ enum class choose { // C++ 20
2323
2424
|Element|Description|
2525
|-|-|
26-
| `earliest` | If a time conversion in a time zone is ambiguous or nonexistent, uses the earlier time point. |
27-
| `latest` | If a time conversion in a time zone is ambiguous or nonexistent, uses the later time point. |
26+
| `earliest` | If a time conversion is ambiguous, uses the earlier time point. |
27+
| `latest` | If a time conversion is ambiguous, uses the later time point. |
2828
2929
## Remarks
3030
31-
If a local time doesn't exist for the time zone, `earliest` and `latest` result in the same time point.
32-
When `choose` isn't passed and an ambiguous or nonexistent time results, either the exception `std::chrono::ambiguous_local_time` or `std::chrono::nonexistent_local_time` is thrown, respectively.
31+
If the result of the conversion is a `nonexistent_local_time`, the time in `earliest` and `latest` are the same.
32+
33+
**Ambiguous conversion error**
34+
35+
During the transition from daylight saving time to standard time in the fall, clocks essentially gain an extra hour. This can be confusing because doesn't the transition to standard time mean losing an hour? By falling back an hour, the hour before the transition will be repeated after the clock adjusts for standard time. Consider the change to standard time in New York, which happens on the first Sunday in November at 2:00am. First, 1:00am goes by. At 2am, the clock transitions to standard time, so now it's 1:00am again. That means the time between 1am and 2am will be "repeated", effectively adding an hour.
36+
37+
If a `local_time` specifies a time during this "extra" hour, it isn't clear how to convert it. Should the converted time be treated as the "first" time that hour happens, or the "second"? If the enum [`choose`](choose-enum.md) isn't specified to indicate which it should be, you'll get an `ambiguous_local_time` exception.
38+
39+
**Nonexistent conversion error**
40+
41+
When converting from standard time to daylight saving time, a different problem can arise. In that case, a different problem can arise. During the transition from standard time to daylight saving time in the spring, clocks essentially lose an hour. This can be confusing because doesn't the transition to daylight saving time mean adding an hour?
42+
43+
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.
3344
3445
## Requirements
3546
@@ -41,5 +52,5 @@ Compiler option:[`/std:c++latest`](../build/reference/std-specify-language-stand
4152
4253
## See also
4354
44-
[`time_zone`](time-zone-class.md)\
45-
[`zoned_time`](zoned-time-class.md)
55+
[`to_sys`](time-zone-class.md#std-chrono-time-zone-to-sys)\
56+
[`zoned_time` constructor](zoned-time-class.md#ctor)

‎docs/standard-library/chrono-functions.md‎

Lines changed: 73 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,57 @@
11
---
2-
description: "Learn more about: &lt;chrono&gt; functions"
3-
title: "&lt;chrono&gt; functions"
4-
ms.date: "08/13/2021"
5-
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::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"]
2+
description: "Learn more about: <chrono> functions"
3+
title: "<chrono> functions"
4+
ms.date: 10/06/2021
5+
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"]
66
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"]
77
---
88

99
# `<chrono>` functions
1010

11+
## <a name="std-chrono-abs-duration"></a> `abs(duration)`
12+
13+
Returns `d` if `d >= d.zero()`; otherwise returns `-d`.
14+
15+
### Syntax
16+
17+
```cpp
18+
template <class Rep, class Period>
19+
constexpr duration<Rep, Period> abs(duration<Rep, Period> d ); // C++17
20+
```
21+
22+
### Parameters
23+
24+
*`Rep`*\
25+
The type of the internal representation of the source `duration` *`d`*.
26+
27+
*`Period`*\
28+
A [`std::ratio`](./ratio.md) type representing the ratio of one second to the source `Rep` type (that is, seconds per `Rep`).
29+
30+
*`d`*\
31+
The source `duration` object.
32+
33+
### Return value
34+
35+
The absolute value of `d`.
36+
37+
### Example: `abs(duration)`
38+
39+
```cpp
40+
// compile using: /std:c++latest
41+
#include <chrono>
42+
#include <iostream>
43+
44+
int main()
45+
{
46+
std::cout << abs(-24h);
47+
return 0;
48+
}
49+
```
50+
51+
```output
52+
24h
53+
```
54+
1155
## <a name="std-chrono-ceil-duration"></a> `ceil(duration)`
1256

1357
Returns the smallest representable `duration` in the target type that's greater than or equal to the specified `duration`.
@@ -92,7 +136,7 @@ Returns a pointer to a [`time_zone`](./time-zone-class.md) as if by a call to `g
92136

93137
## <a name="std-chrono-duration-cast"></a> `duration_cast`
94138

95-
Casts a [`duration`](../standard-library/duration-class.md) object to a specified target `duration` type.
139+
Casts a [`duration`](../standard-library/duration-class.md) to the specified target `duration` type.
96140

97141
### Syntax
98142

@@ -126,6 +170,30 @@ You don't need to use `duration_cast` to convert between `duration` types when t
126170
127171
`duration_cast` doesn't participate in overload resolution unless `ToDuration` is an instance of [`duration`](../standard-library/duration-class.md). It does all conversions by using **`static_cast`** instead of implicit conversions. Multiplications and divisions are avoided if possible. For example, when the compiler knows that the common ratio of the target and source periods has a numerator or denominator of 1. Computations are done in the widest type available, then converted as if by **`static_cast`** to the result type when finished.
128172
173+
### Example `duration_cast`
174+
175+
```cpp
176+
// compile using: /std:c++latest
177+
#include <iostream>
178+
#include <chrono>
179+
180+
using namespace std::chrono;
181+
182+
int main()
183+
{
184+
seconds s(1);
185+
std::cout << duration_cast<microseconds>(s) << '\n';
186+
std::cout << duration_cast<nanoseconds>(s) << '\n';
187+
188+
return 0;
189+
}
190+
```
191+
192+
```output
193+
1000000us
194+
1000000000ns
195+
```
196+
129197
## <a name="std-chrono-floor-duration"></a> `floor(duration)`
130198

131199
Returns the greatest representable `duration` in the target type that's less than or equal to the specified `duration`.

0 commit comments

Comments
 (0)