4 Основная библиотека функций

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

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

4.1 Функции обработки набора узлов

Функция: number last()

Функция last возвращает число, равное размеру контекста обрабатываемого выражения.

Функция: number position()

Функция position возвращает число, равное положению в контексте обрабатываемого выражения.

Функция: number count(node-set)

Функция count возвращает количество узлов в наборе, представленном в качестве аргумента.

Функция: node-set id(object)

Функция id находит элементы по их уникальному идентификатору (см. [5.2.1 Уникальные ID]). Если аргументом функции id является набор узлов, то ее результатом будет объединение узлов, полученных в результате вызова функции id для строкового значения каждого узла в наборе, указанном в качестве аргумента. Если аргумент функции id относится к какому-либо другому типу, то этот аргумент сперва преобразуется в строку как при вызове функции string. Затем полученная строка разбивается на лексемы, разделенные пробельными символами (пробельный символ - это любая последовательность символов, соответствующих сценарию S). Результатом вызова функции в этом случае является набор узлов, состоящий из элементов, относящихся к тому же документу, где находился узел контекста, и имеющих уникальный идентификатор, равный одной из лексем, представленных в этом списке.

• id("foo") находит элемент с уникальным идентификатором foo

• id("foo")/child::para[position()=5] среди непосредственных потомков элемента с уникальным идентификатором foo находит пятый элемент para

Функция: string local-name(node-set?)

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

Функция: string namespace-uri(node-set?)

В наборе, указанном в аргументе, функция namespace-uri находит тот узел, который в документе встретится первым, и в его расширенном имени выделяет URI пространства имен. Если указанный в аргументе набор узлов пуст, первый найденный узел не имеет расширенного имени, или же URI пространства имен в расширенном имени оказался нулевым, то функция возвращает пустую строку. Если аргумент отсутствует, то по умолчанию берется набор, в котором узел контекста является единственным членом.

Замечание: Для узлов, которые не соответствуют ни элементам, ни атрибутам, функция namespace-uri возвращает пустую строку.

Функция: string name(node-set?)

В наборе, указанном в аргументе, функция name находит узел, который в документе встретится первым, и возвращает строку, содержащую QName, которое представляет расширенное имя данного узла. Указанная конструкция QName должна представлять расширенное имя, исходя из деклараций пространств имен, доступная для того узла, чье расширенное имя должно быть представлено. Как правило, это тот самый QName, который был представлен в исходном документе XML. Однако это не обязательно должно быть так в случае, когда декларации, воздействующие на данный узел, с одним и тем же пространством имен связывают несколько префиксов. Тем не менее, реализация может содержать сведения о первоначальном префиксе представляемых узлов, в таком случае может выполняться проверка с тем, чтобы возвращаемая строка была всегда такой же, как QName, используемый в исходном документе XML. Если указанный в аргументе набор узлов пуст или первый узел не имеет расширенного имени, возвращается пустая строка. Если аргумент опущен, то по умолчанию используется набор, содержащий только узел контекста.

Замечание: Для узлов, не являющихся ни элементом, ни атрибутом, строка, возвращаемая функцией name, будет той же самой, что и строка, возвращаемая функцией local-name.

4.2 Функции обработки строк

Функция: string string(object?)

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

• Набор узлов преобразуется в строку, соответствующую строковому значению того узла в этом наборе, который первым встретится в документе. Если представленный набор узлов пуст, возвращается пустая строка.

• Число преобразуется в строку следующим образом

  • NaN преобразуется в строку NaN

  • положительный нуль преобразуется в строку 0

  • отрицательный нуль преобразуется в строку 0

  • положительная бесконечность преобразуется в строку Infinity

  • отрицательная бесконечность преобразуется в строку -Infinity

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

  • В противном случае число представляется в десятичной форме Number, включающей десятичную точку, по крайней мере одну цифру до десятичной точки и, по крайней мере, одну после. Если число отрицательное, то его представлению предшествует знак минус (-). Десятичной точке не должны предшествовать ведущие нули, за исключением одной обязательной цифры перед десятичной точкой. После десятичной точки должна следовать хотя бы одна цифра, вообще же количество цифр после точки должно быть ровно таким, сколько необходимо, чтобы отличить это число от других чисел в формате IEEE 754, но не большим.

• Булево значение false преобразуется в строку false. Булево значение true преобразуется в строку true.

