std.format

Этот модуль реализует функциональность форматирования строк и ввода-вывода. Он сравним с vsprintf() C99 и использует аналогичную схему кодирования формата.

Для ознакомления с возможностями std.format и способом использования этого модуля см. посвящённую статью на DWiki DWiki статью.

Этот модуль ориентирован вокруг двух функций:

Лицензия:

Лицензия Boost 1.0.

Авторы:

Walter Bright, Andrei Alexandrescu и Kenji Hara

Исходный код

std/format.d

class FormatException: object.Exception;

Сигнализирует о несоответствии между форматом и соответствующим аргументом.

Примеры:

import std.exception : assertThrown;
assertThrown!FormatException(format("%d", "foo"));

uint formattedWrite(alias fmt, Writer, A...)(auto ref Writer w, A args)
Constraints: if (isSomeString!(typeof(fmt)));

uint formattedWrite(Writer, Char, A...)(auto ref Writer w, scope const Char[] fmt, A args);

Интерпретирует список аргументов с изменяемой длиной args, форматирует их в соответствии с fmt, и отправляет полученные символы в w. Кодировка вывода такая же, как у Char. Тип Writer должен удовлетворять std.range.primitives.isOutputRange!(Writer, Char).

Аргументы с изменяемой длиной обычно потребляются в порядке. Также поддерживается синтаксис позиционных параметров в стиле POSIX синтаксис. Каждый аргумент форматируется в последовательность символов в соответствии со спецификацией формата, а символы передаются в w. Форматируются все аргументы, указанные в строке формата. Если аргументов меньше, чем спецификаторов формата, выбрасывается FormatException. Если оставшихся аргументов больше, чем требуется спецификацией формата, они игнорируются, но только если хотя бы один аргумент был отформатирован.

Строка формата поддерживает форматирование элементов массивов и вложенных массивов с помощью спецификаторов группировки формата %( и %). Каждая пара %( и %) соответствует одному аргументу массива. Вложенная строка формата применяется к отдельным элементам массива. Завершающая часть строки формата после спецификатора преобразования для элемента массива интерпретируется как разделитель массива и, следовательно, пропускается после последнего элемента массива. Спецификатор %| может использоваться для явного указания начала разделителя, так что предшествующая часть строки будет включена после последнего элемента массива. (См. примеры ниже).

Параметры:

Writer w	Вывод отправляется в этот объект-писатель. Типичные объекты-писатели включают std.array.Appender!string и std.stdio.LockingTextWriter.
Char[] fmt	Строка формата.
A args	Список аргументов с изменяемой длиной.

Возвращаемое значение:

Отформатированное количество аргументов.

Исключения:

Несовпадение аргументов и форматов приводит к сбросу FormatException.

Строка формата

Строки формата состоят из символов, перемежающихся с спецификациями формата. Символы просто копируются на вывод (например, putc) после любого необходимого преобразования в соответствующую последовательность UTF-8.

Строка формата имеет следующий грамматический синтаксис:

FormatString:
    FormatStringItem*
FormatStringItem:
    '%%'
    '%' Position Flags Width Separator Precision FormatChar
    '%(' FormatString '%)'
    '%-(' FormatString '%)'
    OtherCharacterExceptPercent
Position:
    empty
    Integer '$'
Flags:
    empty
    '-' Flags
    '+' Flags
    '#' Flags
    '0' Flags
    ' ' Flags
Width:
    empty
    Integer
    '*'
Separator:
    empty
    ','
    ',' '?'
    ',' '*' '?'
    ',' Integer '?'
    ',' '*'
    ',' Integer
Precision:
    empty
    '.'
    '.' Integer
    '.*'
Integer:
    Digit
    Digit Integer
Digit:
    '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
FormatChar:
    's'|'c'|'b'|'d'|'o'|'x'|'X'|'e'|'E'|'f'|'F'|'g'|'G'|'a'|'A'|'|'

Флаги влияют на форматирование в зависимости от спецификатора следующим образом.

