Строка

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

Кодепоинты и графические кластеры

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

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

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

iex> byte_size("é")
2

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

iex> String.length("é")
1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

iex> ?o
111

iex> ?á
225

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

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

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

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

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

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

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

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

Шаблоны

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

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

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

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

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

Обзор

Типы

codepoint(): Кодепоинт UTF-8. Может занимать один или несколько байт
grapheme(): Несколько кодепоинтов, которые могут восприниматься читателем как один символ
pattern(): Шаблон, используемый в функциях, таких как replace/3 и split/2
t(): Двоичная строка, закодированная в UTF-8

Функции

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

Типы

codepoint()

codepoint() :: t()

Кодовая точка UTF-8. Она может занимать один или несколько байтов.

grapheme()

grapheme() :: t()

Несколько кодовых точек, которые могут восприниматься читателями как один символ

pattern()

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

Шаблон, используемый в функциях, таких как replace/3 и split/2

t()

t() :: binary()

Бинарный файл в кодировке UTF-8.

Обратите внимание, что String.t() и binary() эквивалентны для инструментов анализа. Хотя для тех, кто читает документацию, String.t() подразумевает, что это бинарный файл в кодировке UTF-8.

Функции

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

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(строка, режим \\ :default)

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

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

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

Примеры

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

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

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

chunk(строка, признак)

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

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?(строка, содержимое)

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> pattern = :binary.compile_pattern(["life", "death"])
iex> String.contains?("elixir of life", pattern)
true

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

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

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

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

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

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

downcase(строка, режим \\ :default)

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

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

Примеры

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

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

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

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

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

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

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

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

duplicate(объект, 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?(строка, суффикс)

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

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

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

Выполняет нормализацию в форме канонического разложения (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(строка)

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

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

Примеры

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

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

graphemes(строка)

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

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

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

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

Примеры

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

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

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

jaro_distance(строка1, строка2)

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
iex> String.jaro_distance("same", "same")
1.0

last(строка)

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

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

Примеры

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

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

length(строка)

length(t()) :: non_neg_integer()

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

Примеры

iex> String.length("elixir")
6

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

match?(строка, регулярное_выражение)

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

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

Примеры

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

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

myers_difference(строка1, строка2)

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

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

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

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

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

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

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

Примеры

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

next_grapheme(бинарный)

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

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

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

Примеры

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

next_grapheme_size(строка)

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

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

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

Примеры

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

normalize(строка, форма)

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, character_limit \\ :infinity)

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

printable?(t(), 0) :: true

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

Принимает необязательный character_limit в качестве второго аргумента. Если character_limit равно 0, эта функция вернёт true.

Примеры

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

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

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

iex> String.printable?("abc" <> <<0>>, 0)
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"

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

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

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

Если пустая строка передана как replacement, то вернётся subject:

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

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

replace_leading(string, match, replacement)

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

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

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

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

Примеры

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

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

replace_prefix(string, match, replacement)

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

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

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

Примеры

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

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

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

replace_suffix(string, match, replacement)

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

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

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

Примеры

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

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

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

replace_trailing(string, match, replacement)

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

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

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

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

Примеры

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

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

reverse(string)

reverse(t()) :: t()

Инвертирует графемы в данной строке.

Примеры

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

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

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

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

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

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

slice(string, range)

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

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

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

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

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

Примеры

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

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

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

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

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

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

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

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

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

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

slice(string, start, len)

slice(t(), integer(), non_neg_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 (логическое значение) — если 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> pattern = :binary.compile_pattern([" ", ","])
iex> String.split("1,2 3,4", pattern)
["1", "2", "3", "4"]

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

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

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

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

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

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

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

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

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

split_at(string, position)

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

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

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

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

Примеры

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

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

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

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

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

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

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

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

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

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

Параметры

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

Примеры

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

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

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

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

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

starts_with?(string, prefix)

starts_with?(t(), pattern()) :: 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> pattern = :binary.compile_pattern(["erlang", "elixir"])
iex> String.starts_with?("elixir", pattern)
true

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

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

to_atom(string)

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

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

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

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

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

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

Примеры

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

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

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

Примеры

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

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

to_float(string)

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

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

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

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

Примеры

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

iex> String.to_float("3.0")
3.0

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

to_integer(string)

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

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

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

Примеры

iex> String.to_integer("123")
123

to_integer(string, base)

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

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

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

Примеры

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

trim(string)

trim(t()) :: t()

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

Примеры

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

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

Примеры

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

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

Примеры

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

trim_trailing(string, to_trim)

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

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

Примеры

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

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

upcase(string, mode \\ :default)

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

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

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

Примеры

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

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

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

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

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

valid?(string)

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

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

Примеры

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

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

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

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

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