std.conv

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

Copyright

License

Authors

Shin Fujishiro, Adam D. Ruppe, Kenji Hara

tmpl castFrom convFormat enumRep hexString hexString hexString isEnumStrToStr isExactSomeString isNullToStr isSwitchable literalIsLong literalIsUnsigned octal octal octalFitsInInt roundTo to WideElementType

class ConvException ConvOverflowException

fn asOriginalType bitCast convError convertToOctal dtext hexStrLiteral hexToString isHexLiteral isOctalLiteral octal parse parseCheck parseElement parseError parseEscape signed skipWS strippedOctalLiteral text textImpl toChars toImpl toStr toTextRange unsigned writeDText writeText writeTextImpl writeWText wtext

Types 2

classConvException : Exception

Thrown on conversion errors.

classConvOverflowException : ConvException

Thrown on conversion overflow errors.

Constructors

this(string s, string fn = __FILE__, size_t ln = __LINE__)

Functions 62

private fnauto convError(S, T)(S source, string fn = __FILE__, size_t ln = __LINE__)

private fnauto parseError(lazy string msg, string fn = __FILE__, size_t ln = __LINE__) @safe

private fnvoid parseCheck(alias source)(dchar c, string fn = __FILE__, size_t ln = __LINE__)

fnT toStr(T, S)(S src) if (isSomeString!T)

private fnT toImpl(T, S)(S) if (isInputRange!S && isInfinite!S && isExactSomeString!T)

private fn

T toImpl(T,  S)(S value) if (is(S :  T)  &&
    !isEnumStrToStr!(S,  T)  && !isNullToStr!(S,  T))

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

private fnT toImpl(T, S)(S value) if (isTuple!T)

private fnT toImpl(T, S)(ref S s) if (isStaticArray!S)

private fn

T toImpl(T,  S)(S value) if (!is(S :  T)  &&
     is(typeof(S.init.opCast!T()) :  T)  &&
    !isExactSomeString!T &&
    !is(typeof(T(value))))

When source type supports member template function opCast, it is used.

private fn

T toImpl(T,  S)(S value) if (!is(S :  T)  &&
     is(T ==  struct)  &&  is(typeof(T(value))))

When target type supports 'converting construction', it is used. If target type is struct If target type is class

private fn

T toImpl(T,  S)(S value) if (!is(S :  T)  &&
     is(T ==  class)  &&  is(typeof(new  T(value))))

ditto

private fn

T toImpl(T,  S)(S value) if (!is(S :  T)  &&
    (is(S ==  class)  ||  is(S ==  interface))  && !is(typeof(value.opCast!T()) :  T)  &&
    (is(T ==  class)  ||  is(T ==  interface))  && !is(typeof(new  T(value))))

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

private fn

T toImpl(T,  S)(S value) if (!(is(S :  T)  &&
    !isEnumStrToStr!(S,  T)  && !isNullToStr!(S,  T))  &&
    !isInfinite!S &&  isExactSomeString!T)

Handles type to string conversions

private fn

T toImpl(T,  S)(ref  S value) if (!(is(S :  T)  &&
    !isEnumStrToStr!(S,  T)  && !isNullToStr!(S,  T))  &&
    !isInfinite!S &&  isExactSomeString!T && !isCopyable!S && !isStaticArray!S)

private fn

T toImpl(T,  S)(S value,  uint  radix,  LetterCase letterCase =  LetterCase.upper) if (isIntegral!S &&
     isExactSomeString!T)

@trusted pure

private fn

T toImpl(T,  S)(S value) if (!is(S :  T)  &&
    (isNumeric!S ||  isSomeChar!S ||  isBoolean!S)  &&
    (isNumeric!T ||  isSomeChar!T ||  isBoolean!T)  && !is(T ==  enum))

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

private fn

T toImpl(T,  S)(scope  S value) if (!is(S :  T)  &&
    !isSomeString!S &&  isDynamicArray!S &&
    !isExactSomeString!T &&  isArray!T)

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

private fn

T toImpl(T,  S)(S value) if (!is(S :  T)  &&  isAssociativeArray!S &&
     isAssociativeArray!T && !is(T ==  enum))

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

private fn

T toImpl(T,  S)(S value) if (isInputRange!S &&  isSomeChar!(ElementEncodingType!S)  &&
    !isExactSomeString!T &&  is(typeof(parse!T(value)))  &&
    // https://issues.dlang.org/show_bug.cgi?id=20539
    !(is(T ==  enum)  &&  is(typeof(value ==  OriginalType!T.init))  && !isSomeString!(OriginalType!T)))

