Строка

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

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

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

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

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

iex> byte_size("é")
2

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

iex> String.length("é")
1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Хотя это значительно лучше (мы не проходим по full дважды), можно улучшить. В данном случае, так как мы хотим извлечь подстроку из строки, мы можем использовать 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.
bag_distance(string1, string2): Вычисляет расстояние Бэга между двумя строками.
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): Возвращает Unicode графемы в строке в соответствии с алгоритмом Расширенного графемного кластера.
jaro_distance(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, 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): Разбивает строку на подстроки в каждой позиции 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(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

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

(с версии 1.8.0)

bag_distance(t(), t()) :: float()

Вычисляет расстояние мешка между двумя строками.

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

Расстояние мешка предназначено для эффективного приближения расстояния между двумя строками, чтобы быстро исключить строки, которые сильно различаются.

Алгоритм описан в статье «String Matching with Metric Trees Using an Approximate Distance» авторов Иларии Бартолини, Паоло Чиаччи и Марко Пателла.

Примеры

iex> String.bag_distance("abc", "")
0.0
iex> String.bag_distance("abcd", "a")
0.25
iex> String.bag_distance("abcd", "ab")
0.5
iex> String.bag_distance("abcd", "abc")
0.75
iex> String.bag_distance("abcd", "abcd")
1.0

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

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

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

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

Примеры

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

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

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

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

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?(:unicode.characters_to_nfd_binary("é"), "e")
true

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

iex> String.contains?(:unicode.characters_to_nfc_binary("é"), "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 игнорирует символы Юникода и обеспечивает более высокую производительность, когда известно, что строка содержит только символы 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 Standard Annex #29, Unicode Text Segmentation.

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

Примеры

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

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

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

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

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

Вычисляет расстояние Яро (подобие) между двумя строками.

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

Метрика расстояния Яро предназначена и лучше всего подходит для коротких строк, таких как имена людей. Сам Elixir использует эту функцию для предоставления функциональности «вы имели в виду?». Например, когда вы вызываете функцию в модуле, и у вас есть опечатка в имени функции, мы пытаемся предложить наиболее похожую доступную функцию, если таковая имеется, на основе оценки jaro_distance/2.

Примеры

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

Возвращает количество графем Юникода в 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, next_codepoint/1 работает с бинарными данными, которые не являются валидным UTF-8. Если строка начинается с последовательности байтов, которая не является валидной в кодировке UTF-8, первый элемент возвращаемого кортежа — бинарные данные с первым байтом.

Примеры

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

iex> invalid = "\x80\x80OK" # first two bytes are invalid in UTF-8
iex> {_, rest} = String.next_codepoint(invalid)
{<<128>>, <<128, 79, 75>>}
iex> String.next_codepoint(rest)
{<<128>>, "OK"}

Сравнение с бинарным сопоставлением шаблонов

Бинарное сопоставление шаблонов предоставляет аналогичный способ разложения строки:

iex> <<codepoint::utf8, rest::binary>> = "Elixir"
"Elixir"
iex> codepoint
69
iex> rest
"lixir"

хотя не совсем эквивалентно, потому что codepoint приходит как целое число, а шаблон не будет соответствовать недействительному UTF-8.

Однако бинарный поиск шаблонов проще и эффективнее, поэтому выберите вариант, который лучше подходит для вашего случая.

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)

Данная функция устарела. Используйте :unicode.characters_to_nfc_binary/1 или :unicode.characters_to_nfd_binary/1 вместо неё.

Преобразует все символы в 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, character_limit \\ :infinity)

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

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

Проверяет, содержит ли строка только печатные символы до 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()

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

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

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

Примеры

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

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

replace_prefix(string, match, replacement)

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

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

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

Примеры

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

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

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

replace_suffix(string, match, replacement)

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

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

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

Примеры

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

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

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

replace_trailing(string, match, replacement)

replace_trailing(t(), t(), t()) :: t()

Заменяет все заключительные вхождения 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.

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

Обратите внимание, что эта функция работает с графемами Юникода и считает срезы как смещения графем. Если вы хотите разбить по байтам, обратитесь к 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, 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" и острой ударения. Следующее разделит строку на две части:

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

Однако, если "é" представляется одним символом "e с острым ударением", то это разделит строку только на одну часть:

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, которая разделяет всю строку сразу.

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

Параметры

: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 . Этот предел можно увеличить или уменьшить с помощью параметра VM +t.

Максимальный размер атома составляет 255 кодовых точек Юникода.

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

Примеры

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

to_charlist(string)

to_charlist(t()) :: charlist()

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

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

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

Примеры

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

to_existing_atom(string)

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

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

Максимальный размер атома составляет 255 кодовых точек Юникода.

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

Примеры

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.

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

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

Примеры

iex> String.to_integer("123")
123

Передача строки, которая не представляет целое число, приводит к ошибке:

String.to_integer("invalid data")
#=> ** (ArgumentError) argument error

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

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