ocean.text.convert.Formatter

Lightweight, memory friendly string formatting module

This module provides 4 possible semantics: - For pedestrian usage which doesn't care about allocations, see format - For allocation-friendly semantic where the data is output either to a sink or to a ref char[], see the sformat overloads - To ensure absolutely no allocation happens, see snformat

Users of Phobos' std.format will find many similarities in the API: - format is equivalent to std.format.format - snformat is equivalent to std.format.sformat - sformat is roughly equivalent to std.format.formattedWrite

More...

Members

Aliases

FormatterSink
alias FormatterSink = void delegate(cstring)

Type of 'sink' that can be passed to format, that will just format a string into the provided sink.

Functions

format
istring format(cstring fmt, Args args)

Formats an input string into a newly-allocated string and returns it

sformat
mstring sformat(mstring buffer, cstring fmt, Args args)
mstring sformat(Buffer!(char) buffer, cstring fmt, Args args)

Append the processed (formatted) input onto the end of the provided buffer

sformat
bool sformat(FormatterSink sink, cstring fmt, Args args)

Send the processed (formatted) input into a sink

snformat
mstring snformat(mstring buffer, cstring fmt, Args args)

Write the processed (formatted) input into a fixed-length buffer

Detailed Description

Format specifier

The Formatter uses a format specification similar to C#/.NET over the traditional printf style. As a result, the most simple usage is to call:

format("This value will be default formatted: {}", value);

More specific formatting options are however available.

The format specifier is defined as follows:

'{'INDEX[WIDTH_CHARALIGN_LEFT_CHARALIGN_WIDTH[' '*]][':']FORMAT_STRING'}'

In more details: - INDEX is the positive, decimal and 0 based index of the argument to format. - WIDTH_CHAR is either ',' (comma) if a minimum width is requested, in which case the output will be padded with spaces, or '.' if a maximum width is requested, in which case the output will be cropped and cropping will be noted by the presence of "..." - ALIGN_LEFT_CHAR is '-'. If present, padding / cropping will be done on the left side of the string, otherwise it will be the right side This can only be used after a WIDTH_CHAR. - ALIGN_WIDTH is the positive, decimal width the argument should have. - ':' can optionally be used to separate the index / width specification from the format string. So {}, {:} and {0:X} are all valid. - FORMAT_STRING is an argument-defined format string

Format string

The format string defines how the argument will be formatted, and thus is dependent on the argument type.

Currently the following formatting strings are supported: - 'X' or 'x' are used for hexadecimal formatting of the output. 'X' outputs uppercase, 'x' will output lowercase. Applies to integer types and pointers, and will also output the hexadecimal. - 'e' for floating point type will display exponential notation. Using a number will set the precision, so for example the string "{:2}" with argument 0.123456 will output "0.12" Finally, '.' will prevent padding. Unrecognized formatting strings should be ignored. For composed types, the formatting string is passed along, so using X on a struct or an array will display any integer / pointer members in uppercase hexadecimal.

Meta

License

Tango Dual License: 3-Clause BSD License / Academic Free License v3.0. See LICENSE_TANGO.txt for details.