Template:Str left/doc

The {{Str left}} template is a tool for truncating strings to a predetermined length, it returns the the first <count> characters from the start of a trimmed string.

Usage

{{Str left|<string>|<count>}}

Outputs the resultant <count> of characters creating a substring of characters from the start of the trimmed string (i.e. the substring returned will have length <count>, exclusive of leading whitespace characters, which are trimmed before <count> is invoked).

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

Examples

• {{Str left|Lorem ipsum dolor sit amet|10}} → Lorem ipsu
• {{Str left|   Lorem ipsum dolor sit amet|4}} →    L, (note leading spaces trimmed!)
• {{Str left|Lorem ipsum dolor sit amet|1}} → L
• {{Str left|Lorem ipsum dolor sit amet|0}} →
• {{Str left|Lorem ipsum dolor sit amet}} → L
• {{Str left|Lorem ipsum dolor sit amet|40}} → Lorem ipsum dolor sit ametLorem ipsum do
• {{Str left|àçé|2}} → àç

  This example is demonstrating the safety of this template with the UTF-8 encoding.

Analysis

• The maximum substring stops at 500 characters long, yet gives no error message, meaning that only 500 characters will be extracted even if the <string> is longer and without giving any indication that the result is incomplete.
• This template is computationally inexpensive, and depends on no other templates.

Examples of limitations

All the limitations of use for this template and shown below are caused by the current implementation of the {{padleft:}} 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.

• {{Str left|a c|3}} → a&a

  The output "a c" may have been intended, but the named character entity was truncated upon reading the ampersand, thus with needing to produce three characters from a now two character string, it reiterates from the beginning, leaving us with a&a.

• {{Str left|a&#66;c|3}} → a&a

  This should display "abc", but the named character entity was truncated, leaving us right back at a&a; whitespace was not the issue.

• {{Str left|a c|3}} → a c

  The result is correct, as expected.

• {{Str left|a&#32;c|3}} → a&a

  This last example should be equivalent to the previous one, but it is not.

This template will erase <nowiki>…</nowiki> tags without counting their length:

• {{Str left|a<nowiki/>bcd|3}} → a&l

  Returns three characters as expected

• {{Str left|a<nowiki>E</nowiki>bcd|3}} → a&l

  Returns three characters, but not aEb as might have been expected.

• {{Str left|a<nowiki/>bc|10}} → a<nowik

  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:

• {{Str left|a<noinclude/>bc|3}} → a&l
• {{Str left|a<!-- comment -->bc|3}} → a&l

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:

• {{Str left|Abc.|10}} → Abc.Abc.Ab

Template data

This is the TemplateData for Template:Str left, for use by TemplateWizard, VisualEditor and other tools.

Template description

A template to return substrings of a fixed length of characters from the start of a trimmed string

Template parameters

This template prefers inline formatting of parameters.

Parameter		Description	Type	Status
String	1	The source string to be trimmed and counted Example Lorem ipsum dolor sit amet	Line	required
Trim length	2	Produce a substring of this many characters from the start of the trimmed source string Example 42	Number	required

See also

• Bugzilla:22555 (historical; need for correcting padleft/padright functions and to provide better string-handling parser functions)