std.conv
A one-stop shop for converting values from one type to another. Authors:Walter Bright, Andrei Alexandrescu
- Thrown on conversion errors.
- Thrown on conversion overflow errors.
- String to string conversion works for any two string types having
(char, wchar, dchar) character widths and any
combination of qualifiers (mutable, const, or immutable).
Example:
char[] a = "abc"; auto b = to!(immutable(dchar)[])(a); assert(b == "abc"w);
- Converts array (other than strings) to string. The left bracket, separator, and right bracket are configurable. Each element is converted by calling to!T.
- Associative array to string conversion. The left bracket, key-value separator, element separator, and right bracket are configurable. Each element is printed by calling to!T.
- Object to string conversion calls toString against the object or returns nullstr if the object is null.
- Struct to string conversion calls toString against the struct if it is defined.
- For structs that do not define toString, the conversion to string produces the list of fields.
- Enumerated types are printed as their base type (not the symbolic names).
- A typedef Type Symbol is printed as Type(value).
- If the source type is implicitly convertible to the target type, to simply performs the implicit conversion.
- Boolean values are printed as "true" or "false".
- When the source is a wide string, it is first converted to a narrow string and then parsed.
- When the source is a narrow string, normal text parsing occurs.
- Object-to-object conversions throw exception when the source is non-null and the target is null.
- Narrowing numeric-numeric conversions throw when the value does not fit in the narrower type.
- Array-to-array conversion (except when target is a string type) converts each element in turn by using to.
- Associative array to associative array conversion converts each key and each value in turn.
- Rounded conversion from floating point to integral.
Example:
assert(roundTo!(int)(3.14) == 3); assert(roundTo!(int)(3.49) == 3); assert(roundTo!(int)(3.5) == 4); assert(roundTo!(int)(3.999) == 4); assert(roundTo!(int)(-3.14) == -3); assert(roundTo!(int)(-3.49) == -3); assert(roundTo!(int)(-3.5) == -4); assert(roundTo!(int)(-3.999) == -4);
Rounded conversions do not work with non-integral target types. - The parse family of functions works quite like the
to family, except that (1) it only works with strings as
input, (2) takes the input string by reference and advances it to
the position following the conversion, and (3) does not throw if it
could not convert the entire string. It still throws if an overflow
occurred during conversion or if no character of the input string
was meaningfully converted.
Example:
string test = "123 \t 76.14"; auto a = parse!(uint)(test); assert(a == 123); assert(test == " \t 76.14"); // parse bumps string munch(test, " \t\n\r"); // skip ws assert(test == "76.14"); auto b = parse!(double)(test); assert(b == 76.14); assert(test == "");
- Small unsigned integers to strings.
- Small signed integers to strings.
- Unsigned integers (uint and ulong).
- char, wchar, dchar to a string type.
- Signed values (int and long).
- C-style strings
- float to all string types.
- double to all string types.
- real to all string types.
- ifloat to all string types.
- idouble to all string types.
- ireal to all string types.
- cfloat to all string types.
- cdouble to all string types.
- creal to all string types.
- Convert value to string in radix radix. radix must be a value from 2 to 36. value is treated as a signed value only if radix is 10. The characters A through Z are used to represent values 10 through 36.
- Convenience functions for converting any number and types of arguments
into text (the three character widths).
Example:
assert(text(42, ' ', 1.5, ": xyz") == "42 1.5: xyz"); assert(wtext(42, ' ', 1.5, ": xyz") == "42 1.5: xyz"w); assert(dtext(42, ' ', 1.5, ": xyz") == "42 1.5: xyz"d);