Функция Format. Строки форматирования.

В Delphi существует группа функций форматирования строк. Их рассмотрение начнем с наиболее часто встречающегося представителя — функции Format:

function Format (const Format: string; const Args: array of const): string;

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

Второй параметр функции Format называется списком аргументов. Он и со­держит "вставляемые" в форматирующую строку параметры. Обратите внимение, что этот открытый массив имеет тип array of const. и в нем может передаваться переменное число разнотипных параметров. Например, после выполнения

S:= FormatC Product %s, version %d.%d', [ 'Borland Delphi', 1, 0]);

строке S будет присвоено • Product Borland Delphi, version 1.0'. Рассмотрим подробнее правила, по которьм составляется форматирующая строка.

"Специальные" места в ней называются спецификаторами формата и пред­ставляют собой следующие конструкции

"%" [index":"] ["-"I [width] ["."prec] type

где обозначены:

• символ -%", с которого начинаются все спецификаторы формата (обяза­тельный);
• поле индекса аргумента [ index ": " ] (необязательное);
• признак выравнивания по левому краю ["-"I (необязательный);
• поле ширины [width] (необязательное);
• поле точности [ -. - prec ] (необязательное);
• символ типа преобразования type (обязательный).

Каждый спецификатор формата соответствует как минимум одному из эле­ментов списка аргументов и определяет, как именно рассматривать его и преобразовывать в строку.

Функция Format поддерживает следующие символы типа преобразования:

Символ	Тип	Что означает
d	Десятичный	Элемент должен быть целым числом и преобразуется в строку десятичных цифр. Если при символе есть поле точности, то в выходной строке будет минимум ргес цифр; если при преобразовании числа их потребуется меньше, то строка дополняется слева нулями.
х	Шестнадца­тиричный	Как тип d, но элемент преобразуется в строку шестнад­цатиричных цифр.
е	Научный	Элемент должен быть числом с плавающей точкой. Он преобразуется к нормализованному виду -d.dddE+ddd. Перед десятичной точкой всегда находится одна цифра (при необходимости, с минусом). После символа "Е" идет показатель степени, имеющий знак и состоящий не менее чем из 3 цифр. Общее число символов в представлении числа определяется полем ргес (по умолчанию 15).
f	Фиксиро­ванный	Элемент должен быть числом с плавающей точкой. Он преобразуется к виду -ddd.ddd. Поле ргес означает количество цифр после десятичной точки (по умолчанию 2).
д	Обобщенный	Элемент должен быть числом с плавающей точкой. Он пре­образуется к одному из двух вышеперечисленных видов — выбирается тот, который обеспечивает более короткую запись. Если требуемое число цифр слева от десятичной точки меньше значения поля ширины и само число больше 10", применяется фиксированный тип. Удаляются все впереди идущие нули, десятичная точка (при возможности), а также символы, разделяющие строку на группы по три цифры.
п m	Числовой Денежный	Совпадает с типом f за исключением того, что после каждой группы из трех цифр ставятся разделительные символы:d,ddd, ddd.ddd....Элемент должен быть числом с плавающей точкой, отража­ющей денежную сумму. Способ ее представления зависит от значений глобальных констант, определенных в модуле SYSUTILS (см. ниже). В свою очередь, они зависят от на­стройки Windows на обозначения, принятые в данной стране.
Р	Указатель	Элемент должен быть указателем. На выходе он будет пред­ставлять из себя строку шестнадцатиричных цифр видаХХХХ: YYYY, где ХХХХ — селектор, YYYY — смещение.
s	Строка	Элемент может иметь тип string, PChar или быть отдель­ным символом (Char). Эта строка (или символ) вставляются вместо спецификатора формата. Если присутствует поле ргес и длина строки больше его значения, то она усекается.

 

Примечания:

1. Форматирующие символы можно задавать как в верхнем, так и в нижнем регистрах.

2. Тип преобразования m (денежный) тесно связан с правилами представления, принятыми в конкретной стране. Для этого в модуле SYSUTILS определены значения ряда типизированных констант, начальные значения которых бе­рутся из секции [Inti] файла WIN.INI. Вы можете изменять их значения в соответствии с вашими потребностями:

Имя и тип	Что означает
CurrencyString: string[7];	Символ (или символы), добавляемые к строке с представлением денежной суммы и обозначающие национальную денежную единицу. Это может быть, например, '$', 'DM' или 'руб'.
CurrencyFormat: Byte;	Определяет способ добавления знака денежной единицы к строке. Число 1 будет преобразовано так в зависимости от значения этого параметра: '$!' при 0; '1$' при 1; '$ Г при 2; '1 $' при 3.
NegCurrFormat: Byte;	Определяет способ добавления знака денежной единицы и минуса к строке в том случае, если проис­ходит преобразование отрицательного числа (к поло­жительным числам отношения не имеет). Число -1 будет преобразовано так в зависимости от значения этого параметра: '($!)' при 0; '-$!' при 1; '$-1' при 2; '$!-' при 3; '(!$)' при 4; '-!$' при 5; 'i-$' при 6; '!$-' при 7; '-1 $' при 8; '-$ Г при 9; '$ 1-' при 10.
CurrencyDecimals: Byte;	Число знаков после запятой в представлении денежных сумм. Например, число 10.15 при разных значениях этого параметра отобразится так: '$10' при 0, '$10.15' при 2, '$10.1500' при 4.
ThousandSeparator: Char;	Символ, разделяющий строку на группы по три циф­ры справа налево (разделитель тысяч). Применяется, в частности, в типе преобразования п.
DecimalSeparator: Char;	Символ, отделяющий дробную часть числа от целой.

Мы закончили рассмотрение символа типа преобразования. Рассмотрим осталь­ные составные части спецификатора формата.

Поле ширины устанавливает минимально допустимое количество символов в преобразованной строке. Это означает, что если она короче, чем задано в этом поле, то происходит добавление пробелов до требуемого количества. По умолчанию пробелы добавляются спереди (выравнивание по правому краю), но признак выравнивания по левому краю ("-"; он должен стоять перед полем ширины) позволяет выравнивать строку по-иному.

Поле индекса позволяет динамически изменить последовательность извлечения аргументов из массива. Обычно аргументы извлекаются последовательно, по мере их востребования спецификаторами формата. Поле индекса означает, что следующим нужно извлечь аргумент с данным индексом. Пользуясь индексом, одни и те же аргументы могут быть использованы многократно. Например, вызов Format (' %s %s %0: s %s ', [ 'Yes', 'No' ]) Даст на выходе строку 'Yes No Yes No'.

Поле точности играет разную роль в зависимости от того, с каким типом преобразования применяется. Его особенности приведены вместе с описанием типа (с теми из них, где оно имеет смысл).

Поля индекса, ширины и точности могут быть заданы напрямую или косвенно. Первый способ подразумевает явное указание значения поля (например, ' %10. 5f '). Для косвенного задания значений нужно в соответствующих местах цифры заменить звездочками (например, '%*.*f'). В этом случае вместо звездочек будут подставлены следующие значения из списка аргументов (они обязательно должны быть целыми числами). Например, выражение

Format('Value is %*.*',[10,5, 2.718]);

эквивалентно:

Format('Value is %10.5',[2.718]);

Как уже упоминалось, наиболее употребимой функцией из группы фор­матирующих является Format, которая работает со строками типа string и максимально освобождает программиста от рутинной работы. Другие функции используют то же ядро и правила преобразования, но отличаются параметрами:

procedure FmtStr(var Result: string; const Format: string; const Args: array of const);	To же, что и Format, но оформлено в виде процедуры. Результат преобразо­вания возвращается в параметре Result.
function StrFmt(Buffer, Format: PChar; const Args: array of const): PChar;	Форматирующая строка должна нахо­диться в параметре Format, а резуль­тирующая помещается в буфер Buffer (он должен иметь нужную длину). Функция возвращает указатель на Buffer.
function StrLFmt(Buffer: PChar; MaxLen: Cardinal; Format: PChar; const Args: array of const): PChar;	Работает как StrFmt, но длина резуль­тирующей строки не будет превышать MaxLen символов.
function FormatBuf(var Buffer; BufLen: Cardinal; const Format; FmtLen: Cardinal; const Args: array of const): Cardinal;	Форматирующая строка находится в бу­фере Format длиной FmtLen, a результирующая — в буфере Buffer длиной BufLen. Функция возвращает число реально помещенных в Buffer символов, причем оно всегда меньше или равно BufLen.

(Ксю)

В Delphi существует группа функций форматирования строк. Их рассмотрение начнем с наиболее часто встречающегося представителя — функции Format:

function Format (const Format: string; const Args: array of const): string;

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

Второй параметр функции Format называется списком аргументов. Он и со­держит "вставляемые" в форматирующую строку параметры. Обратите внимение, что этот открытый массив имеет тип array of const. и в нем может передаваться переменное число разнотипных параметров. Например, после выполнения

S:= FormatC Product %s, version %d.%d', [ 'Borland Delphi', 1, 0]);

строке S будет присвоено • Product Borland Delphi, version 1.0'. Рассмотрим подробнее правила, по которьм составляется форматирующая строка.

"Специальные" места в ней называются спецификаторами формата и пред­ставляют собой следующие конструкции

"%" [index":"] ["-"I [width] ["."prec] type

где обозначены:

• символ -%", с которого начинаются все спецификаторы формата (обяза­тельный);
• поле индекса аргумента [ index ": " ] (необязательное);
• признак выравнивания по левому краю ["-"I (необязательный);
• поле ширины [width] (необязательное);
• поле точности [ -. - prec ] (необязательное);
• символ типа преобразования type (обязательный).

Каждый спецификатор формата соответствует как минимум одному из эле­ментов списка аргументов и определяет, как именно рассматривать его и преобразовывать в строку.

Функция Format поддерживает следующие символы типа преобразования:

Символ	Тип	Что означает
d	Десятичный	Элемент должен быть целым числом и преобразуется в строку десятичных цифр. Если при символе есть поле точности, то в выходной строке будет минимум ргес цифр; если при преобразовании числа их потребуется меньше, то строка дополняется слева нулями.
х	Шестнадца­тиричный	Как тип d, но элемент преобразуется в строку шестнад­цатиричных цифр.
е	Научный	Элемент должен быть числом с плавающей точкой. Он преобразуется к нормализованному виду -d.dddE+ddd. Перед десятичной точкой всегда находится одна цифра (при необходимости, с минусом). После символа "Е" идет показатель степени, имеющий знак и состоящий не менее чем из 3 цифр. Общее число символов в представлении числа определяется полем ргес (по умолчанию 15).
f	Фиксиро­ванный	Элемент должен быть числом с плавающей точкой. Он преобразуется к виду -ddd.ddd. Поле ргес означает количество цифр после десятичной точки (по умолчанию 2).
д	Обобщенный	Элемент должен быть числом с плавающей точкой. Он пре­образуется к одному из двух вышеперечисленных видов — выбирается тот, который обеспечивает более короткую запись. Если требуемое число цифр слева от десятичной точки меньше значения поля ширины и само число больше 10", применяется фиксированный тип. Удаляются все впереди идущие нули, десятичная точка (при возможности), а также символы, разделяющие строку на группы по три цифры.
п m	Числовой Денежный	Совпадает с типом f за исключением того, что после каждой группы из трех цифр ставятся разделительные символы:d,ddd, ddd.ddd....Элемент должен быть числом с плавающей точкой, отража­ющей денежную сумму. Способ ее представления зависит от значений глобальных констант, определенных в модуле SYSUTILS (см. ниже). В свою очередь, они зависят от на­стройки Windows на обозначения, принятые в данной стране.
Р	Указатель	Элемент должен быть указателем. На выходе он будет пред­ставлять из себя строку шестнадцатиричных цифр видаХХХХ: YYYY, где ХХХХ — селектор, YYYY — смещение.
s	Строка	Элемент может иметь тип string, PChar или быть отдель­ным символом (Char). Эта строка (или символ) вставляются вместо спецификатора формата. Если присутствует поле ргес и длина строки больше его значения, то она усекается.

 

Примечания:

1. Форматирующие символы можно задавать как в верхнем, так и в нижнем регистрах.

2. Тип преобразования m (денежный) тесно связан с правилами представления, принятыми в конкретной стране. Для этого в модуле SYSUTILS определены значения ряда типизированных констант, начальные значения которых бе­рутся из секции [Inti] файла WIN.INI. Вы можете изменять их значения в соответствии с вашими потребностями:

Имя и тип	Что означает
CurrencyString: string[7];	Символ (или символы), добавляемые к строке с представлением денежной суммы и обозначающие национальную денежную единицу. Это может быть, например, '$', 'DM' или 'руб'.
CurrencyFormat: Byte;	Определяет способ добавления знака денежной единицы к строке. Число 1 будет преобразовано так в зависимости от значения этого параметра: '$!' при 0; '1$' при 1; '$ Г при 2; '1 $' при 3.
NegCurrFormat: Byte;	Определяет способ добавления знака денежной единицы и минуса к строке в том случае, если проис­ходит преобразование отрицательного числа (к поло­жительным числам отношения не имеет). Число -1 будет преобразовано так в зависимости от значения этого параметра: '($!)' при 0; '-$!' при 1; '$-1' при 2; '$!-' при 3; '(!$)' при 4; '-!$' при 5; 'i-$' при 6; '!$-' при 7; '-1 $' при 8; '-$ Г при 9; '$ 1-' при 10.
CurrencyDecimals: Byte;	Число знаков после запятой в представлении денежных сумм. Например, число 10.15 при разных значениях этого параметра отобразится так: '$10' при 0, '$10.15' при 2, '$10.1500' при 4.
ThousandSeparator: Char;	Символ, разделяющий строку на группы по три циф­ры справа налево (разделитель тысяч). Применяется, в частности, в типе преобразования п.
DecimalSeparator: Char;	Символ, отделяющий дробную часть числа от целой.

Мы закончили рассмотрение символа типа преобразования. Рассмотрим осталь­ные составные части спецификатора формата.

Поле ширины устанавливает минимально допустимое количество символов в преобразованной строке. Это означает, что если она короче, чем задано в этом поле, то происходит добавление пробелов до требуемого количества. По умолчанию пробелы добавляются спереди (выравнивание по правому краю), но признак выравнивания по левому краю ("-"; он должен стоять перед полем ширины) позволяет выравнивать строку по-иному.

Поле индекса позволяет динамически изменить последовательность извлечения аргументов из массива. Обычно аргументы извлекаются последовательно, по мере их востребования спецификаторами формата. Поле индекса означает, что следующим нужно извлечь аргумент с данным индексом. Пользуясь индексом, одни и те же аргументы могут быть использованы многократно. Например, вызов Format (' %s %s %0: s %s ', [ 'Yes', 'No' ]) Даст на выходе строку 'Yes No Yes No'.

Поле точности играет разную роль в зависимости от того, с каким типом преобразования применяется. Его особенности приведены вместе с описанием типа (с теми из них, где оно имеет смысл).

Поля индекса, ширины и точности могут быть заданы напрямую или косвенно. Первый способ подразумевает явное указание значения поля (например, ' %10. 5f '). Для косвенного задания значений нужно в соответствующих местах цифры заменить звездочками (например, '%*.*f'). В этом случае вместо звездочек будут подставлены следующие значения из списка аргументов (они обязательно должны быть целыми числами). Например, выражение

Format('Value is %*.*',[10,5, 2.718]);

эквивалентно:

Format('Value is %10.5',[2.718]);

Как уже упоминалось, наиболее употребимой функцией из группы фор­матирующих является Format, которая работает со строками типа string и максимально освобождает программиста от рутинной работы. Другие функции используют то же ядро и правила преобразования, но отличаются параметрами:

procedure FmtStr(var Result: string; const Format: string; const Args: array of const);	To же, что и Format, но оформлено в виде процедуры. Результат преобразо­вания возвращается в параметре Result.
function StrFmt(Buffer, Format: PChar; const Args: array of const): PChar;	Форматирующая строка должна нахо­диться в параметре Format, а резуль­тирующая помещается в буфер Buffer (он должен иметь нужную длину). Функция возвращает указатель на Buffer.
function StrLFmt(Buffer: PChar; MaxLen: Cardinal; Format: PChar; const Args: array of const): PChar;	Работает как StrFmt, но длина резуль­тирующей строки не будет превышать MaxLen символов.
function FormatBuf(var Buffer; BufLen: Cardinal; const Format; FmtLen: Cardinal; const Args: array of const): Cardinal;	Форматирующая строка находится в бу­фере Format длиной FmtLen, a результирующая — в буфере Buffer длиной BufLen. Функция возвращает число реально помещенных в Buffer символов, причем оно всегда меньше или равно BufLen.

 

 

1 function Format (Const Formatting: string; Const Data: array of const): string;

2 function Format (Const Formatting: string; Const Data: array of const; FormatSettings: TFormatSettings): string;

 

Функция Format обеспечивает 'C' подобное форматирование множества простых типов данных в строке. Она обеспечивает очень точное управление по этому форматированию.

Параметр Formatting определяет, как массив Data Данных управляется в возвращенной строке.

Форматируемая cтрока может включать соединение обычных символов (которые передаются неизменными в строку результата), и символам форматирования данных. Такое форматирование лучше всего объясняется кодом примера.

В простых условиях каждые данные, форматирующие подстроку начинаются с % и заканчиваются индикатором типа данных:

d = Десятичное (целое число)
e = Научный
f = Установленный
g = Генерал
m = Деньги
n = Число (плавающее)
p = Указатель
s = Строка
u = Десятичное число без знака
x = Шестнадцатеричный

Общий формат форматирования каждой подстроки следующий:

%[Index:][-][Width][.Precision]Type

где квадратные скобки относятся к дополнительным параметрам, и:. - символы - литералы, первые 2 из которых используются, чтобы идентифицировать два из дополнительных параметров.

Версия 2 этой функции - для использования в пределах потоков. Вы должны заполнить запись FormatSettings перед вызовом запроса. Она берёт местную копию глобальной переменной, форматирующей переменные, которые делают подпрограмму потоко-безопасной.