Aide:StringFunctions

Aide de Vikidia Page mise à jour pour la dernière fois le 29 septembre 2012.  Voir aussi : accueil de l’aide • bavardages • Aide:Modèles

Cette page présente le fonctionnement des « StringFunctions », des extensions de MediaWiki qui permettent d'effectuer des traitements sur du texte.

Les StringFunctions répondent à certaines questions :

• quelle est la longueur de cette phrase ? (len) ;
• cette phrase contient-elle le mot baobab et, si oui, où ? (pos et rpos) ;

et peuvent aussi modifier du texte :

• donne-moi seulement un morceau de cette phrase (sub) ;
• rajoute des caractères jusqu'à atteindre une certaine longueur (pad) ;
• remplace tous les mots A par le mot B (replace) ;
• ne garde que le n-ième morceau de cette phrase, en prenant les virgules comme séparateurs (explode) ;
• encode cette phrase pour qu'elle passe correctement dans une URL (urlencode et urldecode).

Elles s'ajoutent aux mots magiques ((en) documentation) et aux ParserFunctions ((fr) documentation). La documentation des StringFunctions ne possède pas de traduction francophone, ce qui peut être préjudiciable. Ce qui suit est donc une traduction en français de la page d'aide anglophone des StringFunctions du site de MediaWiki.

---

Ce module définit les fonctions suivantes : len, pos, rpos, sub, pad, replace, explode, urlencode et urldecode.

Elles ont toutes une complexité linéaire, ce qui les protège des attaques par déni de service (DoS).

Notes

1. certains paramètres de ces fonctions peuvent être limités par les paramètres globaux de Vikidia pour prévenir d’éventuels abus ;
2. concernant les fonctions sensibles à la casse, il est possible d’user du mot magique {{lc:chaîne ici}}.

len

La fonction #len retourne la longueur de la chaîne donnée. La syntaxe en est :

