Строка

Строка в Elixir — это двоичное представление, закодированное в UTF-8.

Кодовые точки и кластеры графем

Функции в этом модуле работают в соответствии со стандартом Юникод версии 10.0.0.

Согласно стандарту, кодовая точка — это один символ Юникода, который может быть представлен одним или несколькими байтами.

Например, кодовая точка «é» занимает два байта:

iex> byte_size("é")
2

Однако этот модуль возвращает правильную длину:

iex> String.length("é")
1

Кроме того, этот модуль также представляет понятие кластера графем (в дальнейшем упоминаемые как графемы). Графемы могут состоять из нескольких кодовых точек, которые могут восприниматься читателями как один символ. Например, «é» может быть представлен либо как одна кодовая точка «e с острым ударением», либо как буква «e» с последующим «комбинирующим острым ударением» (две кодовые точки):

iex> string = "\u0065\u0301"
iex> byte_size(string)
3
iex> String.length(string)
1
iex> String.codepoints(string)
["e", "́"]
iex> String.graphemes(string)
["é"]

Хотя пример выше состоит из двух символов, он воспринимается пользователями как один.

Графемы также могут быть двумя символами, интерпретируемыми как один некоторыми языками. Например, некоторые языки могут рассматривать «ch» как один символ. Однако, поскольку эта информация зависит от локали, она не учитывается этим модулем.

В общем, функции в этом модуле основаны на стандарте Юникод, но не содержат никакого поведения, специфичного для локали.

Дополнительную информацию о графемах можно найти в Приложении к стандарту Юникод №29. Текущая версия Elixir реализует алгоритм расширенного кластера графем.

Для преобразования двоичных данных в другое кодирование и для механизмов нормализации Юникода см. модуль Erlang’s :unicode.

Операции со строками и двоичными данными

Для работы в соответствии со стандартом Юникод многие функции в этом модуле работают за линейное время, так как им необходимо пройти по всей строке, учитывая правильные кодовые точки Юникода.

Например, String.length/1 будет занимать больше времени по мере увеличения входных данных. С другой стороны, Kernel.byte_size/1 всегда работает за постоянное время (то есть независимо от размера входных данных).

Это означает, что часто при использовании функций этого модуля есть затраты на производительность по сравнению с более низкоуровневыми операциями, которые работают непосредственно с двоичными данными:

Kernel.binary_part/3 - извлечение части двоичных данных
Kernel.bit_size/1 и Kernel.byte_size/1 - функции, связанные с размером
Kernel.is_bitstring/1 и Kernel.is_binary/1 - функции проверки типа
Плюс ряд функций для работы с двоичными данными (байтами) в :binary модуле

Есть много ситуаций, где использование модуля String можно избежать в пользу двоичных функций или сопоставления с образцом. Например, предположим, у вас есть строка prefix и вы хотите удалить этот префикс из другой строки с именем full.

Можно было бы написать:

iex> take_prefix = fn full, prefix ->
...>   base = String.length(prefix)
...>   String.slice(full, base, String.length(full) - base)
...> end
iex> take_prefix.("Mr. John", "Mr. ")
"John"

Хотя функция выше работает, она имеет низкую производительность. Для вычисления длины строки нам нужно пройти по ней полностью, поэтому мы пройдем по строкам prefix и full, а затем обрежем строку full, снова пройдя по ней.

Первая попытка улучшения может быть с использованием диапазонов:

iex> take_prefix = fn full, prefix ->
...>   base = String.length(prefix)
...>   String.slice(full, base..-1)
...> end
iex> take_prefix.("Mr. John", "Mr. ")
"John"

Хотя это значительно лучше (мы не проходим по full дважды), его все еще можно улучшить. В данном случае, поскольку мы хотим извлечь подстроку из строки, мы можем использовать Kernel.byte_size/1 и Kernel.binary_part/3, так как нет возможности нарезать в середине кодовой точки, состоящей более чем из одного байта:

iex> take_prefix = fn full, prefix ->
...>   base = byte_size(prefix)
...>   binary_part(full, base, byte_size(full) - base)
...> end
iex> take_prefix.("Mr. John", "Mr. ")
"John"

Или просто используйте сопоставление с образцом:

iex> take_prefix = fn full, prefix ->
...>   base = byte_size(prefix)
...>   <<_::binary-size(base), rest::binary>> = full
...>   rest
...> end
iex> take_prefix.("Mr. John", "Mr. ")
"John"

С другой стороны, если вы хотите динамически обрезать строку на основе целочисленного значения, тогда использование String.slice/3 является лучшим вариантом, так как это гарантирует, что мы не неправильно разделим действительную кодовую точку на несколько байтов.

Целочисленные кодовые точки

Хотя кодовые точки можно представлять как целые числа, этот модуль представляет все кодовые точки как строки. Например:

iex> String.codepoints("olá")
["o", "l", "á"]

Есть несколько способов получить целочисленную кодовую точку символа. Можно использовать конструкцию ?:

iex> ?o
111

iex> ?á
225

Или также через сопоставление с образцом:

iex> <<aacute::utf8>> = "á"
iex> aacute
225

Как мы видели выше, кодовые точки можно вставить в строку по их шестнадцатеричному коду:

"ol\u0061\u0301" #=>
"olá"

Самосинхронизация

