Module:String/Documentation

Ceci est la page de documentation de Module:String [modifier] [purger].

Cette sous-page contient les instructions et les catégories de son module d'origine et elle n'est pas destinée à être visualisée directement.

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 sont des 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)

Autres fonctions :
À compléter…

Modules externes et autres éléments dont ce module a besoin pour fonctionner :
À compléter…

len

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

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|index_de_départ|index_de_fin}}

OU

{{#invoke:String|sub|s=chaîne_de_caractère_cible|i=index_de_départ|j=index_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 index 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'index 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

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_index|match_number|plain_flag|nomatch_output}}

OU

{{#invoke:String|match|s=source_string|pattern=pattern_string|start=start_index
    |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'index de s auquel commencer la recherche. Le premier caractère de la chaîne de caractères a pour index 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 :

pos

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

Utilisation

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

OU

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

Paramètres

target : La chaîne de caractère à explorer
pos : L'index 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 index 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 index de 0 ou supérieur à la longueur de la chaîne de caractères renvoie une erreur.

find

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_index|plain_flag}}

OR

{{#invoke:String|find|source=source_str|target=target_str|start=start_index|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'index de source auquel commencer la recherche. Le premier caractère de la chaîne de caractères a pour index 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 index 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

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

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 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'index 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'index est inversé on commence à la fin
{{#invoke:String|sub|ABCDEFGHIJ|-5|-2}}    renvoie FGHI
{{#invoke:String|sub|ABCDEFGHIJ|-5|2}}     renvoie une erreur, l'index de fin doit être après l'index de début (2 est placé avant -5) 
{{#invoke:String|sub|ABCDEFGHIJ|-5|7}}     renvoie FGHI, l'index de fin est bien après l'index 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).

Projet Scribunto