Флаг	Затронутые типы	Семантика
'-'	числовые, bool, null, char, string, enum, указатель	Выравнивает результат слева в поле. Это переопределяет любой флаг 0.
'+'	числовые	Представляет положительные числа в формате со знаком префиксом +. Это переопределяет любой флаг пробела.
'#'	целочисленные ('o')	Добавляет к точности, если необходимо, чтобы первая цифра форматирования в восьмеричной форме была '0', даже если и аргумент, и Точность равны нулю.
'#'	целочисленные ('x', 'X')	Если не ноль, предваряет результат 0x (0X).
'#'	плавающие	Всегда вставляет десятичную точку и печатает хвостовые нули.
'0'	числовые	Использует ведущие нули для заполнения вместо пробелов (за исключением значений с плавающей точкой nan и infinity). Игнорируется, если задана Точность.
' '	числовые	Представляет положительные числа в формате со знаком префиксом пробелом.

Ширина

Используется только для числовых, bool, null, char, string, enum и указатель типов. Указывает минимальную ширину поля. Если ширина равна *, дополнительный аргумент типа int, предшествующий фактическому аргументу, используется как ширина. Если ширина отрицательная, это эквивалентно тому, что символ - был задан как символ Флаги.

Точность

Определяет точность числовых преобразований. Если точность равна *, дополнительный аргумент типа int, предшествующий фактическому аргументу, используется как точность. Если она отрицательная, это эквивалентно отсутствию спецификатора Точности.

Разделитель

Вставляет разделительные символы ',', каждые X цифр справа налево, в числовые значения для повышения читабельности. Для дробной части значений с плавающей точкой разделитель вставляется слева направо. Ввод целого числа после ',' позволяет указать X. Если после ',' вставлен '*', тогда X задается дополнительным параметром функции форматирования. Добавление '?' после ',' или спецификатора X позволяет указать разделительный символ как дополнительный параметр.

FormatChar

's'

Соответствующий аргумент форматируется так, как это согласуется с его типом:

bool

Результат — "true" или "false".

целочисленные типы

Используется формат %d.

типы с плавающей точкой

Используется формат %g.

строковые типы

Результат — строка, преобразованная в UTF-8. Точность задает максимальное количество символов для использования в результате.

структуры

Если структура определяет метод toString(), результат — строка, возвращаемая этой функцией. В противном случае результат — StructName(field₀, field₁, ...), где field_n — n-й элемент, отформатированный с помощью стандартного формата.

классы, производные от Object

Результат — строка, возвращаемая методом .toString() экземпляра класса. Точность задает максимальное количество символов для использования в результате.

объединения

Если объединение определяет метод toString(), результат — строка, возвращаемая этой функцией. В противном случае результатом является имя объединения без его содержимого.

статические и динамические массивы, не являющиеся строками

Результат — [s₀, s₁, ...], где s_n — n-й элемент, отформатированный с помощью стандартного формата.

ассоциативные массивы

Результат — эквивалент того, как бы выглядел инициализатор для содержимого ассоциативного массива, например: ["red" : 10, "blue" : 20].

'c'

Соответствующий аргумент должен быть типом символа.

'b','d','o','x','X'

Соответствующий аргумент должен быть целочисленного типа и форматируется как целое число. Если аргумент — тип со знаком, а FormatChar — d, он преобразуется в строку символов со знаком, в противном случае он рассматривается как беззнаковый. Аргумент типа bool форматируется как '1' или '0'. Использованная основа — двоичная для b, восьмеричная для o, десятичная для d и шестнадцатеричная для x или X. x форматирует с использованием строчных букв, X — прописных. Если полученных цифр меньше, чем Точность, то используются ведущие нули по мере необходимости. Если Точность равна 0, и число равно 0, цифр не получается.

'e','E'

Число с плавающей точкой форматируется как одна цифра перед десятичной точкой, Точность цифр после, FormatChar, ±, за которым следует по крайней мере двухзначный показатель: d.dddddde±dd. Если Точность не задана, генерируется шесть цифр после десятичной точки. Если Точность равна 0, десятичная точка не генерируется.

'f','F'

Число с плавающей точкой форматируется в десятичной форме. Точность определяет количество цифр, генерируемых после десятичной точки. По умолчанию — шесть. По крайней мере, одна цифра генерируется перед десятичной точкой. Если Точность равна нулю, десятичная точка не генерируется.

'g','G'

Число с плавающей точкой форматируется либо в формате e, либо в f для g; E или F для G. Формат f используется, если показатель для формата e больше -5 и меньше Точности. Точность задает количество значащих цифр и по умолчанию равна шести. Хвостовые нули опускаются после десятичной точки, если дробная часть равна нулю, тогда десятичная точка не генерируется.

