Module:String: Difference between revisions
separate annotations for str.match from those for str._match
m (48 revisions imported from templatewiki:Module:String) |
(separate annotations for str.match from those for str._match) |
||
| Line 1: | Line 1: | ||
--[[ | --[[ | ||
This module is intended to provide access to basic string functions. | This module is intended to provide access to basic string functions. | ||
Most of the functions provided here can be invoked with named parameters, | Most of the functions provided here can be invoked with named parameters, | ||
unnamed parameters, or a mixture. If named parameters are used, Mediawiki will | unnamed parameters, or a mixture. If named parameters are used, Mediawiki will | ||
automatically remove any leading or trailing whitespace from the parameter. | automatically remove any leading or trailing whitespace from the parameter. | ||
Depending on the intended use, it may be advantageous to either preserve or | Depending on the intended use, it may be advantageous to either preserve or | ||
remove such whitespace. | remove such whitespace. | ||
Global options | Global options | ||
ignore_errors: If set to 'true' or 1, any error condition will result in | ignore_errors: If set to 'true' or 1, any error condition will result in | ||
an empty string being returned rather than an error message. | an empty string being returned rather than an error message. | ||
error_category: If an error occurs, specifies the name of a category to | error_category: If an error occurs, specifies the name of a category to | ||
include with the error message. The default category is | include with the error message. The default category is | ||
[Category:Errors reported by Module String]. | [Category:Errors reported by Module String]. | ||
no_category: If set to 'true' or 1, no category will be added if an error | no_category: If set to 'true' or 1, no category will be added if an error | ||
is generated. | is generated. | ||
Unit tests for this module are available at Module:String/tests. | Unit tests for this module are available at Module:String/tests. | ||
]] | ]] | ||
| Line 39: | Line 39: | ||
If invoked using named parameters, Mediawiki will automatically remove any leading or | If invoked using named parameters, Mediawiki will automatically remove any leading or | ||
trailing whitespace from the target string. | trailing whitespace from the target string. | ||
]] | ]] | ||
function str.len( frame ) | function str.len( frame ) | ||
local new_args = str._getParameters( frame.args, {'s'} ) | |||
local s = new_args['s'] or '' | |||
return mw.ustring.len( s ) | |||
end | end | ||
| Line 61: | Line 61: | ||
i: The fist index of the substring to return, defaults to 1. | 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. | 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 | 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 | 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 | counting from the end of the string. Hence, a value of -1 is the same as | ||
selecting the last character of the string. | selecting the last character of the string. | ||
If the requested indices are out of range for the given string, an error is | If the requested indices are out of range for the given string, an error is | ||
reported. | reported. | ||
]] | ]] | ||
function str.sub( frame ) | 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 | end | ||
| Line 101: | Line 101: | ||
]] | ]] | ||
function str.sublength( frame ) | 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 | |||