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.

Category	Functions
Validation	isAlpha isAlphaNum isASCII isControl isDigit isGraphical isHexDigit isOctalDigit isPrintable isPunctuation isUpper isWhite
Conversions	toLower toUpper
Constants	digits fullHexDigits hexDigits letters lowercase lowerHexDigits newline octalDigits uppercase whitespace
Enums	ControlChar LetterCase

References

ASCII Table, Wikipedia

License:

Boost License 1.0.

Authors:

Walter Bright and Jonathan M Davis

Source

std/ascii.d

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 : 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

enum ControlChar: char;

All control characters in the ASCII table (source).

Examples:

import std.algorithm.comparison, std.algorithm.searching, std.range, std.traits;

// Because all ASCII characters fit in char, so do these
static assert(ControlChar.ack.sizeof == 1);

// All control characters except del are in row starting from 0
static assert(EnumMembers!ControlChar.only.until(ControlChar.del).equal(iota(32)));

static assert(ControlChar.nul == '\0');
static assert(ControlChar.bel == '\a');
static assert(ControlChar.bs  == '\b');
static assert(ControlChar.ff  == '\f');
static assert(ControlChar.lf  == '\n');
static assert(ControlChar.cr  == '\r');
static assert(ControlChar.tab == '\t');
static assert(ControlChar.vt  == '\v');

Examples:

import std.conv;
//Control character table can be used in place of hexcodes.
with (ControlChar) assert(text("Phobos", us, "Deimos", us, "Tango", rs) == "Phobos\x1FDeimos\x1FTango\x1E");

nul

Null

soh

Start of heading

stx

Start of text

etx

End of text

eot

End of transmission

enq

Enquiry

ack

Acknowledge

bel

Bell

bs

Backspace

tab

Horizontal tab

lf

NL line feed, new line

vt

Vertical tab

ff

NP form feed, new page

cr

Carriage return

so

Shift out

si

Shift in

dle

Data link escape

dc1

Device control 1

dc2

Device control 2

dc3

Device control 3

dc4

Device control 4

nak

Negative acknowledge

syn

Synchronous idle

etb

End of transmission block

can

Cancel

em

End of medium

sub

Substitute

esc

Escape

fs

File separator

gs

Group separator

rs

Record separator

us

Unit separator

del

Delete

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('０')); // full-width digit zero (U+FF10)
assert(!isDigit('４')); // 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)
Constraints: 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)
Constraints: 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('á')); // 'á'