Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Calendar
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
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.

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`)
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('á')); // 'á'

Copyright © 1999-2020 by the D Language Foundation | Page generated by Ddoc on Tue Sep 22 09:13:43 2020