Кодирование UTF-8 является самосинхронизирующимся. Это означает, что если встречаются некорректные данные (то есть данные, которые невозможны в соответствии с определением кодирования), необходимо отклонить только одну кодовую точку.

Этот модуль использует это поведение для игнорирования таких недопустимых символов. Например, length/1 вернет правильный результат, даже если в него будет передана некорректная кодовая точка.

Другими словами, этот модуль ожидает, что некорректные данные будут обнаружены в другом месте, обычно при получении данных из внешнего источника. Например, драйвер, который считывает строки из базы данных, будет отвечать за проверку корректности кодирования. String.chunk/2 можно использовать для разделения строки на правильные и неправильные части.

Шаблоны

Многие функции в этом модуле работают с шаблонами. Например, String.split/2 может разделить строку на несколько шаблонов, заданных шаблоном. Этот шаблон может быть строкой, списком строк или скомпилированным шаблоном:

iex> String.split("foo bar", " ")
["foo", "bar"]

iex> String.split("foo bar!", [" ", "!"])
["foo", "bar", ""]

iex> pattern = :binary.compile_pattern([" ", "!"])
iex> String.split("foo bar!", pattern)
["foo", "bar", ""]

Скомпилированный шаблон полезен, когда то же соответствие выполняется многократно. Однако имейте в виду, что скомпилированный шаблон не может храниться в атрибуте модуля, так как шаблон генерируется во время выполнения и не сохраняется после компиляции.

Резюме

Функции

at(string, position): Возвращает графемный символ в позиции position заданной UTF-8 string. Если position больше, чем длина string, то возвращает nil
capitalize(string, mode \\ :default): Преобразует первый символ в заданной строке в верхний регистр, а остальные — в нижний регистр в соответствии с mode
chunk(string, trait): Разбивает строку на фрагменты символов, которые обладают общим признаком
codepoints(string): Возвращает все код-точки в строке
contains?(string, contents): Проверяет, содержит ли string какие-либо из заданных contents
downcase(string, mode \\ :default): Преобразует все символы в заданной строке в нижний регистр в соответствии с mode
duplicate(subject, n): Возвращает строку subject , продублированную n раз
ends_with?(string, suffixes): Возвращает true , если string оканчивается на какой-либо из заданных суффиксов
equivalent?(string1, string2): Возвращает true , если string1 канонически эквивалентна ‘string2’
first(string): Возвращает первый графемный символ из UTF-8 строки, nil если строка пуста
graphemes(string): Возвращает графемы Юникода в строке в соответствии с алгоритмом расширенного графемного кластера
jaro_distance(string1, string2): Возвращает число с плавающей точкой от 0 (отсутствие сходства) до 1 (полное совпадение), представляющее расстояние Jaro между string1 и string2
last(string): Возвращает последнюю графемный символ из UTF-8 строки, nil если строка пуста
length(string): Возвращает количество символов Юникода в UTF-8 строке
match?(string, regex): Проверяет, соответствует ли string заданному регулярному выражению
myers_difference(string1, string2): Возвращает список ключевых слов, представляющий скрипт редактирования
next_codepoint(string): Возвращает следующую код-точку в строке
next_grapheme(binary): Возвращает следующую графемный символ в строке
next_grapheme_size(string): Возвращает размер следующей графемы
normalize(string, form): Преобразует все символы в string в форму нормализации Юникода, идентифицируемую form
pad_leading(string, count, padding \\ [" "]): Возвращает новую строку, дополненную ведущим заполнителем, составленным из элементов padding
pad_trailing(string, count, padding \\ [" "]): Возвращает новую строку, дополненную хвостовым заполнителем, составленным из элементов padding
printable?(string, counter \\ :infinity): Проверяет, содержит ли строка только печатные символы
replace(subject, pattern, replacement, options \\ []): Возвращает новую строку, созданную путем замены вхождений pattern в subject на replacement
replace_leading(string, match, replacement): Заменяет все ведущие вхождения match на replacement в match в string
replace_prefix(string, match, replacement): Заменяет префикс в string на replacement , если он соответствует match
replace_suffix(string, match, replacement): Заменяет суффикс в string на replacement , если он соответствует match
replace_trailing(string, match, replacement): Заменяет все хвостовые вхождения match на replacement в string
reverse(string): Инвертирует графемы в данной строке
slice(string, range): Возвращает подстроку от смещения, задаваемого началом диапазона, до смещения, задаваемого концом диапазона
slice(string, start, len): Возвращает подстроку, начинающуюся со смещения start, и имеющую длину len
split(binary): Разбивает строку на подстроки на каждом вхождении символа Юникода с пробелом, игнорируя ведущие и хвостовые пробелы. Группы пробелов обрабатываются как одно вхождение. Разделение не происходит на неразрывных пробелах
split(string, pattern, options \\ []): Разбивает строку на подстроки на основе шаблона
split_at(string, position): Разбивает строку на две части в указанной позиции. Когда заданное смещение отрицательное, расположение подсчитывается с конца строки
splitter(string, pattern, options \\ []): Возвращает перечислитель, который разделяет строку по запросу
starts_with?(string, prefix): Возвращает true , если string начинается с любого из заданных префиксов
to_atom(string): Преобразует строку в атом
to_charlist(string): Преобразует строку в список символов
to_existing_atom(string): Преобразует строку в существующий атом
to_float(string): Возвращает число с плавающей точкой, текстовое представление которого — string
to_integer(string): Возвращает целое число, текстовое представление которого — string
to_integer(string, base): Возвращает целое число, текстовое представление которого — string в системе счисления base
trim(string): Возвращает строку, из которой удалены все ведущие и хвостовые пробелы Юникода
trim(string, to_trim): Возвращает строку, из которой удалены все ведущие и хвостовые to_trim
trim_leading(string): Возвращает строку, из которой удалены все ведущие пробелы Юникода
trim_leading(string, to_trim): Возвращает строку, из которой удалены все ведущие to_trim
trim_trailing(string): Возвращает строку, из которой удалены все хвостовые пробелы Юникода
trim_trailing(string, to_trim): Возвращает строку, из которой удалены все хвостовые to_trim
upcase(string, mode \\ :default): Преобразует все символы в заданной строке в верхний регистр в соответствии с mode
valid?(string): Проверяет, содержит ли string только допустимые символы

