D Programming Language 2.0

- Comments
- D
- Search
- Home

Last update Sun Jul 10 10:47:37 2011

# std.utf

Encode and decode UTF-8, UTF-16 and UTF-32 strings.

For Win32 systems, the C wchar_t type is UTF-16 and corresponds to the D wchar type. For linux systems, the C wchar_t type is UTF-32 and corresponds to the D utf.dchar type.

UTF character support is restricted to (\u0000 <= character <= \U0010FFFF).

See Also:
Wikipedia
http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8
http://anubis.dkuug.dk/JTC1/SC2/WG2/docs/n1335

License:
Boost License 1.0.

Authors:
Walter Bright

Source:
std/utf.d

class UtfException: object.Exception;
  Exception class that is thrown upon any errors.

pure nothrow @safe bool isValidDchar(dchar c);
  Test if c is a valid UTF-32 character.

  \uFFFE and \uFFFF are considered valid by this function, as they are permitted for internal use by an application, but they are not allowed for interchange by the Unicode standard.

  Returns:
  true if it is, false if not.

pure @safe uint stride(in char[] s, size_t i);
  stride() returns the length of a UTF-8 sequence starting at index i in string s.

  Returns:
  The number of bytes in the UTF-8 sequence.

  Throws:
  UtfException if s[i] is not the start of the UTF-8 sequence.

pure @safe uint strideBack(in char[] s, size_t i);
  strideBack() returns the length of a UTF-8 sequence ending before index i in string s.

  Returns:
  The number of bytes in the UTF-8 sequence.

  Throws:
  UtfException if s[i-1] is not the end of the UTF-8 sequence.

pure nothrow @safe uint stride(in wchar[] s, size_t i);
  stride() returns the length of a UTF-16 sequence starting at index i in string s.

pure @safe uint strideBack(in wchar[] s, size_t i);
  strideBack() returns the length of a UTF-16 sequence ending before index i in string s.

pure nothrow @safe uint stride(in dchar[] s, size_t i);
  stride() returns the length of a UTF-32 sequence starting at index i in string s.

  Returns:
  The return value will always be 1.

pure nothrow @safe uint strideBack(in dchar[] s, size_t i);
  strideBack() returns the length of a UTF-32 sequence ending before index i in string s.

  Returns:
  The return value will always be 1.

pure @safe size_t toUCSindex(in char[] s, size_t i);
pure @safe size_t toUCSindex(in wchar[] s, size_t i);
pure nothrow @safe size_t toUCSindex(in dchar[] s, size_t i);
  Given an index i into an array of characters s[], and assuming that index i is at the start of a UTF character, determine the number of UCS characters up to that index i.

pure @safe size_t toUTFindex(in char[] s, size_t n);
pure nothrow @safe size_t toUTFindex(in wchar[] s, size_t n);
pure nothrow @safe size_t toUTFindex(in dchar[] s, size_t n);
  Given a UCS index n into an array of characters s[], return the UTF index.

@trusted dchar decode(in char[] s, ref size_t idx);
@trusted dchar decode(in wchar[] s, ref size_t idx);
@trusted dchar decode(in dchar[] s, ref size_t idx);
  Decodes and returns character starting at s[idx]. idx is advanced past the decoded character. If the character is not well formed, a UtfException is thrown and idx remains unchanged.

pure @safe size_t encode(ref char[4u] buf, dchar c);
pure @safe size_t encode(ref wchar[2u] buf, dchar c);
  Encodes character c into fixed-size array s. Returns the actual length of the encoded character (a number between 1 and 4 for char[4] buffers, and between 1 and 2 for wchar[2] buffers).

pure @safe void encode(ref char[] s, dchar c);
pure @safe void encode(ref wchar[] s, dchar c);
pure @safe void encode(ref dchar[] s, dchar c);
  Encodes character c and appends it to array s[].

ubyte codeLength(C)(dchar c);
  Returns the number of code units that are required to encode the code point c when C is the character type used to encode it.

  Examples:

      assert(codeLength!char('a') == 1);
      assert(codeLength!wchar('a') == 1);
      assert(codeLength!dchar('a') == 1);

      assert(codeLength!char('\U0010FFFF') == 4);
      assert(codeLength!wchar('\U0010FFFF') == 2);
      assert(codeLength!dchar('\U0010FFFF') == 1);

void validate(S)(in S s);
  Checks to see if string is well formed or not. S can be an array of char, wchar, or dchar. Throws a UtfException if it is not. Use to check all untrusted input for correctness.

@trusted string toUTF8(in char[] s);
@trusted string toUTF8(in wchar[] s);
pure @trusted string toUTF8(in dchar[] s);
  Encodes string s into UTF-8 and returns the encoded string.

@trusted wstring toUTF16(in char[] s);
@trusted const(wchar)* toUTF16z(in char[] s);
@trusted wstring toUTF16(in wchar[] s);
pure @trusted wstring toUTF16(in dchar[] s);
  Encodes string s into UTF-16 and returns the encoded string. toUTF16z() is suitable for calling the 'W' functions in the Win32 API that take an LPWSTR or LPCWSTR argument.

@trusted dstring toUTF32(in char[] s);
@trusted dstring toUTF32(in wchar[] s);
@trusted dstring toUTF32(in dchar[] s);
  Encodes string s into UTF-32 and returns the encoded string.

size_t count(E)(const(E)[] s);
  Returns the total number of code points encoded in a string.

  The input to this function MUST be validly encoded.

  Supercedes:
  This function supercedes std.utf.toUCSindex().

  Standards:
  Unicode 5.0, ASCII, ISO-8859-1, WINDOWS-1252

  Parameters:

  s | the string to be counted

Copyright Digital Mars 2000 - 2010. | Page generated by Ddoc.