std.conv

A one-stop shop for converting values from one type to another.

License:
Boost License 1.0.

Authors:
Walter Bright, Andrei Alexandrescu, Shin Fujishiro, Adam D. Ruppe

Source:
std/conv.d

class ConvException: object.Exception; deprecated alias ConvError;

Thrown on conversion errors.

class ConvOverflowException: std.conv.ConvException; deprecated alias ConvOverflowError;

Thrown on conversion overflow errors.

template to(T)

Entry point that dispatches to the appropriate conversion primitive. Client code normally calls to!TargetType(value) (and not some variant of toImpl).

T toImpl(T, S)(S s);

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!dstring(a);
assert(b == "abc"w);

T toImpl(T, S)(S s, in T leftBracket = "[", in T separator = ", ", in T rightBracket = "]");

Converts array (other than strings) to string. The left bracket, separator, and right bracket are configurable. Each element is converted by calling to!T.

T toImpl(T, S)(S s, in T leftBracket = "[", in T keyval = ":", in T separator = ", ", in T rightBracket = "]");

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.

T toImpl(T, S)(S s, in T nullstr = "null");

Object to string conversion calls toString against the object or returns nullstr if the object is null.

T toImpl(T, S)(S s);

Struct to string conversion calls toString against the struct if it is defined.

T toImpl(T, S)(S s, in T left = S.stringof ~ "(", in T separator = ", ", in T right = ")");

For structs that do not define toString, the conversion to string produces the list of fields.

T toImpl(T, S)(S s);

Enumerated types are converted to strings as their symbolic names.

T toImpl(T, S)(S s, in T left = S.stringof ~ "(", in T right = ")");

A typedef Type Symbol is converted to string as "Type(value)".

Target toImpl(Target, Source)(Source value);

If the source type is implicitly convertible to the target type, to simply performs the implicit conversion.

T toImpl(T, S)(S b);

Boolean values are printed as "true" or "false".

T toImpl(T, S)(S value);

When the source is a wide string, it is first converted to a narrow string and then parsed.

T toImpl(T, S)(S value);

When the source is a narrow string, normal text parsing occurs.

T toImpl(T, S)(S value);

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

T toImpl(T, S)(S value);

Object-to-non-object conversions look for a method "to" of the source object.

Example:

class Date
{
    T to(T)() if(is(T == long))
    {
        return timestamp;
    }
    ...
}

unittest
{
    debug(conv) scope(success) writeln("unittest @", __FILE__, ":", __LINE__, " succeeded.");
    auto d = new Date;
    auto ts = to!long(d); // same as d.to!long()
}

T toImpl(T, S)(S value);

Narrowing numeric-numeric conversions throw when the value does not fit in the narrower type.

T toImpl(T, S)(S src);

Array-to-array conversion (except when target is a string type) converts each element in turn by using to.

T toImpl(T, S)(S src);

Associative array to associative array conversion converts each key and each value in turn.

template roundTo(Target)

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.

Target parse(Target, Source)(ref Source s); Target parse(Target, Source)(ref Source s, uint radix);

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 == "");

Target parse(Target, Source)(ref Source s);

Parsing one character off a string returns the character and bumps the string up one position.

Target parse(Target, Source)(ref Source s, dchar lbracket = '[', dchar rbracket = ']', dchar comma = ',');

Parses an array from a string given the left bracket (default '['), right bracket (default ']'), and element seprator (by default ',').

T toImpl(T, S)(S value);

Small unsigned integers to strings.

T toImpl(T, S)(S value);

Small signed integers to strings.

T toImpl(T, S)(S input);

Unsigned integers (uint and ulong) to string.

T toImpl(T, S)(S c);

char, wchar, dchar to a string type.

T toImpl(T, S)(S value);

Signed values (int and long).

T toImpl(T, S)(S s);

C-style strings

T toImpl(T, S)(S f);

float to all string types.

T toImpl(T, S)(S d);

double to all string types.

T toImpl(T, S)(S r);

real to all string types.

T toImpl(T, S)(S f);

ifloat to all string types.

T toImpl(T, S)(S d);

idouble to all string types.

T toImpl(T, S)(S r);

ireal to all string types.

T toImpl(T, S)(S f);

cfloat to all string types.

T toImpl(T, S)(S d);

cdouble to all string types.

T toImpl(T, S)(S r);

creal to all string types.

T toImpl(T, S)(S value, uint radix); T toImpl(T, S)(S value, uint radix);

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.

T toImpl(T, S)(S value);

Pointer to string conversions prints the pointer as a size_t value.

string text(T...)(T args); wstring wtext(T...)(T args); dstring dtext(T...)(T args);

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);

int octal(string num)(); long octal(string num)(); uint octal(string num)(); ulong octal(string num)(); template octal(alias s) if (isIntegral!(typeof(s)))

The octal facility is intended as an experimental facility to replace octal literals starting with '0', which many find confusing. Using octal!177 or octal!"177" instead of 0177 as an octal literal makes code clearer and the intent more visible. If use of this facility becomes preponderent, a future version of the language may deem old-style octal literals deprecated.

The rules for strings are the usual for literals: If it can fit in an int, it is an int. Otherwise, it is a long. But, if the user specifically asks for a long with the L suffix, always give the long. Give an unsigned iff it is asked for with the U or u suffix. Octals created from integers preserve the type of the passed-in integral.

Example:

// same as 0177
auto x = octal!177;
// octal is a compile-time device
enum y = octal!160;
// Create an unsigned octal
auto z = octal!"1_000_000u";

T* emplace(T, Args...)(void[] chunk, Args args);

Given a raw memory area chunk, constructs an object of non-class type T at that address. The constructor is passed the arguments Args. The chunk must be as least as large as T needs and should have an alignment multiple of T's alignment.

This function can be @trusted if the corresponding constructor of T is @safe.

Returns:
A pointer to the newly constructed object.

T* emplace(T, Args...)(T* chunk, Args args);

Similar to emplace above, except it receives a pointer to an uninitialized object of type T. This overload is useful for e.g. initializing member variables or stack variables defined with T variable = void.

Returns:
A pointer to the newly constructed object.

T emplace(T, Args...)(void[] chunk, Args args);

Given a raw memory area chunk, constructs an object of class type T at that address. The constructor is passed the arguments Args. The chunk must be as least as large as T needs and should have an alignment multiple of T's alignment. (The size of a class instance is obtained by using _traits(classInstanceSize, T)).

This function can be @trusted if the corresponding constructor of T is @safe.

Returns:
A pointer to the newly constructed object.

std

core

std.conv