Редактирование: Модуль:String/doc

{{Docpage}}
{{СИШ}}
{{Используйте песочницу}}

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

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

== Глобальные параметры ==
{|
|{{Code|ignore_errors}}:
|Если параметру присвоено значение {{Code|true}} или {{Code|1}}, вместо любого сообщения об ошибке выводится пустая строка.
|-
|{{Code|error_category}}:
|В случае возникновения ошибки определяет название категории, в которую помещается страница с сообщением об ошибке. По умолчанию помещается в {{C|Страницы с ошибками модуля String|В}}.
|-
|{{Code|no_category}}:
|Если параметру присвоено значение {{Code|true}} или {{Code|1}}, то в случае сообщения об ошибке страница не будет помещена в соответствующую категорию.
|}

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

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

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

: или

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

; Параметры
{|
|{{Code|s}}:
|Целевая строка, часть которой необходимо найти.
|-
|{{Code|pattern}}:
|Строка, совпадение с которой необходимо найти в целевой строке.
|-
|{{Code|plain}}:
|Если параметру присвоено значение {{Code|false}}, функция воспринимает заданную строку как [[mw:Extension:Scribunto/Lua reference manual#Patterns|регулярное выражение]]. По умолчанию — {{Code|true}}.
|-
|}

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

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

: <Code><nowiki>{{#invoke:</nowiki>String|len|''целевая_строка''}}</Code>

: или

: <Code><nowiki>{{#invoke:</nowiki>String|len|s= ''целевая_строка'' }}</Code>

; Параметры
{|
|{{Code|s}}:
|Строка, длину которой необходимо найти.
|}
== sub ==
Функция возвращает часть целевой стоки между указанными индексами (порядковыми номерами символов в целевой строке)

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

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

: или

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

; Параметры
{|
|{{Code|s}}:
|Строка, часть которой необходимо вывести.
|-
|{{Code|i}}:
|Порядковый номер символа, начиная с которого необходимо вывести строку. Значение по умолчанию — 1.
|-
|{{Code|j}}:
|Порядковый номер символа, до которого необходимо вывести строку. Значение по умолчанию — порядковый номер последнего символа.
|}
Первому символу строки присваивается индекс {{Code|1}}. Если параметрам {{Code|i}} или {{Code|j}} присвоено отрицательное значение, то оно распознается модулем как порядковый номер символа, отсчитываемый с конца строки. Другими словами, значение {{Code|-1}} распознается модулем как порядковый номер последнего символа в строке.

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

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

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

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

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

: или

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

; Параметры
{|
|{{Code|s}}:
|Целевая строка, часть которой необходимо найти.
|-
|{{Code|pattern}}:
|Строка, совпадение с которой необходимо найти в целевой строке.
|-
|{{Code|start}}:
|Порядковый номер символа, начиная с которого необходимо произвести поиск совпадения. По умолчанию — {{Code|1}}. Если начиная с заданного символа совпадений не найдено, функция возвращает сообщение об ошибке.
|-
|{{Code|match}}:
|В некоторых случаях может оказаться несколько совпадений с заданной строкой в одной целевой строке. Параметр задает номер совпадения, которое необходимо вывести. Если параметру присвоено отрицательное значение, то оно распознается модулем как порядковый номер совпадения, отсчитываемый с конца строки. Другими словами, значение {{Code|-1}} распознается модулем как порядковый номер последнего совпадения в строке. По умолчанию — 1.
|-
|{{Code|plain}}:
|Если параметру присвоено значение {{Code|true}}, функция воспринимает заданную строку как обычный текст, а не [[mw:Extension:Scribunto/Lua reference manual#Patterns|регулярное выражение]]. По умолчанию — {{Code|false}}.
|-
|{{Code|nomatch}}:
|Последовательность символов, выводимая строкой в случае отсутствия совпадений вместо сообщения об ошибке.
|}
Если введённый индекс по модулю больше длины целевой строки или совпадений найдено меньше, чем число, заданное в параметре {{Code|match}}, то выводится сообщение об ошибке.
Если добавить параметр {{Code|ignore_errors{{=}}true}}, то вместо любого из сообщений об ошибке будет возвращена пустая строка.

Подробнее о [[Регулярное выражение|регулярных выражениях]], используемых в [[Lua]], см. [[mw:Extension:Scribunto/Lua reference manual#Patterns|Руководство по метасимволам]].

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

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

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

: или

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

; Параметры
{|
|{{Code|target}}:
|Строка, в которой производится поиск символа.
|-
|{{Code|pos}}:
|Порядковый номер возвращаемого символа
|}
Если параметру {{Code|pos}} присвоено отрицательное значение, то оно распознается модулем как порядковый номер символа, отсчитываемый с конца строки. Другими словами, значение {{Code|-1}} распознается модулем как порядковый номер последнего символа в строке.

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

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

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

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

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

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

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

: или

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

; Параметры
{|
|{{Code|source}}:
|Строка, в которой ведется поиск целевой строки.
|-
|{{Code|target}}:
|Целевая строка, которая ищется в другой строке.
|-
|{{Code|start}}:
|Порядковый номер символа, начиная с которого ведется поиск совпадений. Значение по умолчанию — 1.
|-
|{{Code|plain}}:
|Если параметру присвоено значение {{Code|true}}, функция воспринимает заданную строку как обычный текст, а не [[mw:Extension:Scribunto/Lua reference manual#Patterns|регулярное выражение]]. По умолчанию — {{Code|true}}.
|}
Функция возвращает значение, большее либо равное значению параметра {{Code|start}}. Если совпадений не найдено, функция возвращает <Code>0</Code>, если одна из строк пустая или не задана, функция также возвращает <Code>0</Code>.

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

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

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

: или

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

; Параметры
{|сlass="simple"
|{{Code|source}}:
|Строка, в которой ведется поиск.
|-
|{{Code|pattern}}:
|Строка, которая ищется в исходной строке.
|-
|{{Code|replace}}:
|Строка, заменяющая целевую.
|-
|{{Code|count}}:
|Количество заменяемых совпадений; по умолчанию — все.
|-
|{{Code|plain}}:
|Если параметру присвоено значение {{Code|true}}, функция воспринимает заданную строку как обычный текст, а не [[mw:Extension:Scribunto/Lua reference manual#Patterns|регулярное выражение]]. По умолчанию — {{Code|true}}.
|}

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

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

: <Code><nowiki>{{#invoke:</nowiki>String|rep|''строка''|''количество_повторов''}}</Code>

; Параметры
{|
|{{Code|source}}:
|Строка, которую необходимо повторить ''n'' раз.
|-
|{{Code|count}}:
|Количество повторов.
|}
; Пример
<Code><nowiki>{{#invoke:String|rep|привет!|3}}</nowiki></Code> → {{#invoke:String|rep|привет!|3}}

<includeonly>
[[Категория:Модули:Базовые]]
[[Категория:Модули:Работа со строками]]
</includeonly>
<noinclude>
[[Категория:Модули:Документация]]</noinclude>