• Способ преобразования в строку объекта, не относящегося к четырем основным типам, зависит от этого типа.

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

Замечание: Функция string не предназначена для преобразования чисел в строки для показа пользователю. Для этой цели предназначены функция format-number и элемент xsl:number из [XSLT].

Функция: string concat(string, string, string*)

Функция concat возвращает объединение представленных аргументов.

Функция: boolean starts-with(string, string)

Функция starts-with возвращает true если строка второго аргумента совпадает с началом строки первого аргумента. В противном случае функция возвращает false.

Функция: boolean contains(string, string)

Функция contains возвращает true если строка второго аргумента является частью строки первого аргумента. В противном случае функция возвращает false.

Функция: string substring-before(string, string)

Функция substring-before возвращает ту часть строки первого аргумента, которая предшествует первому появлению строки второго аргумента. Если строка второго аргумента не содержится в строке первого аргумента, то функция возвращает пустую строку. Например, substring-before("1999/04/01","/") возвратит 1999.

Функция: string substring-after(string, string)

Функция substring-after возвращает ту часть строки первого аргумента, которая следует за первым появлением строки второго аргумента. Если строка второго аргумента не содержится в строке первого аргумента, функция возвращает пустую строку. Например, substring-after("1999/04/01","/") возвращает 04/01, а substring-after("1999/04/01","19") возвращает 99/04/01.

Функция: string substring(string, number, number?)

Функция substring возвращает ту часть строки первого аргумента, которая начинается с позиции, указанной вторым аргументом, и имеет длину, указанную в третьем аргументе. Например, substring("12345",2,3) возвращает "234". Если третий аргумент не был представлен, функция возвращает подстроку, начинающуюся с позиции, указанной во втором аргументе, и продолжащуюся до конца строки. Например, substring("12345",2) возвращает "2345".

Точнее выражаясь, каждый символ в строке (см. [3.6 Строки]) имеет номер позиции: позиция первого символа - 1, второго символа - 2 и т.д.

Замечание: Такой порядок отличается от принятого в Java и ECMAScript, где метод String.substring считает позицию первого символа нулевой.

Возвращаемая подстрока содержит те символы, позиция которых больше или равна округленному значению второго аргумента, а также, если был указан третий аргумент, меньше чем сумма округленных значений второго и третьего аргументов. Использовавшиеся выше операции сравнения и сложения отвечают правилам стандарта IEEE 754, округление осуществляется как при вызове функции round. Приведенные далее примеры иллюстрируют различные нестандартные ситуации:

• substring("12345", 1.5, 2.6) возвращает "234"

• substring("12345", 0, 3) возвращает "12"

• substring("12345", 0 div 0, 3) возвращает ""

• substring("12345", 1, 0 div 0) возвращает ""

• substring("12345", -42, 1 div 0) возвращает "12345"

• substring("12345", -1 div 0, 1 div 0) возвращает ""

Функция: number string-length(string?)

Функция string-length возвращает число символов в строке (см. [3.6 Строки]). Если аргумент опущен, то по умолчанию берется узел контекста и преобразуется в строку, иными словами, берется строковое значение текущего узла контекста.

Функция: string normalize-space(string?)

Функция normalize-space возвращает строку аргумента с нормализацией пробельных символов. Сюда входит удаление начальных и завершающих пробельных символов, а также замена оставшихся последовательностей пробельных символов одиночными пробелами. Пробельными считаются символы, являющиеся таковыми согласно сценарию S в языке XML. Если аргумент опущен, то по умолчанию в строку преобразуется узел контекста, иными словами, в качестве аргумента берется строковое значение текущего узла контекста.

Функция: string translate(string, string, string)

Функция translate возвращает строку первого аргумента, в которой символы, указанные в строке второго аргумента, заменены символами строки третьего аргумента в соответствующей позиции. Например, translate("bar","abc","ABC") возвращает строку BAr. Если в строке второго аргумента имеется символ, для которого нет парного символа в соответствующей позиции третьей строки (поскольку строка второго аргумента длиннее строки третьего аргумента), то все экземпляры этого символа изымаются из первой строки. Например, translate("--aaa--","abc-","ABC") возвращает "AAA". Если какой-либо символ встретился во второй строке несколько раз, то правило замены определяется первым встреченным экземпляром. Если строка третьего аргумента длиннее, чем строка второго, лишние символы игнорируются.