'a','A'

Число с плавающей точкой форматируется в шестнадцатеричной экспоненциальной форме 0xh.hhhhhhp±d. Перед десятичной точкой стоит одна шестнадцатеричная цифра, а после — столько же, сколько задано Точностью. Если Точность равна нулю, десятичная точка не генерируется. Если Точность не задана, генерируется столько шестнадцатеричных цифр, сколько необходимо для точного представления мантиссы. Показатель записывается как можно меньше цифр, но по крайней мере одна, десятичная и представляет собой степень двойки, как в h.hhhhhh*2^±d. Показатель для нуля равен нулю. Шестнадцатеричные цифры x и p записываются заглавными буквами, если FormatChar — заглавными.

NaN числа с плавающей точкой форматируются как nan, если FormatChar строчная, или NAN, если прописная. Бесконечности чисел с плавающей точкой форматируются как inf или infinity, если FormatChar строчная, или INF или INFINITY, если прописная. Позиционные и непозиционные стили могут быть смешаны в одной строке формата. (POSIX оставляет это поведение неопределенным.) Внутренний счетчик для непозиционных параметров отслеживает следующий параметр после наибольшего уже использованного позиционного параметра. Пример использования форматирования массивов и вложенных массивов:

import std.stdio;

void main()
{
    writefln("My items are %(%s %).", [1,2,3]);
    writefln("My items are %(%s, %).", [1,2,3]);
}

Вывод:

My items are 1 2 3.
My items are 1, 2, 3.

Завершающая часть строки формата после спецификатора для каждого элемента интерпретируется как разделитель массива, и поэтому опускается после последнего элемента массива. Разделитель %| может использоваться для указания начала разделителя, так что часть строки формата перед ним сохраняется в последнем элементе массива:

import std.stdio;

void main()
{
    writefln("My items are %(-%s-%|, %).", [1,2,3]);
}

что дает вывод:

My items are -1-, -2-, -3-.

Эти составные спецификаторы формата могут быть вложены в случае аргумента вложенного массива:

import std.stdio;
void main() {
     auto mat = [[1, 2, 3],
                 [4, 5, 6],
                 [7, 8, 9]];

     writefln("%(%(%d %)\n%)", mat);
     writeln();

     writefln("[%(%(%d %)\n %)]", mat);
     writeln();

     writefln("[%([%(%d %)]%|\n %)]", mat);
     writeln();
}

Вывод:

1 2 3
4 5 6
7 8 9


[1 2 3
 4 5 6
 7 8 9]


[[1 2 3]
 [4 5 6]
 [7 8 9]]

Внутри составного спецификатора формата строки и символы экранируются автоматически. Чтобы избежать этого поведения, добавьте флаг - к "%(".

import std.stdio;

void main()
{
    writefln("My friends are %s.", ["John", "Nancy"]);
    writefln("My friends are %(%s, %).", ["John", "Nancy"]);
    writefln("My friends are %-(%s, %).", ["John", "Nancy"]);
}

что дает вывод:

My friends are ["John", "Nancy"].
My friends are "John", "Nancy".
My friends are John, Nancy.

Примеры:

Строка формата может быть проверена во время компиляции (см. format для подробностей):

import std.array : appender;

auto writer = appender!string();
writer.formattedWrite!"%s is the ultimate %s."(42, "answer");
writeln(writer.data); // "42 is the ultimate answer."

// Clear the writer
writer = appender!string();
formattedWrite(writer, "Date: %2$s %1$s", "October", 5);
writeln(writer.data); // "Date: 5 October"

Примеры:

writeln(format("%,d", 1000)); // "1,000"
writeln(format("%,f", 1234567.891011)); // "1,234,567.891011"
writeln(format("%,?d", '?', 1000)); // "1?000"
writeln(format("%,1d", 1000)); // "1,0,0,0"
writeln(format("%,*d", 4, -12345)); // "-1,2345"
writeln(format("%,*?d", 4, '_', -12345)); // "-1_2345"
writeln(format("%,6?d", '_', -12345678)); // "-12_345678"
assert(format("%12,3.3f", 1234.5678) == "   1,234.568", "'" ~
        format("%12,3.3f", 1234.5678) ~ "'");

