Skip to content

Repo sync for protected CLA branch #4347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 43 commits into from
Jan 3, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
43 commits
Select commit Hold shift + click to select a range
be20e45
structure for range iterators
Sep 27, 2022
3a59991
draft
Sep 30, 2022
83b770e
fix merge conflicts
Dec 2, 2022
4c8221e
match incoming changes
Dec 2, 2022
f38bdee
match incoming changes
Dec 2, 2022
2da8fd6
Merge branch 'main' of https://github.com/MicrosoftDocs/cpp-docs-pr i…
Dec 2, 2022
36ece4e
Merge branch 'main' of https://github.com/MicrosoftDocs/cpp-docs-pr i…
Dec 5, 2022
d19d436
draft
Dec 9, 2022
ed23f24
Merge branch 'main' of https://github.com/MicrosoftDocs/cpp-docs-pr i…
Dec 9, 2022
1b9f5d9
draft
Dec 10, 2022
26907b5
draft
Dec 14, 2022
6be8d4b
add sentinel_for and sized_sentinel_for
Dec 14, 2022
d4f5dad
draft
Dec 14, 2022
d77c253
Merge branch 'main' of https://github.com/MicrosoftDocs/cpp-docs-pr i…
Dec 15, 2022
d528729
draft
Dec 15, 2022
6dd32c2
draft
Dec 15, 2022
4fc5411
acrolinx
Dec 15, 2022
2b9467f
fix missing codefence
Dec 15, 2022
23b7ced
fix link
Dec 15, 2022
ae7ab66
add diagrams and crosslink iterator concepts to definitions
Dec 16, 2022
e8d2e60
adjust image size
Dec 16, 2022
d403e86
size
Dec 16, 2022
f6240b1
size
Dec 16, 2022
e961eeb
line up better
Dec 16, 2022
8a74742
force rebuild
Dec 16, 2022
eecf89e
force rebuild
Dec 16, 2022
f614a95
edits
Dec 19, 2022
b18de10
try to make table column narrower
Dec 19, 2022
4819078
last tweak
Dec 19, 2022
5716408
Merge pull request #4702 from TylerMSFT/ranges-iterators
Jak-MS Dec 20, 2022
f6569dc
clarify versions that a change applies to
Dec 20, 2022
2b26d13
tech review
Dec 20, 2022
0967423
Merge pull request #4726 from TylerMSFT/conformance
prmerger-automator[bot] Dec 20, 2022
1b7847d
fix title
Dec 21, 2022
eba28f0
Merge pull request #4728 from TylerMSFT/fixtitle
prmerger-automator[bot] Dec 21, 2022
e024312
fix error - this function doesn't adjust the time in any way. It simp…
Dec 21, 2022
8961bba
wording update
Dec 21, 2022
8bd1054
Merge pull request #4730 from MicrosoftDocs/main
huypub Dec 21, 2022
f093acf
clarify c and s usage per github 3245
Dec 21, 2022
b21c5d4
add clarifying note for cs flag per github 4234
Dec 21, 2022
d42a992
Merge pull request #4729 from TylerMSFT/github3409
prmerger-automator[bot] Dec 21, 2022
751dfaa
Merge pull request #4731 from MicrosoftDocs/main
huypub Dec 22, 2022
a6add0f
Merging changes synced from https://github.com/MicrosoftDocs/cpp-docs…
opbld15 Dec 22, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A basic conversion specification contains only the percent sign and a *type* cha

The *type* conversion specifier character specifies whether to interpret the corresponding argument as a character, a string, a pointer, an integer, or a floating-point number. The *type* character is the only required conversion specification field, and it appears after any optional fields.