{{#len:chaîne}}

La valeur retournée est le nombre de caractères dans chaîne. Si aucune chaîne n’est spécifiée, la valeur de retour est évidemment zéro.

Notes :

• les espaces de fin ne comptent pas. Par exemple: {{#len:Icecream }} retourne 8 ;
• la fonction gère les caractères multibits de la norme UTF-8. Par exemple : {{#len:Žmržlina}} retourne 8 ;
• les balises telles que <nowiki> et celles des autres extensions auront toujours une longueur égale à un, puisque leur contenu est masqué par le parseur. Par exemple: {{#len:<nowiki>This is a </nowiki>test}} retourne 5.

pos

La fonction #pos retourne la position d’un caractère ou groupe de caractères donné au sein de la chaîne. La syntaxe en est :

{{#pos:chaîne|terme recherché|début}}

Le paramètre début, si spécifié, définit la position à laquelle la fonction commence son travail de recherche dans la chaîne.

Si le terme recherché est trouvé, la valeur de retour est un nombre entier représentant la position de la première occurrence du terme dans la chaîne. Notez que le premier caractère d’une chaîne a pour position 0, et non 1. Si le terme recherché n’est pas trouvé, la fonction retourne une chaîne vide.

Notes :

• cette fonction est sensible à la casse ;
• la taille maximale autorisée pour le terme recherché est limitée par le paramètre global $wgStringFunctionsLimitSearch ;
• la fonction gère les caractères multibits de la norme UTF-8. Par exemple : {{#pos:Žmržlina|lina}} retourne 4 ;
• de même que pour #len, <nowiki> et les autres balises d’extensions sont traitées comme ayant une longueur égale à un, puisque la fonction utilise la position des caractères. Par exemple : {{#pos:<nowiki>This is a </nowiki>test|test}} retourne 1.

rpos

La fonction #rpos retourne la dernière position d’un caractère ou groupe de caractères donné au sein de la chaîne. La syntaxe en est :

{{#rpos:chaîne|terme recherché}}

Si le terme recherché est trouvé, la valeur de retour est un nombre entier représentant la position de la dernière occurrence du terme dans la chaîne. Notez que le premier caractère d’une chaîne a pour position 0, et non 1. Si le terme recherché n’est pas trouvé, la fonction retourne -1.

Conseil : lorsque vous utilisez ceci pour rechercher le dernier délimiteur, ajoutez 1 au résultat pour retrouver la position après le dernier délimiteur. Cela fonctionne également lorsque le délimiteur en question n’est pas trouvé : en effet, -1 + 1 est égal à zéro, c’est-à-dire le début de la chaîne entrée.

Notes :

• cette fonction est sensible à la casse ;
• la taille maximale autorisée pour le terme recherché est limitée par le paramètre global $wgStringFunctionsLimitSearch ;
• la fonction gère les caractères multibits de la norme UTF-8. Par exemple : {{#pos:Žmržlina|lina}} retourne 4 ;
• de même que pour #len, <nowiki> et les autres balises d’extensions sont traitées comme ayant une longueur égale à un, ppuisque la fonction utilise la position des caractères. Par exemple : {{#pos:<nowiki>This is a </nowiki>test|test}} retourne 1.

sub

La fonction #sub retourne une sous-chaîne à partir de la chaîne donnée en argument. La syntaxe en est :

{{#sub:chaîne|début|longueur}}

Le paramètre début, s’il est positif (ou même nul), spécifie la position du premier caractère à être retourné. Attention, le premier caractère d’une chaîne a pour position 0, et non 1. Exemple : {{#sub:Icecream|3}} retourne cream.

Si le paramètre début est négatif, il spécifie le nombre de caractères à retourner, en partant de la fin. Exemple : {{#sub:Icecream|-3}} retourne eam.

Le paramètre longueur, s’il est présent et positif, spécifie la taille maximale de la sous-chaîne retournée. Exemple : {{#sub:Icecream|3|3}} retourne cre.

Si le paramètre longueur est négatif, il spécifie le nombre de caractères à omettre à partir de la fin de la chaîne. Exemple : {{#sub:Icecream|3|-3}} retourne cr.

Notes :

• si le paramètre longueur est zéro, il n’est pas utilisé, comme s’il n’avait pas été fourni. Par exemple : {{#sub:Icecream|3|0}} retourne cream ;
• si début représente une position après la troncature depuis la fin (due à un paramètre longueur négatif), la fonction renverra une chaîne vide. Par exemple : {{#sub:Icecream|3|-6}} retourne une chaîne vide ;
• cette fonction gère les caractères multibits de la norme UTF-8. Par exemple : {{#sub:Žmržlina|3}} retourne žlina ;
• de même que pour #len, <nowiki> et les autres balises d’extensions sont traitées comme ayant une longueur égale à un, puisque la fonction utilise la position des caractères. Par exemple : {{#sub:<nowiki>This is a </nowiki>test|1}} retourne test ;
• si votre chaîne comporte un double-point ("comme:ceci"), enlever seulement le texte qui le précède a pour effet de placer la sous-chaîne retournée indentée à la ligne. C’est le cas, par exemple, avec le code suivant : {{#sub:me:test|2|0}}.

pad

La fonction #pad augmente la longueur d’une chaîne donnée jusqu’à la valeur spécifiée. La syntaxe en est :

{{#pad:chaîne|longueur|remplissage|direction}}

Le paramètre longueur spécifie la longueur désirée pour la chaîne renvoyée.

Le paramètre remplissage, s’il est spécifié, est employé pour remplir les espaces vides. Il peut s’agir d’un seul caractère, qui sera répété autant que nécessaire, ou bien d’une chaîne, concaténée autant que nécessaire et tronquée afin que l’ensemble atteigne la longueur désirée. Par exemple : {{#pad:Ice|10|xX}} retourne xXxXxXxIce.

Si le remplissage n’est pas spécifié, la fonction utilise des espaces.

Le paramètre direction, s’il est spécifié, il peut prendre l’une de ces valeurs :

• left - le remplissage s’effectuera par la gauche de la chaîne. Par exemple : {{#pad:Ice|5|x|left}} retourne xxIce.
• right - le remplissage s’effectuera par la droite de la chaîne. Par exemple : {{#pad:Ice|5|x|right}} retourne Icexx.
• center - la chaîne originale sera centrée au sein de la chaîne de retour. Par exemple : {{#pad:Ice|5|x|center}} retourne xIcex.

Si la direction n’est pas spécifiée, le remplissage s’effectuera du côté gauche de la chaîne.

La valeur de retour est la chaîne donnée, rallongée d’un nombre longueur de caractères, en utilisant remplissage pour combler les espaces vides. Si la chaîne de départ est déjà plus longue que longueur, elle n’est ni rallongée, ni tronquée.

Notes :

• la valeur maximale autorisée pour longueur est limitée par le paramètre global $wgStringFunctionsLimitPad ;
• cette fonction ne supporte que partiellement les caractères multibits de la norme UTF-8. Ceux-ci sont correctement traités lorsqu’ils apparaissent dans la chaîne d’origine, mais non respectés s’ils se trouvent dans le remplissage. Par exemple :

  {{#pad:Zmrzlina|12|z}} retourne zzzzZmrzlina ;

  {{#pad:Žmržlina|12|z}} retourne zzzzŽmržlina ;

  {{#pad:Žmržlina|12|ž}} retourne žžŽmržlina ;

• les balises telles que <nowiki> et celles des extensions ne sont pas autorisées dans le remplissage. Si celui-ci contient pareille balise, il sera tronqué.

replace

La fonction #replace retourne la chaîne d’origine dont toutes les occurrences correspondant au terme recherché ont été remplacées par le terme de remplacement.

{{#replace:chaîne|terme recherché|terme de remplacement}}

Si le terme recherché n’est pas spécifié, la fonction cherchera les espaces uniques.

Si le terme de remplacement n’est pas spécifié ou se trouve vide, toutes les occurrences du terme recherché seront enlevées de la chaîne.

Notes :

• cette fonction est sensible à la casse ;
• la taille maximale autorisée pour le terme recherché est limitée par le paramètre global $wgStringFunctionsLimitSearch ;
• la taille maximale autorisée pour le terme de remplacement est limitée par le paramètre global $wgStringFunctionsLimitReplace ;
• même si le terme de remplacement est une espace, une chaîne vide est utilisée. Il s’agit d’un effet de bord du parseur de MediaWiki. Pour utiliser une espace comme terme de remplacement, placez-la entre deux balises <nowiki> ;
  • Exemple : {{#replace:My_little_home_page|_|<nowiki> </nowiki>}} retourne My little home page ;
  • Notez que cela constitue l’unique usage acceptable de <nowiki> dans le terme de remplacement ; autrement, <nowiki> pourrait être utilisée pour contourner $wgStringFunctionsLimitReplace, en injectant un nombre de caractères de taille arbitraire dans la chaîne de sortie. Pour cette raison, toutes les occurrences de <nowiki> (ou de n’importe quelle autre balise d’extension) dans le terme de remplacement sont remplacées par des espaces ;
• cette fonction gère les caractères multibits de la norme UTF-8. Par exemple : {{#replace:Žmržlina|ž|z}} retourne Žmrzlina.

Remplacement insensible à la casse :
Actuellement, la syntaxe ne permet pas le choix « sensible/insensible à la casse ». Cela dit, vous pouvez utiliser des mots magiques de formatage (tels que {{lc:chaîne}}) comme substitut. Par exemple, si vous souhaitez effacer le mot « Catégorie: » d’une chaîne, sans restriction sur la casse, vous pouvez écrire :

{{#replace:{{lc:{{{1}}}}}|catégorie:|}}

Le désavantage de cette méthode est cependant de renvoyer l’ensemble de la chaîne en minuscules. Pour conserver la casse après le remplacement, il vous faudra par exemple utiliser plusieurs remplacements différents pour parvenir à la même chose.

explode

La fonction #explode découpe la chaîne fournie en morceaux et retourne l’un d’entre eux. La syntaxe en est :

{{#explode:chaîne|délimiteur|position}}

Le paramètre délimiteur spécifie une chaîne à utiliser pour découper la chaîne en morceaux. Ce délimiteur ne fait donc partie d'aucun morceau et, quand deux délimiteur sont côte-à-côte, un espace vide est créé entre eux. Si le paramètre n’est pas fourni, une espace est utilisée à sa place.

Le paramètre position spécifie le morceau à retourner, numéroté à partir de zéro. Si ce paramètre n’est pas spécifié, la fonction renvoie le premier morceau (ie. celui dont l’index vaut 0). Lorsqu’une valeur négative est fournie, les morceaux sont comptés depuis la fin ; dans ce cas, le morceau d’index -1 est le dernier de la chaîne. Par exemple :

• {{#explode:And if you tolerate this| |2}} retourne you ;
• {{#explode:String/Functions/Code|/|-1}} retourne Code ;
• {{#explode:Split%By%Percentage%Signs|%|2}} retourne Percentage.

La valeur de retour est le « positionième » morceau de la chaîne. S’il se trouve moins de morceaux que position le spécifie, une chaîne vide est retournée.

Notes :

• cette fonction est sensible à la casse ;
• la taille maximale autorisée pour le délimiteur est limitée par le paramètre global $wgStringFunctionsLimitSearch ;
• cette fonction gère les caractères multibits de la norme UTF-8. Par exemple : {{#explode:Žmržlina|ž|1}} retourne lina.

urlencode et urldecode

Ces deux fonctions opèrent en tandem : #urlencode transforme une chaîne quelconque en chaîne utilisable en tant qu’URL, et #urldecode effectue l’opération inverse. Leur syntaxe en est :

{{#urlencode:chaîne}}
{{#urldecode:chaîne}}

Notes :

• ces fonctions fonctionnent en utilisant directement les fonctions de PHP urlencode() et urldecode() ;
• pour les ancrages au sein d’une page, utilisez plutôt {{anchorencode}}. Les résultats de {{anchorencode}} sont compatibles avec les ancrages générés par les liens comme [[Page#Ancre]] ; ce n’est pas forcément le cas avec les résultats de {{#urlencode}}.