Module:String/Documentation

Le module String (un mot anglais signifiant chaîne de caractères) permet de manipuler des chaînes de caractères. Les fonctions fournies par ce module sont prévues pour un appel depuis des modèles. Appeler ce module depuis un autre module a peu d'intérêt car les fonctions fournies reprennent les fonctions natives de lua et les fonctions fournies par la bibliothèque mw.ustring.

Utilisation

Fonctions exportables :

• len – renvoie le nombre de caractères dans une chaîne, prend en compte les caractères multi-octets (len ou length signifie taille, longueur)
• sub – renvoie une partie de la chaîne de caractères (sub ou sub-string signifie sous-chaîne)
• match – renvoie la première correspondance d'un motif dans une chaîne de caractères
• pos – renvoie le caractère à une position donnée d'une chaîne de caractères
• find – renvoie les indices de fin de chaque occurrence d'un motif dans une chaîne de caractères
• replace – renvoie la chaîne de caractères initiale dans laquelle un motif est remplacé par un autre
• rep – renvoie la chaîne de caractères passée en argument répété autant de fois que souhaité
• count – renvoie le nombre d'occurrences d'un motif dans une chaîne de caractères

Autres fonctions : « Helper functions » (fonctions qui auraient pu être locales, mais pour une raison inconnue sont publiques)

• _getParameters – permet l'extraction dans un tableau des arguments du frame
• _error – permet la mise en forme des messages d'erreur
• _getBoolean – permet l'interprétation de chaînes de caractères comme booléens
• _escapePattern – permet d'« échapper » tous les caractères spéciaux afin qu'ils soient pris en compte comme du texte et non comme des paramètres d'un motif.

Modules externes et autres éléments dont ce module a besoin pour fonctionner :

• Bibliothèque mw.ustring :
  • mw.ustring.len – Renvoie la longueur d'une chaîne de caractères ;
  • mw.ustring.sub – Renvoie une tranche d'une chaîne de caractères ;
  • mw.ustring.gsub – Renvoie une chaîne de caractères dans laquelle toutes les occurrences d'un motif sont remplacées par une chaîne de remplacement ;
  • mw.ustring.match – Renvoie la première correspondance d'un motif dans une chaine de caractères ;
  • mw.ustring.gmatch – Renvoie un itérateur contenant toutes les correspondances d'un motif dans une chaine de caractères ;
  • mw.ustring.find – Renvoie les indices de fin des occurrences d'un motif dans une chaîne de caractères ;
  • mw.ustring.rep – Renvoie une chaîne de caractères répétée plusieurs fois ;
• mw.getCurrentFrame – Renvoie l'objet frame courant, généralement l'objet frame du dernier appel à #invoke.

len

Adapte mw.ustring.len pour un appel depuis un modèle.

Cette fonction renvoie la longueur de la chaîne de caractère cible.

Utilisation

