Модуль:String/doc

Это страница документации Модуль:String.

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

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

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

`ignore_errors`:	Если параметру присвоено значение `true` или `1`, вместо любого сообщения об ошибке выводится пустая строка.
`error_category`:	В случае возникновения ошибки определяет название категории, в которую помещается страница с сообщением об ошибке. По умолчанию помещается в категорию Страницы с ошибками модуля String.
`no_category`:	Если параметру присвоено значение `true` или `1`, то в случае сообщения об ошибке страница не будет помещена в соответствующую категорию.

len

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

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

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

или

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

Параметры

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

sub

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

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

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

или

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

Параметры

`s`:	Строка, часть которой необходимо вывести.
`i`:	Порядковый номер символа, начиная с которого необходимо вывести строку. Значение по умолчанию — 1.
`j`:	Порядковый номер символа, до которого необходимо вывести строку. Значение по умолчанию — порядковый номер последнего символа.

Первому символу строки присваивается индекс 1. Если параметрам i или j присвоено отрицательное значение, то оно распознается модулем как порядковый номер символа, отсчитываемый с конца строки. Другими словами, значение -1 распознается модулем как порядковый номер последнего символа в строке.

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

sublength

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

match

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

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

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

или

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

Параметры

`s`:	Целевая строка, часть которой необходимо найти.
`pattern`:	Строка, совпадение с которой необходимо найти в целевой строке.
`start`:	Порядковый номер символа, начиная с которого необходимо произвести поиск совпадения. По умолчанию — `1`. Если начиная с заданного символа совпадений не найдено, функция возвращает сообщение об ошибке.
`match`:	В некоторых случаях может оказаться несколько совпадений с заданной строкой в одной целевой строке. Параметр задает номер совпадения, которое необходимо вывести. Если параметру присвоено отрицательное значение, то оно распознается модулем как порядковый номер совпадения, отсчитываемый с конца строки. Другими словами, значение `-1` распознается модулем как порядковый номер последнего совпадения в строке. По умолчанию — 1.
`plain`:	Если параметру присвоено значение `true`, функция воспринимает заданную строку как обычный текст. По умолчанию — `false`.
`nomatch`:	Последовательность символов, выводимая строкой в случае отсутствия совпадений вместо сообщения об ошибке.

Если введённый индекс по модулю больше длины целевой строки или совпадений найдено меньше, чем число, заданное в параметре match, то выводится сообщение об ошибке. Если добавить параметр ignore_errors=true, то вместо любого из сообщений об ошибке будет возвращена пустая строка.

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

pos

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

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

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

или

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

Параметры

`target`:	Строка, в которой производится поиск символа.
`pos`:	Порядковый номер возвращаемого символа

Если параметру pos присвоено отрицательное значение, то оно распознается модулем как порядковый номер символа, отсчитываемый с конца строки. Другими словами, значение -1 распознается модулем как порядковый номер последнего символа в строке.

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

str_find

Эта фунция предназначена для поддержания функционирования шаблона {{str find}}. Она сохраняется для того, чтобы поддерживать существующие шаблоны, но она крайне не рекомендуется для использования в новых шаблонах. Рекомендуется вместо неё использовать функцию find.

Возвращает порядковый номер символа, начиная с которого целевая строка, заданная параметром source совпадает со строкой в параметре target. Функция возвращает −1, если совпадений между строками не найдено.

Важно: Если в параметре target не задана строка, либо отсутствует сам параметр, функция возвращает 1, что, как правило, является полной неожиданностью для пользователей.

find

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

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

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

или

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

Параметры

`source`:	Строка, в которой ведется поиск целевой строки.
`target`:	Целевая строка, которая ищется в другой строке.
`start`:	Порядковый номер символа, начиная с которого ведется поиск совпадений. Значение по умолчанию — 1.
`plain`:	Если параметру присвоено значение `true`, функция воспринимает заданную строку как обычный текст. По умолчанию — `true`.

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

Функция должна быть безопасна для строк кодировки UTF-8.

replace

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

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

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

или

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

Параметры

`source`:	Строка, в которой ведется поиск.
`pattern`:	Строка, которая ищется в исходной строке.
`replace`:	Строка, заменяющая целевую.
`count`:	Количество заменяемых совпадений; по умолчанию — все.
`plain`:	Если параметру присвоено значение `true`, функция воспринимает заданную строку как обычный текст. По умолчанию — `true`.

rep

Функция возвращает строку, состоящую из повторений n раз исходной строки. Простая функция для подключения string.rep к шаблонам.

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

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

Параметры

`source`:	Строка, которую необходимо повторить n раз.
`count`:	Количество повторов.

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