Module:String: Difference between revisions

Module:String (edit)

Revision as of 03:11, 9 September 2017

15,733 bytes added , 8 years ago

m

revert (vandalism)

@@ Line 1: / Line 1: @@
+--[[
+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.
+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