Функция StringFormat

         Описание функции


StringFormat

Возвращает форматированную строку (имитация функции sprintf() из языка C).

StringFormat ( "format control", var1 [, ... var32 ] )

Параметры

format control Шаблон, содержащий управляющие последовательности (смотрите Примечания).
var1...var32 До 32 переменных, которые будут выводиться в форматированной строке - "format control".

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

Возвращает форматированную строку, заданную шаблоном "format control".

Примечания

Для предотвращения переполнения буфера, каждая "переменная" (var1...var32) ограничена 65535 символами.
Шаблон (format control) может содержать специальные символы: \n (@LF), \r (@CR), \t (@TAB). Поэтому, если необходимо использовать символ "\", то его следует записывать, как \\. То же самое и для "%" - %%.

Формат управляющей последовательности:
%[флаги] [ширина] [.точность] тип
Обязательными составными частями являются символ начала управляющей последовательности (%) и тип.
Несоответствие количества управляющих последовательностей и количества переменных не приводит к ошибке.

Примеры управляющей последовательности:

%010.2f
%08.12s
%10s
%.2f
%02d
%X


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

ТипТип переменнойВыходной формат
d, iЦелоеДесятичное целое число.
oЦелоеВосьмеричное целое число без знака.
uЦелоеДесятичное целое число без знака.
xЦелоеШестнадцатеричное целое число без знака. Символы "abcdef" в нижнем регистре.
XЦелоеАналогично предыдущему x, но "ABCDEF" в верхнем регистре.
eС плавающей точкойЭкспоненциальный вид [ - ]d.dddd e [знак]ddd, где d единственная десятичная цифра, dddd одна и более десятичных цифр, ddd точно три десятичных цифры и знак + или -.
EС плавающей точкойАналогично e, отличие лишь в регистре показателя (E вместо e).
fС плавающей точкойВыходная запись имеет вид [ - ]dddd.dddd, где dddd одна и более десятичных цифр. Количество цифр перед десятичной точкой зависит от величины числа, и количество цифр после десятичной точки зависит от спецификатора точности.
gС плавающей точкойВыходная запись в формате f или e, в зависимости от того, в каком виде запись является более компактной для заданного значения и точности. Формат e задействуется только когда экспонента меньше -004 или при положительной экспоненте, если экспонента равна спецификатору точности или более. Завершающие нули отбрасываются, а точка появляется, если за ней будут следовать цифры.
GС плавающей точкойАналогично g, отличие лишь в регистре показателя (E вместо e, если он выводится).
sСтрокаСтрока.

        Спецификатор флагов

ФлагЗначениеПо умолчанию
-Устанавливает левое выравнивание результата в пределах ширины области.Правое выравнивание.
+Устанавливает префикс выходного значения, знак "+" или "-", если используется знаковый тип.Знак появляется только для отрицательных величин (-).
0Если спецификатор ширины с префиксом 0, то нули добавляются до заполнения минимальной ширины. Если появляются 0 и "-", то 0 игнорируется. Если 0 используется с типом целого числа (i, u, x, X, o, d) то 0 игнорируется.Отсутствует заполнение.
ПробелПрефикс выходного значения с пробелом, если выходное значение знаковое и положительно; Пробел игнорируется если используются оба флага "Пробел" и "+".Отсутствует.
#При использовании типов o, x, X приписывает префикс любому ненулевому выходному значению соответственно 0, 0x, 0X.Отсутствует.
#При использовании типов e, E, f принуждает выходное значение содержать десятичную точку во всех случаях.Десятичная точка появляется, только если цифры следуют за ней.
#При использовании типов g, G, принуждает выходное значение содержать десятичную точку во всех случаях и предотвращает усечение конечных нулей.
Игнорируется при использовании с типами d, i, u, или s.
Десятичная точка появляется, только если цифры следуют за ней. Конечные нули исключены.

        Спецификатор ширины

Вторым необязательным элементом управляющей последовательности является спецификатор ширины. Ширина - неотрицательное десятичное целое число, указывает минимальную ширину поля (число выводимых символов), включая знак для чисел. Если количество символов меньше указанной, то добавляются пробелы слева или справа, в зависимости от указанного флага выравнивания. Если указанный параметр ширины начинается с 0, то нули добавляются до указанной ширины. Такое поведение не рекомендуется для левого выравнивания в числах.

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

        Спецификатор точности

Третьим необязательным элементом управляющей последовательности является спецификатор точности. Это целое число, с предшествующей точкой (.), которое определяет количество символов вывода, количество десятичных порядков, или количество значимых цифр (см. таблицу ниже). В отличие от спецификатора ширины, спецификатор точности может привести либо к усечению выходной величины, либо к округлению числа с плавающей запятой. Если точность определена как 0 и значение для преобразования равно 0, то результат вывода не имеет символов, как показано ниже:

StringFormat( "%.0d", 0 ); /* Никакие символы не будут возвращены */

    Как на точность влияет тип

ТипЗначениеПо умолчанию
d, i, u, o, x, XТочность задает минимальное количество цифр для вывода. Если количество цифр в аргументе меньше, чем точность, выходное значение дополняется нулями слева. Значение не сокращается, когда количество цифр превышает точность.По умолчанию точность - 1.
e, EТочность определяет количество цифр для вывода после десятичной точки. Последняя цифра вывода округляется.По умолчанию точность - 6; если точность 0 или точка (.) появляется без числа, следующего за ним, десятичная точка не выводится.
f Точность величины определяет количество цифр после запятой. Десятичная точка появляется, только если цифры следуют за ней. Значение округляется до соответствующего количества цифрПо умолчанию точность - 6; если точность 0 или точка (.) появляется без числа, следующего за ним, десятичная точка не выводится.
g, GТочность определяется максимальным количеством значащих цифр вывода.Шесть значащих цифр выводятся, любые конечные нули усечены.
sТочность определяется максимальным количеством символов для вывода. Символы сверх точности не выводятся.Символы выводятся до первого нулевого символа.

Пример

; Пример 1
$n = 43951789
$u = -43951789

Global $sText
; учтите, что двойное %%, выводит символ как есть, буквально '%'; здесь \n - перенос строки, \t - табуляция
$sText &= StringFormat("%%d = '%d'\n", $n) ;                '43951789'          стандартное целое
$sText &= StringFormat("%%e = '%e'\n", $n) ;                '4.395179e+007'     экспоненциальный вид  (мантисса и экспонента)
$sText &= StringFormat("%%u = '%u'\n", $n) ;                '43951789'          положительное целое число без знака
$sText &= StringFormat("%%u <0 = '%u'\n", $u) ;         '4251015507'        отрицательное число (в итоге неверный результат)
$sText &= StringFormat("%%f = '%f'\n", $n) ;                '43951789.000000'   с плавающей точкой
$sText &= StringFormat("%%.2f = '%.2f'\n", $n) ;            '43951789.00'       с плавающей точкой, 2 цифры после десятичной точки
$sText &= StringFormat("%%o = '%o'\n", $n) ;                '247523255'         восьмеричное
$sText &= StringFormat("%%s = '%s'\n", $n) ;                '43951789'          строковый, как текст
$sText &= StringFormat("%%x = '%x'\n", $n) ;                '29ea6ad'           шестнадцатеричный вид (в нижнем регистре)
$sText &= StringFormat("%%X = '%X'\n", $n) ;                '29EA6AD'           шестнадцатеричный вид (в верхнем регистре)

$sText &= StringFormat("%%+d = '%+d'\n", $n) ;          '+43951789'         знак указывающий положительное число
$sText &= StringFormat("%%+d <0= '%+d'\n\n", $u) ;          '-43951789'     знак указывающий отрицательное число

$s = 'пудель'
$t = 'много щенков'

$sText &= StringFormat("%%s = [%s]\n", $s) ;        [пудель]            стандартная строка
$sText &= StringFormat("%%10s = [%10s]\n", $s) ;        [    пудель]        выравнивание пробелами справа
$sText &= StringFormat("%%-10s = [%-10s]\n", $s) ;      [пудель    ]        выравнивание пробелами слева
$sText &= StringFormat("%%010s = [%010s]\n", $s) ;      [0000пудель]        заполнение нулями работает в строках тоже
$sText &= StringFormat("%%10.10s = [%10.10s]\n", $t) ;  [много щенк]        выравнивание слева, но с обрезкой длины превышающей 10 символов

$sText &= StringFormat("%04d-%02d-%02d\n", 2008, 4, 1) ; дата
$sText &= StringFormat("%02d:%02d:%02d\n", 8, 45, 9) ; время
$sText &= StringFormat("%04d-%02d-%02d %02d:%02d:%02d", 2008, 4, 1, 8, 45, 9) ; дата и время

MsgBox(4096, 'Сообщение', $sText)

; Пример 2
$iTime = '5'
$sText = ''

; В многоязычном интерфейсе позволяет вставить переменную в любую позицию.
$sText &= StringFormat("%s minutes passed", $iTime) & @LF
$sText &= StringFormat("прошло %s минут", $iTime)

MsgBox(0, 'Форматированная строка', $sText)

Exit

$iDec = Dec('F4E6DC')
MsgBox(0, 'Число в шестнадцатеричном виде', StringFormat("%06X", $iDec))