Функции форматирования строк

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

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

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

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

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

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

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

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

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

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

• % - символ, с которого начинаются все спецификаторы формата (обязательный);
• [Index:] - поле индекса аргумента (необязательное);
• [-] - признак выравнивания по левому краю (необязательный);
• [Width] - поле ширины (необязательное);
• [.Precision] поле точности (необязательное);
• Type - символ типа преобразования (обязательный).

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

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

• d - Десятичный
  Элемент должен быть целым числом и преобразуется в строку десятичных цифр. Если при символе есть поле точности, то в выходной строке будет минимум ргес цифр; если при преобразовании числа их потребуется меньше, то строка дополняется слева нулями.

• е - Научный
  Элемент должен быть числом с плавающей точкой. Он преобразуется к нормализованному виду -d.dddE+ddd. Перед десятичной точкой всегда находится одна цифра (при необходимости, с минусом). После символа "Е" идет показатель степени, имеющий знак и состоящий не менее чем из 3 цифр. Общее число символов в представлении числа определяется полем ргес (по умолчанию 15).

• f - Фиксированный
  Элемент должен быть числом с плавающей точкой. Он преобразуется к виду -ddd.ddd. Поле ргес означает количество цифр после десятичной точки (по умолчанию 2).

• g - Обобщенный
  Элемент должен быть числом с плавающей точкой. Он преобразуется к одному из двух вышеперечисленных видов - выбирается тот, который обеспечивает более короткую запись. Если требуемое число цифр слева от десятичной точки меньше значения поля ширины и само число больше 10", применяется фиксированный тип. Удаляются все впереди идущие нули, десятичная точка (при возможности), а также символы, разделяющие строку на группы по три цифры.

• n m - Числовой Денежный
  Совпадает с типом f за исключением того, что после каждой группы из трех цифр ставятся разделительные символы: d,ddd, ddd.ddd... Элемент должен быть числом с плавающей точкой, отражающей денежную сумму. Способ ее представления зависит от значений глобальных констант, определенных в модуле SYSUTILS (см. ниже). В свою очередь, они зависят от настройки Windows на обозначения, принятые в данной стране.

• p - Указатель
  Элемент должен быть указателем. На выходе он будет представлять из себя строку шестнадцатиричных цифр вида ХХХХ: YYYY, где ХХХХ - селектор, YYYY - смещение.

• s - Строка
  Элемент может иметь тип string, PChar или быть отдельным символом (Char). Эта строка (или символ) вставляются вместо спецификатора формата. Если присутствует поле ргес и длина строки больше его значения, то она усекается.

• х - Шестнадцатиричный
  Как тип d, но элемент преобразуется в строку шестнадцатиричных цифр.

Примечания:

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

2) Тип преобразования m (денежный) тесно связан с правилами представления, принятыми в конкретной стране. Для этого в модуле SYSUTILS определены значения ряда типизированных констант, начальные значения которых берутся из секции [Intl] файла 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;
  '-$1' при 9;
  '$1-' при 10.

• CurrencyDecimals: Byte;
  Число знаков после запятой в представлении денежных сумм. Например, число 10.15 при разных значениях этого параметра отобразится так:
  '$10' при 0,
  '$10.15' при 2,
  '$10.1500' при 4

• ThousandSeparator: Char;
  Символ, разделяющий строку на группы по три цифры справа налево (разделитель тысяч). Применяется, в частности, в типе преобразования n.

• 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.