XPath 1.0 : liste des fonctions

Erwan Amoureux

Cet article liste et décrit les fonctions et leur mécanisme en Xpath 1.0.
Quelques exemples de combinaisons de fonctions y ont été adjoints.
Un remerciement spécial pour avoir épluché mon orthographe et ma ponctuation à ClaudeLELOUP et _Max_.

Commentez

- Titre : XPath 1.0 : liste des fonctions

- Auteur : Erwan Amoureux

- Parution : 6 décembre 2010

- Mise à jour : 12 juillet 2020

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2010 Erwan Amoureux. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Paramètres de fonctions

- II. Fonctions de conversions

- II-A. String

- II-B. Number

- II-C. Boolean

- III. Fonctions d'ensembles de nœuds

- III-A. Position

- III-B. Last

- III-C. Count

- III-D. Name

- III-E. Local-name

- III-F. Namespace_uri

- IV. Fonctions de chaînes de caractères

- IV-A. Concat

- IV-B. Starts-with

- IV-C. Contains

- IV-D. Substring-before

- IV-E. Substring-after

- IV-F. Substring

- IV-G. String-length

- IV-H. Normalize-space

- IV-I. Translate

- V. Fonctions numériques

- V-A. Sum

- V-B. Floor

- V-C. Ceiling

- V-D. Round

- VI. Fonctions booléennes

- VI-A. Not

- VI-B. True

- VI-C. False

- VII. Exemples de combinaisons

- VII-A. Recherche de balise dont le nom commence par…

- VII-B. Recherche de contenu de chaîne dont on exclut certains caractères

- VII-C. Comparaison de dates

- VII-D. Éliminer les nœuds non numériques lors d'une somme

I - Paramètres de fonctions

Les fonctions XPath prennent en paramètre aussi bien des types simples que des nodesets. Quand le type du paramètre passé n'est pas celui demandé, un transtypage implicite est effectué :

Paramètre demandé de type string

- le paramètre passé est un numérique : on applique la fonction string sur ce numérique ;

- le paramètre passé est un booléen : on applique la fonction string sur ce booléen, on renvoie la chaîne false ou true ;

- le paramètre passé est un nodeset vide : on renvoie une chaîne vide ;

- le paramètre passé est un nodeset d'un nœud : on applique la fonction string sur la valeur textuelle du nœud ;

- le paramètre passé est un nodeset de plusieurs nœuds : on applique la fonction string sur la valeur textuelle du premier nœud.

Paramètre demandé de type numérique

- le paramètre passé est une chaîne : on applique la fonction number, si la chaîne est vide ou contient tout autre caractère qu'un nombre (espace compris) la fonction renvoie la chaîne NaN ;

- le paramètre passé est un booléen : on applique la fonction number sur ce booléen, si le booléen vaut vrai (true), on renvoie 1, faux (false) on renvoie 0 ;

- le paramètre passé est un nodeset vide : on renvoie NaN ;

- le paramètre passé est un nodeset d'un nœud : on applique la fonction string sur la valeur textuelle du nœud, puis on applique la fonction number sur le résultat ;

- le paramètre passé est un nodeset de plusieurs nœuds : on applique la fonction string sur la valeur textuelle du premier nœud puis on applique la fonction number sur le résultat.

Paramètre demandé de type booléen

- le paramètre passé est une chaîne : on applique la fonction boolean, si c'est une chaine vide on renvoie false, true autrement ;

- le paramètre passé est un numérique : on applique la fonction boolean, s'il vaut zéro on renvoie false, true autrement ;

- le paramètre passé est un nodeset vide : on applique la fonction boolean et on renvoie false ;

- le paramètre passé est un nodeset d'un ou plusieurs nœuds : on applique la fonction boolean et on renvoie true.

Pour les paramètres de fonction de type nodeset, il n'y a pas de transtypage. Le comportement varie suivant la fonction. Certaines fonctions prennent le nœud en lecture par défaut si aucun nœud n'est fourni en paramètre. Attention sur ce point, un nodeset vide (chemin XPath ne ramenant pas de nœud) n'est pas l'équivalent d'une absence de passage paramètre.

II - Fonctions de conversions

II-A - String

string( object ?): retourne string

Elle convertit un objet en chaîne de caractères selon les règles suivantes.

Un ensemble de nœuds est converti en chaîne de caractères en retournant la valeur textuelle du premier nœud de l'ensemble passé en argument . Si l'ensemble de nœuds est vide, une chaîne vide est retournée.