Типы

codepoint()

codepoint() :: t()

grapheme()

grapheme() :: t()

pattern()

pattern() :: t() | [t()] | :binary.cp()

t()

t() :: binary()

Функции

at(string, position)

at(t(), integer()) :: grapheme() | nil

Возвращает графемный символ в позиции position заданной UTF-8 string. Если position больше, чем длина string, то возвращает nil.

Примеры

iex> String.at("elixir", 0)
"e"

iex> String.at("elixir", 1)
"l"

iex> String.at("elixir", 10)
nil

iex> String.at("elixir", -1)
"r"

iex> String.at("elixir", -10)
nil

capitalize(string, mode \\ :default)

capitalize(t(), :default | :ascii | :greek) :: t()

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

mode может быть :default, :ascii или :greek. Режим :default учитывает все неявные преобразования, описанные в стандарте Юникод. Режим :ascii преобразует только буквы от A до Z в нижний регистр. Режим :greek включает контекстно-зависимые отображения, найденные в греческом языке.

Примеры

iex> String.capitalize("abcd")
"Abcd"

iex> String.capitalize("ﬁn")
"Fin"

iex> String.capitalize("olá")
"Olá"

chunk(string, trait)

chunk(t(), :valid | :printable) :: [t()]

Разбивает строку на фрагменты символов, которые имеют общий признак.

Признак может быть одним из двух вариантов:

:valid — строка разбивается на фрагменты валидных и невалидных последовательностей символов
:printable — строка разбивается на фрагменты печатных и непечатных последовательностей символов

Возвращает список бинарных данных, каждый из которых содержит только один тип символов.

Если заданная строка пустая, возвращается пустой список.

Примеры

iex> String.chunk(<<?a, ?b, ?c, 0>>, :valid)
["abc\0"]

iex> String.chunk(<<?a, ?b, ?c, 0, 0xFFFF::utf16>>, :valid)
["abc\0", <<0xFFFF::utf16>>]

iex> String.chunk(<<?a, ?b, ?c, 0, 0x0FFFF::utf8>>, :printable)
["abc", <<0, 0x0FFFF::utf8>>]

codepoints(string)

codepoints(t()) :: [codepoint()]

Возвращает все кодовые точки в строке.

Подробности о кодовых точках и графемах см. в документации модуля String.

Примеры

iex> String.codepoints("olá")
["o", "l", "á"]

iex> String.codepoints("оптими зации")
["о", "п", "т", "и", "м", "и", " ", "з", "а", "ц", "и", "и"]

iex> String.codepoints("ἅἪῼ")
["ἅ", "Ἢ", "ῼ"]

iex> String.codepoints("é")
["é"]

iex> String.codepoints("é")
["e", "́"]

contains?(string, contents)

contains?(t(), pattern()) :: boolean()

Проверяет, содержит ли string какие-либо из указанных contents.

contents может быть либо одной строкой, либо списком строк.

Примеры

iex> String.contains? "elixir of life", "of"
true
iex> String.contains? "elixir of life", ["life", "death"]
true
iex> String.contains? "elixir of life", ["death", "mercury"]
false

Пустая строка всегда будет соответствовать:

iex> String.contains? "elixir of life", ""
true
iex> String.contains? "elixir of life", ["", "other"]
true

Аргумент также может быть предварительно скомпилированным шаблоном:

iex> pattern = :binary.compile_pattern(["life", "death"])
iex> String.contains? "elixir of life", pattern
true

Обратите внимание, что эта функция может соответствовать внутри или между графемами. Например, возьмём графему «é», которая состоит из символов «e» и острого ударения. Следующее возвращает true:

iex> String.contains?(String.normalize("é", :nfd), "e")
true

Однако, если «é» представлена одним символом «e с острым» ударением, то она вернёт false:

iex> String.contains?(String.normalize("é", :nfc), "e")
false

downcase(string, mode \\ :default)

downcase(t(), :default | :ascii | :greek) :: t()

Преобразует все символы в заданной строке в нижний регистр в соответствии с mode.

Примеры

iex> String.downcase("ABCD")
"abcd"

iex> String.downcase("AB 123 XPTO")
"ab 123 xpto"

iex> String.downcase("OLÁ")
"olá"

Режим :ascii игнорирует символы Юникода и обеспечивает более высокую производительность, когда известно, что строка содержит только символы ASCII:

iex> String.downcase("OLÁ", :ascii)
"olÁ"

А режим :greek правильно обрабатывает контекстно-зависимую сигму в греческом языке:

iex> String.downcase("ΣΣ")
"σσ"

iex> String.downcase("ΣΣ", :greek)
"σς"

duplicate(subject, n)

duplicate(t(), non_neg_integer()) :: t()

Возвращает строку subject дублированную n раз.

Встраивается компилятором.

Примеры

iex> String.duplicate("abc", 0)
""

iex> String.duplicate("abc", 1)
"abc"

iex> String.duplicate("abc", 2)
"abcabc"

ends_with?(string, suffixes)

ends_with?(t(), t() | [t()]) :: boolean()

Возвращает true если string заканчивается на какой-либо из указанных суффиксов.

suffixes может быть либо одним суффиксом, либо списком суффиксов.

Примеры

iex> String.ends_with? "language", "age"
true
iex> String.ends_with? "language", ["youth", "age"]
true
iex> String.ends_with? "language", ["youth", "elixir"]
false

Пустой суффикс всегда будет соответствовать:

iex> String.ends_with? "language", ""
true
iex> String.ends_with? "language", ["", "other"]
true

equivalent?(string1, string2)

equivalent?(t(), t()) :: boolean()

Возвращает true если string1 канонически эквивалентна ‘string2’.

Выполняет нормализацию в форме канонического разложения (NFD) для строк перед сравнением. Эта функция эквивалентна:

String.normalize(string1, :nfd) == String.normalize(string2, :nfd)

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

Примеры

iex> String.equivalent?("abc", "abc")
true

iex> String.equivalent?("man\u0303ana", "mañana")
true

iex> String.equivalent?("abc", "ABC")
false

iex> String.equivalent?("nø", "nó")
false

first(string)

first(t()) :: grapheme() | nil

Возвращает первый графемный символ из UTF-8 строки, nil если строка пуста.

Примеры

iex> String.first("elixir")
"e"

iex> String.first("եոգլի")
"ե"

graphemes(string)

graphemes(t()) :: [grapheme()]

Возвращает графемы Юникода в строке в соответствии с алгоритмом расширенных графемных кластеров.

Алгоритм описан в Unicode Standard Annex #29, Unicode Text Segmentation.

Подробности о кодовых точках и графемах см. в документации модуля String.

Примеры

iex> String.graphemes("Ńaïve")
["Ń", "a", "ï", "v", "e"]

iex> String.graphemes("é")
["é"]

iex> String.graphemes("é")
["é"]

jaro_distance(string1, string2)

jaro_distance(t(), t()) :: float()

Возвращает значение с плавающей точкой от 0 (отсутствие сходства) до 1 (точное совпадение), представляющее расстояние Яро между string1 и string2.

Метрика расстояния Яро предназначена и лучше всего подходит для коротких строк, таких как имена людей.

Примеры

iex> String.jaro_distance("dwayne", "duane")
0.8222222222222223
iex> String.jaro_distance("even", "odd")
0.0

last(string)

last(t()) :: grapheme() | nil

Возвращает последнюю графему из UTF-8 строки, nil если строка пуста.

Примеры

iex> String.last("elixir")
"r"

iex> String.last("եոգլի")
"ի"

length(string)

length(t()) :: non_neg_integer()

Возвращает количество графем Юникода в строке UTF-8.

Примеры

iex> String.length("elixir")
6

iex> String.length("եոգլի")
5

match?(string, regex)

match?(t(), Regex.t()) :: boolean()

Проверяет, соответствует ли string заданному регулярному выражению.

Примеры

iex> String.match?("foo", ~r/foo/)
true

iex> String.match?("bar", ~r/foo/)
false

myers_difference(string1, string2)

myers_difference(t(), t()) :: [{:eq | :ins | :del, t()}] | nil

Возвращает список ключевых слов, представляющих сценарий редактирования.

См. List.myers_difference/2 для получения дополнительной информации.

Примеры

iex> string1 = "fox hops over the dog"
iex> string2 = "fox jumps over the lazy cat"
iex> String.myers_difference(string1, string2)
[eq: "fox ", del: "ho", ins: "jum", eq: "ps over the ", del: "dog", ins: "lazy cat"]

next_codepoint(string)

next_codepoint(t()) :: {codepoint(), t()} | nil

Возвращает следующую кодовую точку в строке.

Результат — кортеж с кодовой точкой и остальной частью строки или nil в случае, если строка достигла конца.

Как и другие функции модуля String, эта функция не проверяет правильность кодовой точки. Тем не менее, если будет найдена недействительная кодовая точка, она будет возвращена этой функцией.

Примеры

iex> String.next_codepoint("olá")
{"o", "lá"}

next_grapheme(binary)

next_grapheme(t()) :: {grapheme(), t()} | nil

Возвращает следующую графему в строке.

Результат — кортеж с графемой и остальной частью строки или nil в случае, если строка достигла конца.

Примеры

iex> String.next_grapheme("olá")
{"o", "lá"}

next_grapheme_size(string)

next_grapheme_size(t()) :: {pos_integer(), t()} | nil

Возвращает размер следующей графемы.

Результат — кортеж с размером следующей графемы и остальной частью строки или nil в случае, если строка достигла конца.

Примеры

iex> String.next_grapheme_size("olá")
{1, "lá"}

normalize(string, form)

normalize(t(), atom()) :: t()

Преобразует все символы в string в форму нормализации Юникода, указанную в form.

Формы

Поддерживаемые формы:

:nfd — Форма канонического разложения. Символы разлагаются по каноническому совпадению, и несколько комбинирующих символов располагаются в определённом порядке.
:nfc — Форма канонического объединения. Символы разлагаются и затем объединяются по каноническому совпадению.

Примеры

iex> String.normalize("yêṩ", :nfd)
"yêṩ"

iex> String.normalize("leña", :nfc)
"leña"

pad_leading(string, count, padding \\ [" "])

pad_leading(t(), non_neg_integer(), t() | [t()]) :: t()

Возвращает новую строку, заполненную ведущим заполнителем, состоящим из элементов из padding.

Передача списка строк в качестве padding возьмёт один элемент из списка для каждого пропущенного элемента. Если список короче, чем количество вставок, заполнение начнется снова с начала списка. Передача строки padding эквивалентна передаче списка графем в ней. Если padding не указан, он по умолчанию равен пробелу.

Когда count меньше или равно длине string, возвращается string.

Возникает исключение ArgumentError, если переданный padding содержит элемент, не являющийся строкой.

Примеры

iex> String.pad_leading("abc", 5)
"  abc"

iex> String.pad_leading("abc", 4, "12")
"1abc"

iex> String.pad_leading("abc", 6, "12")
"121abc"

iex> String.pad_leading("abc", 5, ["1", "23"])
"123abc"

pad_trailing(string, count, padding \\ [" "])

pad_trailing(t(), non_neg_integer(), t() | [t()]) :: t()

Возвращает новую строку, дополненную заключительным заполнителем, составленным из элементов из padding.

Передача списка строк в качестве padding будет использовать по одному элементу из списка для каждого недостающего значения. Если список короче, чем количество вставляемых элементов, заполнение начнется сначала с начала списка. Передача строки padding эквивалентна передаче списка графем в ней. Если padding не указано, по умолчанию используется пробел.

Когда count меньше или равно длине string, возвращается string.

Возникает исключение ArgumentError, если переданный padding содержит элемент, не являющийся строкой.

Примеры

iex> String.pad_trailing("abc", 5)
"abc  "

iex> String.pad_trailing("abc", 4, "12")
"abc1"

iex> String.pad_trailing("abc", 6, "12")
"abc121"

iex> String.pad_trailing("abc", 5, ["1", "23"])
"abc123"

printable?(string, counter \\ :infinity)

printable?(t(), non_neg_integer() | :infinity) :: boolean()

Проверяет, содержит ли строка только печатаемые символы.

Принимает необязательный limit в качестве второго аргумента. printable?/2 проверяет только печатаемость строки до limit.

Примеры

iex> String.printable?("abc")
true

iex> String.printable?("abc" <> <<0>>)
false

iex> String.printable?("abc" <> <<0>>, 2)
true

replace(subject, pattern, replacement, options \\ [])

replace(t(), pattern() | Regex.t(), t(), keyword()) :: t()

Возвращает новую строку, созданную заменой вхождений pattern в subject на replacement.

pattern может быть строкой или регулярным выражением.

По умолчанию заменяются все вхождения, но это поведение можно контролировать с помощью параметра :global; см. раздел «Параметры» ниже.

Параметры

:global - (boolean) если true, все вхождения pattern заменяются на replacement, иначе заменяется только первое вхождение. По умолчанию true
:insert_replaced - (целое число или список целых чисел) определяет позицию, где необходимо вставить заменённую часть внутри replacement. Если любая позиция, заданная в параметре :insert_replaced, больше, чем длина заменяющей строки, или отрицательна, возникает ArgumentError. См. примеры ниже

Примеры

iex> String.replace("a,b,c", ",", "-")
"a-b-c"

iex> String.replace("a,b,c", ",", "-", global: false)
"a-b,c"

Когда шаблон является регулярным выражением, можно использовать \N или \g{N} в строке replacement для доступа к определённому захвату в регулярном выражении:

iex> String.replace("a,b,c", ~r/,(.)/, ",\\1\\g{1}")
"a,bb,cc"

Обратите внимание, что нам пришлось экранировать обратную косую черту (т. е., мы использовали \\N вместо просто \N для экранирования обратной косой черты; то же самое для \\g{N}). Указав \0, можно вставить весь совпавший шаблон в строку замены.

Когда шаблон является строкой, разработчик может использовать заменённую часть внутри replacement с помощью параметра :insert_replaced и указанием позиции(й) внутри replacement, где будет вставлена строка-шаблон:

iex> String.replace("a,b,c", "b", "[]", insert_replaced: 1)
"a,[b],c"

iex> String.replace("a,b,c", ",", "[]", insert_replaced: 2)
"a[],b[],c"

iex> String.replace("a,b,c", ",", "[]", insert_replaced: [1, 1])
"a[,,]b[,,]c"

Когда в качестве pattern задана пустая строка, функция будет обрабатывать её как неявную пустую строку между каждой графемой, и строка будет вставлена. Если в качестве replacement задана пустая строка, возвращается subject:

iex> String.replace("ELIXIR", "", ".")
".E.L.I.X.I.R."

iex> String.replace("ELIXIR", "", "")
"ELIXIR"

replace_leading(string, match, replacement)

replace_leading(t(), t(), t()) :: t() | no_return()

Заменяет все ведущие вхождения match на replacement match в string.

Возвращает строку без изменений, если вхождений нет.

