Library Reference

version 2.111.0

Internal API

If you spot a problem with this page, click here to create a Bugzilla issue.

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 usinga local clone.

std.conv

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


Category	Functions
Generic	asOriginalType castFrom parse to toChars bitCast
Strings	text wtext dtext hexString
Numeric	octal roundTo signed unsigned
Exceptions	ConvException ConvOverflowException

License:

Boost License 1.0.

Authors:

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

Sourcestd/conv.d

classConvException:object.Exception;

Thrown on conversion errors.

Examples:

import std.exception : assertThrown;assertThrown!ConvException(to!int("abc"));

classConvOverflowException:std.conv.ConvException;

Thrown on conversion overflow errors.

Examples:

import std.exception : assertThrown;assertThrown!ConvOverflowException(to!ubyte(1_000_000));

templateto(T)

Theto template converts a value from one type to another.The source type is deduced and the target type must be specified, for example theexpressionto!int(42.0) converts the number 42 fromdouble toint. The conversion is "safe", i.e.,it checks for overflow;to!int(4.2e10) would throw theConvOverflowException exception. Overflow checks are onlyinserted when necessary, e.g.,to!double(42) does not doany checking because anyint fits in adouble.

Conversions from string to numeric types differ from the C equivalentsatoi() andatol() by checking for overflow and not allowing whitespace.

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

Integer:Sign UnsignedIntegerUnsignedIntegerSign:+-

For conversion to unsigned types, the grammar recognized is:

UnsignedInteger:DecimalDigitDecimalDigitUnsignedInteger

Examples:

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

Examples:

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, useroundTo.)

import std.exception : assertThrown;int a = 420;writeln(to!long(a));// aassertThrown!ConvOverflowException(to!byte(a));writeln(to!int(4.2e6));// 4200000assertThrown!ConvOverflowException(to!uint(-3.14));writeln(to!uint(3.14));// 3writeln(to!uint(3.99));// 3writeln(to!int(-3.99));// -3

Examples:

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);writeln(str);// "2A"auto i =to!int(str, 16);writeln(i);// 42

Examples:

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 are2^24-1 forfloat,2^53-1 fordouble, and2^64-1 forreal (whenreal is 80-bit, e.g. on Intel machines).

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

Examples:

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 charwriteln(to!wchar("ñ"));// 'ñ'assertThrown(to!wchar("😃"));// '😃' does not fit into a wcharwriteln(to!dchar("😃"));// '😃'// Using wstring or dstring as source type does not affect the resultwriteln(to!char("a"w));// 'a'writeln(to!char("a"d));// 'a'// Two code points cannot be converted to a single oneassertThrown(to!char("ab"));

Examples:

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

Examples:

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

This conversion works becauseto!short applies to anint,to!wstring applies to astring,to!string applies to adouble, andto!(double[]) applies to anint[]. The conversion might throw an exception becauseto!short might fail the range check.

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

Examples:

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

Examples:

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, orimmutable).
Converts array (other than strings) to string. Each element is converted by callingto!T.
Associative array to string conversion. Each element is converted by callingto!T.
Object to string conversion callstoString against the object or returns"null" if the object is null.
Struct to string conversion callstoString against the struct if it is defined.
For structs that do not definetoString, 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 inradix 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 theletterCase parameter.
All floating point types to all string types.
Pointer to string conversions convert the pointer to asize_t value. If pointer ischar*, treat it as C-style strings. In that case, this function is@system.

Seestd.format.formatValue on howtoString should be defined.

// Conversion representing dynamic/static array with stringlong[] a = [ 1, 3, 5 ];writeln(to!string(a));// "[1, 3, 5]"// Conversion representing associative array with stringint[string] associativeArray = ["0":1,"1":2];assert(to!string(associativeArray) ==`["0":1, "1":2]` ||to!string(associativeArray) ==`["1":2, "0":1]`);// char* to string conversionwriteln(to!string(cast(char*)null));// ""writeln(to!string("foo\0".ptr));// "foo"// Conversion reinterpreting void array to stringauto w ="abcx"w;const(void)[] b = w;writeln(b.length);// 8auto c =to!(wchar[])(b);writeln(c);// "abcx"

Examples:

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.

AConvException is thrown if the enum does not have the specified member.

import std.exception : assertThrown;enum E { a, b, c }writeln(to!E("a"));// E.awriteln(to!E("b"));// E.bassertThrown!ConvException(to!E("A"));

templateroundTo(Target)

Rounded conversion from floating point to integral.

Rounded conversions do not work with non-integral target types.

Examples:

