Модуль:String/doc

Этот модуль предназначен для обеспечения доступа к основным строковым функциям.

Большая часть функций, имеющихся в модуле, может быть вызвана именованными, неименованными параметрами или обоими вариантами. Если используются именованные параметры, движок Mediawiki автоматически удаляет любые начальные или конечные пробелы из параметра. В зависимости от предполагаемого использования может быть предпочтительным либо сохранение, либо удаление таких пробелов. Экспериментировать с модулем можно на странице Модуль:String/песочница.

Глобальные параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">ignore_errors</syntaxhighlight>:	Если параметру присвоено значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight> или <syntaxhighlight lang="text" class="" id="" style="" inline="1">1</syntaxhighlight>, вместо любого сообщения об ошибке выводится пустая строка.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">error_category</syntaxhighlight>:	В случае возникновения ошибки определяет название категории, в которую помещается страница с сообщением об ошибке. По умолчанию помещается в категорию «Страницы с ошибками модуля String».
<syntaxhighlight lang="text" class="" id="" style="" inline="1">no_category</syntaxhighlight>:	Если параметру присвоено значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight> или <syntaxhighlight lang="text" class="" id="" style="" inline="1">1</syntaxhighlight>, то в случае сообщения об ошибке страница не будет помещена в соответствующую категорию.

subcount

Функция возвращает количество подстрок внутри строки.

Использование

