View source for Help:String functions

==Extension==
Various string functions are part of [[Help:ParserFunctions|Extension:ParserFunctions]].<ref>See [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/ParserFunctions/ParserFunctions_body.php?view=markup ParserFunctions_body.php]</ref> However, this part is disabled on Wikimedia wikis, with <code>$wgPFEnableStringFunctions = false</code>. See also [[bugzilla:6455]] and [[bugzilla:19298]]. The following description is based on these functions being DISABLED.

==Concatenation==
[[w:Concatenation|Concatenation]] is done by [[wikt:juxtaposition|juxtaposition]].

The expansion of the concatenation of two [[Help:Expansion#Help:Expansion#Balancedness|balanced]] wikitexts is equal to the concatenation of the two expanded wikitexts.

However, the rendering of e.g. {{cnw|'''bo}} and {{cnw|ld'''}} does not look the same as that of the concatenated wikitext.

==Trimming==
Trimming is the removal of [[Help:Newlines and spaces|newlines and spaces]] from the start and the end of a string.

Automatically trimmed are:
*the value of a named template parameter
*the value of a parameter of a parser function (see [[mw:Help:Magic words#Parser functions]] and [[mw:Help:Extension:ParserFunctions]]), including the one after the colon

Thus, if trimming is desired, this is in many cases conveniently performed together with another operation one wants to perform. To just trim string S, one applies a template or parser function such that this does not affect the string, apart from the trimming, e.g.:
*<code><nowiki>{{1x|1=S}}</nowiki></code> (using [[Template:1x]] containing <code>{{{1}}}</code>) 
*<code><nowiki>{{#if:x|S}}</nowiki></code>
*<code><nowiki>{{#switch:|S}}</nowiki></code>
*<code><nowiki>{{padleft:S}}</nowiki></code>
*<code><nowiki>{{padright:S}}</nowiki></code>

==Equality==
For [[w:String_functions_(programming)#Equality|equality]] there are <code>[[Template:If##ifeq:|#ifeq:]]</code> and <code>#if:</code>. To force a string-based comparison with <code>#ifeq:</code>, add a non-numerical character to both compared arguments.

Note that this prevents the trimming at the side at which the character is added. If desired, trim the arguments first. If trimming is not desired, put a non-numerical character before and after both strings, e.g. put them in quotes.

==Case==
See [[mw:Help:Magic words#Formatting]].

==Padleft==
The following applies to trimmed strings S and P, and n = 0, 1, 2,.. Note that the ''result'' is ''not'' trimmed: if S is empty the result can end with spaces and/or newlines.

<code><nowiki>{{padleft:S|n|P}}</nowiki></code> pads a given string S on the left with a padding string P (default: "0"), to increase the length (where a newline counts as one character) to min(n,500), or if length (S) ≥ min(n,500) it just returns S. The padding string P is zero or more times repeated, with finally possibly a truncated P. If P is empty, S is returned.

Properties:
*length ( <code><nowiki>{{padleft:S|n|P}}</nowiki></code> ) = if P is non-empty then max ( min(n,500), length (S) ) else length (S)
*<code><nowiki>{{padleft:S|n|P}}</nowiki></code> is equal to S if and only if length (S) ≥ min(n,500) or P is empty.
*<code><nowiki>{{padleft:S|n|P}}</nowiki></code> is equal to P if and only if [length (P) = max ( min(n,500), length (S) ) or 0] and S is equal to a substring of P ending at the end of P (i.e., P is the concatenation RS of some string R with S).

An important special case is that where S is empty: <code><nowiki>{{padleft:|n|P}}</nowiki></code> produces a string of length min(n,500) consisting of zero or more repetitions of P, with finally possibly a truncated P. In particular, if P has a length greater than min(n,500), this is the truncation of P to min(n,500) characters, i.e., the [[w:String_functions_(programming)#substring|substring]] of P of min(n,500) characters starting at the start of P.

The above-mentioned properties reduce to:

*length ( <code><nowiki>{{padleft:|n|P}}</nowiki></code> ) = if P is non-empty then min(n,500) else 0
*<code><nowiki>{{padleft:|n|P}}</nowiki></code> is equal to P if and only if length (P) = min(n,500)

Examples:
*{{xpdop3p3c|padleft:||0||ab}}
*{{xpdop3p3c|padleft:||1||ab}} (truncation)
*{{xpdop3p3c|padleft:||2||ab}}
*{{xpdop3p3c|padleft:||3||ab}}
*{{xpdop3p3c|padleft:||4||ab}}
*{{xpdop3p3c|padleft:||5||ab}}

*<code><nowiki>"{{padleft:|3| a &nbsp;b }}"</nowiki></code> gives "{{padleft:|3| a  b }}" (the parameter is trimmed, the result is not)

*{{xpdop3p3c|padleft:1||0||ab}}
*{{xpdop3p3c|padleft:1||1||ab}}
*{{xpdop3p3c|padleft:1||2||ab}}
*{{xpdop3p3c|padleft:1||3||ab}}
*{{xpdop3p3c|padleft:1||4||ab}}

*{{xpdop3c|padleft:1||5}}
*{{xpdop3p3c|padleft:1||5||}}
*{{xpdop3p3c|padleft:1||5|| }}

{{xpdo5p5c|padleft:a|
|
|b||5}}

*{{xpdop3c|padleft:é|5}}

*<code><nowiki>{{padleft:|2|14:38}}</nowiki></code> gives {{padleft:|2|14:38}} (hour; not needed for the ''current'' time , because there is also the variable <code><nowiki>{{CURRENTHOUR}}</nowiki></code>; see also the [[mw:Help:ParserFunctions##time|#time]] function)

===Maximum string length===
If characters of P are in the result (P is not empty and the string is not already longer than the required length and not longer than 500) the maximum length of the resulting string is 500:
*{{xpdop3p3c|padleft:abc|507|||12345678 0}}
*{{xpdop3p3c|padleft:|507|||123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123}}

However, if no characters of P are in the result (P is empty or the string is already longer than the required length or longer than 500), the whole string S is returned, even if it is longer:

*{{xpdop3p3c|padleft:123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123|507|||}}
*{{xpdop3p3c|padleft:123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789 123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123|507|||p}}

===Applications with respect to a page===
'''Rendering the truncated expanded wikitext of a page:'''

<code><nowiki>{{padleft:|500|{{Help:Parser function}}}}</nowiki></code> gives "{{padleft:|500|{{Help:Parser function}}}}"

Note that when specifying an arbitrary number of characters. links, table structure, XML-style tags etc. may be broken. However, if the braces are balanced in the source page there are neither unbalanced braces in the result, because expansion is done before truncation.

'''Displaying the truncated expanded wikitext:'''

<code><nowiki>{{#tag:nowiki|{{padleft:|500|{{Help:Parser function}}}}}}</nowiki></code> gives "{{#tag:nowiki|{{padleft:|500|{{Help:Parser function}}}}}}"

'''Displaying the truncated wikitext:'''

<code><nowiki>{{padleft:|500|{{msgnw:Help:Parser function}}}}</nowiki></code> gives "{{padleft:|500|{{msgnw:Help:Parser function}}}}"

<code><nowiki>{{padleft:|500|{{Help:Template}}}}</nowiki></code> gives "{{padleft:|500|{{Help:Template}}}}"

The page has been prepared with <code><nowiki><onlyinclude></nowiki></code> tags, so that the small maximum of 500 characters is not wasted on a header box or table code. This also reduces the size of what is transcluded before applying padleft, reducing the [[w:Wikipedia:Template limits#Post-expand include size|post-expand include size]], for which there is a limit of 2048000 bytes per page. A disadvantage could be that other pages cannot include the rest of the page either.

==Padright==
The following applies to trimmed strings S and P, and n = 0, 1, 2,.. Note that the ''result'' is ''not'' trimmed.

<code><nowiki>{{padright:S|n|P}}</nowiki></code> pads a given string S on the right with a padding string P (default: "0"), to increase the length to n, or if length (S) ≥ n it just returns S. The padding string P is zero or more times repeated, with finally possibly a truncated P. If P is empty, S is returned.

Properties:
*length ( <code><nowiki>{{padleft:S|n|P}}</nowiki></code> ) = if P is non-empty then max ( n, length (S) ) else length (S)
*<code><nowiki>{{padright:S|n|P}}</nowiki></code> is equal to S if and only if length (S) ≥ n or P is empty.

The special case where S is empty is the same as for padleft.  

Examples:
*{{xpdop3p3c|padright:||0||ab}}
*{{xpdop3p3c|padright:||1||ab}} (truncation)
*{{xpdop3p3c|padright:||2||ab}}
*{{xpdop3p3c|padright:||3||ab}}
*{{xpdop3p3c|padright:||4||ab}}
*{{xpdop3p3c|padright:||5||ab}}

*{{xpdop3p3c|padright:1||0||ab}}
*{{xpdop3p3c|padright:1||1||ab}}
*{{xpdop3p3c|padright:1||2||ab}}
*{{xpdop3p3c|padright:1||3||ab}}
*{{xpdop3p3c|padright:1||4||ab}}

*{{xpdop3c|padright:1||5}}
*{{xpdop3p3c|padright:1||5||}}
*{{xpdop3p3c|padright:1||5|| }}

*<code><nowiki>"{{padright:abc|13| d &nbsp;e }}"</nowiki></code> gives the wikitext <code>"abcd &nbsp;ed &nbsp;ed "</code> rendered as "{{padright:abc|13| d  e }}"
*<code><nowiki>"{{padright:abc|14| d &nbsp;e }}"</nowiki></code> gives the wikitext <code>"abcd &nbsp;ed &nbsp;ed &nbsp;"</code> rendered as "{{padright:abc|14| d  e  }}"

==Length of a string==
There is no function for the length of a string, but from the above follows:
*<code><nowiki>{{padleft:S|n}}</nowiki></code> is equal to S if and only if length (S) ≥ min(n,500). 

(Note that <code><nowiki>{{padleft:S|n}}</nowiki></code> may end with spaces and/or newlines, so care should be taken that it is not trimmed before the comparison.)

Thus with a binary search the length can be found, except that if it is 500 or more this fact can be found, not the actual length. This is done in [[Template:Len]] with the help of [[Template:Len/digit]]. They use quotation marks around the string, so the maximum length found for the string itself is 498.

==Extracting a character==
As follows from the above, the first character of a string P can be extracted with <code><nowiki>{{padleft:|1|P}}</nowiki></code>. This method is preferable for this case compared with the method below, for efficiency and because there are less limitations.

There is no function for extracting a character from an arbitrary given position of a string. However, for a given character we can compare the truncation of the string up to and including the given position with the truncation of the string until that position, concatenated with the character. Thus we determine whether the character at the given position in the string is equal to the character we tried. (Note that the truncation of the string until the given position may end with spaces and/or newlines, so care should be taken it is not trimmed before the concatenation. Similarly, when trying whether the character is a space or newline, care should be taken that the compared strings are not trimmed before the comparison, because then we would not distinguish between a space and a newline.) Also care should be taken that the result, which may be a space or a newline, is not unintentionally trimmed.

This is done in [[Template:Chr]] with the help of [[Template:Chr/list]]. The latter contains a switch with a case for each of the supported characters.

The [[Help:Newlines and spaces#Automatic newline|automatic newline feature/bug]] for "{|" does not affect the result, except that it adds the newline if "{|" is at the start of the substring, since Sub calls Chr for every character position separately. However, just "*", "#", ":", and ";" without newline cannot be produced by any template or parser function. Possible remedies:
*put the character in &lt;nowiki> tags
*Postpone adding a resulting character to the output until the next charaxter is checked; output it together with that character is the second character is "*", "#", ":", or ";". This seems rather complex, since there is no feature for variables in the computer programming sense; it may require deep nesting, but then one may be restricted by the system limitations on the number of levels. 
*Post-process the resulting string, removing the added newlines. See [[Template:Rmanl]] for a start.

==Extracting a substring==
As mentioned above, if n is not greater than the length of a string P, <code><nowiki>{{padleft:|n|P}}</nowiki></code> produces the truncation of P to n characters, i.e., the [[w:String_functions_(programming)#substring|substring]] of P of n characters starting at the start of P. This method is preferable for this case compared with the method below, for efficiency and because there are less limitations.

There is no function for extracting a substring that does not start at the start of the  string, neither one for looping. However, for every potential position we can determine whether it is within the range of the required substring, and if so, extract the character. The results are simply concatenated.

This is done in [[Template:Sub]]. Note that for each of the required character positions it requires two calls of padleft and a call of a switch. Thus quickly system limits are reached.

==Extracting a substring from the right side of a given string==
Extracting a substring from some given position to the end of a string requires the specification or determination of the length of the string. This also applies to extracting a substring of a given length from the end of the string. Of course, if the length is known it is more efficient to specify it than to have the system determine it.

If the length is not known, [[Template:Subr|Template:Str right]] and [[w:Template:Str rightc]] can be used, respectively, otherwise the previous section can be applied directly.

==XML-style tags==
XML-style tags, e.g. <code>&lt;nowiki&gt;</code> tags and <code>&lt;math&gt;</code> tags, together with their content, are temporarily replaced by a so-called strip marker, a unique code with a length of ca. 37 characters plus the length of the tag name (independent of the length of the content), e.g.

<code>{{#tag:source|<nowiki>foo</nowiki>|lang=java}}</code><ref>See the content of the file [[mw:Manual:Parser.php|Parser.php]].</ref>

This affects string functions. If a strip marker is truncated, the remainder is exposed. Also, padding a string with a strip marker is based on the length of that, not of what it represents.

Examples with <code>&lt;nowiki&gt;</code> tags:

*<code><nowiki>{{padleft:|38|&lt;nowiki>abc&lt;/nowiki>}}</nowiki></code> gives {{padleft:|38|<nowiki>abc</nowiki>}}
*<code><nowiki>{{padleft:|40|&lt;nowiki>abc&lt;/nowiki>}}</nowiki></code> gives {{padleft:|40|<nowiki>abc</nowiki>}}
*<code><nowiki>{{padleft:|41|&lt;nowiki>abc&lt;/nowiki>}}</nowiki></code> gives {{padleft:|41|<nowiki>abc</nowiki>}}
*<code><nowiki>{{padleft:|42|&lt;nowiki>abc&lt;/nowiki>}}</nowiki></code> gives {{padleft:|42|<nowiki>abc</nowiki>}}
*<code><nowiki>{{padleft:|43|&lt;nowiki>abc&lt;/nowiki>}}</nowiki></code> gives {{padleft:|43|<nowiki>abc</nowiki>}}
*<code><nowiki>{{padleft:|48|&lt;nowiki>abc&lt;/nowiki>}}</nowiki></code> gives {{padleft:|48|<nowiki>abc</nowiki>}}

*<code><nowiki>{{padleft:&lt;nowiki>abc&lt;/nowiki>|40|1234567890}}</nowiki></code> gives {{padleft:<nowiki>abc</nowiki>|40|1234567890}}
*<code><nowiki>{{padleft:&lt;nowiki>abc&lt;/nowiki>|43|1234567890}}</nowiki></code> gives {{padleft:<nowiki>abc</nowiki>|43|1234567890}}
*<code><nowiki>{{padleft:&lt;nowiki>abc&lt;/nowiki>|44|1234567890}}</nowiki></code> gives {{padleft:<nowiki>abc</nowiki>|44|1234567890}}
*<code><nowiki>{{padleft:&lt;nowiki>abc&lt;/nowiki>|50|1234567890}}</nowiki></code> gives {{padleft:<nowiki>abc</nowiki>|50|1234567890}}
*<code><nowiki>{{padleft:&lt;nowiki>abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc&lt;/nowiki>|50|1234567890}}</nowiki></code> gives {{padleft:<nowiki>abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc</nowiki>|50|1234567890}}

Examples with <code>&lt;math&gt;</code> tags:

*<code><nowiki>{{padleft:|38|&lt;math>abc&lt;/math>}}</nowiki></code> gives for example {{padleft:|38|<math>abc</math>}}
*<code><nowiki>{{padleft:|40|&lt;math>abc&lt;/math>}}</nowiki></code> gives for example {{padleft:|40|<math>abc</math>}}
*<code><nowiki>{{padleft:|43|&lt;math>abc&lt;/math>}}</nowiki></code> gives {{padleft:|43|<math>abc</math>}}
*<code><nowiki>{{padleft:|48|&lt;math>abc&lt;/nowiki>}}</nowiki></code> gives {{padleft:|48|<math>abc</math>}}

*<code><nowiki>{{padleft:&lt;math>abc&lt;/math>|43|1234567890}}</nowiki></code> gives {{padleft:<math>abc</math>|43|1234567890}}
*<code><nowiki>{{padleft:&lt;math>abc&lt;/math>|44|1234567890}}</nowiki></code> gives {{padleft:<math>abc</math>|44|1234567890}}
*<code><nowiki>{{padleft:&lt;math>abc&lt;/math>|50|1234567890}}</nowiki></code> gives {{padleft:<math>abc</math>|50|1234567890}}
*<code><nowiki>{{padleft:&lt;math>abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc&lt;/math>|50|1234567890}}</nowiki></code> gives {{padleft:<math>abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc</math>|50|1234567890}}

==#titleparts==
See [[Help:Titleparts]].

==String storage==
Suppose we have the string ABCD and also need the substring CD, then because of the inefficiency of finding the substring we can better store (or pass on as parameter values) AB and CD as separate data items.

Date and time variables are available providing output in the form of numbers, allowing easy processing without expensive string operations.

However, for processing the result of <nowiki>{{PAGENAME}}</nowiki> (on the page itself or passed on to a template as parameter value) string functions can be useful, to extract the text after "Wikiproject ", the text between parentheses, the text before the parentheses, etc.

==See also==
*[[mw:Extension:Scribunto/Lua reference manual#String Manipulation]] - for wikis with the Module namespace
*[[:Category:String templates‎]]
*[[mw:Help:Magic words#Formatting]]
*[[mw:Help:Extension:ParserFunctions##titleparts]]
*[[w:Category:String manipulation templates]]
*[[mw:Extension:StringFunctions]]
{{refs}}
{{h:f}}

[[Category:Editor handbook]]