String, or string-like input range, to non-string conversion runs parsing. LI When the source is a wide string

private fn

T toImpl(T,  S)(S value,  uint  radix) if (isSomeFiniteCharInputRange!S &&
     isIntegral!T &&  is(typeof(parse!T(value,  radix))))

ditto

private fn

T toImpl(T,  S)(S value) if (isSomeChar!T && !is(typeof(parse!T(value)))  &&
     is(typeof(parse!dchar(value))))

String, or string-like input range, to char type not directly supported by parse parses the first dchar of the source.

private fn

T toImpl(T,  S)(S value) if (is(T ==  enum)  && !is(S ==  enum)
     &&  is(typeof(value ==  OriginalType!T.init))
     && !isFloatingPoint!(OriginalType!T)  && !isSomeString!(OriginalType!T))

Convert a value that is implicitly convertible to the enum base type into an Enum value. If the value does not match any enum member values a ConvException is thrown. Enums with floating-point or s...

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source source) if (is(immutable  Target ==  immutable  bool)  &&
     isInputRange!Source &&
     isSomeChar!(ElementType!Source))

The `parse` family of functions works quite like the to family )

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  scope  Source s) if (isIntegral!Target && !is(Target ==  enum)  &&
     isSomeChar!(ElementType!Source))

Parses an integer from a character input range.

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source source,  uint  radix) if (isIntegral!Target && !is(Target ==  enum)  &&
     isSomeChar!(ElementType!Source))

ditto

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (is(Target ==  enum)  &&  isSomeString!Source && !is(Source ==  enum))

Parses an `enum` type from a string representing an enum member name. Params: Target = the `enum` type to convert to s = the lvalue of the range to parse doCount = the flag for de...

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source source) if (isFloatingPoint!Target && !is(Target ==  enum)  &&
     isInputRange!Source &&  isSomeChar!(ElementType!Source)  && !is(Source ==  enum))

Parses a floating point number from a character range. Params: Target = a floating point type source = the lvalue of the range to parse doCount = the flag for deciding to report t...

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (staticIndexOf!(immutable  Target,  immutable  dchar,  immutable  ElementEncodingType!Source)  >=  0 &&
     isSomeString!Source && !is(Source ==  enum))

Parses one character from a character range.

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (isSomeChar!Target &&  Target.sizeof >=  ElementType!Source.sizeof && !is(Target ==  enum)  &&
    !isSomeString!Source &&  isInputRange!Source &&  isSomeChar!(ElementType!Source))

ditto

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (is(immutable  Target ==  immutable  typeof(null))  &&
     isInputRange!Source &&
     isSomeChar!(ElementType!Source))

Parses `typeof(null)` from a character range if the range spells `"null"`. This function is case insensitive.

fnauto skipWS(R, Flag!"doCount" doCount = No.doCount)(ref R r)

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s,  dchar  lbracket =  '[',
     dchar  rbracket =  ']',  dchar  comma =  ',') if (isDynamicArray!Target && !is(Target ==  enum)  &&
     isSomeString!Source && !is(Source ==  enum))

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

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s,  dchar  lbracket =  '[',
     dchar  rbracket =  ']',  dchar  comma =  ',') if (isStaticArray!Target && !is(Target ==  enum)  &&
     isExactSomeString!Source)

ditto

auto parse(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s,  dchar  lbracket =  '[',
                              dchar  rbracket =  ']',  dchar  keyval =  ':',  dchar  comma =  ',') 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 `','`). Param...

private fn