Если match равно "", эта функция вызывает исключение ArgumentError: это происходит потому, что эта функция заменяет все вхождения match в начале string, и невозможно заменить «несколько» вхождений "".

Примеры

iex> String.replace_leading("hello world", "hello ", "")
"world"
iex> String.replace_leading("hello hello world", "hello ", "")
"world"

iex> String.replace_leading("hello world", "hello ", "ola ")
"ola world"
iex> String.replace_leading("hello hello world", "hello ", "ola ")
"ola ola world"

replace_prefix(string, match, replacement)

replace_prefix(t(), t(), t()) :: t()

Заменяет префикс в string на replacement если он соответствует match.

Возвращает строку без изменений, если соответствия нет. Если match является пустой строкой (""), replacement просто добавляется в начало string.

Примеры

iex> String.replace_prefix("world", "hello ", "")
"world"
iex> String.replace_prefix("hello world", "hello ", "")
"world"
iex> String.replace_prefix("hello hello world", "hello ", "")
"hello world"

iex> String.replace_prefix("world", "hello ", "ola ")
"world"
iex> String.replace_prefix("hello world", "hello ", "ola ")
"ola world"
iex> String.replace_prefix("hello hello world", "hello ", "ola ")
"ola hello world"

iex> String.replace_prefix("world", "", "hello ")
"hello world"

replace_suffix(string, match, replacement)

replace_suffix(t(), t(), t()) :: t()

Заменяет суффикс в string на replacement если он соответствует match.

Возвращает строку без изменений, если соответствия нет. Если match является пустой строкой (""), replacement просто добавляется в конец string.

Примеры

iex> String.replace_suffix("hello", " world", "")
"hello"
iex> String.replace_suffix("hello world", " world", "")
"hello"
iex> String.replace_suffix("hello world world", " world", "")
"hello world"

iex> String.replace_suffix("hello", " world", " mundo")
"hello"
iex> String.replace_suffix("hello world", " world", " mundo")
"hello mundo"
iex> String.replace_suffix("hello world world", " world", " mundo")
"hello world mundo"

iex> String.replace_suffix("hello", "", " world")
"hello world"

replace_trailing(string, match, replacement)

replace_trailing(t(), t(), t()) :: t() | no_return()

Заменяет все заключительные вхождения match на replacement в string.

Возвращает строку без изменений, если вхождений нет.

Если match равно "", эта функция вызывает исключение ArgumentError: это происходит потому, что эта функция заменяет все вхождения match в конце string, и невозможно заменить «несколько» вхождений "".

Примеры

iex> String.replace_trailing("hello world", " world", "")
"hello"
iex> String.replace_trailing("hello world world", " world", "")
"hello"

iex> String.replace_trailing("hello world", " world", " mundo")
"hello mundo"
iex> String.replace_trailing("hello world world", " world", " mundo")
"hello mundo mundo"

reverse(string)

reverse(t()) :: t()

Обращает порядок графем в заданной строке.

Примеры

iex> String.reverse("abcd")
"dcba"

iex> String.reverse("hello world")
"dlrow olleh"

iex> String.reverse("hello ∂og")
"go∂ olleh"

Обратите внимание, что повторное применение функции обратного преобразования к одной и той же строке не обязательно приводит к исходной строке:

iex> "̀e"
"̀e"
iex> String.reverse("̀e")
"è"
iex> String.reverse String.reverse("̀e")
"è"

В первом примере знак ударения стоит перед гласной, поэтому они считаются двумя графемами. Однако после первого обратного преобразования гласная идёт перед знаком ударения, образуя одну графему. Ещё одно обратное преобразование сохранит её как одну графему.

slice(string, range)

slice(t(), Range.t()) :: t()

Возвращает подстроку с позиции, заданной началом диапазона, до позиции, заданной концом диапазона.

Если начало диапазона не является корректной позицией для заданной строки, или диапазон задан в обратном порядке, возвращается "".

Если начало или конец диапазона отрицательны, вся строка сперва просматривается для преобразования отрицательных индексов в положительные.

Помните, что эта функция работает с графемами Юникода и рассматривает срезы как смещения графем. Если вам нужно разбить по байтам, обратитесь к Kernel.binary_part/3 вместо этого.

Примеры

iex> String.slice("elixir", 1..3)
"lix"

iex> String.slice("elixir", 1..10)
"lixir"

iex> String.slice("elixir", 10..3)
""

iex> String.slice("elixir", -4..-1)
"ixir"

iex> String.slice("elixir", 2..-1)
"ixir"

iex> String.slice("elixir", -4..6)
"ixir"

iex> String.slice("elixir", -1..-4)
""

iex> String.slice("elixir", -10..-7)
""

iex> String.slice("a", 0..1500)
"a"

iex> String.slice("a", 1..1500)
""

slice(string, start, len)

slice(t(), integer(), integer()) :: grapheme()

Возвращает подстроку, начинающуюся с позиции start, и имеющую длину len.

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

Примеры

iex> String.slice("elixir", 1, 3)
"lix"

iex> String.slice("elixir", 1, 10)
"lixir"

iex> String.slice("elixir", 10, 3)
""

iex> String.slice("elixir", -4, 4)
"ixir"

iex> String.slice("elixir", -10, 3)
""

iex> String.slice("a", 0, 1500)
"a"

iex> String.slice("a", 1, 1500)
""

iex> String.slice("a", 2, 1500)
""

