Строка

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

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

Функции в этом модуле работают в соответствии со стандартом Юникод версии 9.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 реализует алгоритм расширенного кластера графем.

Строковые и двоичные операции

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

Например, 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): Преобразует первый символ в заданной строке в верхний регистр, а остальные — в нижний.
chunk(string, trait): Разбивает строку на части символов, которые имеют общий признак.
codepoints(string): Возвращает все коды символов в строке.
contains?(string, contents): Проверяет, содержит ли string какой-либо из заданных contents.
downcase(binary): Преобразует все символы в заданной строке в нижний регистр.
duplicate(subject, n): Возвращает строку subject продублированную n раз.
ends_with?(string, suffixes): Возвращает true, если string оканчивается на любой из заданных суффиксов.
equivalent?(string1, string2): Возвращает true, если string1 канонически эквивалентно ‘string2’.
first(string): Возвращает первый графемный символ из UTF-8 строки, nil если строка пустая.
graphemes(string): Возвращает Unicode графемы в строке в соответствии с алгоритмом расширенного графемного кластера.
jaro_distance(string1, string2): Возвращает значение с плавающей точкой от 0 (не имеет сходства) до 1 (полное совпадение), представляющее расстояние Яро между string1 и string2.
last(string): Возвращает последний графемный символ из UTF-8 строки, nil если строка пустая.
length(string): Возвращает количество Unicode графем в строке UTF-8.
match?(string, regex): Проверяет, соответствует ли string заданному регулярному выражению.
myers_difference(string1, string2): Возвращает список ключевых слов, представляющий сценарий редактирования.
next_codepoint(string): Возвращает следующий код символа в строке.
next_grapheme(binary): Возвращает следующую графему в строке.
next_grapheme_size(string): Возвращает размер следующей графемы.
normalize(string, form): Преобразует все символы в string в форму нормализации Unicode, идентифицированную form.
pad_leading(string, count, padding \\ [" "]): Возвращает новую строку, дополненную ведущим заполнителем, составленным из элементов padding.
pad_trailing(string, count, padding \\ [" "]): Возвращает новую строку, дополненную заключительным заполнителем, составленным из элементов padding.
printable?(string): Проверяет, содержит ли строка только печатные символы.
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): Разделяет строку на подстроки в каждом случае Unicode пробела, игнорируя пробелы в начале и конце. Группы пробелов обрабатываются как одно вхождение. Разделения не происходят на неразрывных пробелах.
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): Возвращает строку, из которой удалены все ведущие и заключительные Unicode пробелы.
trim(string, to_trim): Возвращает строку, из которой удалены все ведущие и заключительные to_trim.
trim_leading(string): Возвращает строку, из которой удалены все ведущие Unicode пробелы.
trim_leading(string, to_trim): Возвращает строку, из которой удалены все ведущие to_trim.
trim_trailing(string): Возвращает строку, из которой удалены все заключительные Unicode пробелы.
trim_trailing(string, to_trim): Возвращает строку, из которой удалены все заключительные to_trim.
upcase(binary): Преобразует все символы в заданной строке в верхний регистр.
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)

capitalize(t()) :: t()

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

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

Примеры

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

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

Примеры

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

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

graphemes(string)

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

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

Алгоритм описан в Приложении к стандарту Юникод № 29, сегментация текста Юникода.

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

Если 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"

Обратите внимание, что нам нужно экранировать обратную косую черту (т.е., мы использовали \\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"

Если какая-либо позиция, указанная в опции :insert_replaced, больше, чем длина строки замены, или является отрицательной, возникает ошибка ArgumentError.

replace_leading(string, match, replacement)

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

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

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

Если 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 в конце строки string на replacement.

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

Если 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()) :: [t()]

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

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

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

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

Когда используемый шаблон является регулярным выражением, строка разделяется с помощью Regex.split/3. В этом случае эта функция принимает дополнительные параметры, которые документированы в Regex.split/3.

Примеры

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

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", ~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, не выдавать пустые шаблоны

Примеры

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

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

В настоящее время 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, иначе будет вызвано исключение ArgumentError.

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

Примеры

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