auto parseEscape(Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (isInputRange!Source &&  isSomeChar!(ElementType!Source))

auto parseElement(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (isInputRange!Source &&  isSomeChar!(ElementType!Source)  && !is(Source ==  enum)  &&
     isExactSomeString!Target)

auto parseElement(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (isInputRange!Source &&  isSomeChar!(ElementType!Source)  && !is(Source ==  enum)  &&
     is(CharTypeOf!Target ==  dchar)  && !is(Target ==  enum))

auto parseElement(Target,  Source,  Flag!"doCount" doCount =  No.doCount)(ref  Source s) if (isInputRange!Source &&  isSomeChar!(ElementType!Source)  &&
    !isSomeString!Target && !isSomeChar!Target)

fnstring text(T...)(T args) if (T.length > 0)Convenience functions for converting one or more arguments of any type into text (the three character widths).

fnwstring wtext(T...)(T args) if (T.length > 0)ditto

fndstring dtext(T...)(T args) if (T.length > 0)ditto

fnvoid writeText(Sink, T...)(ref Sink sink, T args) if (isOutputRange!(Sink, char) && T.length > 0)Convenience functions for writing arguments to an output range as text.

fnvoid writeWText(Sink, T...)(ref Sink sink, T args) if (isOutputRange!(Sink, wchar) && T.length > 0)ditto

fnvoid writeDText(Sink, T...)(ref Sink sink, T args) if (isOutputRange!(Sink, dchar) && T.length > 0)ditto

private fnS textImpl(S, U...)(U args)

private fn

void writeTextImpl(S,  Sink,  U...)(ref  Sink sink,  U args) if (isSomeString!S &&  isOutputRange!(Sink,  ElementEncodingType!S))

private fnT convertToOctal(T)(T i)Convert a decimal integer to an octal integer with the same digits. Params: i = integer to convert Returns: octal integer with the same type and same digits

private fnT octal(T)(const string num)

private fnstring strippedOctalLiteral(string original)

private fnbool isOctalLiteral(const string num) @safe pure nothrow @nogc

fnvoid toTextRange(T, W)(T value, W writer) if (isIntegral!T && isOutputRange!(W, char))

fnauto unsigned(T)(T x) if (isIntegral!T)Returns the corresponding unsigned value for `x` (e.g. if `x` has type `int`, it returns cast(uint x)). The advantage compared to the cast is that you do not need to rewrite the cast if `x` later c...

fnauto unsigned(T)(T x) if (isSomeChar!T)Ditto

fnauto signed(T)(T x) if (isIntegral!T)Returns the corresponding signed value for `x` (e.g. if `x` has type `uint`, it returns cast(int x)). The advantage compared to the cast is that you do not need to rewrite the cast if `x` later cha...

fnOriginalType!E asOriginalType(E)(E value) if (is(E == enum))Returns the representation of an enumerated value, i.e. the value converted to the base type of the enumeration.

private fnbool isHexLiteral(String)(scope const String hexData) @safe pure @nogcCheck the correctness of a string for `hexString`. The result is true if and only if the input string is composed of whitespace characters (\f\n\r\t\v lineSep paraSep nelSep) and an even number of ...

fnstring hexToString(string s)

fnwstring hexToString(wstring s)

fndstring hexToString(dstring s)

private fnauto hexStrLiteral(String)(scope String hexData) @trusted nothrow pure

auto toChars(ubyte  radix =  10,  Char =  char,  LetterCase letterCase =  LetterCase.lower,  T)(T value) if ((radix ==  2 ||  radix ==  8 ||  radix ==  10 ||  radix ==  16)  &&
         isIntegral!T && (radix ==  10 ||  isUnsigned!T))

pure nothrow @nogc @safeConvert integer to a range of characters. Intended to be lightweight and fast.

fnT bitCast(T, S)(ref S value) if (T.sizeof <= S.sizeof) refTakes the raw bits of a value and reinterprets them as a different type.

Templates 18

tmplconvFormat()

tmplisExactSomeString(T)

tmplisEnumStrToStr(S, T)

tmplisNullToStr(S, T)

tmplto(T)

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

Functions

T to(A...)(A args) if (A.length > 0)

T to(S)(ref S arg) if (isStaticArray!S)

T to(S)(ref S arg) if (isAggregateType!S && !isCopyable!S)

tmplisSwitchable(E)

tmplenumRep(T, S, S value) if (is (T == immutable) && isExactSomeString!T && is(S == enum))

tmplroundTo(Target)

Rounded conversion from floating point to integral.

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

Functions

Target roundTo(Source)(Source value)

tmplWideElementType(T)

tmploctal(string num) if (isOctalLiteral(num))

The octal facility provides a means to declare a number in base 8. Using octal!177 or octal!"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 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.

Parameters

From The type to cast from. The programmer must ensure it is legal to make this cast.

Functions

auto ref to(To, T)(auto ref T value)

Parameters

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

Returns

the value after the cast, returned by reference if possible.

tmplhexString(string hexData) if (hexData.isHexLiteral)

Converts a hex literal to a string at compile time.

Takes a string made of hexadecimal digits and returns the matching string by converting each pair of digits to a character. The input string can also include white characters, which can be used to keep the literal string readable in the source code.

The function is intended to replace the hexadecimal literal strings starting with 'x', which could be removed to simplify the core language.

Parameters

hexData string to be converted.

Returns

a string, a wstring or a dstring, according to the type of hexData.

std.conv

Copyright

License

Authors

Types 2

Functions 62

Templates 18

See Also

Parameters

Parameters

Returns

Parameters

Returns

See Also