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
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; assert(to!long(a) == a); assertThrown!ConvOverflowException(to!byte(a)); assert(to!int(4.2e6) == 4200000); assertThrown!ConvOverflowException(to!uint(-3.14)); assert(to!uint(3.14) == 3); assert(to!uint(3.99) == 3); assert(to!int(-3.99) == -3);
When converting strings to numeric types, note that 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); assert(str == "2A"); auto i = to!int(str, 16); assert(i == 42);
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; assert(to!int(to!float(a)) == a); assert(to!int(to!float(-a)) == -a);
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; assert(to!char("a") == 'a'); assertThrown(to!char("ñ")); // 'ñ' does not fit into a char assert(to!wchar("ñ") == 'ñ'); assertThrown(to!wchar("😃")); // '😃' does not fit into a wchar assert(to!dchar("😃") == '😃'); // Using wstring or dstring as source type does not affect the result assert(to!char("a"w) == 'a'); assert(to!char("a"d) == 'a'); // Two code points cannot be converted to a single one assertThrown(to!char("ab"));
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); assert(b == [1.0f, 2, 3]); string str = "1 2 3 4 5 6"; auto numbers = to!(double[])(split(str)); assert(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);
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);
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));
Stringize conversion from all types is supported.
See std.format.formatValue on how toString should be defined.
// Conversion representing dynamic/static array with string long[] a = [ 1, 3, 5 ]; assert(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 assert(to!string(cast(char*) null) == ""); assert(to!string("foo\0".ptr) == "foo"); // Conversion reinterpreting void array to string auto w = "abcx"w; const(void)[] b = w; assert(b.length == 8); auto c = to!(wchar[])(b); assert(c == "abcx");
Strings can be converted to enum types. The enum member with the same name as the input string is returned. The comparison is case-sensitive.
A ConvException is thrown if the enum does not have the specified member.
import std.exception : assertThrown; enum E { a, b, c } assert(to!E("a") == E.a); assert(to!E("b") == E.b); assertThrown!ConvException(to!E("A"));
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.
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