Замена: Функция translate не может обеспечить преобразование регистра для всех языков. Для преобразования регистра в будущих версии XPath могут появиться дополнительные функции.

4.3 Функции обработки булевых значений

Функция: boolean boolean(object)

Функция boolean преобразует аргумент в булево значение следующим образом:

• число преобразуется в true тогда и только тогда, когда оно не является ни NaN, ни положительным или отрицательным нулем

• набор узлов преобразуется в true тогда и только тогда, когда он непустой

• строка преобразуется true тогда и только тогда, когда она имеет ненулевую длину

• процедура преобразования в булево значение объекта, не относящегося в четырем основным типам, зависит от типа этого объекта

Функция: boolean not(boolean)

Функция not возвращает true тогда и только тогда, когда ее аргументом является false, и false в противном случае.

Функция: boolean true()

Функция true возвращает true.

Функция: boolean false()

Функция false возвращает false.

Функция: boolean lang(string)

Функция lang возвращает true или false в зависимости от того, является ли язык узла контекста, указываемый в атрибутах xml:lang, тем же самым языком (или подмножеством языка), что указан в строке атрибута. Язык узла контекста задается значением атрибута xml:lang, указанного в этом узле, либо, если сам узел контекста не имеет атрибута xml:lang, то значением атрибута xml:lang у его ближайшего предка, имеющего такой атрибут. Если требуемый атрибут не найден, функция lang возвращает false. Если же атрибут найден, то функция lang возвращает true когда значение этого атрибута равно значению аргумента. При этом регистр игнорируется. Кроме того, если значение атрибута имеет суффикс, начинающийся с дефиса (-), то перед сравнением такой суффикс может быть отброшен. Например, вызов функции lang("en") возвращает true если узлом контекста является любой из пяти указанных элементов:

<para xml:lang="en"/>
<div xml:lang="en"><para/></div>
<para xml:lang="EN"/>
<para xml:lang="en-us"/>

4.4 Функции обработки чисел

Функция: number number(object?)

Функция number преобразует свой аргумент в число следующим образом:

• строка, образованная необязательным пробельным символом, за которым следует необязательный знак минус, Number и пробельный символ, преобразуется в число IEEE 754, ближайшее к математическому значению, представленному этой строкой (в соответствии с правилом округления IEEE 754). Любая другая строка преобразуется в NaN.

• булево значение true преобразуется в 1, булево значение false преобразуется в 0

• набор узлов сперва преобразуется в строку как при вызове функции string, а затем преобразуется по тому же алгоритму, что и строковый аргумент

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

Если аргумент отсутствует, то по умолчанию берется набор, содержащий только узел контекста.

Замечание: Функция number не должна использоваться для преобразования числовых данных, встреченных в каком-либо элементе XML документа, если не известно, что элемент данного типа представляет числовые данные в независимом от языка формате (обычно перед показом пользователю такой элемент переводятся в формат, соответствующий языку). Кроме того, функция number не может использоваться, если независимый от языка формат элемента не соответствует синтаксису XPath для Number.

Функция: number sum(node-set)

Функция sum возвращает сумму всех узлов из набора, указанного в аргументе. Перед суммированием строковые значения узлов преобразуются в числа.

Функция: number floor(number)

Функция floor возвращает наибольшее число (ближайшее к положительной бесконечности), которое не превышает значение представленного аргумента и является целым.

Функция: number ceiling(number)

Функция ceiling возвращает наименьшее число (ближайшее в отрицательной бесконечности), которое не меньше значения представленного аргумента и является целым.

Функция: number round(number)

Функция round возвращает целое число, ближайшее к значению аргумента. Если таких чисел два, то возвращается то из них, которое ближе к положительной бесконечности. Если аргументом является NaN, функция возвращает NaN. Если аргументом является положительная бесконечность, возвращается положительная бесконечность. Если аргументом является отрицательная бесконечность, возвращается отрицательная бесконечность. Если аргументом является положительный нуль, функция возвращает положительный нуль. Если аргументом является отрицательный нуль, функция возвращает отрицательный нуль. Если аргумент меньше нуля, но больше или равен -0.5, возвращается отрицательный нуль.

Замечание: В последних двух случаях вызов функции round имеет иной результат, чем добавление 0.5 и последующий вызов функции floor.

Назад | Содержание | Вперед