# Standard library header <cwchar>

> C++ Atlas: `cppatlas.com/w/cpp/header/cwchar` | Source: https://en.cppreference.com/w/cpp/header/cwchar | Domain: Standard headers | Standards: C++11

This header was originally in the C standard library as <wchar.h>.

## Official Specification Summary (cppreference)

This header was originally in the C standard library as `<wchar.h>`.

This header is part of the null-terminated wide and multibyte strings libraries. It also provides some C-style I/O functions and conversion from C-style Date.

### Macros

- `NULL`: implementation-defined null pointer constant (macro constant)
- `WEOF`: a non-character value of type `std::wint_t` used to indicate errors (macro constant)
- `WCHAR_MIN`: the smallest valid value of `wchar_t` (macro constant)
- `WCHAR_MAX`: the largest valid value of `wchar_t` (macro constant)

### Types

- `mbstate_t`: conversion state information necessary to iterate multibyte character strings (class)
- `size_t`: unsigned integer type returned by the `sizeof` operator (typedef)
- `wint_t`: integer type that can hold any valid wide character and at least one more value
- `tm`: calendar time type (class)

### Functions

**String manipulation**

- `wcscpy`: copies one wide string to another (function)
- `wcsncpy`: copies a certain amount of wide characters from one string to another (function)
- `wcscat`: appends a copy of one wide string to another (function)
- `wcsncat`: appends a certain amount of wide characters from one wide string to another (function)
- `wcsxfrm`: transform a wide string so that `wcscmp` would produce the same result as `wcscoll` (function)

**String examination**

- `wcslen`: returns the length of a wide string (function)
- `wcscmp`: compares two wide strings (function)
- `wcsncmp`: compares a certain amount of characters from two wide strings (function)
- `wcscoll`: compares two wide strings in accordance to the current locale (function)
- `wcschr`: finds the first occurrence of a wide character in a wide string (function)
- `wcsrchr`: finds the last occurrence of a wide character in a wide string (function)
- `wcsspn`: returns the length of the maximum initial segment that consists of only the wide characters found in another wide string (function)
- `wcscspn`: returns the length of the maximum initial segment that consists of only the wide *not* found in another wide string (function)
- `wcspbrk`: finds the first location of any wide character in one wide string, in another wide string (function)
- `wcsstr`: finds the first occurrence of a wide string within another wide string (function)
- `wcstok`: finds the next token in a wide string (function)

**Wide character array manipulation**

- `wmemcpy`: copies a certain amount of wide characters between two non-overlapping arrays (function)
- `wmemmove`: copies a certain amount of wide characters between two, possibly overlapping, arrays (function)
- `wmemcmp`: compares a certain amount of wide characters from two arrays (function)
- `wmemchr`: finds the first occurrence of a wide character in a wide character array (function)
- `wmemset`: copies the given wide character to every position in a wide character array (function)

**Multibyte/wide character conversion**

- `mbsinit`: checks if the `std::mbstate_t` object represents initial shift state (function)
- `btowc`: widens a single-byte narrow character to wide character, if possible (function)
- `wctob`: narrows a wide character to a single-byte narrow character, if possible (function)
- `mbrlen`: returns the number of bytes in the next multibyte character, given state (function)
- `mbrtowc`: converts the next multibyte character to wide character, given state (function)
- `wcrtomb`: converts a wide character to its multibyte representation, given state (function)
- `mbsrtowcs`: converts a narrow multibyte character string to wide string, given state (function)
- `wcsrtombs`: converts a wide string to narrow multibyte character string, given state (function)

**Input/Output**

- `fgetwc`, `getwc`: gets a wide character from a file stream (function)
- `fgetws`: gets a wide string from a file stream (function)
- `fputwc`, `putwc`: writes a wide character to a file stream (function)
- `fputws`: writes a wide string to a file stream (function)
- `getwchar`: reads a wide character from `stdin` (function)
- `putwchar`: writes a wide character to `stdout` (function)
- `ungetwc`: puts a wide character back into a file stream (function)
- `fwide`: switches a file stream between wide character I/O and narrow character I/O (function)
- `wscanf`, `fwscanf`, `swscanf`: reads formatted wide character input from `stdin`, a file stream or a buffer (function)
- `vwscanf` (C++11), `vfwscanf` (C++11), `vswscanf` (C++11): reads formatted wide character input from `stdin`, a file stream or a buffer using variable argument list (function)
- `wprintf`, `fwprintf`, `swprintf`: prints formatted wide character output to `stdout`, a file stream or a buffer (function)
- `vwprintf`, `vfwprintf`, `vswprintf`: prints formatted wide character output to `stdout`, a file stream or a buffer using variable argument list (function)

**String conversions**

- `wcsftime`: converts a `std::tm` object to custom wide string textual representation (function)
- `wcstol`, `wcstoll`: converts a wide string to an integer value (function)
- `wcstoul`, `wcstoull`: converts a wide string to an unsigned integer value (function)
- `wcstof`, `wcstod`, `wcstold`: converts a wide string to a floating-point value (function)

### Notes

- `NULL` is also defined in the following headers:
  - `<cstddef>`
  - `<cstring>`
  - `<ctime>`
  - `<clocale>`
  - `<cstdio>`
- `std::size_t` is also defined in the following headers:
  - `<cstddef>`
  - `<ctime>`
  - `<cstdio>`
- `std::wint_t` is also defined in the following headers:
  - `<cwctype>`
- `std::tm` is also defined in the following headers:
  - `<ctime>`

### Synopsis