writeln(roundTo!int(3.14));// 3writeln(roundTo!int(3.49));// 3writeln(roundTo!int(3.5));// 4writeln(roundTo!int(3.999));// 4writeln(roundTo!int(-3.14));// -3writeln(roundTo!int(-3.49));// -3writeln(roundTo!int(-3.5));// -4writeln(roundTo!int(-3.999));// -4writeln(roundTo!(constint)(to!(constdouble)(-3.999)));// -4

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sourcesource) if (is(immutable(Target) == immutable(bool)) && isInputRange!Source && isSomeChar!(ElementType!Source));

Theparse family of functions works quite like thetofamily, except that:

It only works with character ranges as input.
It takes the input by reference. This means that rvalues (such as string literals) are not accepted: useto instead.
It advances the input to the position following the conversion.
It does not throw if it could not convert the entire input.

This overload parses abool from a character input range.

Parameters:

Target	the boolean type to convert to
Source`source`	the lvalue of aninput range
doCount	the flag for deciding to report the number of consumed characters

Returns:

Abool ifdoCount is set toNo.doCount
Atuple containing abool and asize_t ifdoCount is set toYes.doCount

Throws:

AConvException if the range does not represent abool.

NoteAll character input range conversions usingto are forwarded toparse and do not require lvalues.

Examples:

import std.typecons : Flag, Yes, No;auto s ="true";bool b =parse!bool(s);assert(b);auto s2 ="true";bool b2 =parse!(bool, string, No.doCount)(s2);assert(b2);auto s3 ="true";auto b3 =parse!(bool, string, Yes.doCount)(s3);assert(b3.data && b3.count == 4);auto s4 ="falSE";auto b4 =parse!(bool, string, Yes.doCount)(s4);assert(!b4.data && b4.count == 5);

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref scope Sources) if (isIntegral!Target && !is(Target == enum) && isSomeChar!(ElementType!Source)); autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sourcesource, uintradix) if (isIntegral!Target && !is(Target == enum) && isSomeChar!(ElementType!Source));

Parses an integer from a characterinput range.

Parameters:

Target	the integral type to convert to
Source`s`	the lvalue of an input range
doCount	the flag for deciding to report the number of consumed characters

Returns:

A number of typeTarget ifdoCount is set toNo.doCount
Atuple containing a number of typeTarget and asize_t ifdoCount is set toYes.doCount

Throws:

AConvException If an overflow occurred during conversion or if no character of the input was meaningfully converted.

Examples:

import std.typecons : Flag, Yes, No;strings ="123";auto a =parse!int(s);writeln(a);// 123string s1 ="123";auto a1 =parse!(int, string, Yes.doCount)(s1);assert(a1.data == 123 && a1.count == 3);

Examples:

import std.string : tr;import std.typecons : Flag, Yes, No;string test ="123 \t  76.14";auto a =parse!uint(test);writeln(a);// 123assert(test ==" \t  76.14");// parse bumps stringtest = tr(test," \t\n\r","","d");// skip wswriteln(test);// "76.14"auto b =parse!double(test);writeln(b);// 76.14writeln(test);// ""string test2 ="123 \t  76.14";auto a2 =parse!(uint, string, Yes.doCount)(test2);assert(a2.data == 123 && a2.count == 3);assert(test2 ==" \t  76.14");// parse bumps stringtest2 = tr(test2," \t\n\r","","d");// skip wswriteln(test2);// "76.14"auto b2 =parse!(double, string, Yes.doCount)(test2);assert(b2.data == 76.14 && b2.count == 5);writeln(test2);// ""

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sources) if (is(Target == enum) && isSomeString!Source && !is(Source == enum));

Parses anenum type from a string representing an enum member name.

Parameters:

Target	theenum type to convert to
Source`s`	the lvalue of the range to parse
doCount	the flag for deciding to report the number of consumed characters

Returns:

Anenum of typeTarget ifdoCount is set toNo.doCount
Atuple containing anenum of typeTarget and asize_t ifdoCount is set toYes.doCount

Throws:

AConvException if typeTarget does not have a member represented bys.

Examples:

import std.typecons : Flag, Yes, No, tuple;enum EnumType :bool { a =true, b =false, c = a }auto str ="a";writeln(parse!EnumType(str));// EnumType.aauto str2 ="a";writeln(parse!(EnumType, string, No.doCount)(str2));// EnumType.aauto str3 ="a";writeln(parse!(EnumType, string, Yes.doCount)(str3));// tuple(EnumType.a, 1)

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sourcesource) if (isFloatingPoint!Target && !is(Target == enum) && isInputRange!Source && isSomeChar!(ElementType!Source) && !is(Source == enum));

Parses a floating point number from a character range.

Parameters:

Target	a floating point type
Source`source`	the lvalue of the range to parse
doCount	the flag for deciding to report the number of consumed characters

Returns:

