Search
View source code
Display the source code in std/conv.d from which this page was generated on github.
Report a bug
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 local clone.

# Template `std.conv.to`

The `to` template converts a value from one type to another. The source type is deduced and the target type must be specified, for example the expression `to!int(42.0)` converts the number 42 from `double` to `int`. The conversion is "safe", i.e., it checks for overflow; `to!int(4.2e10)` would throw the `ConvOverflowException` exception. Overflow checks are only inserted when necessary, e.g., `to!double(42)` does not do any checking because any `int` fits in a `double`.

``` template to(T) ; ```

Conversions from string to numeric types differ from the C equivalents `atoi()` and `atol()` by checking for overflow and not allowing whitespace.

For conversion of strings to signed types, the grammar recognized is:

```Integer: Sign UnsignedInteger
UnsignedInteger
Sign:
+
-```

For conversion to unsigned types, the grammar recognized is:

```UnsignedInteger:
DecimalDigit
DecimalDigit UnsignedInteger```

NameDescription
to
to
to

## Example

Converting a value to its own type (useful mostly for generic code) simply returns its argument.

``````int a = 42;
int b = to!int(a);
double c = to!double(3.14); // c is double with value 3.14
``````

## Example

Converting among numeric types is a safe way to cast them around.

Conversions from floating-point types to integral types allow loss of precision (the fractional part of a floating-point number). The conversion is truncating towards zero, the same way a cast would truncate. (To round a floating point value when casting to an integral, use `roundTo`.)

``````import std.exception : assertThrown;

int a = 420;
writeln(to!long(a)); // a
assertThrown!ConvOverflowException(to!byte(a));

writeln(to!int(4.2e6)); // 4200000
assertThrown!ConvOverflowException(to!uint(-3.14));
writeln(to!uint(3.14)); // 3
writeln(to!uint(3.99)); // 3
writeln(to!int(-3.99)); // -3
``````

## Example

When converting strings to numeric types, note that the D hexadecimal and binary literals are not handled. Neither the prefixes that indicate the base, nor the horizontal bar used to separate groups of digits are recognized. This also applies to the suffixes that indicate the type.

To work around this, you can specify a radix for conversions involving numbers.

``````auto str = to!string(42, 16);
writeln(str); // "2A"
auto i = to!int(str, 16);
writeln(i); // 42
``````

## Example

Conversions from integral types to floating-point types always succeed, but might lose accuracy. The largest integers with a predecessor representable in floating-point format are `2^24-1` for `float`, `2^53-1` for `double`, and `2^64-1` for `real` (when `real` is 80-bit, e.g. on Intel machines).

``````// 2^24 - 1, largest proper integer representable as float
int a = 16_777_215;
writeln(to!int(to!float(a))); // a
writeln(to!int(to!float(-a))); // -a
``````

## Example

Conversion from string types to char types enforces the input to consist of a single code point, and said code point must fit in the target type. Otherwise, `ConvException` is thrown.

``````import std.exception : assertThrown;

writeln(to!char("a")); // 'a'
assertThrown(to!char("ñ")); // 'ñ' does not fit into a char
writeln(to!wchar("ñ")); // 'ñ'
assertThrown(to!wchar("😃")); // '😃' does not fit into a wchar
writeln(to!dchar("😃")); // '😃'

// Using wstring or dstring as source type does not affect the result
writeln(to!char("a"w)); // 'a'
writeln(to!char("a"d)); // 'a'

// Two code points cannot be converted to a single one
assertThrown(to!char("ab"));
``````

## Example

Converting an array to another array type works by converting each element in turn. Associative arrays can be converted to associative arrays as long as keys and values can in turn be converted.

``````import std.string : split;

int[] a = [1, 2, 3];
auto b = to!(float[])(a);
writeln(b); // [1.0f, 2, 3]
string str = "1 2 3 4 5 6";
auto numbers = to!(double[])(split(str));
writeln(numbers); // [1.0, 2, 3, 4, 5, 6]
int[string] c;
c["a"] = 1;
c["b"] = 2;
auto d = to!(double[wstring])(c);
assert(d["a"w] == 1 && d["b"w] == 2);
``````

## Example

Conversions operate transitively, meaning that they work on arrays and associative arrays of any complexity.

This conversion works because `to!short` applies to an `int`, `to!wstring` applies to a `string`, `to!string` applies to a `double`, and `to!(double[])` applies to an `int[]`. The conversion might throw an exception because `to!short` might fail the range check.

``````int[string][double[int[]]] a;
auto b = to!(short[wstring][string[double[]]])(a);
``````

## Example

Object-to-object conversions by dynamic casting throw exception when the source is non-null and the target is null.

``````import std.exception : assertThrown;
// Testing object conversions
class A {}
class B : A {}
class C : A {}
A a1 = new A, a2 = new B, a3 = new C;
assert(to!B(a2) is a2);
assert(to!C(a3) is a3);
assertThrown!ConvException(to!B(a3));
``````

## Example

Stringize conversion from all types is supported.

• 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`).
• Converts array (other than strings) to string. Each element is converted by calling `to!T`.
• Associative array to string conversion. Each element is converted by calling `to!T`.
• Object to string conversion calls `toString` against the object or returns `"null"` 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 converted to strings as their symbolic names.
• Boolean values are converted to `"true"` or `"false"`.
• `char`, `wchar`, `dchar` to a string type.
• Unsigned or signed integers to strings.
[special case]
Convert integral 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 and their case is determined by the letterCase parameter.
• All floating point types to all string types.
• Pointer to string conversions convert the pointer to a `size_t` value. If pointer is `char*`, treat it as C-style strings. In that case, this function is `@system`.
See `std.format.formatValue` on how toString should be defined.

``````// Conversion representing dynamic/static array with string
long[] a = [ 1, 3, 5 ];
writeln(to!string(a)); // "[1, 3, 5]"

// Conversion representing associative array with string
int[string] associativeArray = ["0":1, "1":2];
assert(to!string(associativeArray) == `["0":1, "1":2]` ||
to!string(associativeArray) == `["1":2, "0":1]`);

// char* to string conversion
writeln(to!string(cast(char*)null)); // ""
writeln(to!string("foo\0".ptr)); // "foo"

// Conversion reinterpreting void array to string
auto w = "abcx"w;
const(void)[] b = w;
writeln(b.length); // 8

auto c = to!(wchar[])(b);
writeln(c); // "abcx"
``````

## Authors

Walter Bright, Andrei Alexandrescu, Shin Fujishiro, Adam D. Ruppe, Kenji Hara