The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [*size*](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific.
The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [*size*](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific. For historical reasons, the `wprintf` functions use **`c`** and **`s`** to refer to `wchar_t` characters, and **`C`** and **`S`** specify narrow characters.

Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` variants, are specified by using **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, and **`X`**. Floating-point types such as `float`, `double`, and `long double`, are specified by using **`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, and **`G`**. By default, unless they're modified by a *size* prefix, integer arguments are coerced to `int` type, and floating-point arguments are coerced to `double`. On 64-bit systems, an `int` is a 32-bit value; so, 64-bit integers will be truncated when they're formatted for output unless a *size* prefix of **`ll`** or **`I64`** is used. Pointer types that are specified by **`p`** use the default pointer size for the platform.

Expand Down
14 changes: 7 additions & 7 deletions docs/c-runtime-library/reference/asctime-wasctime.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: "Learn more about: asctime, _wasctime"
title: "asctime, _wasctime"
ms.date: "4/2/2020"
ms.date: 12/21/2022
api_name: ["_wasctime", "asctime", "_o__wasctime", "_o_asctime"]
api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"]
api_type: ["DLLExport"]
Expand Down Expand Up @@ -52,32 +52,32 @@ The **`asctime`** function converts a time stored as a structure to a character
| `tm_yday` | Day of year (0-365; January 1 = 0) |
| `tm_year` | Year (current year minus 1900) |

The converted character string is also adjusted according to the local time zone settings. For information about configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For information about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function.
For information about configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For information about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function.

The string result produced by **`asctime`** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The newline character and the null character occupy the last two positions of the string. **`asctime`** uses a single, statically allocated buffer to hold the return string. Each call to this function destroys the result of the previous call.

**`_wasctime`** is a wide-character version of **`asctime`**. **`_wasctime`** and **`asctime`** behave identically otherwise.
**`_wasctime`** is a wide-character version of **`asctime`**, and otherwise behaves identically to **`asctime`**.

These functions validate their parameters. If *`timeptr`* is a null pointer, or if it contains out-of-range values, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `NULL` and sets `errno` to `EINVAL`.

By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md).

### Generic-text routine mapping

| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined |
| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined |
|---|---|---|---|
| `_tasctime` | **`asctime`** | **`asctime`** | **`_wasctime`** |

## Requirements

| Routine | Required header |
|---|---|
| **`asctime`** | \<time.h> |
| **`_wasctime`** | \<time.h> or \<wchar.h> |
| **`asctime`** | `<time.h>` |
| **`_wasctime`** | `<time.h>` or `<wchar.h>` |

## Example

This program places the system time in the long integer `aclock`, translates it into the structure `newtime` and then converts it to string form for output, using the **`asctime`** function.
This program places the system time in the long integer `aclock`, translates it into the structure `newtime`, and then converts it to string form for output using the **`asctime`** function.

```C
// crt_asctime.c
Expand Down
7 changes: 3 additions & 4 deletions docs/c-runtime-library/reference/fopen-wfopen.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ api_type: ["DLLExport"]
topic_type: ["apiref"]
f1_keywords: ["STDIO/fopen", "CORECRT_WSTDIO/_wfopen", "TCHAR/_tfopen", "fopen", "_wfopen", "_tfopen"]
helpviewer_keywords: ["opening files, for file I/O", "wfopen function", "tfopen function", "_tfopen function", "_wfopen function", "files [C++], opening", "fopen function"]
ms.assetid: e868993f-738c-4920-b5e4-d8f2f41f933d
---
# `fopen`, `_wfopen`

Expand Down Expand Up @@ -70,7 +69,7 @@ The following table summarizes the modes that are used for various **`ccs`** fla

### Encodings used based on ccs flag and BOM

| ccs flag | No BOM (or new file) | BOM: UTF-8 | BOM: UTF-16 |
| `ccs` flag | No BOM (or new file) | BOM: UTF-8 | BOM: UTF-16 |
|--|--|--|--|
| `UNICODE` | **`UTF-16LE`** | **`UTF-8`** | **`UTF-16LE`** |
| **`UTF-8`** | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** |
Expand All @@ -82,7 +81,7 @@ If *`mode`* is **`a, ccs=encoding`** for some `encoding` value, **`fopen`** firs

### Generic-text routine mappings

| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined |
| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined |
|--|--|--|--|
| **`_tfopen`** | **`fopen`** | **`fopen`** | **`_wfopen`** |

Expand Down Expand Up @@ -130,7 +129,7 @@ The following options can be appended to *`mode`* to specify more behaviors.
| **`R`** | Specifies that caching is optimized for, but not restricted to, random access from disk. |
| **`T`** | Specifies a file as temporary. If possible, it isn't flushed to disk. |
| **`D`** | Specifies a file as temporary. It's deleted when the last file pointer is closed. |
| **`ccs=encoding`** | Specifies the encoded character set to use (one of **`UTF-8`**, **`UTF-16LE`**, or `UNICODE`) for this file. Leave unspecified if you want ANSI encoding. |
| **`ccs=encoding`** | Specifies the encoded character set to use (one of **`UTF-8`**, **`UTF-16LE`**, or `UNICODE`) for this file. Leave unspecified if you want ANSI encoding. This flag is separated from flags that precede it by a comma (`,`). For example: `FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");` |

Valid characters for the *`mode`* string that is used in **`fopen`** and **`_fdopen`** correspond to *`oflag`* arguments that are used in [`_open`](open-wopen.md) and [`_sopen`](sopen-wsopen.md), as follows.

Expand Down
17 changes: 15 additions & 2 deletions docs/overview/cpp-conformance-improvements-2019.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,16 @@ To avoid the errors, insert a space in the offending line before the final angle

### References to types with mismatched cv-qualifiers

Previously, MSVC allowed direct binding of a reference from a type with mismatched cv-qualifiers below the top level. This binding could allow modification of supposedly const data referred to by the reference. The compiler now creates a temporary, as required by the standard. In Visual Studio 2017, the following code compiles without warnings. In Visual Studio 2019, the compiler raises warning C4172:
>[!Note]
> This change only affects Visual Studio 2019 versions 16.0 through 16.8. It was reverted starting in Visual Studio 2019 version 16.9

Previously, MSVC allowed direct binding of a reference from a type with mismatched cv-qualifiers below the top level. This binding could allow modification of supposedly const data referred to by the reference.

The compiler for Visual Studio 2019 versions 16.0 through 16.8 instead creates a temporary, as was required by the standard at that time. Later, the standard retroactively changed making the previous behavior of Visual Studio 2017 and earlier correct, and the behavior of Visual Studio 2019 version 16.0 through 16.8 wrong. Consequently, this change was reverted starting in Visual Studio 2019 version 16.9.

See [Similar types and reference binding](#similar-types-and-reference-binding) for a related change.

As an example, in Visual Studio 2017, the following code compiles without warnings. In Visual Studio 2019 versions 16.0 through 16.8, the compiler raises warning C4172. Starting with Visual Studio 2019 version 16.9, the code once again compiles without warnings:

```cpp
struct X
Expand Down Expand Up @@ -2067,10 +2076,14 @@ With this change, a destructor is also potentially throwing if it has a virtual

### Similar types and reference binding

Core Working Group issue [CWG 2352](https://wg21.link/cwg2352) deals with an inconsistency between the reference binding rules and changes to type similarity. The inconsistency was introduced in earlier Defect Reports (such as [CWG 330](https://wg21.link/cwg330)). With this change, code that previously bound a reference to a temporary may now bind directly when the types involved differ only by cv-qualifiers.
Core Working Group issue [CWG 2352](https://wg21.link/cwg2352) deals with an inconsistency between the reference binding rules and changes to type similarity. The inconsistency was introduced in earlier Defect Reports (such as [CWG 330](https://wg21.link/cwg330)). This affected Visual Studio 2019 versions 16.0 through 16.8.

With this change, starting in Visual Studio 2019 version 16.9, code that previously bound a reference to a temporary in Visual Studio 2019 version 16.0 throught 16.8 may now bind directly when the types involved differ only by cv-qualifiers.

Visual Studio 2019 version 16.9 implements the changed behavior in all **`/std`** compiler modes. It's potentially a source breaking change.

See [References to types with mismatched cv-qualifiers](#references-to-types-with-mismatched-cv-qualifiers) for a related change.

This sample shows the changed behavior:

```cpp
Expand Down
2 changes: 1 addition & 1 deletion docs/standard-library/common-view-class.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ For a description of the following entries, see [View class characteristics](vie
| **Range adaptor** | [`views::common`](range-adaptors.md#common) |
| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher |
| **Element type** | Same as the underlying range |
| **View iterator category** | Supports `forward_range` or [`random_access_range`](range-concepts.md#random_access_range) when the underlying range satisfies `random_access_range` and [`sized_range`](range-concepts.md#sized_range) |
| **View iterator category** | `forward_range` or [`random_access_range`](range-concepts.md#random_access_range) when the underlying range satisfies `random_access_range` and [`sized_range`](range-concepts.md#sized_range) |
| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) |
| **Is `const`-iterable** | Only if the underlying range is `const` iterable |
| **Common range** | Yes |
Expand Down
2 changes: 1 addition & 1 deletion docs/standard-library/drop-while-view-class.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ For a description of the following entries, see [View class characteristics](vie
| Characteristic | Description |
|--|--|
| **Range adaptor** | [`views::drop_while`](range-adaptors.md#drop_while) |
| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher and the underlying range's iterators must model `sized_sentinel_for` |
| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher and the underlying range's iterators must model [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for) |
| **Element type** | Same as the underlying range |
| **View iterator category** | Same as the underlying range |
| **Sized** | Only if the underlying range satisfies [`random_access_range`](range-concepts.md#random_access_range) |
Expand Down
4 changes: 2 additions & 2 deletions docs/standard-library/empty-view-class.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ For a description of the following entries, see [View class characteristics](vie
| **Range adaptor** | [`views::empty`](range-adaptors.md#empty) |
| **Underlying range** | None |
| **Element type** | As specified when the `empty_view` is created |
| **View iterator category** | Supports `contiguous_range` |
| **View iterator category** | `contiguous_range` |
| **Sized** | Yes. Always returns 0 |
| **Is `const`-iterable** | Yes |
| **Common range** | Yes |
Expand Down Expand Up @@ -82,7 +82,7 @@ inline constexpr empty_view<T> empty{};
### Parameters

*`T`*\
The type of the underlying element, of which there are none.
The type of the underlying element, of which there is none.

### Remarks

Expand Down
2 changes: 1 addition & 1 deletion docs/standard-library/filter-view-class.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ For a description of the following entries, see [View class characteristics](vie
| **Range adaptor** | [`views::filter`](range-adaptors.md#filter) |
| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher |
| **Element type** | Same as the underlying range |
| **View iterator category** | Supports `input_range`, [`forward_range`](range-concepts.md#forward_range), or [`bidirectional_range`](range-concepts.md#bidirectional_range) depending on the underlying range |
| **View iterator category** | `input_range`, [`forward_range`](range-concepts.md#forward_range), or [`bidirectional_range`](range-concepts.md#bidirectional_range) depending on the underlying range |
| **Sized** | No |
| **Is `const`-iterable** | No |
| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) |
Expand Down
Loading