Строка

Строка в 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 реализует алгоритм расширенного графического кластера.

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

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

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

Например, 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. Jaro
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 в форму уникодовой нормализации, определенную 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 в string, если они совпадают с match
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, 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

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, 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"

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

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

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

По умолчанию строка разбивается на как можно больше частей, но это можно контролировать параметром :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", ~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()) :: 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. Этот лимит можно увеличить или уменьшить с помощью параметра VM +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(строка)

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(строка)

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(строка)

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

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

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

Примеры

iex> String.to_integer("123")
123

to_integer(строка, основание)

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

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

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

Примеры

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

trim(строка)

trim(t()) :: t()

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

Примеры

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

trim(строка, для_удаления)

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

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

Примеры

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

trim_leading(строка)

trim_leading(t()) :: t()

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

Примеры

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

trim_leading(строка, для_удаления)

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

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

Примеры

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

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

trim_trailing(строка)

trim_trailing(t()) :: t()

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

Примеры

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

trim_trailing(строка, для_удаления)

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

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

Примеры

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

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

upcase(бинарный)

upcase(t()) :: t()

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

Примеры

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

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

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

valid?(строка)

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