Cette fonction convertit aussi les nombres (entiers, décimaux) et les booléens (false, true).

Si un ensemble de nœuds est passé en paramètre à une fonction où une chaîne est demandée, cette fonction est appliquée par défaut pour la conversion.

II-B - Number

number( object ?) : retourne nombre

Elle convertit l'argument passé en nombre.

Les booléens « vrai » (true) sont convertis en 1 ; les booléens « faux » (false) sont convertis en 0.

Un ensemble de nœuds est d'abord converti en chaîne de caractères comme avec la fonction string et cette chaîne est ensuite considérée comme argument à la fonction number.

Si l'argument est omis, la valeur retournée par défaut est celle qui aurait été obtenue en considérant un ensemble de nœuds contenant le nœud en lecture.

II-C - Boolean

boolean( object ) : retourne boolean

Elle convertit l'argument passé en booléen.

Un nombre est vrai (true) si et seulement s'il n'est ni un zéro positif ou négatif, ni un NaN.

Un ensemble de nœuds est vrai (true) si et seulement s'il n'est pas vide.

Une chaîne de caractères est vrai (true) si et seulement si sa longueur n'est pas nulle.

Un objet d'un type autre que les quatre de base est converti selon des règles spécifiques à chaque type.

Tout test Xpath utilise la conversion boolean(..) par défaut.

III - Fonctions d'ensembles de nœuds

III-A - Position

position() : retourne nombre

Elle retourne un nombre égal à la position du nœud en lecture par rapport à son contexte d'évaluation. Celui-ci étant généralement son parent sauf en cas de chemin XPath parenthésé.

Pour les détails voir l'article précédent : 3-C Test de position

III-B - Last

last() : retourne nombre

Elle retourne la taille du contexte d'évaluation de l'expression, soit le nombre de nœuds contenus dans la dernière partie du Xpath à laquelle elle succède ou dans la parenthèse.

Récupérer le dernier fils d'un nœud :

Xpath : /ROOT/AA/BB[position()=last()]

<ROOT>

<AA>

<BB/>

</AA>

<AA>

<BB/>

<BB/>

<BB/>

</AA>

<AA>

<BB/>

<BB/>

</AA>

</ROOT>

Récupérer les nœuds qui ont moins de N fils :

Xpath : /ROOT/AA[BB[last()<2]]

<ROOT>

<AA>

<BB/>

</AA>

<AA>

<BB/>

<BB/>

<BB/>

</AA>

<AA>

<BB/>

<BB/>

</AA>

</ROOT>

III-C - Count

count( node-set ) : retourne nombre

Elle retourne le nombre de nœuds de  l'ensemble passé en argument.

Soit le XML :

<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<AA/>
<BB/>
<AA/>
<AA/>
<BB/>
</ROOT>

count(/ROOT/AA) renvoie 2.

count(/ROOT/BB) renvoie 3.