A floating point number of typeTarget ifdoCount is set toNo.doCount
Atuple containing a floating point number of·typeTarget and asize_t ifdoCount is set toYes.doCount

Throws:

AConvException ifsource is empty, if no number could be parsed, or if an overflow occurred.

Examples:

import std.math.operations : isClose;import std.math.traits : isNaN, isInfinity;import std.typecons : Flag, Yes, No;auto str ="123.456";assert(parse!double(str).isClose(123.456));auto str2 ="123.456";assert(parse!(double, string, No.doCount)(str2).isClose(123.456));auto str3 ="123.456";auto r =parse!(double, string, Yes.doCount)(str3);assert(r.data.isClose(123.456));writeln(r.count);// 7auto str4 ="-123.456";r =parse!(double, string, Yes.doCount)(str4);assert(r.data.isClose(-123.456));writeln(r.count);// 8auto str5 ="+123.456";r =parse!(double, string, Yes.doCount)(str5);assert(r.data.isClose(123.456));writeln(r.count);// 8auto str6 ="inf0";r =parse!(double, string, Yes.doCount)(str6);assert(isInfinity(r.data) && r.count == 3 && str6 =="0");auto str7 ="-0";auto r2 =parse!(float, string, Yes.doCount)(str7);assert(r2.data.isClose(0.0) && r2.count == 2);auto str8 ="nan";auto r3 =parse!(real, string, Yes.doCount)(str8);assert(isNaN(r3.data) && r3.count == 3);

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sources) if (staticIndexOf!(immutable(Target), immutable(dchar), immutable(ElementEncodingType!Source)) >= 0 && isSomeString!Source && !is(Source == enum)); autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sources) if (isSomeChar!Target && (Target.sizeof >= ElementType!Source.sizeof) && !is(Target == enum) && !isSomeString!Source && isInputRange!Source && isSomeChar!(ElementType!Source));

Parses one character from a character range.

Parameters:

Target	the type to convert to
Source`s`	the lvalue of aninput range
doCount	the flag for deciding to report the number of consumed characters

Returns:

A character of typeTarget ifdoCount is set toNo.doCount
Atuple containing a character of typeTarget and asize_t ifdoCount is set toYes.doCount

Throws:

AConvException if the range is empty.

Examples:

import std.typecons : Flag, Yes, No;autos ="Hello, World!";char first =parse!char(s);writeln(first);// 'H'writeln(s);// "ello, World!"char second =parse!(char, string, No.doCount)(s);writeln(second);// 'e'writeln(s);// "llo, World!"auto third =parse!(char, string, Yes.doCount)(s);assert(third.data == 'l' && third.count == 1);writeln(s);// "lo, World!"

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sources) if (is(immutable(Target) == immutable(typeof(null))) && isInputRange!Source && isSomeChar!(ElementType!Source));

Parsestypeof(null) from a character range if the rangespells"null". This function is case insensitive.

Parameters:

Target	the type to convert to
Source`s`	the lvalue of aninput range
doCount	the flag for deciding to report the number of consumed characters

Returns:

null ifdoCount is set toNo.doCount
Atuple containingnull and asize_t ifdoCount is set toYes.doCount

Throws:

AConvException if the range doesn't representnull.

Examples:

import std.exception : assertThrown;import std.typecons : Flag, Yes, No;alias NullType =typeof(null);auto s1 ="null";assert(parse!NullType(s1)isnull);writeln(s1);// ""auto s2 ="NUll"d;assert(parse!NullType(s2)isnull);writeln(s2);// ""auto s3 ="nuLlNULl";assert(parse!(NullType, string, No.doCount)(s3)isnull);auto r =parse!(NullType, string, Yes.doCount)(s3);assert(r.dataisnull && r.count == 4);auto m ="maybe";assertThrown!ConvException(parse!NullType(m));assertThrown!ConvException(parse!(NullType, string, Yes.doCount)(m));assert(m =="maybe");// m shouldn't change on failureautos ="NULL";assert(parse!(const NullType)(s)isnull);

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sources, dcharlbracket = '[', dcharrbracket = ']', dcharcomma = ',') if (isDynamicArray!Target && !is(Target == enum) && isSomeString!Source && !is(Source == enum)); autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sources, dcharlbracket = '[', dcharrbracket = ']', dcharcomma = ',') if (isStaticArray!Target && !is(Target == enum) && isExactSomeString!Source);

Parses an array from a string given the left bracket (default '['), right bracket (default']'), and element separator (by default','). A trailing separator is allowed.

Parameters:

Source`s`	The string to parse
dchar`lbracket`	the character that starts the array
dchar`rbracket`	the character that ends the array
dchar`comma`	the character that separates the elements of the array
doCount	the flag for deciding to report the number of consumed characters

Returns:

