Modulo:String: Difference between revisions

From Semi del Verbo
(rimuovo funzione incompleta e rimpiazzata da Modulo:IP validator)
(separate annotations for str.match from those for str._match)
Line 1: Line 1:
--[[
--[[


Questo modulo serve a fornire l'accesso alle funzioni stringa base.
This module is intended to provide access to basic string functions.


La maggior parte delle funzioni di questo modulo possono essere invocate con
Most of the functions provided here can be invoked with named parameters,
parametri con nome, senza nome o con un misto di entrambi. Quando vengono usati
unnamed parameters, or a mixture. If named parameters are used, Mediawiki will
parametri con nome il software di Mediawiki rimuoverà ogni spazio iniziale o finale
automatically remove any leading or trailing whitespace from the parameter.
dal parametro. A seconda dell'uso che si vuole fare della funzione può essere
Depending on the intended use, it may be advantageous to either preserve or
vantaggioso conservare oppure rimuovere questi spazi.
remove such whitespace.


Opzioni globali
Global options
     ignore_errors: se settato a 'true' o 1, ogni condizione di errore ritornerà una stringa vuota
     ignore_errors: If set to 'true' or 1, any error condition will result in
                  piuttosto che un messaggio di errore.
        an empty string being returned rather than an error message.


     error_category: nel caso si verifichi un errore è il nome di una categoria da includere
     error_category: If an error occurs, specifies the name of a category to
                    insieme al messaggio di errore. La categoria di default
        include with the error message. The default category is
                    [Categoria:Errori del Module String]. (TODO:verificare)
        [Category:Errors reported by Module String].


     no_category: Se settato a 'true' o 1, non verranno aggiunte categorie in caso di errore.
     no_category: If set to 'true' or 1, no category will be added if an error
 
        is generated.
Unit tests per questo modulo sono disponibili a Module:String/test.
 
Diverse funzioni fanno uso di pattern Lua, questi sono una forma di espressione regolare, per
maggiori informazioni vedi:
* http://www.lua.org/manual/5.1/manual.html#5.4.1
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Patterns
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Ustring_patterns


Unit tests for this module are available at Module:String/tests.
]]
]]


Line 34: Line 28:
len
len


Questa funzione ritorna la lunghezza di una stringa.
This function returns the length of the target string.


