 Warning: | In 2013, it was decided thatthese functions willnever be enabled on any Wikimedia wiki, because they are inefficient when used on a large scale (seephab:T8455 for some history).These functions do NOT work on Wikimedia wikis! If you are here to write something on a Wikimedia project, you are looking for something else: if your home wiki has string functions, it probably usesLua. For example, the English Wikipedia usesModule:String, which does some of the same thingswith wildly different syntax. There are also individualString-handling templates. If you are NOT editing a Wikimedia wiki, you can disregard this warning. |
TheParserFunctions extension optionally defines variousstring functions if$wgPFEnableStringFunctions=true; is enabled.
These functions consist oflen,pos,rpos,sub,count,replace,explode, andurldecode.
All of these functions operate in O(n) time complexity, making them safe againstDoS attacks.
{{lc:your_string_here}} as a workaround in some cases.$wgPFStringLengthLimit variable, default to1000.The #len function returns the length of the given string. The syntax is:
{{#len:string}}The return value is always a number of characters in the sourcestring (after expansions of template invocations, but before conversion to HTML). If no string is specified, the return value is zero.
{{#len:Žmržlina}} →8{{#len:Icecream }} →8{{#len: a b }} →5 - 3 spaces between 2 characters{{#len: }} →6 - named characters references{{#len: }} →5 - numeric characters references, not ignored despite it designates a space here.<nowiki> and other tag extensions will always have a length of zero, since their content is hidden from the parser. Example:{{#len:<nowiki>This is a </nowiki>test}} →4The #pos function returns the position of a given search term within the string. The syntax is:
{{#pos:string|search term|offset}}Theoffset parameter, if specified, tells a starting position where this function should begin searching.
If thesearch term is found, the return value is a zero-based integer of the first position within thestring.
If thesearch term is not found, the function returns an empty string.
{{#pos:Žmržlina|žlina}} returns 3.<nowiki> and other tag extensions are treated as having a length of zero for the purposes of character position. Example:{{#pos:<nowiki>This is a </nowiki>test|test}} returns 0.The #rpos function returns the last position of a given search term within the string. The syntax is:
{{#rpos:string|search term}}If thesearch term is found, the return value is a zero-based integer of its last position within thestring.
If thesearch term is not found, the function returns -1.
{{#rpos:Žmržlina|lina}} returns 4.<nowiki> and other tag extensions are treated as having a length of zero for the purposes of character position. Example:{{#rpos:<nowiki>This is a </nowiki>test|test}} returns 0.The #sub function returns a substring from the given string. The syntax is:
{{#sub:string|start|length}}Thestart parameter, if positive (or zero), specifies a zero-based index of the first character to be returned.
Example:{{#sub:Icecream|3}} returnscream.
{{#sub:Icecream|0|3}} returnsIce.
If thestart parameter is negative, it specifies how many characters from the end should be returned.
Example:{{#sub:Icecream|-3}} returnseam.
Thelength parameter, if present and positive, specifies the maximum length of the returned string.
Example:{{#sub:Icecream|3|3}} returnscre.
If thelength parameter is negative, it specifies how many characters will be omitted from the end of the string.
Example:{{#sub:Icecream|3|-3}} returnscr.
If thestart parameter is negative, it specifies how many characters from the end should be returned. Thelength parameter, if present and positive, specifies the maximum length of the returned string from the starting point.
Example:{{#sub:Icecream|-3|2}} returnsea.
{{#sub:Icecream|3|0}} returnscream,{{#sub:Icecream|0|3}} returnsIce.{{#sub:Icecream|3|-6}} returns an empty string.{{#sub:Žmržlina|3}} returnsžlina.<nowiki> and other tag extensions are treated as having a length of zero for the purposes of character position. Example:{{#sub:<nowiki>This is a </nowiki>test|1}} returnsest.The #count function returns the number of times a given substring appears within the provided text.
{{#count:string|substring}}The #replace function returns the given string with all occurrences of a search term replaced with a replacement term.
{{#replace:string|search term|replacement term}}If thesearch term is unspecified or empty, a single space will be searched for.
If thereplacement term is unspecified or empty, all occurrences of thesearch term will be removed from thestring.
{{#replace:My_little_home_page|_|<nowiki> </nowiki>}} returnsMy little home page.{{#replace:My_little_home_page|_|<nowiki/> <nowiki/>}} with two self-closing tags.<nowiki> or any other tag extension within the replacement term are replaced with spaces.{{#replace:Žmržlina|ž|z}} returnsŽmrzlina.Currently the syntax doesn't provide a switch to toggle case-sensitivity setting. But you may make use ofmagic words of formatting as a workaround. (e.g.{{lc:your_string_here}}) For example, if you want to remove the word "Category:" from the string regardless of its case, you may type:
{{#replace:{{lc:{{{1}}}}}|category:|}}But the disadvantage is that the output will become all lower-case. If you want to keep the casing after replacement, you have to use multiple nesting levels (i.e. multiple replace calls) to achieve the same thing.
The #explode function splits the given string into pieces and then returns one of the pieces. The pieces are0-indexed. The syntax is:
{{#explode:string|delimiter|position|limit}}Thedelimiter parameter specifies a string to be used to divide thestring into pieces. Thisdelimiter string is then not part of any piece, and when twodelimiter strings are next to each other, they create an empty piece between them. If this parameter is not specified, a single space is used. Thelimit parameter is available in ParserFunctions only, not the standalone StringFunctions version, and allows you to limit the number of parts that the value is split into, with all remaining text included in the final part.
Theposition parameter specifies which piece is to be returned. Pieces are counted from 0. If this parameter is not specified, the first piece is used (piece with number 0). When a negative value is used asposition, the pieces are counted from the end. In this case, piece number -1 means the last piece. Examples:
{{#explode:And if you tolerate this| |2}} returnsyou{{#explode:String/Functions/Code|/|-1}} returnsCode{{#explode:Split%By%Percentage%Signs|%|2}} returnsPercentage{{#explode:And if you tolerate this thing and expect no more| |2|3}} returnsyou tolerate this thing and expect no moreThe return value is theposition-th piece. If there are fewer pieces than theposition specifies, an empty string is returned.
{{#explode:Žmržlina|ž|1}} returnslina.#urldecode converts the escape characters from an 'URL encoded' string back to readable text. The syntax is:
{{#urldecode:value}}urlencode, has been integrated into MediaWiki as of version 1.18; for examples, seeHelp:Magic Words.This module defines three global settings:
These are used to limit some parameters of some functions to ensure the functions operate in O(n) time complexity, and are therefore safe againstDoS attacks.
This setting is used by#pos,#rpos,#replace, and#explode. All these functions search for a substring in a larger string while they operate, which can run in O(n*m) and therefore make the software more vulnerable toDoS attacks. By setting this value to a specific small number, the time complexity is decreased to O(n).
This setting limits the maximum allowed length of the string being searched for.
The default value is 30 multibyte characters.
This setting is used by#replace. This function replaces all occurrences of one string for another, which can be used to quickly generate very large amounts of data, and therefore makes the software more vulnerable toDoS attacks. This setting limits the maximum allowed length of the replacing string.
The default value is 30 multibyte characters.