An array of typeTarget ifdoCount is set toNo.doCount
Atuple containing an array of typeTarget and asize_t ifdoCount is set toYes.doCount

Examples:

import std.typecons : Flag, Yes, No;auto s1 =`[['h', 'e', 'l', 'l', 'o'], "world"]`;auto a1 =parse!(string[])(s1);writeln(a1);// ["hello", "world"]auto s2 =`["aaa", "bbb", "ccc"]`;auto a2 =parse!(string[])(s2);writeln(a2);// ["aaa", "bbb", "ccc"]auto s3 =`[['h', 'e', 'l', 'l', 'o'], "world"]`;auto len3 = s3.length;auto a3 =parse!(string[], string, Yes.doCount)(s3);writeln(a3.data);// ["hello", "world"]writeln(a3.count);// len3

autoparse(Target, Source, Flag!"doCount" doCount = No.doCount)(ref Sources, dcharlbracket = '[', dcharrbracket = ']', dcharkeyval = ':', dcharcomma = ',') if (isAssociativeArray!Target && !is(Target == enum) && isSomeString!Source && !is(Source == enum));

Parses an associative array from a string given the left bracket (default '['), right bracket (default']'), key-value separator (default ':'), and element seprator (by default',').

Parameters:

Source`s`	the string to parse
dchar`lbracket`	the character that starts the associative array
dchar`rbracket`	the character that ends the associative array
dchar`keyval`	the character that associates the key with the value
dchar`comma`	the character that separates the elements of the associative array
doCount	the flag for deciding to report the number of consumed characters

Returns:

An associative array of typeTarget ifdoCount is set toNo.doCount
Atuple containing an associative array of typeTarget and asize_t ifdoCount is set toYes.doCount

Examples:

import std.typecons : Flag, Yes, No, tuple;import std.range.primitives : save;import std.array : assocArray;auto s1 ="[1:10, 2:20, 3:30]";auto copyS1 = s1.save;auto aa1 =parse!(int[int])(s1);writeln(aa1);// [1:10, 2:20, 3:30]// parse!(int[int], string, Yes.doCount)(copyS1)writeln(tuple([1:10, 2:20, 3:30], copyS1.length));auto s2 =`["aaa":10, "bbb":20, "ccc":30]`;auto copyS2 = s2.save;auto aa2 =parse!(int[string])(s2);writeln(aa2);// ["aaa":10, "bbb":20, "ccc":30]assert(tuple(["aaa":10,"bbb":20,"ccc":30], copyS2.length) ==parse!(int[string], string, Yes.doCount)(copyS2));auto s3 =`["aaa":[1], "bbb":[2,3], "ccc":[4,5,6]]`;auto copyS3 = s3.save;auto aa3 =parse!(int[][string])(s3);writeln(aa3);// ["aaa":[1], "bbb":[2, 3], "ccc":[4, 5, 6]]assert(tuple(["aaa":[1],"bbb":[2,3],"ccc":[4,5,6]], copyS3.length) ==parse!(int[][string], string, Yes.doCount)(copyS3));auto s4 =`[]`;int[int] emptyAA;writeln(tuple(emptyAA, s4.length));// parse!(int[int], string, Yes.doCount)(s4)

stringtext(T...)(Targs) if (T.length > 0); wstringwtext(T...)(Targs) if (T.length > 0); dstringdtext(T...)(Targs) if (T.length > 0);

Convenience functions for converting one or more arguments of any type into text (the three character widths).

Examples:

writeln(text(42, ' ', 1.5,": xyz"));// "42 1.5: xyz"cwriteln(wtext(42, ' ', 1.5,": xyz"));// "42 1.5: xyz"wwriteln(dtext(42, ' ', 1.5,": xyz"));// "42 1.5: xyz"d

templateoctal(string num) if (isOctalLiteral(num)) templateoctal(alias decimalInteger) if (is(typeof(decimalInteger)) && isIntegral!(typeof(decimalInteger)))

Theoctal facility provides a means to declare a number in base 8.Usingoctal!177 oroctal!"177" for 127 represented in octal(same as 0177 in C).

The rules for strings are the usual for literals: If it can fit in anint, it is anint. Otherwise, it is along. But, if theuser specifically asks for along with theL suffix, alwaysgive thelong. Give an unsigned iff it is asked for with theU oru suffix. Octals created from integers preserve the typeof the passed-in integral.

To	The type to cast to.
T`value`	The value to cast. It must be of typeFrom, otherwise a compile-time error is emitted.

radix	2, 8, 10, 16
Char	character type for output
letterCase	lower for deadbeef, upper for DEADBEEF
T`value`	integer to convert. Can be ubyte, ushort, uint or ulong. If radix is 10, can also be byte, short, int or long.

Movatterモバイル変換

Library Reference

std.conv