Uso:
Usage:
{{#invoke:String|len|stringa|}}
{{#invoke:String|len|target_string|}}
O
OR
{{#invoke:String|len|s=stringa}}
{{#invoke:String|len|s=target_string}}


Parametri
Parameters
     s: La stringa di cui ritornare la lunghezza
     s: The string whose length to report


Se invocata usando parametri nominati, Mediawiki rimuoverà automaticamente ogni spazio iniziale
If invoked using named parameters, Mediawiki will automatically remove any leading or
o finale dalla stringa.
trailing whitespace from the target string.
]]
]]
function str.len( frame )
function str.len( frame )
    local new_args = str._getParameters( frame.args, {'s'} );
local new_args = str._getParameters( frame.args, {'s'} )
    local s = new_args['s'] or '';
local s = new_args['s'] or ''
    return mw.ustring.len( s )
return mw.ustring.len( s )
end
end


Line 56: Line 50:
sub
sub


Questa funzione ritorna la sottostringa di una stringa bersaglio, come indicato dagli indici
This function returns a substring of the target string at specified indices.


Uso:
Usage:
{{#invoke:String|sub|stringa_bersaglio|indice_iniziale|indice_finale}}
{{#invoke:String|sub|target_string|start_index|end_index}}
O
OR
{{#invoke:String|sub|s=stringa_bersaglio|i=indice_iniziale|j=indice_finale}}
{{#invoke:String|sub|s=target_string|i=start_index|j=end_index}}


Parameters
Parameters
     s: La stringa da cui estrarre una sottostringa
     s: The string to return a subset of
     i: La posizione iniziale del primo carattere della sottostringa da ritornare, se non
     i: The fist index of the substring to return, defaults to 1.
      specificato è 1.
     j: The last index of the string to return, defaults to the last character.
     j: La posizione finale dell'ultimo carattere della sottostringa da ritornare, se non
      specificato corrisponde alla lunghezza della stringa_bersaglio (l'ultimo carattere).


I caratteri della stringa sono numerati a partire da 1. Se i o j hanno un valore negativo allora
The first character of the string is assigned an index of 1. If either i or j
contano la posizione contando dalla fine della stringa, -1 è l'ultimo carattere della stringa,
is a negative value, it is interpreted the same as selecting a character by
-2 il penultimo, ecc...
counting from the end of the string.  Hence, a value of -1 is the same as
selecting the last character of the string.


Se le posizioni sono al di fuori degli estremi della stringa viene ritornato un messaggio di
If the requested indices are out of range for the given string, an error is
errore.
reported.
]]
]]
function str.sub( frame )
function str.sub( frame )
    local new_args = str._getParameters( frame.args, { 's', 'i', 'j' } );
local new_args = str._getParameters( frame.args, { 's', 'i', 'j' } )
    local s = new_args['s'] or '';
local s = new_args['s'] or ''
    local i = tonumber( new_args['i'] ) or 1;
local i = tonumber( new_args['i'] ) or 1
    local j = tonumber( new_args['j'] ) or -1;
local j = tonumber( new_args['j'] ) or -1


    local len = mw.ustring.len( s );
local len = mw.ustring.len( s )


    -- Convert negatives for range checking
-- Convert negatives for range checking
    if i < 0 then
if i < 0 then
        i = len + i + 1;
i = len + i + 1
    end
end
    if j < 0 then
if j < 0 then
        j = len + j + 1;
j = len + j + 1
    end
end


    if i > len or j > len or i < 1 or j < 1 then
if i > len or j > len or i < 1 or j < 1 then
        return str._error( 'Indici fuori dagli estremi della stringa' );
return str._error( 'String subset index out of range' )
    end
end
    if j < i then
if j < i then
        return str._error( 'Indici in ordine sbagliato' );
return str._error( 'String subset indices out of order' )
    end
end


    return mw.ustring.sub( s, i, j )
return mw.ustring.sub( s, i, j )
end
end


--[[
--[[
Questa funzione implementa tutte le caratteristiche di  {{str sub}} e viene mantenuta per motivi
This function implements that features of {{str sub old}} and is kept in order
di compatibilità con template più vecchi.
to maintain these older templates.
]]
]]
function str.sublength( frame )
function str.sublength( frame )
    local i = tonumber( frame.args.i ) or 0
local i = tonumber( frame.args.i ) or 0
    local len = tonumber( frame.args.len )
local len = tonumber( frame.args.len )
    return mw.ustring.sub( frame.args.s, i + 1, len and ( i + len ) )
return mw.ustring.sub( frame.args.s, i + 1, len and ( i + len ) )
end
end


--[[
--[[
match
_match


Questa funzione ritorna dalla stringa bersaglio una sottostringa corrispondente a un pattern
This function returns a substring from the source string that matches a
specificato.
specified pattern. It is exported for use in other modules


Uso:
Usage:
{{#invoke:String|match|source_string|pattern_string|start_index|match_number|plain_flag|nomatch_output}}
strmatch = require("Module:String")._match
O
sresult = strmatch( s, pattern, start, match, plain, nomatch )
{{#invoke:String|match|s=source_string|pattern=pattern_string|start=start_index
    |match=match_number|plain=plain_flag|nomatch=nomatch_output}}


Parametri
Parameters
     s: La stringa da cercare
     s: The string to search
     pattern: Il pattern da cercare nella stringa
     pattern: The pattern or string to find within the string
     start: La posizione iniziale da cui iniziare la ricerca, se non specificato è 1.
     start: The index within the source string to start the search.  The first
     match: Se c'è ci sono corrispondenze multiple quale ritornare, 1 per la prima
        character of the string has index 1.  Defaults to 1.
    corrispondenza, 2 per la seconda ecc.. Un valore negativo indica di contare
     match: In some cases it may be possible to make multiple matches on a single
    all'indietro a partire dall'ultima corrispondenza, quindi match = -1 significa
        string.  This specifies which match to return, where the first match is
    chiedere l'ultima corrispondenza. Se non specificato è 1
        match= 1.  If a negative number is specified then a match is returned
     plain: Se vero specifica che il pattern deve essere considerato come una
        counting from the last match. Hence match = -1 is the same as requesting
          stringa normale, piuttosto che un pattern Lua. Se non specificata è falsa.
        the last match. Defaults to 1.
     nomatch: Il valore da ritornare se non ci sono corrispondenze, invece di ritornare
     plain: A flag indicating that the pattern should be understood as plain
            un errore.
        text. Defaults to false.
     nomatch: If no match is found, output the "nomatch" value rather than an error.


Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli
For information on constructing Lua patterns, a form of [regular expression], see:
spazi iniziali e finali. In alcune circostanze questo può essere il comportamento
desiderato, in altre si potrebbe volerli conservare.


Se match_number o start_index sono al di fuori degli estremi della stringa s, allora
* http://www.lua.org/manual/5.1/manual.html#5.4.1
la funzione ritorna un errore. Viene generato un errore anche se il non vengono trovate
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Patterns
corrispondenze. Per sopprimere gli errori si può aggiungere il parametro ignore_errors=true,
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Ustring_patterns
in questo caso in caso di errore verrò ritornata una stringa vuota.


]]
]]
function str.match(frame)
-- This sub-routine is exported for use in other modules
    return str._match(frame.args)
function str._match( s, pattern, start, match_index, plain_flag, nomatch )
if s == '' then
return str._error( 'Target string is empty' )
end
if pattern == '' then
return str._error( 'Pattern string is empty' )
end
start = tonumber(start) or 1
if math.abs(start) < 1 or math.abs(start) > mw.ustring.len( s ) then
return str._error( 'Requested start is out of range' )
end
if match_index == 0 then
return str._error( 'Match index is out of range' )
end
if plain_flag then
pattern = str._escapePattern( pattern )
end
 
local result
if match_index == 1 then
-- Find first match is simple case
result = mw.ustring.match( s, pattern, start )
else
if start > 1 then
s = mw.ustring.sub( s, start )
end
 
local iterator = mw.ustring.gmatch(s, pattern)
if match_index > 0 then
-- Forward search
for w in iterator do
match_index = match_index - 1
if match_index == 0 then
result = w
break
end
end
else
-- Reverse search
local result_table = {}
local count = 1
for w in iterator do
result_table[count] = w
count = count + 1
end
 
result = result_table[ count + match_index ]
end
end
 
if result == nil then
if nomatch == nil then
return str._error( 'Match not found' )
else
return nomatch
end
else
return result
end
end
end


--[[
--[[
Entry point per chiamata diretta da un modulo
match
]]
 
function str._match( args )
This function returns a substring from the source string that matches a
    local new_args = str._getParameters( args, {'s', 'pattern', 'start', 'match', 'plain', 'nomatch'} );
specified pattern.
    local s = new_args['s'] or '';
 
    local start = tonumber( new_args['start'] ) or 1;
Usage:
     local plain_flag = str._getBoolean( new_args['plain'] or false );
{{#invoke:String|match|source_string|pattern_string|start_index|match_number|plain_flag|nomatch_output}}
    local pattern = new_args['pattern'] or '';
OR
    local match_index = math.floor( tonumber(new_args['match']) or 1 );
{{#invoke:String|match|s=source_string|pattern=pattern_string|start=start_index
    local nomatch = new_args['nomatch'];
     |match=match_number|plain=plain_flag|nomatch=nomatch_output}}


     if s == '' then
Parameters
        return nomatch or str._error( 'La stringa in cui cercare è vuota' );
     s: The string to search
     end
    pattern: The pattern or string to find within the string
    if pattern == '' then
     start: The index within the source string to start the search.  The first
         return nomatch or str._error( 'La stringa o pattern da cercare è vuota' );
         character of the string has index 1.  Defaults to 1.
     end
     match: In some cases it may be possible to make multiple matches on a single
    if math.abs(start) < 1 or math.abs(start) > mw.ustring.len( s ) then
        string. This specifies which match to return, where the first match is
         return nomatch or str._error( 'La posizione iniziale richiesta è fuori dagli estremi della stringa' );
        match= 1. If a negative number is specified then a match is returned
    end
         counting from the last match. Hence match = -1 is the same as requesting
    if match_index == 0 then
         the last match.  Defaults to 1.
         return nomatch or str._error( 'Match index è nullo' );
     plain: A flag indicating that the pattern should be understood as plain
     end
         text.  Defaults to false.
    if plain_flag then
     nomatch: If no match is found, output the "nomatch" value rather than an error.
         pattern = str._escapePattern( pattern );
     end


    local result
If invoked using named parameters, Mediawiki will automatically remove any leading or
    if match_index == 1 then
trailing whitespace from each string. In some circumstances this is desirable, in
        -- Il caso più semplice, trova la prima corrispondenza
other cases one may want to preserve the whitespace.
        result = mw.ustring.match( s, pattern, start )
    else
        if start > 1 then
            s = mw.ustring.sub( s, start );
        end


        local iterator = mw.ustring.gmatch(s, pattern);
If the match_number or start_index are out of range for the string being queried, then
        if match_index > 0 then
this function generates an error.  An error is also generated if no match is found.
            -- Ricerca in avanti
If one adds the parameter ignore_errors=true, then the error will be suppressed and
            for w in iterator do
an empty string will be returned on any failure.
                match_index = match_index - 1;
                if match_index == 0 then
                    result = w;
                    break;
                end
            end
        else
            -- Ricerca all'indietro deve estrarre tutte le corrispondenze
            local result_table = {};
            local count = 1;
            for w in iterator do
                result_table[count] = w;
                count = count + 1;
            end


            result = result_table[ count + match_index ];
For information on constructing Lua patterns, a form of [regular expression], see:
        end
    end


    if result == nil then
* http://www.lua.org/manual/5.1/manual.html#5.4.1
        if nomatch == nil then
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Patterns
            return str._error( 'Corrispondenza non trovata' );
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Ustring_patterns
        else
 
            return nomatch;
]]
        end
-- This is the entry point for #invoke:String|match
    else
function str.match( frame )
        return result;
local new_args = str._getParameters( frame.args, {'s', 'pattern', 'start', 'match', 'plain', 'nomatch'} )
    end
local s = new_args['s'] or ''
local start = tonumber( new_args['start'] ) or 1
local plain_flag = str._getBoolean( new_args['plain'] or false )
local pattern = new_args['pattern'] or ''
local match_index = math.floor( tonumber(new_args['match']) or 1 )
local nomatch = new_args['nomatch']
 
return str._match( s, pattern, start, match_index, plain_flag, nomatch )
end
end


Line 226: Line 257:
pos
pos


Questa funzione ritorna il carattere della stringa in posizione pos.
This function returns a single character from the target string at position pos.


Uso:
Usage:
{{#invoke:String|pos|stringa_bersaglio|indice}}
{{#invoke:String|pos|target_string|index_value}}
O
OR
{{#invoke:String|pos|target=stringa_bersaglio|pos=indice}}
{{#invoke:String|pos|target=target_string|pos=index_value}}


Parametri
Parameters
     target: La stringa in cui cercare
     target: The string to search
     pos: La posizione del carattere da ritornare
     pos: The index for the character to return


Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli
If invoked using named parameters, Mediawiki will automatically remove any leading or
spazi iniziali e finali. In alcune circostanze questo può essere il comportamento
trailing whitespace from the target string. In some circumstances this is desirable, in
desiderato, in altre si potrebbe volerli conservare.
other cases one may want to preserve the whitespace.


I caratteri della stringa sono numerati a partire da 1. Se pos è un valore negativo allora
The first character has an index value of 1.
conta la posizione partendo dalla fine della stringa, -1 è l'ultimo carattere della stringa,
-2 il penultimo, ecc...


Se la posizione richiesta è 0 o al di fuori degli estremi della stringa viene ritornato
If one requests a negative value, this function will select a character by counting backwards
un errore.
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.
]]
]]
function str.pos( frame )
function str.pos( frame )
    local new_args = str._getParameters( frame.args, {'target', 'pos'} );
local new_args = str._getParameters( frame.args, {'target', 'pos'} )
    local target_str = new_args['target'] or '';
local target_str = new_args['target'] or ''
    local pos = tonumber( new_args['pos'] ) or 0;
local pos = tonumber( new_args['pos'] ) or 0


    if pos == 0 or math.abs(pos) > mw.ustring.len( target_str ) then
if pos == 0 or math.abs(pos) > mw.ustring.len( target_str ) then
        return str._error( 'Indice della stringa fuori dagli estremi' );
return str._error( 'String index out of range' )
    end
end


    return mw.ustring.sub( target_str, pos, pos );
return mw.ustring.sub( target_str, pos, pos )
end
end


Line 263: Line 294:
str_find
str_find


Questa funzione duplica il comportamento di  {{str_find}}, incluso i suoi comportamenti
This function duplicates the behavior of {{str_find}}, including all of its quirks.
irregolari. Questa funzione è fornita per motivi di compatibilità con i vecchi template,
This is provided in order to support existing templates, but is NOT RECOMMENDED for
ma SI RACCOMANDA di non utilizzarla in nuovi template. Nello sviluppo di nuovo codice
new code and templatesNew code is recommended to use the "find" function instead.
si raccomanda di usare la funzione "find".


Parametri
Returns the first index in "source" that is a match to "target".  Indexing is 1-based,
    source: La stringa in cui cercare
and the function returns -1 if the "target" string is not present in "source".
    target: la stringa da cercare


Ritorna la posizione nella stringa source del primo carattere in cui c'è è stata
Important Note: If the "target" string is empty / missing, this function returns a
trovata la stringa target. I caratteri della stringa sono numerati a partire da 1. La funzione
value of "1", which is generally unexpected behavior, and must be accounted for
ritorna -1 se la stringa "target" non è contenuta in "source".
separatetly.
 
Nota importante: Per compatibilità con il vecchio template se la stringa "target" è vuota o manca
la funzione ritorna un valore di "1"
]]
]]
function str.str_find( frame )
function str.str_find( frame )
    local new_args = str._getParameters( frame.args, {'source', 'target'} );
local new_args = str._getParameters( frame.args, {'source', 'target'} )
    local source_str = new_args['source'] or '';
local source_str = new_args['source'] or ''
    local target_str = new_args['target'] or '';
local target_str = new_args['target'] or ''


    if target_str == '' then
if target_str == '' then
        return 1;
return 1
    end
end


    local start = mw.ustring.find( source_str, target_str, 1, true )
local start = mw.ustring.find( source_str, target_str, 1, true )
    if start == nil then
if start == nil then
        start = -1
start = -1
    end
end


    return start
return start
end
end


Line 299: Line 325:
find
find


Questa funzione permette di cercare una stringa bersaglio o un pattern Lua all'interno di
This function allows one to search for a target string or pattern within another
un'altra stringa.
string.


Uso:
Usage:
{{#invoke:String|find|stringa_sorgente|stringa_bersaglio|indice_iniziale|plain_flag}}
{{#invoke:String|find|source_str|target_string|start_index|plain_flag}}
O
OR
{{#invoke:String|find|source=stringa_sorgente|target=stringa_bersaglio|start=indice_iniziale|plain=plain_flag}}
{{#invoke:String|find|source=source_str|target=target_str|start=start_index|plain=plain_flag}}


Parametri
Parameters
     source: La stringa in cui cercare
     source: The string to search
     target: La stringa o pattern Lua da cercare
     target: The string or pattern to find within source
     start: La posizione da cui iniziare la ricerca, se non specificato è 1
     start: The index within the source string to start the search, defaults to 1
     plain: Se è vero indica che la stringa target deve essere considerata come una
     plain: Boolean flag indicating that target should be understood as plain
          testo normale e non come un pattern Lua, se non specificata è vera
        text and not as a Lua style regular expression, defaults to true


Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli
If invoked using named parameters, Mediawiki will automatically remove any leading or
spazi iniziali e finali. In alcune circostanze questo può essere il comportamento
trailing whitespace from the parameter. In some circumstances this is desirable, in
desiderato, in altre si potrebbe volerli conservare.
other cases one may want to preserve the whitespace.


Questa funzione ritorna la prima posizione maggiore o uguale a  "start" a partire dalla quale
This function returns the first index >= "start" where "target" can be found
"target" si trova in  "source".  I caratteri della stringa sono numerati a partire da 1.
within "source".  Indices are 1-based. If "target" is not found, then this
Se "target" non viene trovato ritorna 0. Se "source" o "target" sono mancanti o vuoti ritorna 0.
function returns 0. If either "source" or "target" are missing / empty, this
function also returns 0.


Questa funzione dovrebbe essere sicura per stringhe  UTF-8.
This function should be safe for UTF-8 strings.
]]
]]
function str.find( frame )
function str.find( frame )
    local new_args = str._getParameters( frame.args, {'source', 'target', 'start', 'plain' } );
local new_args = str._getParameters( frame.args, {'source', 'target', 'start', 'plain' } )
    local source_str = new_args['source'] or '';
local source_str = new_args['source'] or ''
    local pattern = new_args['target'] or '';
local pattern = new_args['target'] or ''
    local start_pos = tonumber(new_args['start']) or 1;
local start_pos = tonumber(new_args['start']) or 1
    local plain = new_args['plain'] or true;
local plain = new_args['plain'] or true


    if source_str == '' or pattern == '' then
if source_str == '' or pattern == '' then
        return 0;
return 0
    end
end


    plain = str._getBoolean( plain );
plain = str._getBoolean( plain )


    local start = mw.ustring.find( source_str, pattern, start_pos, plain )
local start = mw.ustring.find( source_str, pattern, start_pos, plain )
    if start == nil then
if start == nil then
        start = 0
start = 0
    end
end


    return start
return start
end
end


Line 348: Line 375:
replace
replace


Questa funzione permette di rimpiazzare una stringa o pattern bersaglio con un'altra
This function allows one to replace a target string or pattern within another
stringa.
string.


Uso:
Usage:
{{#invoke:String|replace|stringa_sorgente|stringa_pattern|nuova_stringa|numero_di_sostituzioni|plain_flag}}
{{#invoke:String|replace|source_str|pattern_string|replace_string|replacement_count|plain_flag}}
O
OR
{{#invoke:String|replace|source=stringa_sorgente|pattern=stringa_pattern|replace=nuova_stringa|
{{#invoke:String|replace|source=source_string|pattern=pattern_string|replace=replace_string|
   count=numero_di_sostituzioni|plain=plain_flag}}
   count=replacement_count|plain=plain_flag}}


Parametri:
Parameters
     source: La stringa da cercare
     source: The string to search
     pattern: La stringa o pattern Lua da trovare in  source
     pattern: The string or pattern to find within source
     replace: Il testo di sostituzione
     replace: The replacement text
     count: Il numero di volte in cui rimpiazzare la stringa, se non specificato tutte.
     count: The number of occurences to replace, defaults to all.
     plain: Se vero indica che il pattern deve essere considerato come testo normale e non
     plain: Boolean flag indicating that pattern should be understood as plain
          come pattern Lua, il valore di default è vero
        text and not as a Lua style regular expression, defaults to true
]]
]]
function str.replace( frame )
function str.replace( frame )
    local new_args = str._getParameters( frame.args, {'source', 'pattern', 'replace', 'count', 'plain' } );
local new_args = str._getParameters( frame.args, {'source', 'pattern', 'replace', 'count', 'plain' } )
    local source_str = new_args['source'] or '';
local source_str = new_args['source'] or ''
    local pattern = new_args['pattern'] or '';
local pattern = new_args['pattern'] or ''
    local replace = new_args['replace'] or '';
local replace = new_args['replace'] or ''
    local count = tonumber( new_args['count'] );
local count = tonumber( new_args['count'] )
    local plain = new_args['plain'] or true;
local plain = new_args['plain'] or true


    if source_str == '' or pattern == '' then
if source_str == '' or pattern == '' then
        return source_str;
return source_str
    end
end
    plain = str._getBoolean( plain );
plain = str._getBoolean( plain )


    if plain then
if plain then
        pattern = str._escapePattern( pattern );
pattern = str._escapePattern( pattern )
        replace = mw.ustring.gsub( replace, "%%", "%%%%" ); --Only need to escape replacement sequences.
replace = mw.ustring.gsub( replace, "%%", "%%%%" ) --Only need to escape replacement sequences.
    end
end


    local result;
local result


    if count ~= nil then
if count ~= nil then
        result = mw.ustring.gsub( source_str, pattern, replace, count );
result = mw.ustring.gsub( source_str, pattern, replace, count )
    else
else
        result = mw.ustring.gsub( source_str, pattern, replace );
result = mw.ustring.gsub( source_str, pattern, replace )
    end
end


    return result;
return result
end
end


--[[
--[[
     Funzione per utilizzare string.rep in un template.
     simple function to pipe string.rep to templates.
]]
]]
function str.rep( frame )
function str.rep( frame )
    local repetitions = tonumber( frame.args[2] )
local repetitions = tonumber( frame.args[2] )
    if not repetitions then
if not repetitions then
        if frame.args[2] == '' then -- se il secondo parametro è una stringa nulla ritorno una stringa nulla
return str._error( 'function rep expects a number as second parameter, received "' .. ( frame.args[2] or '' ) .. '"' )
            return ''
end
        else
return string.rep( frame.args[1] or '', repetitions )
            return str._error( 'la funzione rep si aspetta un secondo parametro con il numero di ripetizioni, ricevuto "' .. ( frame.args[2] or '' ) .. '"' )
        end
    end
    return mw.ustring.rep( frame.args[1] or '', repetitions )
end
end


--[[
--[[
    Funzione per decodificare una stringa codificata percentualmente.
escapePattern
    Richiama la funzione mw.uri.decode di scribunto, vedi
 
    https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#mw.uri.decode
This function escapes special characters from a Lua string pattern. See [1]
]]
for details on how patterns work.


function str.decode( frame )
[1] https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Patterns
    local valid_enctype = { QUERY = true, WIKI = true, PATH = true}


    local new_args = str._getParameters(frame.args, {'source', 'enctype'})
Usage:
    local source = new_args['source'] or ''
{{#invoke:String|escapePattern|pattern_string}}
    local enc_type = new_args['enctype'] or 'QUERY'
    if not valid_enctype[enc_type] then
        enc_type = 'QUERY'
    end
    return mw.uri.decode(source, enc_type)
end


--[[
Parameters
     Funzione per semplificare stringhe con diacritici
     pattern_string: The pattern string to escape.
]]
]]
 
function str.escapePattern( frame )
function str.collate( frame )
local pattern_str = frame.args[1]
 
if not pattern_str then
    local collation = {
return str._error( 'No pattern string specified' )
        { '[áàăắằẵẳâấầẫẩǎåǻäǟãȧǡąāảȁȃạặậḁⱥᶏᴂɐᶐɒ]' , 'a'},
end
        {'[ÁÀĂẮẰẴẲÂẤẦẪẨǍÅÅǺÄǞÃȦǠĄĀẢȀȂẠẶẬḀȺᴁ]', 'A'},
local result = str._escapePattern( pattern_str )
        {'[ḃḅḇbƀɓ]', 'b'},
return result
        {'[ḂḄḆɃ]', 'B'},
        {'[ćĉčċçḉȼƈ]', 'c'},
        {'[ĆĈČĊÇḈȻƇ]', 'C'},
        {'[đḍḓḏðď]', 'd'},
        {'[ĐḌḒḎÐĎ]', 'D'},
        {'[éèèêếềễểěëẽėȩḝęēḗḕẻȅȇẹệḙḛǝ]', 'e'},
        {'[ÉÈÈÊẾỀỄỂĚËẼĖȨḜĘĒḖḔẺȄȆẸỆḘḚƎ]', 'E'},
        {'[ḟⅎ]', 'f'},
        {'[ḞℲ]', 'F'},
        {'[ǵğĝǧġģḡᵹɠ]', 'g'},
        {'[ǴĞĜǦĠĢḠƓ]', 'G'},
        {'[ĥȟḧḣḩħḥḫẖ]', 'h'},
        {'[ĤȞḦḢḨĦḤḪ]', 'H'},
        {'[íìĭîǐïḯĩįīỉȉȋịḭı]', 'i'},
        {'[ÍÌĬÎǏÏḮĨĮĪỈȈȊỊḬİ]', 'I'},
        {'[ĵǰ]', 'j'},
        {'[Ĵ]', 'J'},
        {'[ḱǩķ]', 'k'},
        {'[ḰǨĶ]', 'K'},
        {'[ĺľļłḷḹḽḻl·l·ŀƚⱡ]', 'l'},
        {'[ĹĽĻŁḶḸḼḺL·L·ĿȽⱠ]', 'L'},
        {'[ḿṁṃ]', 'm'},
        {'[ḾṀṂ]', 'M'},
        {'[ńǹňñṅņṇṋṉ]', 'n'},
        {'[ŃǸŇÑṄŅṆṊṈ]', 'N'},
        {'[óòŏôốồỗổǒöȫőõṍṏȭȯȱøǿǫǭōṓṑỏȍȏơớờỡởợọộ]', 'o'},
        {'[ÓÒŎÔỐỒỖỔǑÖȪŐÕṌṎȬȮȰØǾǪǬŌṒṐỎȌȎƠỚỜỠỞỢỌỘ]', 'O'},
        {'[ṕṗ]', 'p'},
        {'[ṔṖ]', 'P'},
        {'[ŕřṙŗȑȓṛṝṟ]', 'r'},
        {'[ŔŘṘŖȐȒṚṜṞ]', 'R'},
        {'[śṥŝšṧṡşṣṩș]', 's'},
        {'[ŚṤŜŠṦṠŞṢṨȘ]', 'S'},
        {'[ťṫẗţṭțṱṯ]', 't'},
        {'[ŤṪŢṬȚṰṮ]', 'T'},
        {'[úùŭûǔůüǘǜǚǖűũṹųūṻủȕȗưứừữửựụṳṷṵʉ]', 'u'},
        {'[ÚÙŬÛǓŮÜǗǛǙǕŰŨṸŲŪṺỦȔȖƯỨỪỮỬỰỤṲṶṴɄ]', 'U'},
        {'[ṽṿʋ]', 'v'},
        {'[ṼṾƲ]', 'V'},
        {'[ẃẁŵẘẅẇẉⱳ]', 'w'},
        {'[ẂẀŴ̊ẄẆẈⱲ]', 'W'},
        {'[ýỳŷẙÿỹẏȳỷỵɏƴ]', 'y'},
        {'[ÝỲŶ̊ŸỸẎȲỶỴɎƳ]', 'Y'},
        {'[źẑžżẓẕƶȥʐⱬ]', 'z'},
        {'[ŹẐŽŻẒẔƵȤʐⱫ]', 'Z'},
    }
 
    local new_args = str._getParameters(frame.args, {'source'})
    local source = new_args['source'] or ''
    --local source = mw.ustring.toNFC(source)
 
    for _, el in ipairs(collation) do
        source = mw.ustring.gsub( source, el[1], el[2])
    end
    return source
end
end


--[[
--[[
    Funzione per estrarre da un titolo la stringa adatta all'ordinamento alfabetico.  
count
This function counts the number of occurrences of one string in another.
]]
]]
 
function str.count(frame)
function str.titolo_alfa(frame)
local args = str._getParameters(frame.args, {'source', 'pattern', 'plain'})
    -- Evito "I", "A", "Die"... che darebbero molte false corrispondenze in lingue diverse
local source = args.source or ''
    local articoli = {"Il ", "Lo ", "La ", "L'", "Gli ", "Le ", "Un ", "Uno ", "Una ", "Un'", "The ", "An ", "Les ", "El ", "Los ", "Las ", "Der ", "Das "}
local pattern = args.pattern or ''
 
local plain = str._getBoolean(args.plain or true)
    local source = frame.args[1]
if plain then
    if not source or source == '' then
pattern = str._escapePattern(pattern)
        source = mw.title.getCurrentTitle().text
end
    end
local _, count = mw.ustring.gsub(source, pattern, '')
    if not source or source == '' then
return count
        return ''
    end
    source = mw.ustring.gsub(source, ' %(.*%)$', '')
    source = str.collate( { args = { source } } )
    source = mw.ustring.gsub(source, "^['%(%.¡¿ ]*", '')
    for _,article in ipairs(articoli) do
        source = mw.ustring.gsub(source, "^(" .. article .. ")(.*)$", "%2, %1")
    end
    source = mw.ustring.gsub(source, '^%l', mw.ustring.upper)
    source = mw.text.trim(source)
    return source
end
 
 
-- =================================================================
-- Classe per gestire i parametri
-- =================================================================
local Param = {}
Param.__index = Param
 
function Param.new(par_name, alt_name)
    if  par_name ~= "$index" and not mw.ustring.find(par_name, '#') then par_name = par_name .. '#' end;
    return setmetatable({
        name = par_name,
        base_name = mw.ustring.gsub(par_name, ' ?#', '', 1),
        alt = alt_name or ''
    }, Param)
end
 
function Param:get_other_value(args, index)
    if self.name == '$index' then
        return tostring(index), true
    else
        return args[mw.ustring.gsub(self.name, '#', tostring(index), 1)] or '', false
    end
end
 
function Param:get_first_value(args, index, base_index)
    function value_or_nil (s)
        if s and s~= '' then return s end
        return nil
    end
 
    if self.name == '$index' then
        return tostring(index), true
    end
    if index == base_index then
        return value_or_nil(args[mw.ustring.gsub(self.name, '#', tostring(index), 1)]) or
              value_or_nil(args[self.base_name]) or value_or_nil(args[self.alt]) or '', false
    else
        return value_or_nil(args[mw.ustring.gsub(self.name, '#', tostring(index), 1)]) or
              value_or_nil(args[self.alt]) or '', false
    end
end
 
 
setmetatable(Param, { __call = function(_, ...) return Param.new(...) end })
-- =================================================================
-- fine dichiarazione classe per parametro
-- =================================================================
 
-- =================================================================
-- Classe per gestire il messaggio
    -- =================================================================
local Message = {}
Message.__index = Message
 
function Message.new(msg)
    -- converto parentesi graffe che sono state precedute da "\"
    msg = mw.ustring.gsub(msg, '\\{', '{')
    msg = mw.ustring.gsub(msg, '\\}', '}')
    local frame = mw.getCurrentFrame():getParent() or mw.getCurrentFrame()
 
    return setmetatable({
        msg =  msg,
        values = {},
        frame = frame,
    }, Message)
end
 
function Message:reset_values()
    self.values = {}
end
 
function Message:add_value(value)
    self.values[#self.values+1] = value
end
end
function Message:text()
    return self.frame:preprocess(mw.message.newRawMessage(self.msg, self.values):plain())
end
setmetatable(Message, { __call = function(_, ...) return Message.new(...) end })
-- =================================================================
-- fine dichiarazione classe per messaggio
-- =================================================================


--[[
--[[
    Funzione per unire una o più liste di valori in una stringa.
endswith
 
This function determines whether a string ends with another string.
Uso:
{{#invoke:String|arraytostring|par1=xxx|par2=xxx....|parn=xxxx|msg=msg|separator=|congiunzione=|pre=|post=|lista=}}
 
Parametri:
    par1...parn: i nomi base dei parametri da inserire nel messsaggio, devono contenere il carattere '#' che precisa la
            posizione in cui inserire l'indice. Se viene valorizzato a '$index' avrà automaticamente il valore del
            contatore.
    msg: il messaggio (cioè la riga unitaria) in cui eventuali caratteri '{', '}' dovranno essere
        preceduti da '\', mentre una "|" dovrà essere inserita con il template {{!}}.
        I valori da sostituire sono da inserire come $n ($1 sarà sostituito dal
        valore di par1, $2 dal valore di par2, ecc...)
    separatore: La stringa da inserire tra ogni valore
    congiunzione: La stringa da inserire invece di separatore tra l'ultimo e il penultimo valore. Se
                  non precisato viene usato il valore di separatore
    pre: eventuale stringa che precede l'unione delle stringhe
    post: eventuale stringa che segue l'unione delle stringhe
    indentazione: una stringa da ripetere cumulativamente per ogni messaggio (tipicamente '&nbsp')
    lista: se valorizzata a:
                'puntata' imposta i parametri per una lista puntata
                'ordinata' imposta i parametri per una lista ordinata
                'infobox' imposta l'unione come una lista, eccetto che nel caso ci sia
                          solo un elemento
                Se lista è valorizzata  separatore/congiunzione/pre/post sono ignorati, salvo il caso di 'infobox' e la
                lista contenga solo un elemento.
    nmin = indice iniziale da cui partire a scandire i parametri (di default pari a 1)
    nmax = indice massimo a cui arrivare con i parametri (se non precisato illimitato)
    nobbligatori = l'indice minimo che deve essere valutato anche in presenza di buchi nella sequenza (comunque l'indice massimo
                  che viene valutato è nmax)
    baseIndex = valore dell'indice che può essere sostituito da stringa nulla  (default = 1)
 
Esempi di chiamata:
    {{#invoke:string:arraytostring|par1=var#|separatore=,|congiunzione=#32;e#32;}}
    {{#invoke:string:arraytostring|par1=disegnatore #|par2=disegnatore # nota|msg = $1 <small>$2</small>|lista=infobox }}
    {{#invoke:string:arraytostring|par1=editore #|par2=etichetta #|par3=editore # nota| msg=$1 \{\{#if:$2{{!}}$2 <small>$3</small>\}\}|lista=infobox }}
 
]]
]]
function str.arraytostring(frame)
function str.endswith(frame)
 
local args = str._getParameters(frame.args, {'source', 'pattern'})
    local base_args = frame.args
local source = args.source or ''
    local params = {}
local pattern = args.pattern or ''
    if not base_args then return str._error('Lista parametri vuota') end
if pattern == '' then
    -- carico la lista dei parametri
-- All strings end with the empty string.
    local index = 1
return "yes"
    while true do
end
        local par_name = base_args['par' .. index] or (index == 1 and base_args['par']) or ''
if mw.ustring.sub(source, -mw.ustring.len(pattern), -1) == pattern then
        if par_name == '' then break end;
return "yes"
        --carico eventuale nome alternativo per il primo parametro
else
        local alt_name = base_args['altpar' .. index] or (index == 1 and base_args['altpar']) or ''
return ""
        params[index] = Param(par_name, alt_name)
end
        index = index + 1
    end
    --carico il messaggio
    local msg = base_args.msg or '$1'
    --if msg == '' then return str._error('Manca il messaggio da riprodurre.') end
    local message = Message(msg)
    elements = {}
    -- carico gli altri parametri di formattazione
    local Nmax = tonumber(base_args.Nmax) or tonumber(base_args.nmax) or 0
    local base_index = tonumber(base_args.baseindex) or tonumber(base_args.baseIndex) or 1
    local index = tonumber(base_args.Nmin) or tonumber(base_args.nmin) or base_index
    local Nobbligatori = tonumber(base_args.Nobbligatori) or tonumber(base_args.nobbligatori) or base_index-1
    local indentazione = base_args.indentazione or nil
    local args = frame:getParent().args
    -- estraggo il primo valore
    local found = false
 
    for i, param in ipairs(params) do
        local v, is_index = param:get_first_value(args, index, base_index)
        if (not(is_index) or base_index<=Nobbligatori) and v ~= '' then found = true end
        message:add_value(mw.text.trim(v))
    end
    if found then
        elements[#elements+1] = message:text()
        index = index + 1
    end
    -- elaboro i valori successivi
    while true do
        if Nmax > 0 and index > Nmax then break end
        message:reset_values()
        found = false
        for i, param in ipairs(params) do
            local v, is_index = param:get_other_value(args, index)
            if (not(is_index) or index<=Nobbligatori) and v ~= '' then found = true end
            message:add_value(mw.text.trim(v))
        end
        if found then
            elements[#elements+1] = message:text()
        elseif index >= Nobbligatori then
            break
        end
        index = index + 1
    end
    if #elements == 0 then return '' end
    -- carico separatori, congiunzione, pre e postazione
    local pre, post, separatore, congiunzione, indent = '', '', '', '', ''
    local lista = base_args.lista or ''
    if lista == 'puntata' or (lista =='infobox' and #elements >1) then
        pre = '<UL><LI>'
        post = '</LI>\n</UL>'
        separatore = '</LI>\n<LI>'
        congiunzione = separatore
    elseif lista == 'ordinata' then
        pre = '<OL><LI>'
        post = '</LI>\n</OL>'
        separatore = '</LI>\n<LI>'
        congiunzione = separatore
    else
        pre = base_args.pre or ''
        post = base_args.post or ''
        separatore = base_args.separatore or ''
        congiunzione = base_args.congiunzione or separatore
    end
    if indentazione then
        local current_indentazione = indentazione
        for i, msg in ipairs(elements) do
            elements[i] = current_indentazione .. elements[i]
            current_indentazione = current_indentazione .. indentazione
        end
    end
    return pre .. mw.text.listToText(elements, separatore, congiunzione) .. post
end
end


--[[
--[[
    Funzione per unire una lista di valori in una stringa.
join
 
Uso:
{{#invoke:String|listtostring|par_number=xxx|msg=msg|separator=|congiunzione=|pre=|post=|lista=}}
 
Parametri:
    par_number: il numero di parametri che compongono il messaggio
    msg: il messaggio (cioè la riga unitaria) in cui eventuali caratteri '{', '}' dovranno essere
        preceduti da '\', mentre una "|" dovrà essere inserita con il template {{!}}.
        I valori da sostituire sono da inserire come $n (nel primo messaggio $1 sarà sostituito dal parametro posizionale di
        posizione Nmin, $2 da Nmin+2, ecc...., nel secondo messaggio $1 sarà sostituito dal parametro posizionale Nmin+par_number,
        $2 da Nmin+par_number+2, ec....)
        valore di par1, $2 dal valore di par2, ecc...)
    separatore: La stringa da inserire tra ogni valore
    congiunzione: La stringa da inserire invece di separatore tra l'ultimo e il penultimo valore. Se
                  non precisato viene usato il valore di separatore
    pre: eventuale stringa che precede l'unione delle stringhe
    post: eventuale stringa che segue l'unione delle stringhe
    lista: se valorizzata a:
                'puntata' imposta i parametri per una lista puntata
                'ordinata' imposta i aprametri per una lista ordinata
                'infobox' imposta l'unione come una lista, eccetto che nel caso ci sia
                          solo un elemento
                Se lista è valorizzata  separatore/congiunzione/pre/post sono ignorati, salvo il caso di 'infobox' e la
                lista contenga solo un elemento.
    nmax = indice massimo a cui arrivare con i parametri (se non precisato illimitato)
    nobbligatori = l'indice minimo che deve essere valutato anche in presenza di buchi nella sequenza (comunque l'indice massimo
                  che viene valutato è nmax)
    baseIndex = valore del primo parametro posizionale da cui cominciare a leggere (default = 1)


Join all non empty arguments together; the first argument is the separator.
Usage:
{{#invoke:String|join|sep|one|two|three}}
]]
]]
 
function str.join(frame)
 
local args = {}
function str.listtostring(frame)
local sep
 
for _, v in ipairs( frame.args ) do
    local base_args = frame.args
if sep then
    local params = {}
if v ~= '' then
    if not base_args then return str._error('Lista parametri vuota') end
table.insert(args, v)
    -- carico la lista dei parametri
end
    local base_index = tonumber(base_args.base_index) or 1
else
    local par_number = tonumber(base_args.par_number) or 1
sep = v
    local Nmax = tonumber(base_args.nmax) or 0
end
    local Nobbligatori = tonumber(base_args.nobbligatori) or base_index-1
end
    --carico il messaggio
return table.concat( args, sep or '' )
    local message = Message(base_args.msg or '$1')
    elements = {}
    -- carico gli altri parametri di formattazione
    local index = base_index
    local args = frame:getParent().args
      -- elaboro i valori successivi
    local found = true
    while true do
        if Nmax > 0 and index > Nmax then break end
        message:reset_values()
        found = false
        for i = index, index+par_number-1 do
            message:add_value(args[i] or '')
            if args[i] then
                found = true
            end
        end
        if found then
            elements[#elements+1] = message:text()
        elseif index > Nobbligatori then
            break
        end
        index = index + par_number
    end
    if #elements == 0 then return '' end
    -- carico separatori, congiunzione, pre e postazione
    local pre, post, separatore, congiunzione = '', '', '', ''
    local lista = base_args.lista or ''
    if lista == 'puntata' or (lista =='infobox' and #elements >1) then
        pre = '<UL><LI>'
        post = '</LI>\n</UL>'
        separatore = '</LI>\n<LI>'
        congiunzione = separatore
    elseif lista == 'ordinata' then
        pre = '<OL><LI>'
        post = '</LI>\n</OL>'
        separatore = '</LI>\n<LI>'
        congiunzione = separatore
    else
        pre = base_args.pre or ''
        post = base_args.post or ''
        separatore = base_args.separatore or ''
        congiunzione = base_args.congiunzione or separatore
    end
    return pre .. mw.text.listToText(elements, separatore, congiunzione) .. post
end
end


--[[
--[[
Funzione di aiuto che popola la lista di argomenti, dato che l'utente può voler utilizzare sia
Helper function that populates the argument list given that user may need to use a mix of
parametri nominati che non nominati. Questo è rilevante perchè gli spazi iniziali iniziali
named and unnamed parameters. This is relevant because named parameters are not
e finali dei parametri nominati sono eliminati, mentre quelli dei parametri non nominati
identical to unnamed parameters due to string trimming, and when dealing with strings
non lo sono. Secondo l'applicazione  si potrebbe a volte conservare o rimuovere gli spazi.
we sometimes want to either preserve or remove that whitespace depending on the application.
]]
]]
function str._getParameters( frame_args, arg_list )
function str._getParameters( frame_args, arg_list )
    local new_args = {};
local new_args = {}
    local index = 1;
local index = 1
    local value;
local value


    for i,arg in ipairs( arg_list ) do
for _, arg in ipairs( arg_list ) do
        value = frame_args[arg]
value = frame_args[arg]
        if value == nil then
if value == nil then
            value = frame_args[index];
value = frame_args[index]
            index = index + 1;
index = index + 1
        end
end
        new_args[arg] = value;
new_args[arg] = value
    end
end


    return new_args;
return new_args
end
end


--[[
--[[
Funzione di appoggio per gestire i messaggi di errore.
Helper function to handle error messages.
]]
]]
function str._error( error_str )
function str._error( error_str )
    local frame = mw.getCurrentFrame();
local frame = mw.getCurrentFrame()
    local error_category = frame.args.error_category or 'Errori riportati dal modulo String';
local error_category = frame.args.error_category or 'Errors reported by Module String'
    local ignore_errors = frame.args.ignore_errors or false;
local ignore_errors = frame.args.ignore_errors or false
    local no_category = frame.args.no_category or false;
local no_category = frame.args.no_category or false


    if str._getBoolean(ignore_errors) then
if str._getBoolean(ignore_errors) then
        return '';
return ''
    end
end


    local error_str = '<strong class="error">Errore nel modulo String: ' .. error_str .. '</strong>';
local error_str = '<strong class="error">String Module Error: ' .. error_str .. '</strong>'
    if error_category ~= '' and not str._getBoolean( no_category ) then
if error_category ~= '' and not str._getBoolean( no_category ) then
        error_str = '[[Categoria:' .. error_category .. ']]' .. error_str;
error_str = '[[Category:' .. error_category .. ']]' .. error_str
    end
end


    return error_str;
return error_str
end
end


--[[
--[[
Funzione di appoggio per interpretare le stringhe come valori booleane
Helper Function to interpret boolean strings
]]
]]
function str._getBoolean( boolean_str )
function str._getBoolean( boolean_str )
    local boolean_value;
local boolean_value


    if type( boolean_str ) == 'string' then
if type( boolean_str ) == 'string' then
        boolean_str = boolean_str:lower();
boolean_str = boolean_str:lower()
        if boolean_str == 'false' or boolean_str == 'no' or boolean_str == '0'
if boolean_str == 'false' or boolean_str == 'no' or boolean_str == '0'
                or booleean_str == 'falso' or boolean_str == '' then
or boolean_str == '' then
            boolean_value = false;
boolean_value = false
        else
else
            boolean_value = true;
boolean_value = true
        end
end
    elseif type( boolean_str ) == 'boolean' then
elseif type( boolean_str ) == 'boolean' then
        boolean_value = boolean_str;
boolean_value = boolean_str
    else
else
        error('Nessun valore booleano trovato' );
error( 'No boolean value found' )
    end
end
    return boolean_value
return boolean_value
end
end


--[[
--[[
Funzione di appoggio per aggiungere un carattere di escape a tutti i caratteri speciali,
Helper function that escapes all pattern characters so that they will be treated
così da trattare una stringa come testo normale e non come pattern di Lua.
as plain text.
]]
]]
function str._escapePattern( pattern_str )
function str._escapePattern( pattern_str )
    return mw.ustring.gsub( pattern_str, "([%(%)%.%%%+%-%*%?%[%^%$%]])", "%%%1" );
return mw.ustring.gsub( pattern_str, "([%(%)%.%%%+%-%*%?%[%^%$%]])", "%%%1" )
end
end


return str
return str
-- Version history:
-- 29/3/2013 traduzione iniziale da en:module:String versione 540627185 del 26 febbraio 2013
-- 07/05/2013 aggiunta funzione rep da en:module:String versione 552254999 del 26 aprile 2013
-- 19/08/2013 aggiunta funzione arraytostring

Revision as of 15:49, 2 August 2020

Modulo Lua per la manipolazione di stringhe.

La maggior parte delle funzioni di questo modulo possono essere invocate con parametri con nome, senza nome o con un misto di entrambi. Il software di MediaWiki, quando vengono usati parametri con nome, rimuoverà ogni spazio iniziale o finale dal parametro. A seconda dell'uso che si vuole fare della funzione può essere vantaggioso conservare oppure rimuovere questi spazi.

Chiamata delle funzioni

Questo modulo è pensato per essere richiamato da template, non direttamente da una voce. Il modulo è richiamabile anche da un altro modulo Lua, ma in questo caso è meglio usare direttamente le funzioni Lua di manipolazione delle stringhe:

Per richiamare il modulo da un template usare la sintassi: {{{{{|safesubst:}}}#invoke:String|nome della funzione|parametro 1|parametro 2|...|parametro n|}}. Per esempio d'uso vedi il template {{Str len}}

Opzioni globali

Alcune funzioni possono dare un messaggio di errore o impostare una categoria di errori, la generazione di questo messaggio e/o la creazione di questa categoria possono essere controllate dalle seguenti opzioni.

ignore_errors: se impostato a 1 o "true" ogni condizione di errore darà una stringa vuota piuttosto che un messaggio di errore.
error_category: nel caso si verifichi un errore è il nome di una categoria da includere insieme al messaggio di errore. La categoria di default è Categoria:Errori riportati dal modulo String.
no_category: Se settato a 1 o "true", non verranno aggiunte categorie in caso di errore.

Funzioni

len

Questa funzione restituisce la lunghezza di una stringa.

Uso
  • {{#invoke:String|len|stringa}}

O

  • {{#invoke:String|len|s= stringa }}
Parametri
  • s: La stringa di cui restituire la lunghezza

Se invocata usando parametri nominati, Mediawiki rimuoverà automaticamente ogni spazio iniziale o finale dalla stringa.

sub

Questa funzione restituisce la sottostringa di una stringa bersaglio, come indicato dagli indici

Uso
  • {{#invoke:String|sub|stringa_bersaglio|indice_iniziale|indice_finale}}

O

  • {{#invoke:String|sub|s= stringa_bersaglio |i= indice_iniziale |j= indice_finale }}
Parametri
  • s: La stringa da cui estrarre una sottostringa
  • i: La posizione iniziale del primo carattere della sottostringa da restituire, se non specificato è 1.
  • j: La posizione finale dell'ultimo carattere della sottostringa da restituire, se non specificato corrisponde alla lunghezza della stringa_bersaglio (l'ultimo carattere).

I caratteri della stringa sono numerati a partire da 1. Se i o j hanno un valore negativo allora contano la posizione contando dalla fine della stringa, -1 è l'ultimo carattere della stringa, -2 il penultimo, ecc...

Se le posizioni sono al di fuori degli estremi della stringa viene restituito un messaggio di errore.

match

Questa funzione restituisce una sottostringa della stringa bersaglio corrispondente a un pattern specificato.

Uso
  • {{#invoke:String|match|source_string|pattern_string|start_index|match_number|plain_flag|nomatch_output}}

O

  • {{#invoke:String|match|s= source_string |pattern= pattern_string |start= start_index |match= match_number |plain= plain_flag |nomatch= nomatch_output }}
Parametri
  • s: la stringa da cercare
  • pattern: il pattern da cercare nella stringa s
  • start: la posizione iniziale da cui iniziare la ricerca, se non specificato è 1.
  • match: se ci sono corrispondenze multiple, quale restituire: 1 per la prima corrispondenza, 2 per la seconda, ecc... Un valore negativo indica di contare all'indietro a partire dall'ultima corrispondenza, quindi match = -1 significa chiedere l'ultima corrispondenza. Se non specificato è 1
  • plain: se vero specifica che il pattern deve essere considerato come una stringa normale, piuttosto che un pattern Lua. Se non specificata è falso.
  • nomatch: il valore da restituire se non ci sono corrispondenze, invece di un errore.

Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli spazi iniziali e finali. In alcune circostanze questo può essere il comportamento desiderato, in altre si potrebbe volerli conservare.

Se match o start sono al di fuori degli estremi della stringa s, allora la funzione restituisce un errore. Viene generato un errore anche se il non vengono trovate corrispondenze. Per sopprimere gli errori si può aggiungere il parametro ignore_errors=true, in questo caso in caso di errore verrà restituita una stringa vuota.

pos

Questa funzione restituisce il carattere della stringa in posizione pos.

Uso
  • {{#invoke:String|pos|stringa_bersaglio|indice}}

O

  • {{#invoke:String|pos|target= stringa_bersaglio |pos= indice }}
Parametri
  • target: la stringa in cui cercare
  • pos: la posizione del carattere da restituire

Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli spazi iniziali e finali. In alcune circostanze questo può essere il comportamento desiderato, in altre si potrebbe volerli conservare.

I caratteri della stringa sono numerati a partire da 1. Se pos è un valore negativo allora conta la posizione partendo dalla fine della stringa, -1 è l'ultimo carattere della stringa, -2 il penultimo, ecc...

Se la posizione richiesta è 0 o al di fuori degli estremi della stringa viene restituito un errore.

str_find

Questa funzione duplica il comportamento di {{str_find}}, inclusi i casi particolari. Questa funzione è fornita per motivi di compatibilità con i vecchi template, ma SI RACCOMANDA di non utilizzarla in nuovi template. Nello sviluppo di nuovo codice si raccomanda di usare la funzione find.

Parametri
  • source: la stringa in cui cercare
  • target: la stringa da cercare

Restituisce la posizione nella stringa source del primo carattere in cui è stata trovata la stringa target. I caratteri della stringa sono numerati a partire da 1. La funzione restituisce -1 se la stringa target non è contenuta in source.

Nota importante: Per compatibilità con il vecchio template, se la stringa target è vuota o manca, la funzione restituisce il valore "1"

find

Questa funzione permette di cercare una stringa bersaglio o un pattern Lua all'interno di un'altra stringa.

Uso
  • {{#invoke:String|find|stringa_sorgente|stringa_bersaglio|indice_iniziale|plain_flag}}

O

  • {{#invoke:String|find|source= stringa_sorgente |target= stringa_bersaglio |start= indice_iniziale |plain= plain_flag }}
Parametri
  • source: la stringa in cui cercare
  • target: la stringa o pattern Lua da cercare
  • start: la posizione da cui iniziare la ricerca, se non specificato è 1
  • plain: Se è vero indica che la stringa target deve essere considerata come un testo normale e non come un pattern Lua, se non specificata è vera

Se richiamata usando parametri nominati Mediawiki rimuoverà automaticamente tutti gli spazi iniziali e finali. In alcune circostanze questo può essere il comportamento desiderato, in altre si potrebbe volerli conservare.

Questa funzione restituisce la prima posizione maggiore o uguale a start a partire dalla quale target si trova in source. I caratteri della stringa sono numerati a partire da 1. Se target non viene trovato dà 0. Se source o target sono mancanti o vuoti dà 0.

Questa funzione dovrebbe essere sicura per stringhe UTF-8.

replace

Questa funzione permette di rimpiazzare una stringa o pattern bersaglio con un'altra stringa.

Uso
  • {{#invoke:String|replace|stringa_sorgente|stringa_pattern|nuova_stringa|numero_di_sostituzioni|plain_flag}}

O

  • {{#invoke:String|replace|source= stringa_sorgente |pattern= stringa_pattern |replace= nuova_stringa | count= numero_di_sostituzioni |plain= plain_flag }}
Parametri
  • source: la stringa in cui cercare
  • pattern: la stringa o pattern Lua da trovare in source
  • replace: il testo di sostituzione
  • count: il numero di volte in cui rimpiazzare la stringa, se non specificato tutte.
  • plain: se vero indica che il pattern deve essere considerato come testo normale e non come pattern Lua, il valore di default è vero

arraytostring

Formatta una o più liste di valori in una singola stringa

Uso
  • {{#invoke:String|arraytostring|par1|formato|separatore|congiunzione}}
Parametri
  • par1 ... parn: il nome base delle variabili da unire, deve contenere il carattere "#" che precisa la posizione in cui inserire l'indice. Ad esempio se par1 è "Param#", la funzione unirà i valori della lista di parametri Param1, Param2, Param3, ecc...
    Il parametro "Param" (senza numero) sarà considerato equivalente a "Param1" (questo comportamento può essere modificato con il parametro "baseIndex")
  • msg: formattazione da applicare alla compilazione dei parametri. Il simbolo $n fa da segnaposto per il parametro "parn". È possibile inserire codice mediawiki, ma eventuali caratteri "{" e "}" dovranno essere preceduti da un "\", mentre il carattere "|" dovrà essere inserito con la costante {{!}}. Un eventuale "\}" finale deve sempre essere staccato, con spazio o altro, dal "}}" di fine comando.
  • separatore: una stringa (opzionale) da inserire tra ogni valore
  • congiunzione: una stringa (opzionale) da inserire al posto del separatore tra l'ultimo e il penultimo valore. Se non dichiarata viene usato il valore di "separatore"
  • nmin: indice iniziale da cui partire a scandire i parametri (di default pari a 1)
  • nmax: indice massimo a cui è possibile arrivare con i parametri (se non precisato è illimitato)
  • nobbligatori = l'indice minimo che deve essere valutato anche in presenza di buchi nella sequenza (come indice massimo sarà comunque valutato "nmax")
  • baseIndex: valore dell'indice parametrico che coincide con il parametro senza indice (normalmente è 1, quindi i parametri "par1" e "par" sono equivalenti; se per esempio viene impostato a 0 allora è "par0" che sarà equivalente a "par")
  • lista: parametro a cui è possibile assegnare uno tra i seguenti valori.
    puntata - formatta l'elenco di valori come una lista puntata (i valori di "separatore" e "congiunzione" sono ignorati)
    ordinata - formatta l'elenco di valori come una lista numerata (i valori di "separatore" e "congiunzione" sono ignorati)
    infobox - formatta l'elenco di valori come una lista puntata (i valori di "separatore" e "congiunzione" sono ignorati), eccetto che nel caso in cui ci sia un solo elemento
Esempi di chiamata
{{#invoke:string|arraytostring|par1=var#|separatore=&#32;|congiunzione=&#32;e&#32;}}
Formatta una lista di parametri "var1", "var2" ... "varn" separandoli con una virgola, tranne per gli ultimi due uniti dalla congiunzione " e "
{{#invoke:string|arraytostring|par1=disegnatore #|par2=disegnatore # nota|msg = $1 <small>$2</small>|lista=infobox}}
Formatta coppie di parametri "disegnatore 1", "disegnatore 2" ... "disegnatore n" e "disegnatore 1 nota", "disegnatore 2 nota" ... "disegnatore n nota". Ogni coppia sarà formattata come "Disegnatore disegnatore nota" e queste saranno unite in una lista puntata. Usata in {{Personaggio}} per formattare le liste di disegnatori/autori/editori, ecc...
{{#invoke:String|arraytostring|par1=#|msg=''$1''|separatore=<nowiki>|</nowiki>|Nmin=2}}
Unisce i parametri ordinali "2", "3" ... "n" in una lista separate da "|". Ogni valore viene reso in corsivo. Usata in {{tl}} per formattare la lista opzionale di parametri.

collate

Questa funzione restituisce la stringa privata degli eventuali segni diacritici sulle lettere dell'alfabeto latino. Trasforma ad esempio "Çịàö" in "Errore script: la funzione "collate" non esiste.", preferibile ad esempio per gli ordinamenti alfabetici.

Uso
  • {{#invoke:String|collate|stringa}}
Parametri
  • stringa: La stringa da cui togliere i segni

decode

Questa funzione accetta una stringa codificata con il sistema a percentuali usato negli URL e restituisce la stringa decodificata. Fa quindi l'opposto della funzione di sistema urlencode. Trasforma ad esempio "Come%20va%3F" in "Errore script: la funzione "decode" non esiste.".

Uso
  • {{#invoke:String|decode|stringa}}
Parametri
  • stringa: La stringa da decodificare

titolo_alfa

Questa funzione accetta una stringa che corrisponde a un titolo di opera e restituisce la stringa adattata all'ordinamento alfabetico. Trasforma ad esempio "La pietà" in "Errore script: la funzione "titolo_alfa" non esiste.". Non funziona sempre, non potendo capire il significato delle parole, ma risolve automaticamente la maggior parte dei casi.

Uso
  • {{#invoke:String|titolo_alfa|titolo}}
Parametri
  • titolo: Il titolo di opera. Di default viene preso il titolo della pagina in cui ci si trova.

Unit test

Unit test per questo modulo sono disponibili a Modulo:String/test, per la loro esecuzione visitare Discussioni_modulo:String/test.

Documentazione sui pattern Lua

Diverse funzioni fanno uso di pattern Lua, questi sono una forma di espressione regolare, per maggiori informazioni sulla loro sintassi vedi:


--[[

This module is intended to provide access to basic string functions.

Most of the functions provided here can be invoked with named parameters,
unnamed parameters, or a mixture.  If named parameters are used, Mediawiki will
automatically remove any leading or trailing whitespace from the parameter.
Depending on the intended use, it may be advantageous to either preserve or
remove such whitespace.

Global options
    ignore_errors: If set to 'true' or 1, any error condition will result in
        an empty string being returned rather than an error message.

    error_category: If an error occurs, specifies the name of a category to
        include with the error message.  The default category is
        [Category:Errors reported by Module String].

    no_category: If set to 'true' or 1, no category will be added if an error
        is generated.

Unit tests for this module are available at Module:String/tests.
]]

local str = {}

--[[
len

This function returns the length of the target string.

Usage:
{{#invoke:String|len|target_string|}}
OR
{{#invoke:String|len|s=target_string}}

Parameters
    s: The string whose length to report

If invoked using named parameters, Mediawiki will automatically remove any leading or
trailing whitespace from the target string.
]]
function str.len( frame )
	local new_args = str._getParameters( frame.args, {'s'} )
	local s = new_args['s'] or ''
	return mw.ustring.len( s )
end

--[[
sub

This function returns a substring of the target string at specified indices.

Usage:
{{#invoke:String|sub|target_string|start_index|end_index}}
OR
{{#invoke:String|sub|s=target_string|i=start_index|j=end_index}}

Parameters
    s: The string to return a subset of
    i: The fist index of the substring to return, defaults to 1.
    j: The last index of the string to return, defaults to the last character.

The first character of the string is assigned an index of 1.  If either i or j
is a negative value, it is interpreted the same as selecting a character by
counting from the end of the string.  Hence, a value of -1 is the same as
selecting the last character of the string.

If the requested indices are out of range for the given string, an error is
reported.
]]
function str.sub( frame )
	local new_args = str._getParameters( frame.args, { 's', 'i', 'j' } )
	local s = new_args['s'] or ''
	local i = tonumber( new_args['i'] ) or 1
	local j = tonumber( new_args['j'] ) or -1

	local len = mw.ustring.len( s )

	-- Convert negatives for range checking
	if i < 0 then
		i = len + i + 1
	end
	if j < 0 then
		j = len + j + 1
	end

	if i > len or j > len or i < 1 or j < 1 then
		return str._error( 'String subset index out of range' )
	end
	if j < i then
		return str._error( 'String subset indices out of order' )
	end

	return mw.ustring.sub( s, i, j )
end

--[[
This function implements that features of {{str sub old}} and is kept in order
to maintain these older templates.
]]
function str.sublength( frame )
	local i = tonumber( frame.args.i ) or 0
	local len = tonumber( frame.args.len )
	return mw.ustring.sub( frame.args.s, i + 1, len and ( i + len ) )
end

--[[
_match

This function returns a substring from the source string that matches a
specified pattern. It is exported for use in other modules

Usage:
strmatch = require("Module:String")._match
sresult = strmatch( s, pattern, start, match, plain, nomatch )

Parameters
    s: The string to search
    pattern: The pattern or string to find within the string
    start: The index within the source string to start the search.  The first
        character of the string has index 1.  Defaults to 1.
    match: In some cases it may be possible to make multiple matches on a single
        string.  This specifies which match to return, where the first match is
        match= 1.  If a negative number is specified then a match is returned
        counting from the last match.  Hence match = -1 is the same as requesting
        the last match.  Defaults to 1.
    plain: A flag indicating that the pattern should be understood as plain
        text.  Defaults to false.
    nomatch: If no match is found, output the "nomatch" value rather than an error.

For information on constructing Lua patterns, a form of [regular expression], see:

* http://www.lua.org/manual/5.1/manual.html#5.4.1
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Patterns
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Ustring_patterns

]]
-- This sub-routine is exported for use in other modules
function str._match( s, pattern, start, match_index, plain_flag, nomatch )
	if s == '' then
		return str._error( 'Target string is empty' )
	end
	if pattern == '' then
		return str._error( 'Pattern string is empty' )
	end
	start = tonumber(start) or 1
	if math.abs(start) < 1 or math.abs(start) > mw.ustring.len( s ) then
		return str._error( 'Requested start is out of range' )
	end
	if match_index == 0 then
		return str._error( 'Match index is out of range' )
	end
	if plain_flag then
		pattern = str._escapePattern( pattern )
	end

	local result
	if match_index == 1 then
		-- Find first match is simple case
		result = mw.ustring.match( s, pattern, start )
	else
		if start > 1 then
			s = mw.ustring.sub( s, start )
		end

		local iterator = mw.ustring.gmatch(s, pattern)
		if match_index > 0 then
			-- Forward search
			for w in iterator do
				match_index = match_index - 1
				if match_index == 0 then
					result = w
					break
				end
			end
		else
			-- Reverse search
			local result_table = {}
			local count = 1
			for w in iterator do
				result_table[count] = w
				count = count + 1
			end

			result = result_table[ count + match_index ]
		end
	end

	if result == nil then
		if nomatch == nil then
			return str._error( 'Match not found' )
		else
			return nomatch
		end
	else
		return result
	end
end

--[[
match

This function returns a substring from the source string that matches a
specified pattern.

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

Parameters
    s: The string to search
    pattern: The pattern or string to find within the string
    start: The index within the source string to start the search.  The first
        character of the string has index 1.  Defaults to 1.
    match: In some cases it may be possible to make multiple matches on a single
        string.  This specifies which match to return, where the first match is
        match= 1.  If a negative number is specified then a match is returned
        counting from the last match.  Hence match = -1 is the same as requesting
        the last match.  Defaults to 1.
    plain: A flag indicating that the pattern should be understood as plain
        text.  Defaults to false.
    nomatch: If no match is found, output the "nomatch" value rather than an error.

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

If the match_number or start_index are out of range for the string being queried, then
this function generates an error.  An error is also generated if no match is found.
If one adds the parameter ignore_errors=true, then the error will be suppressed and
an empty string will be returned on any failure.

For information on constructing Lua patterns, a form of [regular expression], see:

* http://www.lua.org/manual/5.1/manual.html#5.4.1
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Patterns
* http://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Ustring_patterns

]]
-- This is the entry point for #invoke:String|match
function str.match( frame )
	local new_args = str._getParameters( frame.args, {'s', 'pattern', 'start', 'match', 'plain', 'nomatch'} )
	local s = new_args['s'] or ''
	local start = tonumber( new_args['start'] ) or 1
	local plain_flag = str._getBoolean( new_args['plain'] or false )
	local pattern = new_args['pattern'] or ''
	local match_index = math.floor( tonumber(new_args['match']) or 1 )
	local nomatch = new_args['nomatch']

	return str._match( s, pattern, start, match_index, plain_flag, nomatch )
end

--[[
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.
]]
function str.pos( frame )
	local new_args = str._getParameters( frame.args, {'target', 'pos'} )
	local target_str = new_args['target'] or ''
	local pos = tonumber( new_args['pos'] ) or 0

	if pos == 0 or math.abs(pos) > mw.ustring.len( target_str ) then
		return str._error( 'String index out of range' )
	end

	return mw.ustring.sub( target_str, pos, pos )
end

--[[
str_find

This function duplicates the behavior of {{str_find}}, including all of its quirks.
This is provided in order to support existing templates, but is NOT RECOMMENDED for
new code and templates.  New code is recommended to use the "find" function instead.

Returns the first index in "source" that is a match to "target".  Indexing is 1-based,
and the function returns -1 if the "target" string is not present in "source".

Important Note: If the "target" string is empty / missing, this function returns a
value of "1", which is generally unexpected behavior, and must be accounted for
separatetly.
]]
function str.str_find( frame )
	local new_args = str._getParameters( frame.args, {'source', 'target'} )
	local source_str = new_args['source'] or ''
	local target_str = new_args['target'] or ''

	if target_str == '' then
		return 1
	end

	local start = mw.ustring.find( source_str, target_str, 1, true )
	if start == nil then
		start = -1
	end

	return start
end

--[[
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.
]]
function str.find( frame )
	local new_args = str._getParameters( frame.args, {'source', 'target', 'start', 'plain' } )
	local source_str = new_args['source'] or ''
	local pattern = new_args['target'] or ''
	local start_pos = tonumber(new_args['start']) or 1
	local plain = new_args['plain'] or true

	if source_str == '' or pattern == '' then
		return 0
	end

	plain = str._getBoolean( plain )

	local start = mw.ustring.find( source_str, pattern, start_pos, plain )
	if start == nil then
		start = 0
	end

	return start
end

--[[
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
]]
function str.replace( frame )
	local new_args = str._getParameters( frame.args, {'source', 'pattern', 'replace', 'count', 'plain' } )
	local source_str = new_args['source'] or ''
	local pattern = new_args['pattern'] or ''
	local replace = new_args['replace'] or ''
	local count = tonumber( new_args['count'] )
	local plain = new_args['plain'] or true

	if source_str == '' or pattern == '' then
		return source_str
	end
	plain = str._getBoolean( plain )

	if plain then
		pattern = str._escapePattern( pattern )
		replace = mw.ustring.gsub( replace, "%%", "%%%%" ) --Only need to escape replacement sequences.
	end

	local result

	if count ~= nil then
		result = mw.ustring.gsub( source_str, pattern, replace, count )
	else
		result = mw.ustring.gsub( source_str, pattern, replace )
	end

	return result
end

--[[
    simple function to pipe string.rep to templates.
]]
function str.rep( frame )
	local repetitions = tonumber( frame.args[2] )
	if not repetitions then
		return str._error( 'function rep expects a number as second parameter, received "' .. ( frame.args[2] or '' ) .. '"' )
	end
	return string.rep( frame.args[1] or '', repetitions )
end

--[[
escapePattern

This function escapes special characters from a Lua string pattern. See [1]
for details on how patterns work.

[1] https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#Patterns

Usage:
{{#invoke:String|escapePattern|pattern_string}}

Parameters
    pattern_string: The pattern string to escape.
]]
function str.escapePattern( frame )
	local pattern_str = frame.args[1]
	if not pattern_str then
		return str._error( 'No pattern string specified' )
	end
	local result = str._escapePattern( pattern_str )
	return result
end

--[[
count
This function counts the number of occurrences of one string in another.
]]
function str.count(frame)
	local args = str._getParameters(frame.args, {'source', 'pattern', 'plain'})
	local source = args.source or ''
	local pattern = args.pattern or ''
	local plain = str._getBoolean(args.plain or true)
	if plain then
		pattern = str._escapePattern(pattern)
	end
	local _, count = mw.ustring.gsub(source, pattern, '')
	return count
end

--[[
endswith
This function determines whether a string ends with another string.
]]
function str.endswith(frame)
	local args = str._getParameters(frame.args, {'source', 'pattern'})
	local source = args.source or ''
	local pattern = args.pattern or ''
	if pattern == '' then
		-- All strings end with the empty string.
		return "yes"
	end
	if mw.ustring.sub(source, -mw.ustring.len(pattern), -1) == pattern then
		return "yes"
	else
		return ""
	end
end

--[[
join

Join all non empty arguments together; the first argument is the separator.
Usage:
{{#invoke:String|join|sep|one|two|three}}
]]
function str.join(frame)
	local args = {}
	local sep
	for _, v in ipairs( frame.args ) do
		if sep then
			if v ~= '' then
				table.insert(args, v)
			end
		else
			sep = v
		end
	end
	return table.concat( args, sep or '' )
end

--[[
Helper function that populates the argument list given that user may need to use a mix of
named and unnamed parameters.  This is relevant because named parameters are not
identical to unnamed parameters due to string trimming, and when dealing with strings
we sometimes want to either preserve or remove that whitespace depending on the application.
]]
function str._getParameters( frame_args, arg_list )
	local new_args = {}
	local index = 1
	local value

	for _, arg in ipairs( arg_list ) do
		value = frame_args[arg]
		if value == nil then
			value = frame_args[index]
			index = index + 1
		end
		new_args[arg] = value
	end

	return new_args
end

--[[
Helper function to handle error messages.
]]
function str._error( error_str )
	local frame = mw.getCurrentFrame()
	local error_category = frame.args.error_category or 'Errors reported by Module String'
	local ignore_errors = frame.args.ignore_errors or false
	local no_category = frame.args.no_category or false

	if str._getBoolean(ignore_errors) then
		return ''
	end

	local error_str = '<strong class="error">String Module Error: ' .. error_str .. '</strong>'
	if error_category ~= '' and not str._getBoolean( no_category ) then
		error_str = '[[Category:' .. error_category .. ']]' .. error_str
	end

	return error_str
end

--[[
Helper Function to interpret boolean strings
]]
function str._getBoolean( boolean_str )
	local boolean_value

	if type( boolean_str ) == 'string' then
		boolean_str = boolean_str:lower()
		if boolean_str == 'false' or boolean_str == 'no' or boolean_str == '0'
				or boolean_str == '' then
			boolean_value = false
		else
			boolean_value = true
		end
	elseif type( boolean_str ) == 'boolean' then
		boolean_value = boolean_str
	else
		error( 'No boolean value found' )
	end
	return boolean_value
end

--[[
Helper function that escapes all pattern characters so that they will be treated
as plain text.
]]
function str._escapePattern( pattern_str )
	return mw.ustring.gsub( pattern_str, "([%(%)%.%%%+%-%*%?%[%^%$%]])", "%%%1" )
end

return str