split(binary)

split(t()) :: [t()]

Делит строку на подстроки в каждой точке появления пробела Юникода, игнорируя ведущие и заключительные пробелы. Группы пробелов обрабатываются как одно вхождение. Разбиения не происходят на неразрывных пробелах.

Примеры

iex> String.split("foo bar")
["foo", "bar"]

iex> String.split("foo" <> <<194, 133>> <> "bar")
["foo", "bar"]

iex> String.split(" foo   bar ")
["foo", "bar"]

iex> String.split("no\u00a0break")
["no\u00a0break"]

split(string, pattern, options \\ [])

split(t(), pattern() | Regex.t(), keyword()) :: [t()]

Делит строку на подстроки на основе шаблона.

Возвращает список этих подстрок. Шаблон может быть строкой, списком строк или регулярным выражением.

Строка делится на максимально возможное количество частей по умолчанию, но это поведение можно контролировать параметром :parts.

Пустые строки удаляются из результата только если параметр :trim установлен в true.

Если используемый шаблон является регулярным выражением, строка разбивается с помощью Regex.split/3.

Параметры

:parts (положительное целое число или :infinity) - строка делится не более чем на столько частей, сколько указано в этом параметре. Если :infinity, строка будет разделена на все возможные части. По умолчанию :infinity.
:trim (boolean) - если true, пустые строки удаляются из результирующего списка.

Эта функция также принимает все параметры, принятые Regex.split/3, если pattern является регулярным выражением.

Примеры

Разбиение по строковому шаблону:

iex> String.split("a,b,c", ",")
["a", "b", "c"]

iex> String.split("a,b,c", ",", parts: 2)
["a", "b,c"]

iex> String.split(" a b c ", " ", trim: true)
["a", "b", "c"]

Список шаблонов:

iex> String.split("1,2 3,4", [" ", ","])
["1", "2", "3", "4"]

Регулярное выражение:

iex> String.split("a,b,c", ~r{,})
["a", "b", "c"]

iex> String.split("a,b,c", ~r{,}, parts: 2)
["a", "b,c"]

iex> String.split(" a b c ", ~r{\s}, trim: true)
["a", "b", "c"]

iex> String.split("abc", ~r{b}, include_captures: true)
["a", "b", "c"]

Разбиение на пустую строку возвращает графемы:

iex> String.split("abc", "")
["", "a", "b", "c", ""]

iex> String.split("abc", "", trim: true)
["a", "b", "c"]

iex> String.split("abc", "", parts: 1)
["abc"]

iex> String.split("abc", "", parts: 3)
["", "a", "bc"]

Также можно передать предварительно скомпилированный шаблон:

iex> pattern = :binary.compile_pattern([" ", ","])
iex> String.split("1,2 3,4", pattern)
["1", "2", "3", "4"]

Обратите внимание, что эта функция может разбивать строку внутри или между границами графем. Например, рассмотрим графему «é», которая состоит из символов «e» и острого ударения. Следующее возвращает true:

iex> String.split(String.normalize("é", :nfd), "e")
["", "́"]

Однако, если «é» представлена одним символом «e с острым» ударением, то она вернёт false:

iex> String.split(String.normalize("é", :nfc), "e")
["é"]

split_at(string, position)

split_at(t(), integer()) :: {t(), t()}

Разделяет строку на две части по заданному смещению. При отрицательном смещении позиция считается с конца строки.

Смещение ограничено длиной строки. Возвращает кортеж из двух элементов.

Примечание: имейте в виду, что эта функция разделяет по графемам, и для этого ей необходимо линейно пройти по строке. Если вы хотите разделить строку или двоичные данные на основе количества байтов, используйте Kernel.binary_part/3 вместо этого.

Примеры

iex> String.split_at "sweetelixir", 5
{"sweet", "elixir"}

iex> String.split_at "sweetelixir", -6
{"sweet", "elixir"}

iex> String.split_at "abc", 0
{"", "abc"}

iex> String.split_at "abc", 1000
{"abc", ""}

iex> String.split_at "abc", -1000
{"", "abc"}

splitter(string, pattern, options \\ [])

splitter(t(), pattern(), keyword()) :: Enumerable.t()

Возвращает перечислитель, который разделяет строку по требованию.

Это отличается от split/3, которая разделяет всю строку сразу.

Обратите внимание, что splitter не поддерживает регулярные выражения (так как часто эффективнее, если регулярное выражение проходит по строке сразу, а не многократно).

Параметры

:trim - когда true, не выводить пустые шаблоны

Примеры

iex> String.splitter("1,2 3,4 5,6 7,8,...,99999", [" ", ","]) |> Enum.take(4)
["1", "2", "3", "4"]

iex> String.splitter("abcd", "") |> Enum.take(10)
["", "a", "b", "c", "d", ""]

iex> String.splitter("abcd", "", trim: true) |> Enum.take(10)
["a", "b", "c", "d"]

starts_with?(string, prefix)

starts_with?(t(), t() | [t()]) :: boolean()

Возвращает true, если string начинается с одного из заданных префиксов.

prefix может быть либо одним префиксом, либо списком префиксов.

Примеры

iex> String.starts_with? "elixir", "eli"
true
iex> String.starts_with? "elixir", ["erlang", "elixir"]
true
iex> String.starts_with? "elixir", ["erlang", "ruby"]
false

