LEVIATHAN v962456e · 962456eee1

Standard Library

class char

A single Unicode character, stored as one code point.

since 0.1.0-alpha.1linuxwindowswasm

Overview

A char holds one Unicode scalar value, from 0 to 0x10FFFF excluding the surrogate range, and is stored unboxed. The default value is the character with code 0. A single-quoted literal is a char only where a char is expected, as in char c = 'a';; on its own 'a' is a string. Characters compare by code point with ==, < and the other comparison operators, but they have no arithmetic: use code() to get the number and std::charFromCode to build a character from one.

The classification methods (isDigit, isAlpha, isUpper, isLower, isSpace) and the case conversions (toUpper, toLower) understand ASCII only. For any other character the classification methods return false and the case conversions return the character unchanged. string.chars() splits a string into char values.

Description

A char holds exactly one Unicode scalar value: a code point from 0 to 0x10FFFF, excluding the surrogate range 0xD800 to 0xDFFF. It is a value type and defaults to the scalar 0.

A char is not a number. Chars compare by scalar value with ==, !=, <, <=, > and >=, but there is deliberately no arithmetic on them: c + 1 is a compile error. Convert with code() to get the number, and with std::charFromCode to get a char back.

A single-quoted literal becomes a char only where a char is expected; see lang.char-literals. To get a char out of a string, use string.at(byteOffset) or iterate string.chars().

Working with chars

char a = 'a';
char z = 'z';
char e = 'é';
char digit = '7';
console.writeln(a.code());
console.writeln(e.code());
console.writeln(a < z);
console.writeln(a.toUpper());
console.writeln(e.toUpper());
console.writeln(a.isAlpha());
console.writeln(e.isAlpha());
console.writeln(digit.isDigit());
console.writeln(std::charFromCode(955));
console.writeln(std::charFromCode(65).toString() + "!");
console.writeln(e.toString().length());
Run it ▶
97
233
true
A
é
true
false
true
λ
A!
2

Rules

  • code() returns the scalar value as an int. toString() returns the UTF-8 encoding of the char as a string, so 'é'.toString().length() is 2.
  • std::charFromCode(n) returns the char for scalar n. It throws a catchable RuntimeException when n is negative, above 0x10FFFF or a surrogate.
  • isDigit(), isAlpha(), isUpper(), isLower() and isSpace() look at ASCII characters only. Every non-ASCII char answers false, so 'é'.isAlpha() is false.
  • toUpper() and toLower() change ASCII letters only. A non-ASCII char is returned unchanged.
  • A char cannot be added to, subtracted from or assigned to an int without code().

Examples

Whitespace classification:

isSpace

char sp = ' ';
char tab = '\t';
char x = 'x';
console.writeln(sp.isSpace());
console.writeln(tab.isSpace());
console.writeln(x.isSpace());
Run it ▶
true
true
false

An invalid scalar throws:

try {
    console.writeln(std::charFromCode(55296));
} catch (RuntimeException ex) {
    console.writeln("caught: ${ex.message}");
}
not run — blocked by an open compiler bug

The program prints caught: code point 55296 is not a valid Unicode scalar (0..0x10FFFF minus surrogates). The compiled backend currently returns a char without checking the range and prints no error.

Notes

std::charFromCode is a free function in the std namespace. There is no char::fromCode spelling.

Examples

Characters and code points

char c = 'a';
console.writeln(c.code());
console.writeln(c.toUpper());
console.writeln(c.isAlpha());
char next = std::charFromCode(c.code() + 1);
console.writeln(next);
console.writeln(c < next);
char e = std::charFromCode(233);
console.writeln(e.isAlpha());
console.writeln(e.toString().length());
Run it ▶
97
A
true
b
true
false
2

Methods

code

code() -> int

Return the code point of the character.

Returns

The Unicode scalar value, from 0 to 0x10FFFF.

Examples

char z = 'z';
console.writeln(z.code());
char euro = '€';
console.writeln(euro.code());
char nul = '\0';
console.writeln(nul.code());
Run it ▶
122
8364
0

See also: charFromCode

isAlpha

isAlpha() -> bool

Test whether the character is a letter.

Only the ASCII letters A to Z and a to z count, so an accented letter such as é is not alpha.

Returns

true for an ASCII letter, otherwise false.

Examples

char a = 'a';
console.writeln(a.isAlpha());
char seven = '7';
console.writeln(seven.isAlpha());
char e = std::charFromCode(233);
console.writeln(e.isAlpha());
Run it ▶
true
false
false

isDigit

isDigit() -> bool

Test whether the character is a decimal digit.

Only the ASCII digits 0 to 9 count; digits of other scripts do not.

Returns

true for 0 to 9, otherwise false.

Examples

char seven = '7';
console.writeln(seven.isDigit());
char a = 'a';
console.writeln(a.isDigit());
Run it ▶
true
false

isLower

isLower() -> bool

Test whether the character is a lowercase letter.

Only the ASCII letters a to z count.

Returns

true for a to z, otherwise false.

Examples

char a = 'a';
console.writeln(a.isLower());
char q = 'Q';
console.writeln(q.isLower());
Run it ▶
true
false

See also: isUpper

isSpace

isSpace() -> bool

Test whether the character is white space.

The white-space characters are the space, the tab, the line feed and the carriage return.

Returns

true for those four characters, otherwise false.

Examples

char space = ' ';
console.writeln(space.isSpace());
char newline = '\n';
console.writeln(newline.isSpace());
char a = 'a';
console.writeln(a.isSpace());
Run it ▶
true
true
false

isUpper

isUpper() -> bool

Test whether the character is an uppercase letter.

Only the ASCII letters A to Z count.

Returns

true for A to Z, otherwise false.

Examples

char q = 'Q';
console.writeln(q.isUpper());
char a = 'a';
console.writeln(a.isUpper());
Run it ▶
true
false

See also: isLower

toLower

toLower() -> char

Convert an uppercase ASCII letter to lowercase.

Any other character, including a non-ASCII uppercase letter, is returned unchanged.

Returns

The lowercase letter, or this when it is not an uppercase ASCII letter.

Examples

char q = 'Q';
console.writeln(q.toLower());
char seven = '7';
console.writeln(seven.toLower());
Run it ▶
q
7

See also: toUpper

toString

toString() -> string

Convert the character to a one-character string.

The string holds the character's UTF-8 encoding, so its length() counts bytes: 1 for ASCII and up to 4 for other characters.

Returns

A string containing just this character.

Examples

char h = 'h';
console.writeln("letter " + h.toString());
char e = std::charFromCode(233);
console.writeln(e.toString());
console.writeln(e.toString().length());
Run it ▶
letter h
é
2

toUpper

toUpper() -> char

Convert a lowercase ASCII letter to uppercase.

Any other character, including a non-ASCII lowercase letter such as é, is returned unchanged.

Returns

The uppercase letter, or this when it is not a lowercase ASCII letter.

Examples

char a = 'a';
console.writeln(a.toUpper());
char seven = '7';
console.writeln(seven.toUpper());
char e = std::charFromCode(233);
console.writeln(e.toUpper().code());
Run it ▶
A
7
233

See also: toLower

See also

  • charFromCode — Make a char from a Unicode code point.
  • chars — Decode the string into an array of characters.
  • Char literals — A single-quoted literal becomes a char when the context expects one and it holds exactly one Unicode scalar.
  • string — An immutable sequence of text, stored as UTF-8.