```cpp
namespace std {
  using size_t =    /* see description */; // freestanding
  using mbstate_t = /* see description */; // freestanding
  using wint_t =    /* see description */; // freestanding

  struct tm;

  int fwprintf(FILE* stream, const wchar_t* format, ...);
  int fwscanf(FILE* stream, const wchar_t* format, ...);
  int swprintf(wchar_t* s, size_t n, const wchar_t* format, ...);
  int swscanf(const wchar_t* s, const wchar_t* format, ...);
  int vfwprintf(FILE* stream, const wchar_t* format, va_list arg);
  int vfwscanf(FILE* stream, const wchar_t* format, va_list arg);
  int vswprintf(wchar_t* s, size_t n, const wchar_t* format, va_list arg);
  int vswscanf(const wchar_t* s, const wchar_t* format, va_list arg);
  int vwprintf(const wchar_t* format, va_list arg);
  int vwscanf(const wchar_t* format, va_list arg);
  int wprintf(const wchar_t* format, ...);
  int wscanf(const wchar_t* format, ...);
  wint_t fgetwc(FILE* stream);
  wchar_t* fgetws(wchar_t* s, int n, FILE* stream);
  wint_t fputwc(wchar_t c, FILE* stream);
  int fputws(const wchar_t* s, FILE* stream);
  int fwide(FILE* stream, int mode);
  wint_t getwc(FILE* stream);
  wint_t getwchar();
  wint_t putwc(wchar_t c, FILE* stream);
  wint_t putwchar(wchar_t c);
  wint_t ungetwc(wint_t c, FILE* stream);
  double wcstod(const wchar_t* nptr, wchar_t** endptr);
  float wcstof(const wchar_t* nptr, wchar_t** endptr);
  long double wcstold(const wchar_t* nptr, wchar_t** endptr);
  long int wcstol(const wchar_t* nptr, wchar_t** endptr, int base);
  long long int wcstoll(const wchar_t* nptr, wchar_t** endptr, int base);
  unsigned long int wcstoul(const wchar_t* nptr, wchar_t** endptr, int base);
  unsigned long long int wcstoull(const wchar_t* nptr, wchar_t** endptr, int base);
  wchar_t* wcscpy(wchar_t* s1, const wchar_t* s2);                // freestanding
  wchar_t* wcsncpy(wchar_t* s1, const wchar_t* s2, size_t n);     // freestanding
  wchar_t* wmemcpy(wchar_t* s1, const wchar_t* s2, size_t n);     // freestanding
  wchar_t* wmemmove(wchar_t* s1, const wchar_t* s2, size_t n);    // freestanding
  wchar_t* wcscat(wchar_t* s1, const wchar_t* s2);                // freestanding
  wchar_t* wcsncat(wchar_t* s1, const wchar_t* s2, size_t n);     // freestanding
  int wcscmp(const wchar_t* s1, const wchar_t* s2);               // freestanding
  int wcscoll(const wchar_t* s1, const wchar_t* s2);
  int wcsncmp(const wchar_t* s1, const wchar_t* s2, size_t n);    // freestanding
  size_t wcsxfrm(wchar_t* s1, const wchar_t* s2, size_t n);
  int wmemcmp(const wchar_t* s1, const wchar_t* s2, size_t n);    // freestanding
  const wchar_t* wcschr(const wchar_t* s, wchar_t c);             // freestanding
  wchar_t* wcschr(wchar_t* s, wchar_t c);                         // freestanding
  size_t wcscspn(const wchar_t* s1, const wchar_t* s2);           // freestanding
  const wchar_t* wcspbrk(const wchar_t* s1, const wchar_t* s2);   // freestanding
  wchar_t* wcspbrk(wchar_t* s1, const wchar_t* s2);               // freestanding
  const wchar_t* wcsrchr(const wchar_t* s, wchar_t c);            // freestanding
  wchar_t* wcsrchr(wchar_t* s, wchar_t c);                        // freestanding
  size_t wcsspn(const wchar_t* s1, const wchar_t* s2);            // freestanding
  const wchar_t* wcsstr(const wchar_t* s1, const wchar_t* s2);    // freestanding
  wchar_t* wcsstr(wchar_t* s1, const wchar_t* s2);                // freestanding
  wchar_t* wcstok(wchar_t* s1, const wchar_t* s2, wchar_t** ptr); // freestanding
  const wchar_t* wmemchr(const wchar_t* s, wchar_t c, size_t n);  // freestanding
  wchar_t* wmemchr(wchar_t* s, wchar_t c, size_t n);              // freestanding
  size_t wcslen(const wchar_t* s);                                // freestanding
  wchar_t* wmemset(wchar_t* s, wchar_t c, size_t n);              // freestanding
  size_t wcsftime(wchar_t* s, size_t maxsize, const wchar_t* format, const tm* timeptr);
  wint_t btowc(int c);
  int wctob(wint_t c);

  // multibyte / wide string and character conversion functions
  int mbsinit(const mbstate_t* ps);
  size_t mbrlen(const char* s, size_t n, mbstate_t* ps);
  size_t mbrtowc(wchar_t* pwc, const char* s, size_t n, mbstate_t* ps);
  size_t wcrtomb(char* s, wchar_t wc, mbstate_t* ps);
  size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps);
  size_t wcsrtombs(char* dst, const wchar_t** src, size_t len, mbstate_t* ps);
}

#define NULL      /* see description */ // freestanding
#define WCHAR_MAX /* see description */ // freestanding
#define WCHAR_MIN /* see description */ // freestanding
#define WEOF      /* see description */ // freestanding
```

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 345 | C++98 | `std::tm` was not provided in `<cwchar>` | provided |

---
Attribution: content from https://en.cppreference.com/w/cpp/header/cwchar (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.