View source for Template:Str left/doc

{{Doc/subpage}}
{{Wikipedia port|documentation=1}}
<!-- Categories go where indicated at the bottom of this page, please -->

== Usage ==
: {{Template link expanded|Str left|<string>|<count>}}

Gives the resultant <count> of characters ''creating a substring of characters'' from the start of the [[w:Trim (programming)|trimmed]] string (i.e. the substring returned will have length <count>, exclusive of leading whitespace characters, which are trimmed first before <count> is invoked).

If <count> is invalid, empty or zero, an empty string is returned. If undefined, it defaults to 1.

== Limitations ==
* Length to 500: The maximum substring stops at 500 long, yet gives no error message. Only 500 characters can be extracted even if the <string> is longer.
* Inexpensive (uses no other templates).

== Examples ==
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 10 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 10 }}
:*<code><nowiki>{{Str left| &nbsp; Lorem ipsum dolor sit amet | 4 }}</nowiki></code> &rarr; {{Str left|    Lorem ipsum dolor sit amet | 4 }}, (note leading spaces trimmed!)
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 1 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 1 }}
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 0 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 0 }}
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | }}
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | Lorem ipsum dolor sit amet <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | Lorem ipsum dolor sit amet }}
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 40 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | Lorem ipsum dolor sit amet | 40 }}
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | àçé | 2 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | àçé | 2 }}
:*: This example is demonstrating the safety of this template with the UTF-8 encoding (this should work now) :

===Examples of limitations===
All the limitations of use for this template and shown below are caused by the current implementation of the <nowiki>{{padleft:}}</nowiki> parser function used in this template, which does not filter its third parameter containing the characters used for padding a string to the specified length (it currently counts incorrectly the characters to extract from the padding string, and incorrectly measures its effective length; in addition this parameter is limited to 500 bytes).

The following examples are demonstrating that this template does not interpret character entity references as the character they represent. It treats them as multiple characters and can leave them truncated.
* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&amp;nbsp;c | 3 <nowiki>}}</nowiki></code> → {{ {{BASEPAGENAME}} | a&nbsp;c | 3 }}
*: The output "a&nbsp;c" may have been intended, but the named character entity was truncated, leaving no length available for the final "c".
* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&amp;#66;c | 3 <nowiki>}}</nowiki></code> → {{ {{BASEPAGENAME}} | a&#66;c | 3 }}
*: This should display "abc", but the named character entity was truncated, leaving no length available for the final "c".
* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a c | 3 <nowiki>}}</nowiki></code> → {{ {{BASEPAGENAME}} | a c | 3 }}
*: The result is correct, as expected.
* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&amp;#32;c | 3 <nowiki>}}</nowiki></code> → {{ {{BASEPAGENAME}} | a&#32;c | 3 }}
*: This last example should be equivalent to the previous one, but it is not.

This template will erase nowiki tags without counting their length:
* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&lt;nowiki/&gt;bcd | 3 <nowiki>}}</nowiki></code> → {{ {{BASEPAGENAME}} | a<nowiki/>bcd | 3 }}
*: Returns three characters as expected
* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&lt;nowiki>E&lt;/nowiki&gt;bcd | 3 <nowiki>}}</nowiki></code> → {{ {{BASEPAGENAME}} | a<nowiki>E</nowiki>bcd | 3 }}
*: Returns three characters, but not aEb as might have been expected.
* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&lt;nowiki/&gt;bc | 10 <nowiki>}}</nowiki></code> → {{ {{BASEPAGENAME}} | a<nowiki/>bc | 10 }}
*: Returns 10 characters as expected.

HTML comments, and the "noinclude", "includeonly" and "onlyinclude" wiki markup tags are also ignored, because they are preprocessed in template parameters, before including it and substituting parameters:
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&lt;noinclude/&gt;bc | 3 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | a<noinclude/>bc | 3 }}
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | a&lt;!-- comment --&gt;bc | 3 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | a<!-- comment -->bc | 3 }}

Note also that the specified length will cause the input string to be padded by repeating it, if this length is larger than the input string length:
:* <code><nowiki>{{</nowiki> {{BASEPAGENAME}} | Abc. | 10 <nowiki>}}</nowiki></code> &rarr; {{ {{BASEPAGENAME}} | Abc. | 10 }}

<includeonly>{{Sandbox other||
<!-- Categories go below this line, please -->
[[Category:String manipulation templates]]
}}</includeonly>