uint formattedRead(alias fmt, R, S...)(auto ref R r, auto ref S args)
Constraints: if (isSomeString!(typeof(fmt)));

uint formattedRead(R, Char, S...)(auto ref R r, const(Char)[] fmt, auto ref S args);

Читает символы из входного диапазона r, преобразует их в соответствии с fmt, и записывает их в args.

Параметры:

R r	Диапазон для чтения.
const(Char)[] fmt	Формат данных для чтения.
S args	Поток данных для записи.

Возвращает:

При успешном выполнении функция возвращает количество заполненных переменных. Это значение может совпадать с ожидаемым количеством чтений или быть меньше, вплоть до нуля, если произошла ошибка сопоставления.

Выбрасывает:

Исключение FormatException если S.length == 0 и fmt содержат спецификаторы формата.

Примеры:

Строка формата может быть проверена во время компиляции (см. format для подробностей):

string s = "hello!124:34.5";
string a;
int b;
double c;
s.formattedRead!"%s!%s:%s"(a, b, c);
assert(a == "hello" && b == 124 && c == 34.5);

struct FormatSpec(Char) if (is(Unqual!Char == Char));

Общий обработчик для printf стилей спецификаторов формата. Используется для построения более специфических функций форматирования.

Примеры:

import std.array;
auto a = appender!(string)();
auto fmt = "Number: %6.4e\nString: %s";
auto f = FormatSpec!char(fmt);

writeln(f.writeUpToNextSpec(a)); // true

writeln(a.data); // "Number: "
writeln(f.trailing); // "\nString: %s"
writeln(f.spec); // 'e'
writeln(f.width); // 6
writeln(f.precision); // 4

writeln(f.writeUpToNextSpec(a)); // true

writeln(a.data); // "Number: \nString: "
writeln(f.trailing); // ""
writeln(f.spec); // 's'

writeln(f.writeUpToNextSpec(a)); // false
writeln(a.data); // "Number: \nString: "

int width;

Минимальная ширина, по умолчанию 0.

int precision;

Точность. Ее семантика зависит от типа аргумента. Для чисел с плавающей точкой точность определяет количество десятичных знаков, печатаемых.

int separators;

Количество цифр, печатаемых между разделителями.

int separatorCharPos;

Устанавливается в DYNAMIC когда символ-разделитель задается во время выполнения.

dchar separatorChar;

Символ, вставляемый между цифрами.

enum int DYNAMIC;

Специальное значение для ширины и точности. DYNAMIC ширина или точность означает, что они были указаны с '*' в строке формата и передаются во время выполнения через varargs.

enum int UNSPECIFIED;

Специальное значение для точности, означающее, что спецификатор формата не содержал явной точности.

char spec;

Фактический спецификатор формата, 's' по умолчанию.

ubyte indexStart;

Индекс аргумента для позиционных параметров, от 1 до ubyte.max. (0 означает не используется).

ubyte indexEnd;

Индекс последнего аргумента для диапазона позиционных параметров, от 1 до ubyte.max. (0 означает не используется).

bool flDash;

Спецификатор формата содержал '-' (совместимость с printf).

bool flZero;

Спецификатор формата содержал '0' (совместимость с printf).

bool flSpace;

Спецификатор формата содержал ' ' (совместимость с printf).

bool flPlus;

Спецификатор формата содержал '+' (совместимость с printf).

bool flHash;

Спецификатор формата содержал '#' (совместимость с printf).

bool flSeparator;

Спецификатор формата содержал ','

const(Char)[] nested;

В случае составного спецификатора формата, начинающегося с "%(" и заканчивающегося "%)", _nested содержит строку, находящуюся между двумя разделителями.

const(Char)[] sep;

В случае составного спецификатора формата, _sep содержит строку, расположенную после "%|". sep is null означает отсутствие разделителя, иначе sep.empty означает разделитель длиной 0.

const(Char)[] trailing;

_trailing содержит остаток строки формата.

pure @safe this(in Char[] fmt);

Создает новый FormatSpec используя строку формата fmt, никакой обработки не производится до тех пор, пока не потребуется.

scope bool writeUpToNextSpec(OutputRange)(ref OutputRange writer);

Записывает строку формата в выходной диапазон до тех пор, пока не будет найден следующий спецификатор формата, и анализирует этот спецификатор.

См. FormatSpec для примера, как использовать writeUpToNextSpec.

Параметры:

