Функция 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))