Primitive Type char
1.0.0 ·Expand description
A character type.
The char
type represents a single character. More specifically, since
‘character’ isn’t a well-defined concept in Unicode, char
is a ‘Unicode
scalar value’.
This documentation describes a number of methods and trait implementations on the
char
type. For technical reasons, there is additional, separate
documentation in the std::char
module as well.
Validity
A char
is a ‘Unicode scalar value’, which is any ‘Unicode code point’
other than a surrogate code point. This has a fixed numerical definition:
code points are in the range 0 to 0x10FFFF, inclusive.
Surrogate code points, used by UTF-16, are in the range 0xD800 to 0xDFFF.
No char
may be constructed, whether as a literal or at runtime, that is not a
Unicode scalar value:
// Undefined behaviour
unsafe { char::from_u32_unchecked(0x110000) };
RunUSVs are also the exact set of values that may be encoded in UTF-8. Because
char
values are USVs and str
values are valid UTF-8, it is safe to store
any char
in a str
or read any character from a str
as a char
.
The gap in valid char
values is understood by the compiler, so in the
below example the two ranges are understood to cover the whole range of
possible char
values and there is no error for a non-exhaustive match.
let c: char = 'a';
match c {
'\0' ..= '\u{D7FF}' => false,
'\u{E000}' ..= '\u{10FFFF}' => true,
};
RunAll USVs are valid char
values, but not all of them represent a real
character. Many USVs are not currently assigned to a character, but may be
in the future (“reserved”); some will never be a character
(“noncharacters”); and some may be given different meanings by different
users (“private use”).
Representation
char
is always four bytes in size. This is a different representation than
a given character would have as part of a String
. For example:
let v = vec!['h', 'e', 'l', 'l', 'o'];
// five elements times four bytes for each element
assert_eq!(20, v.len() * std::mem::size_of::<char>());
let s = String::from("hello");
// five elements times one byte per element
assert_eq!(5, s.len() * std::mem::size_of::<u8>());
RunAs always, remember that a human intuition for ‘character’ might not map to Unicode’s definitions. For example, despite looking similar, the ‘é’ character is one Unicode code point while ‘é’ is two Unicode code points:
let mut chars = "é".chars();
// U+00e9: 'latin small letter e with acute'
assert_eq!(Some('\u{00e9}'), chars.next());
assert_eq!(None, chars.next());
let mut chars = "é".chars();
// U+0065: 'latin small letter e'
assert_eq!(Some('\u{0065}'), chars.next());
// U+0301: 'combining acute accent'
assert_eq!(Some('\u{0301}'), chars.next());
assert_eq!(None, chars.next());
RunThis means that the contents of the first string above will fit into a
char
while the contents of the second string will not. Trying to create
a char
literal with the contents of the second string gives an error:
error: character literal may only contain one codepoint: 'é'
let c = 'é';
^^^
Another implication of the 4-byte fixed size of a char
is that
per-char
processing can end up using a lot more memory:
let s = String::from("love: ❤️");
let v: Vec<char> = s.chars().collect();
assert_eq!(12, std::mem::size_of_val(&s[..]));
assert_eq!(32, std::mem::size_of_val(&v[..]));
RunImplementations§
source§impl char
impl char
1.52.0 · sourcepub const REPLACEMENT_CHARACTER: char = '�'
pub const REPLACEMENT_CHARACTER: char = '�'
U+FFFD REPLACEMENT CHARACTER
(�) is used in Unicode to represent a
decoding error.
It can occur, for example, when giving ill-formed UTF-8 bytes to
String::from_utf8_lossy
.
1.52.0 · sourcepub const UNICODE_VERSION: (u8, u8, u8) = crate::unicode::UNICODE_VERSION
pub const UNICODE_VERSION: (u8, u8, u8) = crate::unicode::UNICODE_VERSION
The version of Unicode that the Unicode parts of
char
and str
methods are based on.
New versions of Unicode are released regularly and subsequently all methods
in the standard library depending on Unicode are updated. Therefore the
behavior of some char
and str
methods and the value of this constant
changes over time. This is not considered to be a breaking change.
The version numbering scheme is explained in Unicode 11.0 or later, Section 3.1 Versions of the Unicode Standard.
1.52.0 · sourcepub fn decode_utf16<I>(iter: I) -> DecodeUtf16<<I as IntoIterator>::IntoIter> ⓘwhere
I: IntoIterator<Item = u16>,
pub fn decode_utf16<I>(iter: I) -> DecodeUtf16<<I as IntoIterator>::IntoIter> ⓘwhere I: IntoIterator<Item = u16>,
Creates an iterator over the UTF-16 encoded code points in iter
,
returning unpaired surrogates as Err
s.
Examples
Basic usage:
// 𝄞mus<invalid>ic<invalid>
let v = [
0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
];
assert_eq!(
char::decode_utf16(v)
.map(|r| r.map_err(|e| e.unpaired_surrogate()))
.collect::<Vec<_>>(),
vec![
Ok('𝄞'),
Ok('m'), Ok('u'), Ok('s'),
Err(0xDD1E),
Ok('i'), Ok('c'),
Err(0xD834)
]
);
RunA lossy decoder can be obtained by replacing Err
results with the replacement character:
// 𝄞mus<invalid>ic<invalid>
let v = [
0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
];
assert_eq!(
char::decode_utf16(v)
.map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER))
.collect::<String>(),
"𝄞mus�ic�"
);
Run1.52.0 (const: 1.67.0) · sourcepub const fn from_u32(i: u32) -> Option<char>
pub const fn from_u32(i: u32) -> Option<char>
Converts a u32
to a char
.
Note that all char
s are valid u32
s, and can be cast to one with
as
:
let c = '💯';
let i = c as u32;
assert_eq!(128175, i);
RunHowever, the reverse is not true: not all valid u32
s are valid
char
s. from_u32()
will return None
if the input is not a valid value
for a char
.
For an unsafe version of this function which ignores these checks, see
from_u32_unchecked
.
Examples
Basic usage:
let c = char::from_u32(0x2764);
assert_eq!(Some('❤'), c);
RunReturning None
when the input is not a valid char
:
let c = char::from_u32(0x110000);
assert_eq!(None, c);
Run1.52.0 (const: unstable) · sourcepub unsafe fn from_u32_unchecked(i: u32) -> char
pub unsafe fn from_u32_unchecked(i: u32) -> char
Converts a u32
to a char
, ignoring validity.
Note that all char
s are valid u32
s, and can be cast to one with
as
:
let c = '💯';
let i = c as u32;
assert_eq!(128175, i);
RunHowever, the reverse is not true: not all valid u32
s are valid
char
s. from_u32_unchecked()
will ignore this, and blindly cast to
char
, possibly creating an invalid one.
Safety
This function is unsafe, as it may construct invalid char
values.
For a safe version of this function, see the from_u32
function.
Examples
Basic usage:
let c = unsafe { char::from_u32_unchecked(0x2764) };
assert_eq!('❤', c);
Run1.52.0 (const: 1.67.0) · sourcepub const fn from_digit(num: u32, radix: u32) -> Option<char>
pub const fn from_digit(num: u32, radix: u32) -> Option<char>
Converts a digit in the given radix to a char
.
A ‘radix’ here is sometimes also called a ‘base’. A radix of two indicates a binary number, a radix of ten, decimal, and a radix of sixteen, hexadecimal, to give some common values. Arbitrary radices are supported.
from_digit()
will return None
if the input is not a digit in
the given radix.
Panics
Panics if given a radix larger than 36.
Examples
Basic usage:
let c = char::from_digit(4, 10);
assert_eq!(Some('4'), c);
// Decimal 11 is a single digit in base 16
let c = char::from_digit(11, 16);
assert_eq!(Some('b'), c);
RunReturning None
when the input is not a digit:
let c = char::from_digit(20, 10);
assert_eq!(None, c);
RunPassing a large radix, causing a panic:
sourcepub fn is_digit(self, radix: u32) -> bool
pub fn is_digit(self, radix: u32) -> bool
Checks if a char
is a digit in the given radix.
A ‘radix’ here is sometimes also called a ‘base’. A radix of two indicates a binary number, a radix of ten, decimal, and a radix of sixteen, hexadecimal, to give some common values. Arbitrary radices are supported.
Compared to is_numeric()
, this function only recognizes the characters
0-9
, a-z
and A-Z
.
‘Digit’ is defined to be only the following characters:
0-9
a-z
A-Z
For a more comprehensive understanding of ‘digit’, see is_numeric()
.
Panics
Panics if given a radix larger than 36.
Examples
Basic usage:
assert!('1'.is_digit(10));
assert!('f'.is_digit(16));
assert!(!'f'.is_digit(10));
RunPassing a large radix, causing a panic:
const: 1.67.0 · sourcepub const fn to_digit(self, radix: u32) -> Option<u32>
pub const fn to_digit(self, radix: u32) -> Option<u32>
Converts a char
to a digit in the given radix.
A ‘radix’ here is sometimes also called a ‘base’. A radix of two indicates a binary number, a radix of ten, decimal, and a radix of sixteen, hexadecimal, to give some common values. Arbitrary radices are supported.
‘Digit’ is defined to be only the following characters:
0-9
a-z
A-Z
Errors
Returns None
if the char
does not refer to a digit in the given radix.
Panics
Panics if given a radix larger than 36.
Examples
Basic usage:
assert_eq!('1'.to_digit(10), Some(1));
assert_eq!('f'.to_digit(16), Some(15));
RunPassing a non-digit results in failure:
assert_eq!('f'.to_digit(10), None);
assert_eq!('z'.to_digit(16), None);
RunPassing a large radix, causing a panic:
sourcepub fn escape_unicode(self) -> EscapeUnicode ⓘ
pub fn escape_unicode(self) -> EscapeUnicode ⓘ
Returns an iterator that yields the hexadecimal Unicode escape of a
character as char
s.
This will escape characters with the Rust syntax of the form
\u{NNNNNN}
where NNNNNN
is a hexadecimal representation.
Examples
As an iterator:
for c in '❤'.escape_unicode() {
print!("{c}");
}
println!();
RunUsing println!
directly:
println!("{}", '❤'.escape_unicode());
RunBoth are equivalent to:
println!("\\u{{2764}}");
RunUsing to_string
:
assert_eq!('❤'.escape_unicode().to_string(), "\\u{2764}");
Run1.20.0 · sourcepub fn escape_debug(self) -> EscapeDebug ⓘ
pub fn escape_debug(self) -> EscapeDebug ⓘ
Returns an iterator that yields the literal escape code of a character
as char
s.
This will escape the characters similar to the Debug
implementations
of str
or char
.
Examples
As an iterator:
for c in '\n'.escape_debug() {
print!("{c}");
}
println!();
RunUsing println!
directly:
println!("{}", '\n'.escape_debug());
RunBoth are equivalent to:
println!("\\n");
RunUsing to_string
:
assert_eq!('\n'.escape_debug().to_string(), "\\n");
Runsourcepub fn escape_default(self) -> EscapeDefault ⓘ
pub fn escape_default(self) -> EscapeDefault ⓘ
Returns an iterator that yields the literal escape code of a character
as char
s.
The default is chosen with a bias toward producing literals that are legal in a variety of languages, including C++11 and similar C-family languages. The exact rules are:
- Tab is escaped as
\t
. - Carriage return is escaped as
\r
. - Line feed is escaped as
\n
. - Single quote is escaped as
\'
. - Double quote is escaped as
\"
. - Backslash is escaped as
\\
. - Any character in the ‘printable ASCII’ range
0x20
..0x7e
inclusive is not escaped. - All other characters are given hexadecimal Unicode escapes; see
escape_unicode
.
Examples
As an iterator:
for c in '"'.escape_default() {
print!("{c}");
}
println!();
RunUsing println!
directly:
println!("{}", '"'.escape_default());
RunBoth are equivalent to:
println!("\\\"");
RunUsing to_string
:
assert_eq!('"'.escape_default().to_string(), "\\\"");
Runconst: 1.52.0 · sourcepub const fn len_utf8(self) -> usize
pub const fn len_utf8(self) -> usize
Returns the number of bytes this char
would need if encoded in UTF-8.
That number of bytes is always between 1 and 4, inclusive.
Examples
Basic usage:
let len = 'A'.len_utf8();
assert_eq!(len, 1);
let len = 'ß'.len_utf8();
assert_eq!(len, 2);
let len = 'ℝ'.len_utf8();
assert_eq!(len, 3);
let len = '💣'.len_utf8();
assert_eq!(len, 4);
RunThe &str
type guarantees that its contents are UTF-8, and so we can compare the length it
would take if each code point was represented as a char
vs in the &str
itself:
// as chars
let eastern = '東';
let capital = '京';
// both can be represented as three bytes
assert_eq!(3, eastern.len_utf8());
assert_eq!(3, capital.len_utf8());
// as a &str, these two are encoded in UTF-8
let tokyo = "東京";
let len = eastern.len_utf8() + capital.len_utf8();
// we can see that they take six bytes total...
assert_eq!(6, tokyo.len());
// ... just like the &str
assert_eq!(len, tokyo.len());
Runconst: 1.52.0 · sourcepub const fn len_utf16(self) -> usize
pub const fn len_utf16(self) -> usize
Returns the number of 16-bit code units this char
would need if
encoded in UTF-16.
That number of code units is always either 1 or 2, for unicode scalar values in the basic multilingual plane or supplementary planes respectively.
See the documentation for len_utf8()
for more explanation of this
concept. This function is a mirror, but for UTF-16 instead of UTF-8.
Examples
Basic usage:
let n = 'ß'.len_utf16();
assert_eq!(n, 1);
let len = '💣'.len_utf16();
assert_eq!(len, 2);
Run1.15.0 · sourcepub fn encode_utf8(self, dst: &mut [u8]) -> &mut str
pub fn encode_utf8(self, dst: &mut [u8]) -> &mut str
Encodes this character as UTF-8 into the provided byte buffer, and then returns the subslice of the buffer that contains the encoded character.
Panics
Panics if the buffer is not large enough.
A buffer of length four is large enough to encode any char
.
Examples
In both of these examples, ‘ß’ takes two bytes to encode.
let mut b = [0; 2];
let result = 'ß'.encode_utf8(&mut b);
assert_eq!(result, "ß");
assert_eq!(result.len(), 2);
RunA buffer that’s too small:
1.15.0 · sourcepub fn encode_utf16(self, dst: &mut [u16]) -> &mut [u16]
pub fn encode_utf16(self, dst: &mut [u16]) -> &mut [u16]
Encodes this character as UTF-16 into the provided u16
buffer,
and then returns the subslice of the buffer that contains the encoded character.
Panics
Panics if the buffer is not large enough.
A buffer of length 2 is large enough to encode any char
.
Examples
In both of these examples, ‘𝕊’ takes two u16
s to encode.
let mut b = [0; 2];
let result = '𝕊'.encode_utf16(&mut b);
assert_eq!(result.len(), 2);
RunA buffer that’s too small:
sourcepub fn is_alphabetic(self) -> bool
pub fn is_alphabetic(self) -> bool
Returns true
if this char
has the Alphabetic
property.
Alphabetic
is described in Chapter 4 (Character Properties) of the Unicode Standard and
specified in the Unicode Character Database DerivedCoreProperties.txt
.
Examples
Basic usage:
assert!('a'.is_alphabetic());
assert!('京'.is_alphabetic());
let c = '💝';
// love is many things, but it is not alphabetic
assert!(!c.is_alphabetic());
Runconst: unstable · sourcepub fn is_lowercase(self) -> bool
pub fn is_lowercase(self) -> bool
Returns true
if this char
has the Lowercase
property.
Lowercase
is described in Chapter 4 (Character Properties) of the Unicode Standard and
specified in the Unicode Character Database DerivedCoreProperties.txt
.
Examples
Basic usage:
assert!('a'.is_lowercase());
assert!('δ'.is_lowercase());
assert!(!'A'.is_lowercase());
assert!(!'Δ'.is_lowercase());
// The various Chinese scripts and punctuation do not have case, and so:
assert!(!'中'.is_lowercase());
assert!(!' '.is_lowercase());
RunIn a const context:
#![feature(const_unicode_case_lookup)]
const CAPITAL_DELTA_IS_LOWERCASE: bool = 'Δ'.is_lowercase();
assert!(!CAPITAL_DELTA_IS_LOWERCASE);
Runconst: unstable · sourcepub fn is_uppercase(self) -> bool
pub fn is_uppercase(self) -> bool
Returns true
if this char
has the Uppercase
property.
Uppercase
is described in Chapter 4 (Character Properties) of the Unicode Standard and
specified in the Unicode Character Database DerivedCoreProperties.txt
.
Examples
Basic usage:
assert!(!'a'.is_uppercase());
assert!(!'δ'.is_uppercase());
assert!('A'.is_uppercase());
assert!('Δ'.is_uppercase());
// The various Chinese scripts and punctuation do not have case, and so:
assert!(!'中'.is_uppercase());
assert!(!' '.is_uppercase());
RunIn a const context:
#![feature(const_unicode_case_lookup)]
const CAPITAL_DELTA_IS_UPPERCASE: bool = 'Δ'.is_uppercase();
assert!(CAPITAL_DELTA_IS_UPPERCASE);
Runsourcepub fn is_whitespace(self) -> bool
pub fn is_whitespace(self) -> bool
Returns true
if this char
has the White_Space
property.
White_Space
is specified in the Unicode Character Database PropList.txt
.
Examples
Basic usage:
assert!(' '.is_whitespace());
// line break
assert!('\n'.is_whitespace());
// a non-breaking space
assert!('\u{A0}'.is_whitespace());
assert!(!'越'.is_whitespace());
Runsourcepub fn is_alphanumeric(self) -> bool
pub fn is_alphanumeric(self) -> bool
Returns true
if this char
satisfies either is_alphabetic()
or is_numeric()
.
Examples
Basic usage:
assert!('٣'.is_alphanumeric());
assert!('7'.is_alphanumeric());
assert!('৬'.is_alphanumeric());
assert!('¾'.is_alphanumeric());
assert!('①'.is_alphanumeric());
assert!('K'.is_alphanumeric());
assert!('و'.is_alphanumeric());
assert!('藏'.is_alphanumeric());
Runsourcepub fn is_control(self) -> bool
pub fn is_control(self) -> bool
Returns true
if this char
has the general category for control codes.
Control codes (code points with the general category of Cc
) are described in Chapter 4
(Character Properties) of the Unicode Standard and specified in the Unicode Character
Database UnicodeData.txt
.
Examples
Basic usage:
// U+009C, STRING TERMINATOR
assert!(''.is_control());
assert!(!'q'.is_control());
Runsourcepub fn is_numeric(self) -> bool
pub fn is_numeric(self) -> bool
Returns true
if this char
has one of the general categories for numbers.
The general categories for numbers (Nd
for decimal digits, Nl
for letter-like numeric
characters, and No
for other numeric characters) are specified in the Unicode Character
Database UnicodeData.txt
.
This method doesn’t cover everything that could be considered a number, e.g. ideographic numbers like ‘三’. If you want everything including characters with overlapping purposes then you might want to use a unicode or language-processing library that exposes the appropriate character properties instead of looking at the unicode categories.
If you want to parse ASCII decimal digits (0-9) or ASCII base-N, use
is_ascii_digit
or is_digit
instead.
Examples
Basic usage:
assert!('٣'.is_numeric());
assert!('7'.is_numeric());
assert!('৬'.is_numeric());
assert!('¾'.is_numeric());
assert!('①'.is_numeric());
assert!(!'K'.is_numeric());
assert!(!'و'.is_numeric());
assert!(!'藏'.is_numeric());
assert!(!'三'.is_numeric());
Runsourcepub fn to_lowercase(self) -> ToLowercase ⓘ
pub fn to_lowercase(self) -> ToLowercase ⓘ
Returns an iterator that yields the lowercase mapping of this char
as one or more
char
s.
If this char
does not have a lowercase mapping, the iterator yields the same char
.
If this char
has a one-to-one lowercase mapping given by the Unicode Character
Database UnicodeData.txt
, the iterator yields that char
.
If this char
requires special considerations (e.g. multiple char
s) the iterator yields
the char
(s) given by SpecialCasing.txt
.
This operation performs an unconditional mapping without tailoring. That is, the conversion is independent of context and language.
In the Unicode Standard, Chapter 4 (Character Properties) discusses case mapping in general and Chapter 3 (Conformance) discusses the default algorithm for case conversion.
Examples
As an iterator:
for c in 'İ'.to_lowercase() {
print!("{c}");
}
println!();
RunUsing println!
directly:
println!("{}", 'İ'.to_lowercase());
RunBoth are equivalent to:
println!("i\u{307}");
RunUsing to_string
:
assert_eq!('C'.to_lowercase().to_string(), "c");
// Sometimes the result is more than one character:
assert_eq!('İ'.to_lowercase().to_string(), "i\u{307}");
// Characters that do not have both uppercase and lowercase
// convert into themselves.
assert_eq!('山'.to_lowercase().to_string(), "山");
Runsourcepub fn to_uppercase(self) -> ToUppercase ⓘ
pub fn to_uppercase(self) -> ToUppercase ⓘ
Returns an iterator that yields the uppercase mapping of this char
as one or more
char
s.
If this char
does not have an uppercase mapping, the iterator yields the same char
.
If this char
has a one-to-one uppercase mapping given by the Unicode Character
Database UnicodeData.txt
, the iterator yields that char
.
If this char
requires special considerations (e.g. multiple char
s) the iterator yields
the char
(s) given by SpecialCasing.txt
.
This operation performs an unconditional mapping without tailoring. That is, the conversion is independent of context and language.
In the Unicode Standard, Chapter 4 (Character Properties) discusses case mapping in general and Chapter 3 (Conformance) discusses the default algorithm for case conversion.
Examples
As an iterator:
for c in 'ß'.to_uppercase() {
print!("{c}");
}
println!();
RunUsing println!
directly:
println!("{}", 'ß'.to_uppercase());
RunBoth are equivalent to:
println!("SS");
RunUsing to_string
:
assert_eq!('c'.to_uppercase().to_string(), "C");
// Sometimes the result is more than one character:
assert_eq!('ß'.to_uppercase().to_string(), "SS");
// Characters that do not have both uppercase and lowercase
// convert into themselves.
assert_eq!('山'.to_uppercase().to_string(), "山");
RunNote on locale
In Turkish, the equivalent of ‘i’ in Latin has five forms instead of two:
- ‘Dotless’: I / ı, sometimes written ï
- ‘Dotted’: İ / i
Note that the lowercase dotted ‘i’ is the same as the Latin. Therefore:
let upper_i = 'i'.to_uppercase().to_string();
RunThe value of upper_i
here relies on the language of the text: if we’re
in en-US
, it should be "I"
, but if we’re in tr_TR
, it should
be "İ"
. to_uppercase()
does not take this into account, and so:
let upper_i = 'i'.to_uppercase().to_string();
assert_eq!(upper_i, "I");
Runholds across languages.
sourcepub const fn as_ascii(&self) -> Option<AsciiChar>
🔬This is a nightly-only experimental API. (ascii_char
#110998)
pub const fn as_ascii(&self) -> Option<AsciiChar>
ascii_char
#110998)Returns Some
if the value is within the ASCII range,
or None
if it’s not.
This is preferred to Self::is_ascii
when you’re passing the value
along to something else that can take ascii::Char
rather than
needing to check again for itself whether the value is in ASCII.
1.23.0 (const: 1.52.0) · sourcepub const fn to_ascii_uppercase(&self) -> char
pub const fn to_ascii_uppercase(&self) -> char
Makes a copy of the value in its ASCII upper case equivalent.
ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, but non-ASCII letters are unchanged.
To uppercase the value in-place, use make_ascii_uppercase()
.
To uppercase ASCII characters in addition to non-ASCII characters, use
to_uppercase()
.
Examples
let ascii = 'a';
let non_ascii = '❤';
assert_eq!('A', ascii.to_ascii_uppercase());
assert_eq!('❤', non_ascii.to_ascii_uppercase());
Run1.23.0 (const: 1.52.0) · sourcepub const fn to_ascii_lowercase(&self) -> char
pub const fn to_ascii_lowercase(&self) -> char
Makes a copy of the value in its ASCII lower case equivalent.
ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, but non-ASCII letters are unchanged.
To lowercase the value in-place, use make_ascii_lowercase()
.
To lowercase ASCII characters in addition to non-ASCII characters, use
to_lowercase()
.
Examples
let ascii = 'A';
let non_ascii = '❤';
assert_eq!('a', ascii.to_ascii_lowercase());
assert_eq!('❤', non_ascii.to_ascii_lowercase());
Run1.23.0 (const: 1.52.0) · sourcepub const fn eq_ignore_ascii_case(&self, other: &char) -> bool
pub const fn eq_ignore_ascii_case(&self, other: &char) -> bool
Checks that two values are an ASCII case-insensitive match.
Equivalent to to_ascii_lowercase(a) == to_ascii_lowercase(b)
.
Examples
let upper_a = 'A';
let lower_a = 'a';
let lower_z = 'z';
assert!(upper_a.eq_ignore_ascii_case(&lower_a));
assert!(upper_a.eq_ignore_ascii_case(&upper_a));
assert!(!upper_a.eq_ignore_ascii_case(&lower_z));
Run1.23.0 · sourcepub fn make_ascii_uppercase(&mut self)
pub fn make_ascii_uppercase(&mut self)
Converts this type to its ASCII upper case equivalent in-place.
ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, but non-ASCII letters are unchanged.
To return a new uppercased value without modifying the existing one, use
to_ascii_uppercase()
.
Examples
let mut ascii = 'a';
ascii.make_ascii_uppercase();
assert_eq!('A', ascii);
Run1.23.0 · sourcepub fn make_ascii_lowercase(&mut self)
pub fn make_ascii_lowercase(&mut self)
Converts this type to its ASCII lower case equivalent in-place.
ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, but non-ASCII letters are unchanged.
To return a new lowercased value without modifying the existing one, use
to_ascii_lowercase()
.
Examples
let mut ascii = 'A';
ascii.make_ascii_lowercase();
assert_eq!('a', ascii);
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_alphabetic(&self) -> bool
pub const fn is_ascii_alphabetic(&self) -> bool
Checks if the value is an ASCII alphabetic character:
- U+0041 ‘A’ ..= U+005A ‘Z’, or
- U+0061 ‘a’ ..= U+007A ‘z’.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(uppercase_a.is_ascii_alphabetic());
assert!(uppercase_g.is_ascii_alphabetic());
assert!(a.is_ascii_alphabetic());
assert!(g.is_ascii_alphabetic());
assert!(!zero.is_ascii_alphabetic());
assert!(!percent.is_ascii_alphabetic());
assert!(!space.is_ascii_alphabetic());
assert!(!lf.is_ascii_alphabetic());
assert!(!esc.is_ascii_alphabetic());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_uppercase(&self) -> bool
pub const fn is_ascii_uppercase(&self) -> bool
Checks if the value is an ASCII uppercase character: U+0041 ‘A’ ..= U+005A ‘Z’.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(uppercase_a.is_ascii_uppercase());
assert!(uppercase_g.is_ascii_uppercase());
assert!(!a.is_ascii_uppercase());
assert!(!g.is_ascii_uppercase());
assert!(!zero.is_ascii_uppercase());
assert!(!percent.is_ascii_uppercase());
assert!(!space.is_ascii_uppercase());
assert!(!lf.is_ascii_uppercase());
assert!(!esc.is_ascii_uppercase());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_lowercase(&self) -> bool
pub const fn is_ascii_lowercase(&self) -> bool
Checks if the value is an ASCII lowercase character: U+0061 ‘a’ ..= U+007A ‘z’.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(!uppercase_a.is_ascii_lowercase());
assert!(!uppercase_g.is_ascii_lowercase());
assert!(a.is_ascii_lowercase());
assert!(g.is_ascii_lowercase());
assert!(!zero.is_ascii_lowercase());
assert!(!percent.is_ascii_lowercase());
assert!(!space.is_ascii_lowercase());
assert!(!lf.is_ascii_lowercase());
assert!(!esc.is_ascii_lowercase());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_alphanumeric(&self) -> bool
pub const fn is_ascii_alphanumeric(&self) -> bool
Checks if the value is an ASCII alphanumeric character:
- U+0041 ‘A’ ..= U+005A ‘Z’, or
- U+0061 ‘a’ ..= U+007A ‘z’, or
- U+0030 ‘0’ ..= U+0039 ‘9’.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(uppercase_a.is_ascii_alphanumeric());
assert!(uppercase_g.is_ascii_alphanumeric());
assert!(a.is_ascii_alphanumeric());
assert!(g.is_ascii_alphanumeric());
assert!(zero.is_ascii_alphanumeric());
assert!(!percent.is_ascii_alphanumeric());
assert!(!space.is_ascii_alphanumeric());
assert!(!lf.is_ascii_alphanumeric());
assert!(!esc.is_ascii_alphanumeric());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_digit(&self) -> bool
pub const fn is_ascii_digit(&self) -> bool
Checks if the value is an ASCII decimal digit: U+0030 ‘0’ ..= U+0039 ‘9’.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(!uppercase_a.is_ascii_digit());
assert!(!uppercase_g.is_ascii_digit());
assert!(!a.is_ascii_digit());
assert!(!g.is_ascii_digit());
assert!(zero.is_ascii_digit());
assert!(!percent.is_ascii_digit());
assert!(!space.is_ascii_digit());
assert!(!lf.is_ascii_digit());
assert!(!esc.is_ascii_digit());
Runconst: unstable · sourcepub fn is_ascii_octdigit(&self) -> bool
🔬This is a nightly-only experimental API. (is_ascii_octdigit
#101288)
pub fn is_ascii_octdigit(&self) -> bool
is_ascii_octdigit
#101288)Checks if the value is an ASCII octal digit: U+0030 ‘0’ ..= U+0037 ‘7’.
Examples
#![feature(is_ascii_octdigit)]
let uppercase_a = 'A';
let a = 'a';
let zero = '0';
let seven = '7';
let nine = '9';
let percent = '%';
let lf = '\n';
assert!(!uppercase_a.is_ascii_octdigit());
assert!(!a.is_ascii_octdigit());
assert!(zero.is_ascii_octdigit());
assert!(seven.is_ascii_octdigit());
assert!(!nine.is_ascii_octdigit());
assert!(!percent.is_ascii_octdigit());
assert!(!lf.is_ascii_octdigit());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_hexdigit(&self) -> bool
pub const fn is_ascii_hexdigit(&self) -> bool
Checks if the value is an ASCII hexadecimal digit:
- U+0030 ‘0’ ..= U+0039 ‘9’, or
- U+0041 ‘A’ ..= U+0046 ‘F’, or
- U+0061 ‘a’ ..= U+0066 ‘f’.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(uppercase_a.is_ascii_hexdigit());
assert!(!uppercase_g.is_ascii_hexdigit());
assert!(a.is_ascii_hexdigit());
assert!(!g.is_ascii_hexdigit());
assert!(zero.is_ascii_hexdigit());
assert!(!percent.is_ascii_hexdigit());
assert!(!space.is_ascii_hexdigit());
assert!(!lf.is_ascii_hexdigit());
assert!(!esc.is_ascii_hexdigit());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_punctuation(&self) -> bool
pub const fn is_ascii_punctuation(&self) -> bool
Checks if the value is an ASCII punctuation character:
- U+0021 ..= U+002F
! " # $ % & ' ( ) * + , - . /
, or - U+003A ..= U+0040
: ; < = > ? @
, or - U+005B ..= U+0060
[ \ ] ^ _ `
, or - U+007B ..= U+007E
{ | } ~
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(!uppercase_a.is_ascii_punctuation());
assert!(!uppercase_g.is_ascii_punctuation());
assert!(!a.is_ascii_punctuation());
assert!(!g.is_ascii_punctuation());
assert!(!zero.is_ascii_punctuation());
assert!(percent.is_ascii_punctuation());
assert!(!space.is_ascii_punctuation());
assert!(!lf.is_ascii_punctuation());
assert!(!esc.is_ascii_punctuation());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_graphic(&self) -> bool
pub const fn is_ascii_graphic(&self) -> bool
Checks if the value is an ASCII graphic character: U+0021 ‘!’ ..= U+007E ‘~’.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(uppercase_a.is_ascii_graphic());
assert!(uppercase_g.is_ascii_graphic());
assert!(a.is_ascii_graphic());
assert!(g.is_ascii_graphic());
assert!(zero.is_ascii_graphic());
assert!(percent.is_ascii_graphic());
assert!(!space.is_ascii_graphic());
assert!(!lf.is_ascii_graphic());
assert!(!esc.is_ascii_graphic());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_whitespace(&self) -> bool
pub const fn is_ascii_whitespace(&self) -> bool
Checks if the value is an ASCII whitespace character: U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED, U+000C FORM FEED, or U+000D CARRIAGE RETURN.
Rust uses the WhatWG Infra Standard’s definition of ASCII whitespace. There are several other definitions in wide use. For instance, the POSIX locale includes U+000B VERTICAL TAB as well as all the above characters, but—from the very same specification—the default rule for “field splitting” in the Bourne shell considers only SPACE, HORIZONTAL TAB, and LINE FEED as whitespace.
If you are writing a program that will process an existing file format, check what that format’s definition of whitespace is before using this function.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(!uppercase_a.is_ascii_whitespace());
assert!(!uppercase_g.is_ascii_whitespace());
assert!(!a.is_ascii_whitespace());
assert!(!g.is_ascii_whitespace());
assert!(!zero.is_ascii_whitespace());
assert!(!percent.is_ascii_whitespace());
assert!(space.is_ascii_whitespace());
assert!(lf.is_ascii_whitespace());
assert!(!esc.is_ascii_whitespace());
Run1.24.0 (const: 1.47.0) · sourcepub const fn is_ascii_control(&self) -> bool
pub const fn is_ascii_control(&self) -> bool
Checks if the value is an ASCII control character: U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE. Note that most ASCII whitespace characters are control characters, but SPACE is not.
Examples
let uppercase_a = 'A';
let uppercase_g = 'G';
let a = 'a';
let g = 'g';
let zero = '0';
let percent = '%';
let space = ' ';
let lf = '\n';
let esc = '\x1b';
assert!(!uppercase_a.is_ascii_control());
assert!(!uppercase_g.is_ascii_control());
assert!(!a.is_ascii_control());
assert!(!g.is_ascii_control());
assert!(!zero.is_ascii_control());
assert!(!percent.is_ascii_control());
assert!(!space.is_ascii_control());
assert!(lf.is_ascii_control());
assert!(esc.is_ascii_control());
RunTrait Implementations§
source§impl AsciiExt for char
impl AsciiExt for char
§type Owned = char
type Owned = char
source§fn is_ascii(&self) -> bool
fn is_ascii(&self) -> bool
source§fn to_ascii_uppercase(&self) -> Self::Owned
fn to_ascii_uppercase(&self) -> Self::Owned
source§fn to_ascii_lowercase(&self) -> Self::Owned
fn to_ascii_lowercase(&self) -> Self::Owned
source§fn eq_ignore_ascii_case(&self, o: &Self) -> bool
fn eq_ignore_ascii_case(&self, o: &Self) -> bool
source§fn make_ascii_uppercase(&mut self)
fn make_ascii_uppercase(&mut self)
source§fn make_ascii_lowercase(&mut self)
fn make_ascii_lowercase(&mut self)
1.2.0 · source§impl<'a> Extend<&'a char> for String
impl<'a> Extend<&'a char> for String
source§impl Extend<char> for String
impl Extend<char> for String
1.13.0 · source§impl From<u8> for char
impl From<u8> for char
Maps a byte in 0x00..=0xFF to a char
whose code point has the same value, in U+0000..=U+00FF.
Unicode is designed such that this effectively decodes bytes with the character encoding that IANA calls ISO-8859-1. This encoding is compatible with ASCII.
Note that this is different from ISO/IEC 8859-1 a.k.a. ISO 8859-1 (with one less hyphen), which leaves some “blanks”, byte values that are not assigned to any character. ISO-8859-1 (the IANA one) assigns them to the C0 and C1 control codes.
Note that this is also different from Windows-1252 a.k.a. code page 1252, which is a superset ISO/IEC 8859-1 that assigns some (not all!) blanks to punctuation and various Latin characters.
To confuse things further, on the Web
ascii
, iso-8859-1
, and windows-1252
are all aliases
for a superset of Windows-1252 that fills the remaining blanks with corresponding
C0 and C1 control codes.
1.17.0 · source§impl<'a> FromIterator<&'a char> for String
impl<'a> FromIterator<&'a char> for String
source§impl FromIterator<char> for String
impl FromIterator<char> for String
source§impl Ord for char
impl Ord for char
source§impl PartialOrd<char> for char
impl PartialOrd<char> for char
source§fn le(&self, other: &char) -> bool
fn le(&self, other: &char) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<'a> Pattern<'a> for char
impl<'a> Pattern<'a> for char
Searches for chars that are equal to a given char
.
Examples
assert_eq!("Hello world".find('o'), Some(4));
Run§type Searcher = CharSearcher<'a>
type Searcher = CharSearcher<'a>
pattern
#27721)source§fn into_searcher(self, haystack: &'a str) -> <char as Pattern<'a>>::Searcher
fn into_searcher(self, haystack: &'a str) -> <char as Pattern<'a>>::Searcher
pattern
#27721)self
and the haystack
to search in.source§fn is_contained_in(self, haystack: &'a str) -> bool
fn is_contained_in(self, haystack: &'a str) -> bool
pattern
#27721)source§fn is_prefix_of(self, haystack: &'a str) -> bool
fn is_prefix_of(self, haystack: &'a str) -> bool
pattern
#27721)source§fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str>
fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str>
pattern
#27721)source§fn is_suffix_of(self, haystack: &'a str) -> boolwhere
<char as Pattern<'a>>::Searcher: ReverseSearcher<'a>,
fn is_suffix_of(self, haystack: &'a str) -> boolwhere <char as Pattern<'a>>::Searcher: ReverseSearcher<'a>,
pattern
#27721)source§impl Step for char
impl Step for char
source§fn steps_between(_: &char, _: &char) -> Option<usize>
fn steps_between(_: &char, _: &char) -> Option<usize>
step_trait
#42168)source§fn forward_checked(start: char, count: usize) -> Option<char>
fn forward_checked(start: char, count: usize) -> Option<char>
step_trait
#42168)source§fn backward_checked(start: char, count: usize) -> Option<char>
fn backward_checked(start: char, count: usize) -> Option<char>
step_trait
#42168)source§unsafe fn forward_unchecked(start: char, count: usize) -> char
unsafe fn forward_unchecked(start: char, count: usize) -> char
step_trait
#42168)source§unsafe fn backward_unchecked(start: char, count: usize) -> char
unsafe fn backward_unchecked(start: char, count: usize) -> char
step_trait
#42168)1.59.0 · source§impl TryFrom<char> for u8
impl TryFrom<char> for u8
Map char
with code point in U+0000..=U+00FF to byte in 0x00..=0xFF with same value, failing
if the code point is greater than U+00FF.
See impl From<u8> for char
for details on the encoding.