OutputRange writer

выходной диапазон

Возвращает:

Истина, когда найден спецификатор формата.

Выбрасывает:

FormatException когда найденный спецификатор формата не может быть проанализирован.

const pure @safe string toString();

const void toString(OutputRange)(ref OutputRange writer)
Constraints: if (isOutputRange!(OutputRange, char));

Возвращает строку, содержащую все переменные члена на отдельной строке.

Параметры:

OutputRange writer

Выходной диапазон, принимающий тип output range

Возвращает:

Строку, когда не используется выходной диапазон; выходной диапазон в противном случае.

FormatSpec!Char singleSpec(Char)(Char[] fmt);

Вспомогательная функция, возвращающая FormatSpec для одного спецификатора, заданного в fmt.

Параметры:

Char[] fmt

Спецификатор формата.

Возвращает:

FormatSpec со спецификатором, проанализированным.

Выбрасывает:

FormatException когда задано более одного спецификатора или спецификатор имеет неправильный формат.

Примеры:

import std.exception : assertThrown;
auto spec = singleSpec("%2.3e");

writeln(spec.trailing); // ""
writeln(spec.spec); // 'e'
writeln(spec.width); // 2
writeln(spec.precision); // 3

assertThrown!FormatException(singleSpec(""));
assertThrown!FormatException(singleSpec("2.3e"));
assertThrown!FormatException(singleSpec("%2.3eTest"));

void formatValue(Writer, T, Char)(auto ref Writer w, auto ref T val, ref scope const FormatSpec!Char f);

Форматирует любое значение в Char, принимая OutputRange, используя заданный FormatSpec.

Агрегаты

struct, union, class, и interface форматируются вызовом toString.

toString должно иметь одну из следующих сигнатур:

void toString(W)(ref W w, scope const ref FormatSpec fmt)
void toString(W)(ref W w)
string toString();

Где W — это диапазон вывода, который принимает символы. Тип шаблона не обязательно должен называться W. Следующие перегрузки также принимаются по соображениям обратной совместимости или для использования в виртуальных функциях. Рекомендуется, чтобы любой новый код отказывался от этих перегрузок, если это возможно, для повышения скорости и принятия атрибутов.

void toString(scope void delegate(const(char)[]) sink, const ref FormatSpec fmt);
void toString(scope void delegate(const(char)[]) sink, string fmt);
void toString(scope void delegate(const(char)[]) sink);

Для объектов класса, имеющих интерфейс диапазона ввода,

• Если экземпляр toString переопределил Object.toString, он используется.
• В противном случае объекты форматируются как диапазон ввода.

Для объектов struct и union, у которых нет toString,

• Если у них есть интерфейс диапазона, они форматируются как диапазон ввода.
• В противном случае они форматируются как Type(field1, filed2, ...).

В противном случае, форматируются просто как имя их типа.

Параметры:

Писатель w	Диапазон вывода для записи.
T val	Значение для записи.
FormatSpec!Char f	std.format.FormatSpec, определяющий, как записать значение.

Примеры:

Следующий код сравнивает использование formatValue и formattedWrite.

import std.array : appender;

auto writer1 = appender!string();
writer1.formattedWrite("%08b", 42);

auto writer2 = appender!string();
auto f = singleSpec("%08b");
writer2.formatValue(42, f);

assert(writer1.data == writer2.data && writer1.data == "00101010");

Примеры:

bool форматируются как "true" или "false" с %s и как 1 или 0 с целочисленными спецификациями формата.

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
formatValue(w, true, spec);

writeln(w.data); // "true"

Примеры:

Литтерал null форматируется как "null".

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
formatValue(w, null, spec);

writeln(w.data); // "null"

Примеры:

Целые числа форматируются как в core.stdc.stdio.printf.

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%d");
formatValue(w, 1337, spec);

writeln(w.data); // "1337"

Примеры:

Значения с плавающей точкой форматируются как в core.stdc.stdio.printf

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%.1f");
formatValue(w, 1337.7, spec);

writeln(w.data); // "1337.7"

Примеры:

Отдельные символы (char, wchar, or dchar`) форматируются как символы Юникода с %s и как целые числа с целочисленными спецификациями формата.

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%c");
formatValue(w, 'a', spec);

writeln(w.data); // "a"

Примеры:

Строки форматируются как в core.stdc.stdio.printf

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
formatValue(w, "hello", spec);

writeln(w.data); // "hello"

Примеры:

Массивы статического размера форматируются как динамические массивы.

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
char[2] two = ['a', 'b'];
formatValue(w, two, spec);

writeln(w.data); // "ab"

Примеры:

Динамические массивы форматируются как диапазоны ввода. Специализации:

• void[] форматируется как ubyte[].
• Массив const преобразуется в диапазон ввода путем удаления его квалификатора.

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
auto two = [1, 2];
formatValue(w, two, spec);

writeln(w.data); // "[1, 2]"

Примеры:

Ассоциативные массивы форматируются с использованием ':' и ", " в качестве разделителей и заключены в '[' и ']'.

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");
auto aa = ["H":"W"];
formatValue(w, aa, spec);

writeln(w.data); // "[\"H\":\"W\"]"

Примеры:

enum форматируются как их базовое значение

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");

enum A { first, second, third }

formatValue(w, A.second, spec);

writeln(w.data); // "second"

Примеры:

Форматирование структуры путем определения метода toString, который принимает диапазон вывода. Рекомендуется, чтобы любой toString использующий диапазоны вывода использовал std.range.primitives.put, а не метод диапазона напрямую.

import std.array : appender;
import std.range.primitives;

static struct Point
{
    int x, y;

    void toString(W)(ref W writer, scope const ref FormatSpec!char f)
    if (isOutputRange!(W, char))
    {
        // std.range.primitives.put
        put(writer, "(");
        formatValue(writer, x, f);
        put(writer, ",");
        formatValue(writer, y, f);
        put(writer, ")");
    }
}

auto w = appender!string();
auto spec = singleSpec("%s");
auto p = Point(16, 11);

formatValue(w, p, spec);
writeln(w.data); // "(16,11)"

Примеры:

Еще один пример форматирования struct с определенным toString, на этот раз с использованием метода scope delegate. Этот метод теперь не рекомендуется для невиртуальных функций. По возможности, пожалуйста, используйте метод диапазона вывода вместо него.

static struct Point
{
    int x, y;

    void toString(scope void delegate(scope const(char)[]) @safe sink,
                  scope const FormatSpec!char fmt) const
    {
        sink("(");
        sink.formatValue(x, fmt);
        sink(",");
        sink.formatValue(y, fmt);
        sink(")");
    }
}

auto p = Point(16,11);
writeln(format("%03d", p)); // "(016,011)"
writeln(format("%02x", p)); // "(10,0b)"

Примеры:

Указатели форматируются как шестнадцатеричные целые числа.

import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");

auto q = cast(void*) 0xFFEECCAA;
formatValue(w, q, spec);

writeln(w.data); // "FFEECCAA"

Примеры:

Вектора SIMD форматируются как массивы.

import core.simd;
import std.array : appender;
auto w = appender!string();
auto spec = singleSpec("%s");

static if (is(float4))
{
    version (X86) {}
    else
    {
        float4 f4;
        f4.array[0] = 1;
        f4.array[1] = 2;
        f4.array[2] = 3;
        f4.array[3] = 4;

        formatValue(w, f4, spec);
        writeln(w.data); // "[1, 2, 3, 4]"
    }
}

Примеры:

Делегаты форматируются ReturnType delegate(Parameters) FunctionAttributes

import std.conv : to;

int i;

int foo(short k) @nogc
{
    return i + k;
}

@system int delegate(short) @nogc bar() nothrow pure
{
    int* p = new int(1);
    i = *p;
    return &foo;
}

writeln(to!string(&bar)); // "int delegate(short) @nogc delegate() pure nothrow @system"
writeln(() @trusted
{ return bar()(3);
}()); // 4

T unformatValue(T, Range, Char)(ref Range input, ref scope const FormatSpec!Char spec);

Читает значение из заданного диапазона ввода в соответствии со спецификацией и возвращает его как тип T.

Параметры:

T	тип для возврата
Range input	диапазон ввода для чтения
FormatSpec!Char spec	FormatSpec для использования при чтении из input

Возвращает:

Значение из input типа T

Исключения:

FormatException если spec не может прочитать тип T

См. также:

std.conv.parse и std.conv.to

Примеры:

Булевы значения

auto str = "false";
auto spec = singleSpec("%s");
writeln(unformatValue!bool(str, spec)); // false

str = "1";
spec = singleSpec("%d");
assert(unformatValue!bool(str, spec));

Примеры:

Нулевые значения

auto str = "null";
auto spec = singleSpec("%s");
writeln(str.unformatValue!(typeof(null))(spec)); // null

Примеры:

Целые значения

auto str = "123";
auto spec = singleSpec("%s");
writeln(str.unformatValue!int(spec)); // 123

str = "ABC";
spec = singleSpec("%X");
writeln(str.unformatValue!int(spec)); // 2748

str = "11610";
spec = singleSpec("%o");
writeln(str.unformatValue!int(spec)); // 5000

Примеры:

Числа с плавающей точкой

import std.math : approxEqual;

auto str = "123.456";
auto spec = singleSpec("%s");
assert(str.unformatValue!double(spec).approxEqual(123.456));

Примеры:

Диапазоны символов ввода

auto str = "aaa";
auto spec = singleSpec("%s");
writeln(str.unformatValue!char(spec)); // 'a'

// Using a numerical format spec reads a Unicode value from a string
str = "65";
spec = singleSpec("%d");
writeln(str.unformatValue!char(spec)); // 'A'

str = "41";
spec = singleSpec("%x");
writeln(str.unformatValue!char(spec)); // 'A'

str = "10003";
spec = singleSpec("%d");
writeln(str.unformatValue!dchar(spec)); // '✓'

Примеры:

Массивы и статические массивы

string str = "aaa";
auto spec = singleSpec("%s");
writeln(str.unformatValue!(dchar[])(spec)); // "aaa"d

str = "aaa";
spec = singleSpec("%s");
dchar[3] ret = ['a', 'a', 'a'];
writeln(str.unformatValue!(dchar[3])(spec)); // ret

str = "[1, 2, 3, 4]";
spec = singleSpec("%s");
writeln(str.unformatValue!(int[])(spec)); // [1, 2, 3, 4]

str = "[1, 2, 3, 4]";
spec = singleSpec("%s");
int[4] ret2 = [1, 2, 3, 4];
writeln(str.unformatValue!(int[4])(spec)); // ret2

Примеры:

Ассоциативные массивы

auto str = `["one": 1, "two": 2]`;
auto spec = singleSpec("%s");
writeln(str.unformatValue!(int[string])(spec)); // ["one":1, "two":2]

typeof(fmt) format(alias fmt, Args...)(Args args)
Constraints: if (isSomeString!(typeof(fmt)));

immutable(Char)[] format(Char, Args...)(in Char[] fmt, Args args)
Constraints: if (isSomeChar!Char);

Форматирует аргументы в строку.

Если строка формата фиксирована, передача ее в качестве параметра шаблона проверяет правильность типов параметров во время компиляции. Это также может привести к улучшению производительности.

Параметры:

Char[] fmt	Строка формата. Для подробной спецификации см. formattedWrite.
Args args	Переменная последовательность аргументов для форматирования в возвращаемую строку.

Исключения:

если количество аргументов не соответствует количеству параметров формата и наоборот.

Примеры:

Проверка типа может быть выполнена, когда fmt известен во время компиляции:

auto s = format!"%s is %s"("Pi", 3.14);
writeln(s); // "Pi is 3.14"

static assert(!__traits(compiles, {s = format!"%l"();}));     // missing arg
static assert(!__traits(compiles, {s = format!""(404);}));    // surplus arg
static assert(!__traits(compiles, {s = format!"%d"(4.03);})); // incompatible arg

char[] sformat(alias fmt, Args...)(char[] buf, Args args)
Constraints: if (isSomeString!(typeof(fmt)));

char[] sformat(Char, Args...)(return scope char[] buf, scope const(Char)[] fmt, Args args);

Форматирует аргументы в буфер buf, который должен быть достаточно большим, чтобы вместить результат.

Возвращает:

Срез buf, содержащий отформатированную строку.

Исключения:

RangeError если buf недостаточно велик, чтобы вместить отформатированную строку. FormatException, если длина args отличается от количества спецификаторов формата в fmt.

Примеры:

Строка формата может быть проверена на этапе компиляции (см. format для подробностей):

char[10] buf;

writeln(buf[].sformat!"foo%s"('C')); // "fooC"
writeln(sformat(buf[], "%s foo", "bar")); // "bar foo"