View source code Display the source code in std/conv.d from which this page was generated on github. 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. Page wiki View or edit the community-maintained wiki page associated with this page.

Module std.conv

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

Functions

Name Description
dtext Convenience functions for converting any number and types of arguments into text (the three character widths).
emplace Given a raw memory area chunk, constructs an object of non-class type T at that address. The constructor is passed the arguments args, if any. The chunk must be as least as large as T needs and should have an alignment multiple of T's alignment.
emplace 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)).
emplace Given a pointer chunk to uninitialized memory (but already typed as a non-class type T), constructs an object of type T at that address from arguments args.
emplace Given a pointer chunk to uninitialized memory (but already typed as T), constructs an object of non-class type T at that address.
octal 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).
parse The parse family of functions works quite like the to family, except that (1) it only works with character ranges as input, (2) takes the input by reference and advances it to the position following the conversion, and (3) does not throw if it could not convert the entire input. It still throws if an overflow occurred during conversion or if no character of the input was meaningfully converted.
parse Parsing one character off a string returns the character and bumps the string up one position.
parse Parses an array from a string given the left bracket (default '['), right bracket (default ']'), and element separator (by default ',').
parse Parses an associative array from a string given the left bracket (default '['), right bracket (default ']'), key-value separator (default ':'), and element seprator (by default ',').
signed 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 changes type (e.g from uint to ulong).
text Convenience functions for converting any number and types of arguments into text (the three character widths).
toImpl If the source type is implicitly convertible to the target type, to simply performs the implicit conversion.
toImpl When source type supports member template function opCast, it is used.
toImpl When target type supports 'converting construction', it is used.
  • If target type is struct, T(value) is used.
  • If target type is class, new T(value) is used.
toImpl Object-to-object conversions by dynamic casting throw exception when the source is non-null and the target is null.
toImpl Narrowing numeric-numeric conversions throw when the value does not fit in the narrower type.
toImpl Array-to-array conversion (except when target is a string type) converts each element in turn by using to.
toImpl 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 printed 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 printed as "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 prints the pointer as a size_t value. If pointer is char*, treat it as C-style strings. In that case, this function is @system.
toImpl 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 string base types are not supported.
toImpl String to non-string conversion runs parsing.
  • When the source is a wide string, it is first converted to a narrow string and then parsed.
  • When the source is a narrow string, normal text parsing occurs.
toImpl Associative array to associative array conversion converts each key and each value in turn.
toImpl 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 printed 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 printed as "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 prints the pointer as a size_t value. If pointer is char*, treat it as C-style strings. In that case, this function is @system.
unsigned 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 changes type (e.g from int to long).
wtext Convenience functions for converting any number and types of arguments into text (the three character widths).

Classes

Name Description
ConvException Thrown on conversion errors.
ConvOverflowException Thrown on conversion overflow errors.

Templates

Name Description
castFrom A wrapper on top of the built-in cast operator that allows one to restrict casting of the original type of the value.
roundTo Rounded conversion from floating point to integral.
to The to family of functions converts a value from type Source to type Target. 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.

Enum values

Name Type Description
octal 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).

Global variables

Name Type Description
hexString void Converts a hex literal to a string at compile time.

Authors

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

License

Boost License 1.0.

Comments