{{#invoke:String|len|chaîne_de_caractère_cible}}

OU

{{#invoke:String|len|s=chaîne_de_caractère_cible}}

Paramètres

• s : la chaîne de caractère dont la longueur doit être signalée

S'il est appelé à l'aide de paramètres nommés, MediaWiki supprimera automatiquement tout espace blanc de début ou de fin de la chaîne de caractère cible.

sub

Adapte mw.ustring.sub pour un appel depuis un modèle.

Cette fonction renvoie une sous-chaîne de caractère spécifiée par des indices numériques d'une chaîne cible.

Utilisation

{{#invoke:String|sub|chaîne_de_caractère_cible|indice_de_départ|indice_de_fin}}

OU

{{#invoke:String|sub|s=chaîne_de_caractère_cible|i=indice_de_départ|j=indice_de_fin}}

Paramètres

• s : la chaîne de caractère de départ
• i : le début de la sous-chaîne de caractère commence à l'entier indiqué par ce paramètre, par défaut à 1.
• j : la fin de la sous-chaîne de caractère finit à l'entier indiqué par ce paramètre.

Le premier caractère de la chaîne se voit attribuer un indice de 1. Si i ou j est une valeur négative, cela est interprété comme la sélection d'un caractère en comptant à rebours à partir de la fin de la chaîne de caractère cible. Par conséquent, une valeur de -1 revient à sélectionner le dernier caractère de la chaîne.

Si les indices demandés sont hors limites pour la chaîne donnée, une erreur est signalée. Si un paramètre d'indice est omis, la chaîne de caractère cible est reprise à l'identique, au commencement ou à la fin suivant l'omission et le signe du paramètre restant.

match

Adapte mw.ustring.match et mw.ustring.gmatch pour un appel depuis un modèle. pour un appel depuis un modèle.

Cette fonction renvoie une sous-chaîne de caractères issue de la chaîne de caractères source correspondant à un motif spécifique.

Utilisation

{{#invoke:String|match|source_string|pattern_string|start_indice|match_number|plain_flag|nomatch_output}}

OU

{{#invoke:String|match|s=source_string|pattern=pattern_string|start=start_indice
    |match=match_number|plain=plain_flag|nomatch=nomatch_output}}

Paramètres

• s : La chaîne de caractères sur laquelle effectuer la recherche
• pattern : Le motif recherché
• start : L'indice de s auquel commencer la recherche. Le premier caractère de la chaîne de caractères a pour indice 1. Par défaut, 1.
• match : Dans certains cas, il est possible d'effectuer plusieurs correspondances sur une seule chaîne. Le paramètre match spécifie la correspondance à conserver, défini tel que pour la première correspondance match = 1. Si un nombre négatif est donné comme valeur de match, la correspondance est renvoyée en partant de la fin. Ainsi, match = -1 est équivalent à demander la dernière correspondance. Par défaut, 1.
• plain : Booléen indiquant si le motif doit être interprété en tant que texte brut. Par défaut, false.
• nomatch : Valeur à retourner si aucune correspondance n'est trouvée.

Lorsqu'invoqué en utilisant des paramètres nommés, Mediawiki retire automatiquement tout espace vide en début et en fin d'une chaîne de caractères. Dans certaines situations, ce comportement est désirable. Dans d'autres, on veut l'éviter.

Si les valeurs des paramètres match ou start sont plus élevées que la longueur de la chaîne de caractères s, cette fonction génère une erreur. Une erreur est aussi générée si aucune correspondance n'est trouvée et que le paramètre nomatch n'est pas défini. En ajoutant le paramètre ignore_errors=true, les erreurs seront supprimées et remplacées par le renvoi d'un chaîne de caractères vide.

Pour davantage d'informations sur la construction de motifs Lua qui sont une forme d'expression régulière, voir :

• http://www.lua.org/manual/5.1/manual.html#5.4.1
• mw:Extension:Scribunto/Lua reference manual/fr#Motifs (pattern)
• mw:Extension:Scribunto/Lua reference manual/fr#Motifs ustring (pattern)

pos

Cette fonction renvoie le caractère d'une chaîne de caractères situé à la position pos.

Utilisation

{{#invoke:String|pos|target_string|indice_value}}

OU

{{#invoke:String|pos|target=target_string|pos=indice_value}}

Paramètres

• target : La chaîne de caractère à explorer
• pos : L'indice du caractère à renvoyer au sein de la chaîne target.

Lorsqu'invoqué en utilisant des paramètres nommés, Mediawiki retire automatiquement tout espace vide en début et en fin d'une chaîne de caractères. Dans certaines situations, ce comportement est désirable. Dans d'autres, on veut l'éviter.

Le premier caractère de la chaîne se voit attribuer un indice de 1.

Si un nombre négatif est donné comme valeur de target, la fonction compte en partant de la fin. Ainsi, target = -1 est équivalent à demander le dernier caractère.

Un indice de 0 ou supérieur à la longueur de la chaîne de caractères renvoie une erreur.

find

Adapte mw.ustring.find pour un appel depuis un modèle.

Cette fonction permet la recherche d'une chaîne de caractères ou d'un motif au sein d'une autre chaîne de caractères.

Utilisation

{{#invoke:String|find|source_str|target_string|start_indice|plain_flag}}

OR

{{#invoke:String|find|source=source_str|target=target_str|start=start_indice|plain=plain_flag}}

Paramètres

• source : La chaîne de caractère à explorer
• target : Le motif ou la chaîne de caractères à trouver
• start : L'indice de source auquel commencer la recherche. Le premier caractère de la chaîne de caractères a pour indice 1.
• plain : Indicateur booléen indiquant que le modèle doit être compris comme du texte brut et non comme une expression régulière de style Lua compatible Unicode; la valeur par défaut est true

Lorsqu'invoqué en utilisant des paramètres nommés, Mediawiki retire automatiquement tout espace vide en début et en fin d'une chaîne de caractères. Dans certaines situations, ce comportement est désirable. Dans d'autres, on veut l'éviter.

Cette fonction renvoie le premier indice de source en commençant de start auquel on peut trouver target. Si target n'est pas trouvée, cette fonction renvoie 0. Si l'un des deux paramètres source ou target est omis ou vide, cette fonction retourne également 0.

Cette fonction fonctionne pour les chaînes de caractères encodées en UTF-8.

replace

Adapte mw.ustring.gsub pour un appel depuis un modèle.

Cette fonction permet le remplacement d'une chaîne de caractères ou d'un motif cible au sein d'une chaîne de caractères par une autre chaîne de caractères.

Utilisation

{{#invoke:String|replace|source_str|pattern_string|replace_string|replacement_count|plain_flag}}

OR

{{#invoke:String|replace|source=source_string|pattern=pattern_string|replace=replace_string|
   count=replacement_count|plain=plain_flag}}

Paramètres

• source : La chaîne de caractère à explorer
• pattern : Le motif ou la chaîne de caractères à trouver dans source
• replace : Le texte de remplacement
• count : Le nombre d'occurrences à remplacer. Par défaut, toutes.
• plain : Indicateur booléen indiquant que le modèle doit être compris comme du texte brut et non comme une expression régulière de style Lua compatible Unicode; la valeur par défaut est true

rep

Adapte mw.ustring.rep pour un appel depuis un modèle.

Cette fonction répète la même chaîne de multiple fois.

Utilisation

{{#invoke:String|rep|texte|nombre}}

Paramètres :

• texte : le texte à répéter
• nombre : le nombre de répétition

count

Cette fonction utilise une fonctionnalité de mw.ustring.gsub.

Cette fonction compte le nombre de fois qu'un motif apparaît dans la chaîne de caractère.

Utilisation

{{#invoke:String|count|texte|motif|plain_flag}}

Paramètres

• texte : la chaîne de caracère
• motif : le motif (ou pattern) a rechercher
• plain_flag : Indicateur booléen indiquant que le modèle doit être compris comme du texte brut et non comme une expression régulière de style Lua compatible Unicode; la valeur par défaut est true

Exemples

len

{{#invoke:String|len|ABCDEFGHIJ}}

renvoie 10

{{#invoke:String|len|É}} 

renvoie 1, même si É occupe 2 octets

{{#invoke:String|len| }}  

renvoie 1 , les espaces blancs sont pris en compte

sub

{{#invoke:String|sub|ABCDEFGHIJ|0}}        renvoie une erreur, ici l'indice commence à 1 (contrairement à d'autres langages de programmation)
{{#invoke:String|sub|ABCDEFGHIJ|5}}        renvoie EFGHIJ, on commence à partir du 5ème caractère et on prend le reste
{{#invoke:String|sub|ABCDEFGHIJ|1|3}}      renvoie ABC, on commence à partir du 1er jusqu'au 3ème
{{#invoke:String|sub|ABCDEFGHIJ|1|1}}      renvoie A
{{#invoke:String|sub|ABCDEFGHIJ|-1}}       renvoie J, l'indice est inversé on commence à la fin
{{#invoke:String|sub|ABCDEFGHIJ|-5|-2}}    renvoie FGHI
{{#invoke:String|sub|ABCDEFGHIJ|-5|2}}     renvoie une erreur, l'indice de fin doit être après l'indice de début (2 est placé avant -5) 
{{#invoke:String|sub|ABCDEFGHIJ|-5|7}}     renvoie FGHI, l'indice de fin est bien après l'indice de début

count

Exemples :

• {{#invoke:String|count|aabbcc|a}} : 2 --nombre de a
• {{#invoke:String|count|aabbcc|z}} : 0 --nombre de z
• {{#invoke:String|count|aabbcc|[ac]|plain=false}} : 4 --nombre de a ou de c
• {{#invoke:String|count|11-aa-2587|[0-9]|plain=false}} : 6 --nombre de chiffres
• {{#invoke:String|count|Il était une fois| |plain=true}} : 3 --nombre de blancs
• {{#invoke:String|count|Il était une fois|[ ]|plain=false}} : 3 --nombre de blancs

Voir aussi

• Catégorie:Modèle de manipulation de chaîne

• (en) Cet article est partiellement ou en totalité issu de l’article de Wikipédia en anglais intitulé « Module:String/doc » (voir la liste des auteurs).