count(/ROOT/*) renvoie 5.

III-D - Name

name( node-set ?) : retourne string

Elle retourne une chaîne contenant un nom qualifié (nom complet y compris le préfixe) représentant le nom du premier nœud de l'ensemble passé en argument. Si aucun nœud n'est passé en argument, le nœud utilisé par défaut sera le nœud en lecture soit l'équivalent de self::node().

Nous avons vu dans le cours sur le fonctionnement des prédicats comment on pouvait sélectionner des nœuds de même niveau, mais de nom différent notamment grâce à l'axe self::
Cette technique ne fonctionne néanmoins que lorsque les noms des nœuds recherchés sont constants, ce qui, dans des contextes XSLT ou XQuery par exemple, n'est pas toujours le cas. Pour ceci on utilisera alors la fonction name().

Xpath : /ROOT/AA/*[name()='BB']

<ROOT>

<AA>

<BB/>

<CC/>

</AA>

<ROOT>

III-E - Local-name

local-name( node-set ?) : retourne string

Elle retourne la partie locale du nom expansé (le nom sans le préfixe) du premier nœud de l'ensemble passé en argument. Si aucun nœud n'est passé en argument, le nœud utilisé par défaut sera le nœud en lecture soit l'équivalent de self::node().

Comparaison entre name() et local-name() :

Xpath : /ROOT/*/*[name()=« BB »]

<ROOT test:xmlns=« URI_de_test »>

<AA>

<test:BB/>

</AA>

<test:AA>

<BB/>

<test:BB/>

<BB/>

</AA>

</ROOT>

Xpath : /ROOT/*/*[local-name()=« BB »]

<ROOT test:xmlns=« URI_de_test »>

<AA>

<test:BB/>

</AA>

<test:AA>

<BB/>

<test:BB/>

<BB/>

</AA>

</ROOT>

III-F - Namespace_uri

namespace-uri( node-set ?) : retourne string

Elle retourne l'URI du namespace du premier nœud du nodeset passé en paramètre. Si aucun nœud n'est passé en argument, le nœud utilisé par défaut sera le nœud en lecture soit l'équivalent de self::node().

Xpath : //*[namespace-uri()=« URI_de_test »]

<ROOT test:xmlns=« URI_de_test »>

<AA>

<test:BB/>

</AA>

<test:AA>

<BB/>

<test:BB/>

<BB/>

</AA>

</ROOT>

IV - Fonctions de chaînes de caractères

IV-A - Concat

concat( string , string , string *) : retourne string

Elle retourne le résultat de la concaténation des arguments. Attention, lui passer un nodeset de plusieurs nœuds en paramètre ne permettra pas la concaténation de leur valeur textuelle. Chaque nodeset est considéré comme un seul argument et à ce titre seul le premier nœud est traité.

Exemple :

concat(« AB »,« CDE »,« EF ») retourne ABCDEF

IV-B - Starts-with

starts-with( string , string ) : retourne boolean

Elle retourne la valeur booléenne true si la première chaîne de caractères passée en argument commence par la chaîne de caractères passée en deuxième argument.

Exemple :

starts-with(« ABCDE »,« ABC »>) retourne true.

starts-with(« ABCDE »,« B ») retourne false.

IV-C - Contains

contains( string , string ) : retourne boolean

Elle retourne true si la première chaîne de caractères passée en argument contient la chaîne de caractères passée en deuxième argument sinon retourne la valeur false.

Exemple :

contains(« ABCDE », « BC ») retourne true.

contains(« ABCDE », « Z ») retourne false.

IV-D - Substring-before

substring-before( string , string ) : retourne string

Elle retourne la sous-chaîne de caractères du premier argument qui précède la première occurrence de la deuxième chaîne de caractères dans le premier argument, ou une chaîne vide si le premier argument ne contient aucune occurrence de la deuxième.

Exemple :

substring-before(« 1999/04/01 »,« / ») retourne 1999.

IV-E - Substring-after

substring-after( string , string ) : retourne string

Elle retourne la sous-chaîne de caractères du premier argument qui suit la première occurrence de la deuxième chaîne de caractères dans le premier argument, ou une chaîne vide si le premier argument ne contient aucune occurrence de la deuxième.

Exemple :

substring-after(« 1999/04/01 »,« / ») retourne 04/01, et substring-after(« 1999/04/01 »,« 19 ») retourne 99/04/01.

IV-F - Substring

substring( string , number , number ?) : retourne string

Elle retourne la sous-chaîne du premier argument commençant à la position spécifiée par le second argument et de longueur spécifiée par le troisième argument.

Exemple :

substring(« 12345 »,2,3) retourne 234.

Si le troisième argument n'est pas spécifié, la fonction retourne la sous-chaîne comprise entre la position de départ spécifiée et la fin de la chaîne de caractères initiale.

Exemple :

substring(« 12345 »,2) retourne 2345.

IV-G - String-length

string-length( string ?) : retourne nombre

Elle retourne le nombre de caractères de la chaîne. Si l'argument est omis, la valeur retournée est égale à la longueur de valeur textuelle du nœud en lecture.

IV-H - Normalize-space

normalize-space( string ?) : retourne string

Elle retourne la chaîne de caractères passée en argument après y avoir normalisé les espaces blancs : suppression des espaces en début et fin et remplacement des séquences de blancs successifs par un seul caractère blanc. Si l'argument est omis, la fonction retourne la chaîne obtenue en ayant utilisé comme argument la valeur textuelle du nœud en lecture.

normalize-space('  test  avec nombreux   espaces ') retourne la chaine : « test avec nombreux espaces ».

IV-I - Translate

translate( string , string , string ) : retourne string

Elle retourne la première chaîne de caractères passée en argument dans laquelle les occurrences des caractères de la deuxième chaîne sont remplacées par les caractères correspondant aux mêmes positions de la troisième chaîne.

Exemple :

translate(« bar »,« abc »,« ABC ») retourne la chaîne BAr.

Si l'un des caractères du deuxième argument n'a pas de position correspondante dans le troisième (parce que le deuxième argument est plus long que le troisième), alors les occurrences de ce caractère sont supprimées du premier argument.

Exemple :

translate(« --aaa-- »,« abc- »,« ABC ») retourne AAA.

Si un caractère apparaît plus d'une fois dans la deuxième chaîne, alors c'est la première occurrence de ce caractère qui détermine la règle de transformation.

Exemple :

translate(« bar »,« abbc »,« AcBC ») retourne cAr.

Si la chaîne passée en troisième argument est plus longue que la deuxième, alors, les caractères excédentaires sont ignorés.

Exemple :

translate(« bar »,« abc »,« ABCr ») retourne BAr.

V - Fonctions numériques

V-A - Sum

sum( node-set ) : retourne nombre

La fonction sum retourne la somme, pour tous les nœuds de l'ensemble passé en argument, du résultat de la conversion en numérique de leur valeur textuelle. Si un ou plusieurs nœuds sélectionnés ne sont pas convertibles, la fonction renverra NaN.

Attention de ne pas oublier que la conversion d'un nœud vide n'est pas zéro, mais NaN.

Exemple :

<ROOT>
<AA>
1
</AA>
<AA>
2
</AA>
</ROOT>

sum(/ROOT/AA) retourne 3

V-B - Floor

floor( number ) : retourne nombre

La fonction floor retourne le plus grand nombre entier inférieur à l'argument du côté de l'infini positif. Soit l'entier immédiatement inférieur à sa gauche.

Exemple : floor(4.2) retourne 4 ; floor(-4.2) retourne -5.

V-C - Ceiling

ceiling( number ) : retourne nombre

La fonction ceiling retourne le plus petit (du côté de l'infini négatif) nombre entier qui ne soit pas inférieur à l'argument. Soit l'entier immédiatement supérieur à sa droite.

Exemple : ceiling(4.2) retourne 5 ; ceiling(-4.2) retourne -4.

V-D - Round

round( number ) : retourne nombre

retourne le nombre entier le plus proche de l'argument. Si deux nombres sont possibles, alors celui des deux qui est le plus proche de l'infini positif (à sa droite) est retourné.

Exemple : round(4.2) retourne 4 ; round(4.6) retourne 5 ; round(4.5) retourne 5 ;
round(-4.2) retourne -4 ; round(-4.6) retourne -5 ; round(-4.5) retourne -4.

VI - Fonctions booléennes

VI-A - Not

not( boolean ) : retourne boolean

La fonction not retourne l'inverse de la valeur du booléen passé en argument : vrai (true) si l'argument est faux et vice-versa.

VI-B - True

true() : retourne boolean

La fonction true retourne true.

Cette fonction est très peu utilisée, la conversion par transtypage étant la règle.

VI-C - False

false() : retourne boolean

La fonction false retourne false.

Cette fonction est très peu utilisée, la conversion par transtypage étant la règle.

VII - Exemples de combinaisons

VII-A - Recherche de balise dont le nom commence par…

Xpath : //*[starts-with(name(),'B')]

<ROOT >

<AA>

<BB/>

</AA>

<BA>

<BB/>

<CB/>

<DB/>

</BA>

</ROOT>

VII-B - Recherche de contenu de chaîne dont on exclut certains caractères

Xpath : /ROOT/*[contains(translate(.,'0123456789',''),'testA')]

<ROOT>

<A>test128A ;</A>

<A>test1728B ;</A>

<A>test28A ;</A>

<A>essai196A ;</A>

<A>test12C ;</A>

<A>essai8A ;</A>

<A>test12899A ;</A>

</ROOT>

VII-C - Comparaison de dates

On va rester ici dans un cas simple, une date toujours formatée jj/mm/aaaa, mais il est tout à fait possible de traiter d'autres formats moins réguliers en s'appuyant sur le séparateur et des combinaisons de substring-before ou after.

Xpath : /ROOT/A[concat( substring(., 7, 4),substring(., 4, 2),substring(., 1, 2))<20071201]

<ROOT>

<A>01/12/2006</A>

<A>01/12/2007</A>

<A>01/11/2007</A>

</ROOT>

VII-D - Éliminer les nœuds non numériques lors d'une somme

Xpath : sum(/ROOT/A[number(.)!='NaN']) retourne 37.

<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<A>non renseigné</A>
<A>absent</A>
<A>10</A>
<A>15</A>
<A>12</A>
<A>non renseigné</A>
<A/>
</ROOT>