Строка

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

Кодепоинты и графемы

Функции в этом модуле действуют в соответствии со стандартом Unicode, версия 6.3.0.

В соответствии со стандартом, кодепоинт — это один символ Unicode, который может быть представлен одним или несколькими байтами.

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

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» как графему. Однако, поскольку эта информация зависит от локали, она не учитывается этим модулем.

В целом, функции в этом модуле полагаются на стандарт Unicode, но не содержат никакого локали-зависимого поведения.

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

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

Чтобы действовать в соответствии со стандартом Unicode, многие функции в этом модуле выполняются за линейное время, поскольку им необходимо пройти по всей строке, учитывая правильные символы 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 дважды), это можно улучшить. В этом случае, так как мы хотим извлечь подстроку из строки, мы можем использовать byte_size/1 и 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.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(строка, позиция): Возвращает графемный символ в позиции position заданной utf8 string. Если position больше, чем длина string, то возвращает nil
capitalize(строка): Преобразует первый символ в заданной строке в верхний регистр, а остальные — в нижний.
chunk(строка, признак): Разбивает строку на куски символов, имеющих общий признак.
codepoints(строка): Возвращает все кодовые точки в строке.
contains?(строка, содержимое): Проверяет, содержит ли string любой из заданных contents.
downcase(бинарный): Преобразует все символы в заданной строке в нижний регистр.
duplicate(объект, n): Возвращает строку subject, дублированную n раз.
ends_with?(строка, суффиксы): Возвращает true если string оканчивается на любой из указанных суффиксов.
equivalent?(строка1, строка2): Возвращает true если string1 канонически эквивалентна ‘строка2’.
first(строка): Возвращает первый графемный символ из utf8 строки, nil если строка пуста.
graphemes(строка): Возвращает Unicode графемы в строке согласно алгоритму расширенного графемного кластера.
jaro_distance(строка1, строка2): Возвращает значение с плавающей точкой от 0 (соответствует отсутствию сходства) до 1 (является точным совпадением), представляющее расстояние Яро между string1 и string2.
last(строка): Возвращает последний графемный символ из utf8 строки, nil если строка пуста.
length(строка): Возвращает количество Unicode графем в utf8 строке.
match?(строка, регулярное_выражение): Проверяет, соответствует ли string заданному регулярному выражению.
myers_difference(str1, str2): Возвращает список ключевых слов, представляющий сценарий редактирования.
next_codepoint(строка): Возвращает следующую кодовую точку в строке.
next_grapheme(бинарный): Возвращает следующую графему в строке.
next_grapheme_size(строка): Возвращает размер следующей графемы.
normalize(строка, форма): Преобразует все символы в string в форму Unicode нормализации, определенную form.
pad_leading(строка, количество, заполнение \\ [" "]): Возвращает новую строку, дополненную ведущим заполнителем, состоящим из элементов из padding.
pad_trailing(строка, количество, заполнение \\ [" "]): Возвращает новую строку, дополненную заключительным заполнителем, состоящим из элементов из padding.
printable?(строка): Проверяет, содержит ли строка только печатные символы.
replace(объект, шаблон, замена, параметры \\ []): Возвращает новую строку, созданную путем замены вхождений pattern в subject на replacement.
replace_leading(строка, совпадение, замена): Заменяет все ведущие вхождения match на replacement от match в string.
replace_prefix(строка, совпадение, замена): Заменяет префикс в string на replacement если он соответствует match.
replace_suffix(строка, совпадение, замена): Заменяет суффикс в string на replacement если он соответствует match.
replace_trailing(строка, совпадение, замена): Заменяет все заключительные вхождения match на replacement в string.
reverse(строка): Инвертирует графемы в заданной строке.
slice(строка, диапазон): Возвращает подстроку от смещения, заданного началом диапазона, до смещения, заданного концом диапазона.
slice(строка, начало, длина): Возвращает подстроку, начинающуюся со смещения start, и длиной len.
split(бинарный): Делит строку на подстроки на каждом Unicode пробеле, с игнорированием ведущих и заключительных пробелов. Группы пробелов обрабатываются как одно вхождение. Разделение не происходит на неразрывных пробелах.
split(строка, шаблон, параметры \\ []): Разбивает строку на подстроки, основываясь на шаблоне.
split_at(строка, позиция): Разбивает строку на две части в указанной позиции. При отрицательной позиции, позиция вычисляется от конца строки.
splitter(строка, шаблон, параметры \\ []): Возвращает перечислимый объект, который разбивает строку по требованию.
starts_with?(строка, префикс): Возвращает true если string начинается с любого из указанных префиксов.
to_atom(строка): Преобразует строку в атом.
to_charlist(строка): Преобразует строку в список символов.
to_existing_atom(строка): Преобразует строку в существующий атом.
to_float(строка): Возвращает число с плавающей точкой, текстовое представление которого string.
to_integer(строка): Возвращает целое число, текстовое представление которого string.
to_integer(строка, основание): Возвращает целое число, текстовое представление которого string в основании base.
trim(строка): Возвращает строку, из которой удалены все ведущие и заключительные Unicode пробелы.
trim(строка, обрезать): Возвращает строку, из которой удалены все ведущие и заключительные to_trim.
trim_leading(строка): Возвращает строку, из которой удалены все ведущие Unicode пробелы.
trim_leading(строка, обрезать): Возвращает строку, из которой удалены все ведущие to_trim.
trim_trailing(строка): Возвращает строку, из которой удалены все заключительные Unicode пробелы.
trim_trailing(строка, обрезать): Возвращает строку, из которой удалены все заключительные to_trim.
upcase(бинарный): Преобразует все символы в заданной строке в верхний регистр.
valid?(строка): Проверяет, содержит ли string только допустимые символы.

