Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

std.ascii

Functions which operate on ASCII characters.
All of the functions in std.ascii accept Unicode characters but effectively ignore them if they're not ASCII. All isX functions return false for non-ASCII characters, and all toX functions do nothing to non-ASCII characters.
For functions which operate on Unicode characters, see std.uni.

References ASCII Table, Wikipedia

Authors:
Walter Bright and Jonathan M Davis
immutable string fullHexDigits;
0 .. 9A .. Fa .. f
immutable string hexDigits;
0 .. 9A .. F
immutable string lowerHexDigits;
0 .. 9a .. f
immutable string digits;
0 .. 9
immutable string octalDigits;
0 .. 7
immutable string letters;
A .. Za .. z
immutable string uppercase;
A .. Z
immutable string lowercase;
a .. z
immutable string whitespace;
ASCII whitespace
enum LetterCase: bool;
Letter case specifier.
Examples:
import std.conv : to;

writeln(42.to!string(16, LetterCase.upper)); // "2A"
writeln(42.to!string(16, LetterCase.lower)); // "2a"
Examples:
import std.digest.hmac : hmac;
import std.digest.digest : toHexString;
import std.digest.sha : SHA1;
import std.string : representation;

const sha1HMAC = "A very long phrase".representation
    .hmac!SHA1("secret".representation)
    .toHexString!(LetterCase.lower);
