Mòdul:String/ús

Aquest mòdul proporciona accés a funcions bàsiques sobre cadenes (strings).

La majoria d'aquestes funcions es poden invocar amb paràmetres amb nom, sense nom o una barreja. Si s'usen paràmetres amb nom cal tenir en compte que el Mediawiki elimina els espais en blanc inicials i finals del valor del paràmetre. Segons l'ús previst pot ser convenient tant conservar-los com eliminar-los.

Algunes funciones admeten paràmetres amb patrons Lua que són una mena d'expressions regulars. Vegeu en el manual: patterns i Ustring patterns.

Opcions globals:

• ignore_errors: posat a 'true' o 1, en cas d'error retorn una cadena buida en lloc del missatge d'error.
• error_category: si es detecta un error especifica el nom de la categoria a incloure amb el missatge d'error. Per defecte és Categoria:Errors detectats pel mòdul String.
• no_category: posat a 'true' o 1, no afegeix cap categoria si es genera un error.

Funcions

len

Retorna la longitud de la cadena. >>> Es pot cridar amb {{Str len}}.

Sintaxi

{{#invoke:string|len|cadena}}

{{#invoke:string|len|s=cadena}}

Paràmetres:

s: La cadena a trobar la seva longitud

sub

Retorna una subcadena de la cadena indicada en els índex especificats. >>> Es pot cridar amb {{Str sub}}.

Sintaxi

{{#invoke:string|sub|cadena|índex inicial|índex final}}

{{#invoke:string|sub|s=cadena|i=índex inicial|j=índex final}}

Paràmetres:

s: la cadena on extraure la subcadena

i: índex inicial de la subcadena, per defecte 1, el primer caràcter de la cadena.

j: índex final de la subcadena, per defecte la longitud total, fins l'últim caràcter.

Si qualsevol dels dos índexs tenen valor negatiu llavors comptarà des del final de la cadena. Així, -1 és l'índex de l'últim caràcter de la cadena. Si els índexs són superiors a la longitud de la cadena llavors reportarà un error.

match

Retorna una subcadena de la cadena indicada que coincideixi amb un patró especificat.

Sintaxi

{{#invoke:string|match|cadena|patró|índex inicial|número coincidència|indicador text net|text no coincidència}}

{{#invoke:string|match|s=cadena|pattern=patró|start=índex inicial|match=número coincidència|plain=indicador text net|nomatch=text no coincidència}}

Paràmetres:

s: cadena on es fa la cerca

pattern: patró o cadena a cercar.

start: índex de la cadena on començar a cercar, per defecte 1, el primer caràcter.

match: si es troben múltiples coincidències, especifica quina d'elles retornar. Per defecte és 1, la primera coincidència trobada. Un número negatiu compta des del final, per tant match=-1 és l'última coincidència.

plain: indica si el patró s'ha d'interpretar com a text net, per defecte 'false'.

nomatch: en cas de no trobar cap coincidència, retorna el valor de "nomatch" en lloc d'un error.

Si el número match o l'índex start estan fora del rang de la cadena, llavors la funció genera un error. També genera un error si no troba cap coincidència. Amb el paràmetre global ignore_errors=true se suprimeix l'error i retorna una cadena buida.

pos

Retorna el caràcter de la cadena que es troba en la posició indicada.

Sintaxi

{{#invoke:string|pos|cadena|índex}}

{{#invoke:string|pos|target=cadena|pos=índex}}

Paràmetres:

target: cadena on cercar

pos: índex del caràcter a retornar

El primer caràcter té l'índex 1. L'últim és -1, comptant des del final. Si età fora del rang de la cadena llavors retornarà un error.

find

Retorna la posició on es troba una cadena o patró cercant en una altra cadena. >>> Es pot cridar amb {{Str find}}.

Sintaxi

{{#invoke:string|find|cadena|cerca|índex inicial|indicador text net}}

{{#invoke:string|find|source=cadena|target=cerca|start=índex inicial|plain=indicador text net}}

Paràmetres:

source: cadena on cercar

target: cadena a cercar o patró de cerca

start: índex de la cadena font on començar a cercar, per defecte 1, el primer caràcter.

plain: indica si la cerca s'ha d'interpretar com a text net, en cas contrari com a patró Lua. Per defecte és 'true'.

Retorna el primer índex, major o igual que "start", on "target" s'ha trobat a "source". Si no el troba retorna 0. Si "source" o "target" estan buits o indefinits també retorna 0. Se suposa que funciona bé amb cadenes UTF-8.

replace

Permet reemplaçar una cadena o patró en una altra cadena. >>> Es pot cridar amb {{Str rep}}.

Sintaxi

{{#invoke:string|replace|cadena|patró|reemplaçament|comptador|indicador text net}}

{{#invoke:string|replace|source=cadena|pattern=patró|replace=reemplaçament|count=comptador|plain=indicador text net}}

Paràmetres:

source: cadena on cercar

pattern: cadena de cerca o patró a cercar

replace: text de reemplaçament

count: número d'ocurrències a reemplaçar, per defecte totes.

plain: indica si la cerca s'ha d'interpretar com a text net, en cas contrari com a patró Lua. Per defecte és 'true'.

rep

Repeteix la cadena un número de vegades.

{{#invoke:string|rep|cadena|vegades}}

Paràmetres:

cadena: cadena a repetir

vegades: número de vegades a repetir

strip

Suprimeix caràcters de la cadena. >>> Es pot cridar amb {{Str strip}}.

Sintaxi

{{#invoke:String|strip|cadena|caràcters|text_pla}}

{{#invoke:String|strip|source=cadena|chars=caràcters|plain=text_pla}}

Paràmetres:

source: La cadena a tractar

chars: El patró o llista de caràcters a suprimir de la cadena

plain: Indicador sobre si el paràmetre chars ha de ser entès com a text pla (si és true) o si ha de ser entès com a expressió regular de tipus Lua (si és false). Per defecte és true.

Els espais en blanc del principi i el final també se suprimeixen de la cadena.

split

Trosseja una cadena segons un separador, i retorna el tros n-èssim, segons l'índex donat. >>> Es pot cridar amb {{Str split}}.

Sintaxi

{{#invoke:String|split|cadena|separador|índex}}

{{#invoke:String|split|source=cadena|separator=separador|count=índex}}

Paràmetres:

source: La cadena a tractar

separator: El separador pel qual s'ha de trossejar la cadena

count: L'índex del tros a retornar

isNumber

Estableix si la cadena és un nombre. >>> Es pot cridar amb {{Str IsNumber}}.

Sintaxi

{{#invoke:String|isNumber|cadena}}

{{#invoke:String|isNumber|source=cadena}}

Paràmetres:

source: La cadena a tractar

count

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