Типы

codepoint()

codepoint() :: t

grapheme()

grapheme() :: t

pattern()

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

t()

t() :: binary

Функции

at(строка, позиция)

at(t, integer) :: grapheme | nil

Возвращает графемное представление в позиции position заданного utf8 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)

capitalize(t) :: t

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

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

Примеры

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, 0x0FFFF::utf8>>, :valid)
["abc\0", <<0x0FFFF::utf8>>]

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

downcase(binary)

downcase(t) :: t

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

Примеры

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

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

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

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

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

Примеры

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

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

graphemes(string)

graphemes(t) :: [grapheme]

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

Алгоритм описан в приложении Unicode Standard Annex #29, сегментация текстов Unicode.

Подробнее о кодпоинтах и графемах см. документацию модуля 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

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

Примеры

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

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

length(string)

length(t) :: non_neg_integer

Возвращает количество графем Unicode в utf8-строке.

Примеры

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(str1, str2)

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

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

Алгоритм описан в статье «An O(ND) Difference Algorithm and Its Variations» Э. Майерса.

Примеры

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 в форму нормализации Unicode, определенную 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.

Когда 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)

printable?(t) :: boolean

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

Примеры

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

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

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

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

По умолчанию заменяются все вхождения, если опция global установлена в false, то будет заменено только первое.

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

Примеры

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"

Обратите внимание, что нам пришлось экранировать символ экранирования \. Используя \0, можно вставить весь совпавший шаблон в строку замены. Если шаблон — строка, разработчик может использовать заменённую часть внутри replacement с помощью опции :insert_replace и указанием позиции(й) внутри 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” Если любая позиция, указанная в опции :insert_replace, больше длины строки замены или отрицательна, возникает ArgumentError.

replace_leading(string, match, replacement)

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

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

Примеры

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)

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

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

Примеры

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"

replace_suffix(string, match, replacement)

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

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

Примеры

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"

replace_trailing(string, match, replacement)

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

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

Примеры

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) :: [t]

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

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

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

Пустые строки удаляются из результата только если опция trim установлена в true (значение по умолчанию — false).

Примеры

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

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{})
["a", "b", "c", ""]

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

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

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

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

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

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.t) :: Enumerable.t

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

В отличие от split/3, который разбивает всю строку сразу.

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

Опции

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

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

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

В настоящее время Elixir не поддерживает преобразование строк, содержащих символы Юникода больше 0xFF.

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

Примеры

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

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

В настоящее время Elixir не поддерживает преобразование строк, содержащих символы Юникода больше 0xFF.

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

Примеры

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, иначе будет выброшено исключение «аргумент некорректен».

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

Примеры

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

iex> String.to_float("3.0")
3.0

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(binary)

upcase(t) :: t

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

Примеры

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

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

iex> String.upcase("olá")
"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?("asd" <> <<0xFFFF :: 16>>)
false