Menu
Search

API Documentation

version 2.098.0

overview

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

Contained Functions

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

License

Boost License 1.0.