1. Главная
  2. Функции XPath
  3. format-number()

format-number XPath

Become a Patron!

Функция format-number принимает на вход три параметра. Первым параметром является число, которое необходимо преобразовать в строку, применив при этом форматирование. Вторым параметром является образец, в соответствии с которым будет форматироваться число. Третий параметр указывает название десятичного формата, который следует применять.

Синтаксис

XPath 1.0

string format-number( number, string, string? )

Спецификация

Описание и примеры

Образец форматирования в XSLT определяется точно так же, как в классе DecimalFormat языка Java. Для того чтобы читателю, не знакомому с Java, не пришлось изучать документацию этого языка, мы приведем полный синтаксис образцов форматирования. Продукции образца форматирования мы будем помечать номерами с префиксом NF, чтобы не путать их с другими продукциями.

Прежде всего, образец форматирования может состоять из двух частей: первая часть определяет форматирование положительного числа, вторая часть — отрицательного. Запишем это в виде EBNF-продукции:

[NF 1] NFPattern ::= NFSubpattern (NFSubpatternDelim NFSubpattern)?

Двум частям образца форматирования соответствуют нетерминалы NFSubpattern, которые разделены нетерминалом NFSubpatternDelim.

В случае если вторая часть образца форматирования опущена, отрицательные числа форматируются точно так же, как и положительные, но им предшествует префикс отрицательного числа (по умолчанию — знак “минус”, “-”).

Примеры

format-number(1234.567,'#.00;negative #.00') ? '1234.57'
format-number(-1234.567,'#.00;negative #.00') ? 'negative 1234.57'
format-number(-1234.567,'#.00') ? '-1234.57'

Каждая из частей образца форматирования состоит из префикса (NFPrefix), целой части (NFInteger), необязательной дробной части (NFFractional) и суффикса (NFSuffix).

[NF 2] NFSubpattern ::= NFPrefix NFinteger NFFractional? NFSuffix

Префикс или суффикс образца форматирования могут содержать символ процента. Если суффикс содержит символ процента, число должно быть умножено на 100 и выведено со знаком процента. Наличие символа процента в префиксе на форматирование не влияет.

Пример

format-number(0.45,'0.00%') ? '45.00%'
format-number(0.45,'0.##%') ? '45%'
format-number(0.45678,'%0.00') ? '%0.46'
format-number(0.45678,'0.####%') ? '45.678%'

Префикс задает строку, которая будет предшествовать числу, это может быть последовательность любых неформатирующих символов (NFChar) плюс символ процента (NFPercent). Аналогично, суффикс будет следовать за числом, и он тоже не может содержать форматирующих символов (за исключением символа процента).

[NF 3] NFPrefix ::= (NFChar NFPercent?)*
[NF 4] NFSuffix ::= (NFChar NFPercent?)*

Пример

Если мы хотим заключить наше число, к примеру, в квадратные скобки, мы должны будем включить в его образец форматирования префикс “[” и суффикс “]”:

format-number(123456, '[#]') ? '[123456]'

Нетерминал NFinteger определяет, как будет выглядеть целая часть числа. Он начинается несколькими символами NFOptDigit (по умолчанию “#”), показывающими позиции, в которых цифры необязательны, и состоит из символов NFReqDigit (по умолчанию “0”), показывающих позиции обязательных цифр, а также символа NFGroupDelim (по умолчанию “,”), показывающего позицию символа-разделителя групп цифр.

[NF 5] NFInteger ::= NFOptDigit*
                     (NFReqDigit* NFGroupDelim
                     | NFGroupDelim NFOptDigit*)?
                     NFReqDigit+

Примеры

format-number(1234.56,'#0000') ? '1235'
format-number(1234.56,'00000') ? '01235'
format-number(1234.56,'00,000') ? '01,235'
format-number(1234.56,'000,00') ? '0,12,35'

Замечание. Некоторые процессоры позволяют указывать несколько символов-разделителей. Однако даже в этом случае они учитывают только последний из этих символов.

Пример

format-number(123456789.0123,'0000,000,00') ? '1,23,45,67,89'

Дробная часть числа, представленная нетерминалом NFFraction, начинается символом-разделителем целой и дробной части NFFractionDelim (по умолчанию “.”), продолжается последовательностью символов обязательных позиций цифр NFReqDigit и заканчивается последовательностью символов необязательных позиций NFOptDigit:

[NF 6] NFFraction ::= NFFractionDelim NFReqDigit* NFOptDigit*

Примеры

format-number(1234.567,'#.00') ? '1234.57'
format-number(1234.567,'#.00#') ? '1234.567'
format-number(1234.567,'#.0000') ? '1234.5670'

Продукция NFChar, использующаяся при определении префикса (NFPrefix) и суффикса (NFSuffix), может содержать любые неформатирующие символы:

[NF 7] NFChar ::= (Char - NFSymbol)

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

  • символ обязательной позиции цифры (по умолчанию “0”);
  • символ необязательной позиции цифры (по умолчанию “#”);
  • символ-разделитель образцов форматирования для положительного и отрицательного числа (по умолчанию “;”);
  • символ-разделитель целой и дробной части (по умолчанию “.”);
  • символ процента (по умолчанию “%”).

Перечислим их продукции:

[NF 8] NFSymbol           ::= NFReqDigit
                              | NFOptDigit
                              | NFSubpatternDelim
                              | NFFractionDelim
                              | NFGroupDelim
                              | NFPercent

[NF 9] NFReqDigit         ::= '0'

[NF 10] NFOptDigit        ::= '#'

[NF 11] NFSubpatternDelim ::= ';'

[NF 12] NFFractionDelim   ::= '.'

[NF 13] NFGroupDelim      ::= ','

[NF 14] NFPercent         ::= '%'

Синтаксические правила, которые мы привели выше, пока не являются стандартными. Они корректно передают синтаксис образца форматирования, но являются более строгими, чем определения в документации языка Java.