Skip to content

Repo sync for protected CLA branch #4590

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 3 commits into from
Jun 16, 2023
Merged
Changes from all commits
Commits
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
12 changes: 4 additions & 8 deletions docs/c-runtime-library/to-functions.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
---
description: "Learn more about: to Functions"
title: "to Functions"
ms.date: "11/04/2016"
ms.date: 06/15/2023
helpviewer_keywords: ["to functions", "string conversion, to different characters", "string conversion, case", "lowercase, converting strings", "uppercase, converting strings", "case, converting", "characters, converting"]
ms.assetid: f636a4c6-8c9f-4be2-baac-064f9dbae300
---
# `to` functions

Expand All @@ -27,28 +26,24 @@ The **`to`** functions and macro conversions are as follows.
| `_toupper` | `_toupper` | Converts `c` to uppercase |
| `towupper` | None | Converts c to corresponding wide-character uppercase letter |

To use the function versions of the **`to`** routines that are also defined as macros, either remove the macro definitions with `#undef` directives or don't include CTYPE.H. If you use the /Za compiler option, the compiler uses the function version of `toupper` or `tolower`. Declarations of the `toupper` and `tolower` functions are in STDLIB.H.
To use the function versions of the **`to`** routines that are also defined as macros, either remove the macro definitions with `#undef` directives or don't include `CTYPE.H`. If you use the /Za compiler option, the compiler uses the function version of `toupper` or `tolower`. Declarations of the `toupper` and `tolower` functions are in `STDLIB.H`.

The `__toascii` routine sets all but the low-order 7 bits of `c` to 0, so that the converted value represents a character in the ASCII character set. If `c` already represents an ASCII character, `c` is unchanged.

The `tolower` and `toupper` routines:

- Are dependent on the `LC_CTYPE` category of the current locale (`tolower` calls `isupper` and `toupper` calls `islower`).

- Convert `c` if `c` represents a convertible letter of the appropriate case in the current locale and the opposite case exists for that locale. Otherwise, `c` is unchanged.

The `_tolower` and `_toupper` routines:

- Are locale-independent, much faster versions of `tolower` and **toupper.**

- Can be used only when **isascii(**`c`**)** and either **isupper(**`c`**)** or **islower(**`c`**)**, respectively, are nonzero.

- Have undefined results if `c` isn't an ASCII letter of the appropriate case for converting.

The `towlower` and `towupper` functions return a converted copy of `c` if and only if both of the following conditions are nonzero. Otherwise, `c` is unchanged.

- `c` is a wide character of the appropriate case (that is, for which `iswupper` or **iswlower,** respectively, is nonzero).

- There's a corresponding wide character of the target case (that is, for which `iswlower` or **iswupper,** respectively, is nonzero).

## Example
Expand All @@ -63,6 +58,7 @@ The `towlower` and `towupper` functions return a converted copy of `c` if and on

#include <ctype.h>
#include <string.h>
#include <stdio.h>

char msg[] = "Some of THESE letters are Uppercase.";
char *p;
Expand Down Expand Up @@ -92,5 +88,5 @@ sOME OF these LETTERS ARE uPPERCASE.
## See also

[Data conversion](./data-conversion.md)\
[Locale](./locale.md)\
[`Locale`](./locale.md)\
[`is`, `isw` routines](./is-isw-routines.md)