Пустая строка всегда будет соответствовать:

iex> String.starts_with? "elixir", ""
true
iex> String.starts_with? "elixir", ["", "other"]
true

to_atom(string)

to_atom(String.t()) :: atom()

Преобразует строку в атом.

Предупреждение: эта функция динамически создаёт атомы, а атомы не собираются сборщиком мусора. Поэтому string не должно быть недоверенным значением, таким как входные данные, полученные из сокета или во время веб-запроса. Рассмотрите использование to_existing_atom/1 вместо этого.

По умолчанию максимальное количество атомов равно 1_048_576. Этот предел можно повысить или понизить, используя параметр виртуальной машины +t.

Максимальный размер атома составляет 255 символов. До OTP 20 разрешались только символы latin1.

Встраивается компилятором.

Примеры

iex> String.to_atom("my_atom")
:my_atom

to_charlist(string)

to_charlist(t()) :: charlist()

Преобразует строку в список символов.

Точнее, эта функция принимает UTF-8 кодированный двоичный массив и возвращает список его целочисленных кодовых точек. Это аналогично codepoints/1, за исключением того, что последнее возвращает список кодовых точек в виде строк.

Если вам нужно работать с байтами, обратитесь к модулю :binary.

Примеры

iex> String.to_charlist("æß")
'æß'

to_existing_atom(string)

to_existing_atom(String.t()) :: atom()

Преобразует строку в существующий атом.

Максимальный размер атома составляет 255 символов. До OTP 20 разрешались только символы latin1.

Встраивается компилятором.

Примеры

iex> _ = :my_atom
iex> String.to_existing_atom("my_atom")
:my_atom

iex> String.to_existing_atom("this_atom_will_never_exist")
** (ArgumentError) argument error

to_float(string)

to_float(String.t()) :: float()

Возвращает число с плавающей точкой, текстовое представление которого string.

string должно быть строковым представлением числа с плавающей точкой, включая десятичную точку. Для разбора строки без десятичной точки как числа с плавающей точкой следует использовать Float.parse/1. В противном случае будет поднято исключение ArgumentError.

Встраивается компилятором.

Примеры

iex> String.to_float("2.2017764e+0")
2.2017764

iex> String.to_float("3.0")
3.0

String.to_float("3")
#=> ** (ArgumentError) argument error

to_integer(string)

to_integer(String.t()) :: integer()

Возвращает целое число, текстовое представление которого string.

Встраивается компилятором.

Примеры

iex> String.to_integer("123")
123

to_integer(string, base)

to_integer(String.t(), 2..36) :: integer()

Возвращает целое число, текстовое представление которого string в системе счисления base.

Встраивается компилятором.

Примеры

iex> String.to_integer("3FF", 16)
1023

trim(string)

trim(t()) :: t()

Возвращает строку, из которой удалены все начальные и конечные пробелы Unicode.

Примеры

iex> String.trim("\n  abc\n  ")
"abc"

trim(string, to_trim)

trim(t(), t()) :: t()

Возвращает строку, из которой удалены все начальные и конечные to_trim.

Примеры

iex> String.trim("a  abc  a", "a")
"  abc  "

trim_leading(string)

trim_leading(t()) :: t()

Возвращает строку, из которой удалены все начальные пробелы Unicode.

Примеры

iex> String.trim_leading("\n  abc   ")
"abc   "

trim_leading(string, to_trim)

trim_leading(t(), t()) :: t()

Возвращает строку, из которой удалены все начальные to_trim.

Примеры

iex> String.trim_leading("__ abc _", "_")
" abc _"

iex> String.trim_leading("1 abc", "11")
"1 abc"

trim_trailing(string)

trim_trailing(t()) :: t()

Возвращает строку, из которой удалены все конечные пробелы Unicode.

Примеры

iex> String.trim_trailing("   abc\n  ")
"   abc"

trim_trailing(string, to_trim)

trim_trailing(t(), t()) :: t()

Возвращает строку, из которой удалены все конечные to_trim.

Примеры

iex> String.trim_trailing("_ abc __", "_")
"_ abc "

iex> String.trim_trailing("abc 1", "11")
"abc 1"

upcase(string, mode \\ :default)

upcase(t(), :default | :ascii | :greek) :: t()

Преобразует все символы в заданной строке в верхний регистр в соответствии с mode.

mode может быть :default, :ascii или :greek. Режим :default учитывает все безусловные преобразования, описанные в стандарте Unicode. :ascii преобразует только буквы от a до z в верхний регистр. :greek включает контекстно-зависимые соответствия, обнаруженные в греческом языке.

Примеры

iex> String.upcase("abcd")
"ABCD"

iex> String.upcase("ab 123 xpto")
"AB 123 XPTO"

iex> String.upcase("olá")
"OLÁ"

Режим :ascii игнорирует символы Unicode и обеспечивает более эффективную реализацию, когда вы знаете, что строка содержит только символы ASCII:

iex> String.upcase("olá", :ascii)
"OLá"

valid?(string)

valid?(t()) :: boolean()

Проверяет, содержит ли string только допустимые символы.

Примеры

iex> String.valid?("a")
true

iex> String.valid?("ø")
true

iex> String.valid?(<<0xFFFF :: 16>>)
false

iex> String.valid?(<<0xEF, 0xB7, 0x90>>)
true

iex> String.valid?("asd" <> <<0xFFFF :: 16>>)
false