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. Cette fonction est prévue 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.

Fonctionnement

{{#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.

Fonctionnement

{{#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

This function returns a single character from the target string at position pos.

Usage:

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

OR

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

Parameters

target: The string to search
pos: The index for the character to return

If invoked using named parameters, Mediawiki will automatically remove any leading or trailing whitespace from the target string. In some circumstances this is desirable, in other cases one may want to preserve the whitespace.

The first character has an index value of 1.

If one requests a negative value, this function will select a character by counting backwards from the end of the string. In other words pos = -1 is the same as asking for the last character.

A requested value of zero, or a value greater than the length of the string returns an error.

find

This function allows one to search for a target string or pattern within another string.

Usage:

{{#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}}

Parameters

source: The string to search
target: The string or pattern to find within source
start: The index within the source string to start the search, defaults to 1
plain: Boolean flag indicating that target should be understood as plain text and not as a Lua style regular expression, defaults to true

If invoked using named parameters, Mediawiki will automatically remove any leading or trailing whitespace from the parameter. In some circumstances this is desirable, in other cases one may want to preserve the whitespace.

This function returns the first index >= "start" where "target" can be found within "source". Indices are 1-based. If "target" is not found, then this function returns 0. If either "source" or "target" are missing / empty, this function also returns 0.

This function should be safe for UTF-8 strings.

replace

This function allows one to replace a target string or pattern within another string.

Usage:

{{#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}}

Parameters

source: The string to search
pattern: The string or pattern to find within source
replace: The replacement text
count: The number of occurences to replace, defaults to all.
plain: Boolean flag indicating that pattern should be understood as plain text and not as a Lua style regular expression, defaults to 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épeter
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