writeln(sha1HMAC); // "49f2073c7bf58577e8c9ae59fe8cfd37c9ab94e5"
upper
Upper case letters
lower
Lower case letters
immutable string newline;
Newline sequence for this system.
pure nothrow @nogc @safe bool isAlphaNum(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is a letter or a number (0 .. 9, a .. z, A .. Z).
Examples:
assert( isAlphaNum('A'));
assert( isAlphaNum('1'));
assert(!isAlphaNum('#'));

// N.B.: does not return true for non-ASCII Unicode alphanumerics:
assert(!isAlphaNum('á'));
pure nothrow @nogc @safe bool isAlpha(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is an ASCII letter (A .. Z, a .. z).
Examples:
assert( isAlpha('A'));
assert(!isAlpha('1'));
assert(!isAlpha('#'));

// N.B.: does not return true for non-ASCII Unicode alphabetic characters:
assert(!isAlpha('á'));
pure nothrow @nogc @safe bool isLower(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is a lowercase ASCII letter (a .. z).
Examples:
assert( isLower('a'));
assert(!isLower('A'));
assert(!isLower('#'));

// N.B.: does not return true for non-ASCII Unicode lowercase letters
assert(!isLower('á'));
assert(!isLower('Á'));
pure nothrow @nogc @safe bool isUpper(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is an uppercase ASCII letter (A .. Z).
Examples:
assert( isUpper('A'));
assert(!isUpper('a'));
assert(!isUpper('#'));

// N.B.: does not return true for non-ASCII Unicode uppercase letters
assert(!isUpper('á'));
assert(!isUpper('Á'));
pure nothrow @nogc @safe bool isDigit(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is a digit (0 .. 9).
Examples:
assert( isDigit('3'));
assert( isDigit('8'));
assert(!isDigit('B'));
assert(!isDigit('#'));

// N.B.: does not return true for non-ASCII Unicode numbers
assert(!isDigit('0')); // full-width digit zero (U+FF10)
assert(!isDigit('4')); // full-width digit four (U+FF14)
pure nothrow @nogc @safe bool isOctalDigit(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is a digit in base 8 (0 .. 7).
Examples:
assert( isOctalDigit('0'));
assert( isOctalDigit('7'));
assert(!isOctalDigit('8'));
assert(!isOctalDigit('A'));
assert(!isOctalDigit('#'));
pure nothrow @nogc @safe bool isHexDigit(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is a digit in base 16 (0 .. 9, A .. F, a .. f).
Examples:
assert( isHexDigit('0'));
assert( isHexDigit('A'));
assert( isHexDigit('f')); // lowercase hex digits are accepted
assert(!isHexDigit('g'));
assert(!isHexDigit('G'));
assert(!isHexDigit('#'));
pure nothrow @nogc @safe bool isWhite(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether or not c is a whitespace character. That includes the space, tab, vertical tab, form feed, carriage return, and linefeed characters.
Examples:
assert( isWhite(' '));
assert( isWhite('\t'));
assert( isWhite('\n'));
assert(!isWhite('1'));
assert(!isWhite('a'));
assert(!isWhite('#'));

// N.B.: Does not return true for non-ASCII Unicode whitespace characters.
static import std.uni;
assert(std.uni.isWhite('\u00A0'));
assert(!isWhite('\u00A0')); // std.ascii.isWhite
pure nothrow @nogc @safe bool isControl(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether c is a control character.
Examples:
assert( isControl('\0'));
assert( isControl('\022'));
assert( isControl('\n')); // newline is both whitespace and control
assert(!isControl(' '));
assert(!isControl('1'));
assert(!isControl('a'));
assert(!isControl('#'));

// N.B.: non-ASCII Unicode control characters are not recognized:
assert(!isControl('\u0080'));
assert(!isControl('\u2028'));
assert(!isControl('\u2029'));
pure nothrow @nogc @safe bool isPunctuation(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether or not c is a punctuation character. That includes all ASCII characters which are not control characters, letters, digits, or whitespace.
Examples:
assert( isPunctuation('.'));
assert( isPunctuation(','));
assert( isPunctuation(':'));
assert( isPunctuation('!'));
assert( isPunctuation('#'));
assert( isPunctuation('~'));
assert( isPunctuation('+'));
assert( isPunctuation('_'));

assert(!isPunctuation('1'));
assert(!isPunctuation('a'));
assert(!isPunctuation(' '));
assert(!isPunctuation('\n'));
assert(!isPunctuation('\0'));

// N.B.: Non-ASCII Unicode punctuation characters are not recognized.
assert(!isPunctuation('\u2012')); // (U+2012 = en-dash)
pure nothrow @nogc @safe bool isGraphical(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether or not c is a printable character other than the space character.
Examples:
assert( isGraphical('1'));
assert( isGraphical('a'));
assert( isGraphical('#'));
assert(!isGraphical(' ')); // whitespace is not graphical
assert(!isGraphical('\n'));
assert(!isGraphical('\0'));

// N.B.: Unicode graphical characters are not regarded as such.
assert(!isGraphical('á'));
pure nothrow @nogc @safe bool isPrintable(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether or not c is a printable character - including the space character.
Examples:
assert( isPrintable(' '));  // whitespace is printable
assert( isPrintable('1'));
assert( isPrintable('a'));
assert( isPrintable('#'));
assert(!isPrintable('\0')); // control characters are not printable

// N.B.: Printable non-ASCII Unicode characters are not recognized.
assert(!isPrintable('á'));
pure nothrow @nogc @safe bool isASCII(dchar c);
Parameters:
dchar c The character to test.
Returns:
Whether or not c is in the ASCII character set - i.e. in the range 0 .. 0x7F.
Examples:
assert( isASCII('a'));
assert(!isASCII('á'));
auto toLower(C)(C c)
if (is(C : dchar));
Converts an ASCII letter to lowercase.
Parameters:
C c A character of any type that implicitly converts to dchar. In the case where it's a built-in type, or an enum of a built-in type, Unqual!(OriginalType!C) is returned, whereas if it's a user-defined type, dchar is returned.
Returns:
The corresponding lowercase letter, if c is an uppercase ASCII character, otherwise c itself.
Examples:
writeln(toLower('a')); // 'a'
writeln(toLower('A')); // 'a'
writeln(toLower('#')); // '#'

// N.B.: Non-ASCII Unicode uppercase letters are not converted.
writeln(toLower('Á')); // 'Á'
auto toUpper(C)(C c)
if (is(C : dchar));
Converts an ASCII letter to uppercase.
Parameters:
C c Any type which implicitly converts to dchar. In the case where it's a built-in type, or an enum of a built-in type, Unqual!(OriginalType!C) is returned, whereas if it's a user-defined type, dchar is returned.
Returns:
The corresponding uppercase letter, if c is a lowercase ASCII character, otherwise c itself.
Examples:
writeln(toUpper('a')); // 'A'
writeln(toUpper('A')); // 'A'
writeln(toUpper('#')); // '#'

// N.B.: Non-ASCII Unicode lowercase letters are not converted.
writeln(toUpper('á')); // 'á'