{{#invoke:String|subcount|исходная_строка|подстрока|true / false}}

или

{{#invoke:String|subcount|s=исходная_строка|pattern=подстрока|plain=true / false}}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">s</syntaxhighlight>:	Целевая строка, часть которой необходимо найти.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">pattern</syntaxhighlight>:	Строка, совпадение с которой необходимо найти в целевой строке.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">plain</syntaxhighlight>:	Если параметру присвоено значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">false</syntaxhighlight>, функция воспринимает заданную строку как регулярное выражение. По умолчанию — <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight>.

len

Функция возвращает длину целевой строки.

Использование

{{#invoke:String|len|целевая_строка}}

или

{{#invoke:String|len|s= целевая_строка }}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">s</syntaxhighlight>:

Строка, длину которой необходимо найти.

sub

Функция возвращает часть целевой стоки между указанными индексами (порядковыми номерами символов в целевой строке)

Использование

{{#invoke:String|sub|целевая_строка|начальный_индекс|конечный_индекс}}

или

{{#invoke:String|sub|s= целевая_строка |i= начальный_индекс |j= конечный_индекс }}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">s</syntaxhighlight>:	Строка, часть которой необходимо вывести.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">i</syntaxhighlight>:	Порядковый номер символа, начиная с которого необходимо вывести строку. Значение по умолчанию — 1.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">j</syntaxhighlight>:	Порядковый номер символа, до которого необходимо вывести строку. Значение по умолчанию — порядковый номер последнего символа.

Первому символу строки присваивается индекс <syntaxhighlight lang="text" class="" id="" style="" inline="1">1</syntaxhighlight>. Если параметрам <syntaxhighlight lang="text" class="" id="" style="" inline="1">i</syntaxhighlight> или <syntaxhighlight lang="text" class="" id="" style="" inline="1">j</syntaxhighlight> присвоено отрицательное значение, то оно распознается модулем как порядковый номер символа, отсчитываемый с конца строки. Другими словами, значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">-1</syntaxhighlight> распознается модулем как порядковый номер последнего символа в строке.

Если введённые индексы по модулю больше длины целевой строки, то выводится сообщение об ошибке.

sublength

С помощью этой функции реализован шаблон {{Str sub}}, она сохраняется для поддержания его работоспособности.

match

Функция возвращает часть целевой строки, которая соответствует заданной строке.

Использование

{{#invoke:String|match|исходная_строка|заданная_строка|начальный_индекс|номер_совпадения|true / false|значение_если_нет_совпадений}}

или

{{#invoke:String|match|s= исходная_строка |pattern= заданная_строка |start= начальный_индекс|match= номер_совпадения|plain= true / false |nomatch= значение_если_нет_совпадений }}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">s</syntaxhighlight>:	Целевая строка, часть которой необходимо найти.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">pattern</syntaxhighlight>:	Строка, совпадение с которой необходимо найти в целевой строке.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">start</syntaxhighlight>:	Порядковый номер символа, начиная с которого необходимо произвести поиск совпадения. По умолчанию — <syntaxhighlight lang="text" class="" id="" style="" inline="1">1</syntaxhighlight>. Если начиная с заданного символа совпадений не найдено, функция возвращает сообщение об ошибке.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">match</syntaxhighlight>:	В некоторых случаях может оказаться несколько совпадений с заданной строкой в одной целевой строке. Параметр задает номер совпадения, которое необходимо вывести. Если параметру присвоено отрицательное значение, то оно распознается модулем как порядковый номер совпадения, отсчитываемый с конца строки. Другими словами, значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">-1</syntaxhighlight> распознается модулем как порядковый номер последнего совпадения в строке. По умолчанию — 1.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">plain</syntaxhighlight>:	Если параметру присвоено значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight>, функция воспринимает заданную строку как обычный текст, а не регулярное выражение. По умолчанию — <syntaxhighlight lang="text" class="" id="" style="" inline="1">false</syntaxhighlight>.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">nomatch</syntaxhighlight>:	Последовательность символов, выводимая строкой в случае отсутствия совпадений вместо сообщения об ошибке.

Если введённый индекс по модулю больше длины целевой строки или совпадений найдено меньше, чем число, заданное в параметре <syntaxhighlight lang="text" class="" id="" style="" inline="1">match</syntaxhighlight>, то выводится сообщение об ошибке. Если добавить параметр <syntaxhighlight lang="text" class="" id="" style="" inline="1">ignore_errors=true</syntaxhighlight>, то вместо любого из сообщений об ошибке будет возвращена пустая строка.

Подробнее о регулярных выражениях, используемых в Lua, см. Руководство по метасимволам.

pos

Функция возвращает один символ из целевой строки под заданным порядковым номером.

Использование

{{#invoke:String|pos|целевая_строка|значение_индекса}}

или

{{#invoke:String|pos|target= целевая_строка |pos= значение_индекса }}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">target</syntaxhighlight>:	Строка, в которой производится поиск символа.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">pos</syntaxhighlight>:	Порядковый номер возвращаемого символа

Если параметру <syntaxhighlight lang="text" class="" id="" style="" inline="1">pos</syntaxhighlight> присвоено отрицательное значение, то оно распознается модулем как порядковый номер символа, отсчитываемый с конца строки. Другими словами, значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">-1</syntaxhighlight> распознается модулем как порядковый номер последнего символа в строке.

Если заданный порядковый номер равен 0 или больше длины строки, функция возвращает сообщение об ошибке.

str_find

Эта фунция предназначена для поддержания функционирования шаблона {{str find}}. Она сохраняется для того, чтобы поддерживать существующие шаблоны, но она крайне не рекомендуется для использования в новых шаблонах. Рекомендуется вместо неё использовать функцию <syntaxhighlight lang="text" class="" id="" style="" inline="1">find</syntaxhighlight>.

Возвращает порядковый номер символа, начиная с которого целевая строка, заданная параметром <syntaxhighlight lang="text" class="" id="" style="" inline="1">source</syntaxhighlight> совпадает со строкой в параметре <syntaxhighlight lang="text" class="" id="" style="" inline="1">target</syntaxhighlight>. Функция возвращает −1, если совпадений между строками не найдено.

Важно: Если в параметре <syntaxhighlight lang="text" class="" id="" style="" inline="1">target</syntaxhighlight> не задана строка, либо отсутствует сам параметр, функция возвращает 1, что, как правило, является полной неожиданностью для пользователей.

find

Функция позволяет выполнить поиск целевой строки в другой строке.

Использование

{{#invoke:String|find|исходная_строка|целевая_строка|начальный_индекс|true / false}}

или

{{#invoke:String|find|source= исходная_строка |target= целевая_строка |start= начальный_индекс|plain= true / false }}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">source</syntaxhighlight>:	Строка, в которой ведется поиск целевой строки.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">target</syntaxhighlight>:	Целевая строка, которая ищется в другой строке.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">start</syntaxhighlight>:	Порядковый номер символа, начиная с которого ведется поиск совпадений. Значение по умолчанию — 1.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">plain</syntaxhighlight>:	Если параметру присвоено значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight>, функция воспринимает заданную строку как обычный текст, а не регулярное выражение. По умолчанию — <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight>.

Функция возвращает значение, большее либо равное значению параметра <syntaxhighlight lang="text" class="" id="" style="" inline="1">start</syntaxhighlight>. Если совпадений не найдено, функция возвращает 0, если одна из строк пустая или не задана, функция также возвращает 0.

replace

Функция позволяет заменить целевую строку в другой строке.

Использование

{{#invoke:String|replace|исходная_строка|целевая_строка|заменяющая_строка|количество_замен|true / false}}

или

{{#invoke:String|replace|source= исходная_строка |pattern= целевая_строка|replace= заменяющая_строка |count= количество_замен |plain= true / false }}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">source</syntaxhighlight>:	Строка, в которой ведется поиск.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">pattern</syntaxhighlight>:	Строка, которая ищется в исходной строке.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">replace</syntaxhighlight>:	Строка, заменяющая целевую.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">count</syntaxhighlight>:	Количество заменяемых совпадений; по умолчанию — все.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">plain</syntaxhighlight>:	Если параметру присвоено значение <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight>, функция воспринимает заданную строку как обычный текст, а не регулярное выражение. По умолчанию — <syntaxhighlight lang="text" class="" id="" style="" inline="1">true</syntaxhighlight>.

rep

Функция возвращает строку, состоящую из повторений n раз исходной строки.

Использование

{{#invoke:String|rep|строка|количество_повторов}}

Параметры

<syntaxhighlight lang="text" class="" id="" style="" inline="1">source</syntaxhighlight>:	Строка, которую необходимо повторить n раз.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">count</syntaxhighlight>:	Количество повторов.

Пример

{{#invoke:String|rep|привет!|3}} → привет!привет!привет!