@spec 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

@spec 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

@spec byte_slice(t(), integer(), non_neg_integer()) :: t()

Возвращает подстроку, начиная с (или после) start_bytes и с максимальным заданным size_bytes.

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

Если смещение больше количества байтов в строке, то возвращает "". Подобно String.slice/2, отрицательное start_bytes будет скорректировано до конца строки (но в байтах).

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

Примеры

Рассмотрим строку "héllo". Посмотрим ее представление:

iex> inspect("héllo", binaries: :as_binaries)
"<<104, 195, 169, 108, 108, 111>>"

Хотя строка имеет 5 символов, она состоит из 6 байтов. Теперь представьте, что мы хотим получить только первые два байта. Для этого давайте воспользуемся binary_slice/3, который не учитывает кодовые точки:

iex> binary_slice("héllo", 0, 2)
<<104, 195>>

Как вы можете видеть, эта операция небезопасна и возвращает недопустимую строку. Это потому, что мы разрезали строку посредине байтов, представляющих "é". С другой стороны, мы могли бы использовать String.slice/3:

iex> String.slice("héllo", 0, 2)
"hé"

Хотя приведенное выше правильно, оно содержит 3 байта. Если у вас есть требование, где вам нужен максимум 2 байта, результат также будет недопустимым. В таких сценариях вы можете использовать эту функцию, которая выполнит срез заданных байтов, но очистит усеченные кодовые точки:

iex> String.byte_slice("héllo", 0, 2)
"h"

Усеченные кодовые точки в начале также очищаются:

iex> String.byte_slice("héllo", 2, 3)
"llo"

Обратите внимание, что если вы хотите работать с исходными байтами, то вы должны использовать binary_slice/3 вместо этого.

@spec capitalize(t(), :default | :ascii | :greek | :turkic) :: t()

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

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

См. также upcase/2 и capitalize/2 для других преобразований. Если вам нужна вариация этой функции, которая не приводит остальную часть строки в нижний регистр, см. Erlang :string.titlecase/1.

Примеры

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

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

@spec 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>>]

@spec codepoints(t()) :: [codepoint()]

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

Чтобы получить кодовые точки в их естественном целочисленном представлении, см. to_charlist/1. Подробности о кодовых точках и графемах см. в документации модуля String.

Примеры

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

iex> String.codepoints("оптими зации")
["о", "п", "т", "и", "м", "и", " ", "з", "а", "ц", "и", "и"]

iex> String.codepoints("ἅἪῼ")
["ἅ", "Ἢ", "ῼ"]

iex> String.codepoints("\u00e9")
["é"]

iex> String.codepoints("\u0065\u0301")
["e", "́"]

@spec contains?(t(), [t()] | pattern()) :: boolean()

Ищет, содержит ли string какой-либо из заданных contents.

contents может быть строкой, списком строк или скомпилированным шаблоном. Если contents является списком, эта функция будет искать, является ли какая-либо из строк в contents частью string.

Примеры

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

Пустой список никогда не будет соответствовать:

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

iex> String.contains?("", [])
false

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

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

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

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

@spec downcase(t(), :default | :ascii | :greek | :turkic) :: t()

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

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

См. также upcase/2 и capitalize/2 для других преобразований.

Примеры

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)
"σς"

И :turkic правильно обрабатывает букву i с вариантом без точки:

iex> String.downcase("Iİ")
"ii̇"

iex> String.downcase("Iİ", :turkic)
"ıi"

@spec 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"

@spec 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

@spec 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

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

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

Примеры

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

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

iex> String.first("")
nil

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

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

Алгоритм описан в Unicode Standard Annex #29, Unicode Text Segmentation.

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

Примеры

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

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

iex> String.graphemes("\u0065\u0301")
["é"]

@spec 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

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

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

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

Примеры

iex> String.last("")
nil

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

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

@spec length(t()) :: non_neg_integer()

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

Примеры

iex> String.length("elixir")
6

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

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

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

Примеры

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

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

Elixir также предоставляет текстовый оператор соответствия =~/2 и функцию Regex.match?/2 в качестве альтернатив для проверки строк на соответствие регулярным выражениям.

@spec 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"]

@spec 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.

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

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

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

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

Примеры

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

iex> String.next_grapheme("")
nil

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

Возвращает размер (в байтах) следующей графемы.

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

Примеры

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

iex> String.next_grapheme_size("")
nil

@spec normalize(t(), :nfd | :nfc | :nfkd | :nfkc) :: t()

Преобразует все символы в string в форму Unicode нормализации, определенную form.

Некорректные коды Unicode пропускаются, а оставшаяся часть строки преобразуется. Если вы хотите, чтобы алгоритм останавливался и возвращался при некорректном коде, используйте :unicode.characters_to_nfd_binary/1, :unicode.characters_to_nfc_binary/1, :unicode.characters_to_nfkd_binary/1 и :unicode.characters_to_nfkc_binary/1 вместо этого.

Формы нормализации :nfkc и :nfkd не следует слепо применять к произвольному тексту. Поскольку они удаляют многие различия в форматировании, они помешают обратной конвертации из и в многие устаревшие наборы символов.

Формы

Поддерживаемые формы:

• :nfd - Нормальная форма канонического разложения. Символы разлагаются по каноническому соответствию, а несколько комбинирующих символов упорядочиваются в определенном порядке.

• :nfc - Нормальная форма канонического объединения. Символы разлагаются и затем объединяются по каноническому соответствию.

• :nfkd - Нормальная форма совместимого разложения. Символы разлагаются по совместимости, а несколько комбинирующих символов упорядочиваются в определенном порядке.

• :nfkc - Нормальная форма совместимого объединения. Символы разлагаются и затем объединяются по совместимости.

Примеры

iex> String.normalize("yêṩ", :nfd)
"yêṩ"

iex> String.normalize("leña", :nfc)
"leña"

iex> String.normalize("fi", :nfkd)
"fi"

iex> String.normalize("fi", :nfkc)
"fi"

@spec 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"

@spec pad_trailing(t(), non_neg_integer(), t() | [t()]) :: t()

Возвращает новую строку, заполненную завершающим заполнителем, который состоит из элементов из padding.

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

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

@spec 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

@spec replace(t(), pattern() | Regex.t(), t() | (t() -> t() | iodata()), keyword()) ::
  t()

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

subject всегда является строкой.

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

replacement может быть строкой или функцией, которая получает совпавший шаблон и должна возвращать замену как строку или iodata.

По умолчанию заменяет все вхождения, но это поведение можно контролировать с помощью опции :global; см. раздел «Опции» ниже.

Опции

• :global - (boolean) если true, все вхождения pattern заменяются на replacement, в противном случае заменяется только первое вхождение. По умолчанию true

Примеры

iex> String.replace("a,b,c", ",", "-")
"a-b-c"

iex> String.replace("a,b,c", ",", "-", global: false)
"a-b,c"

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

iex> String.replace("a,b,c", ["a", "c"], fn <<char>> -> <<char + 1>> end)
"b,b,d"

Если шаблон — регулярное выражение, в строке \N или \g{N} можно указать доступ к определенному захвату в регулярном выражении:

iex> String.replace("a,b,c", ~r/,(.)/, ",\\1\\g{1}")
"a,bb,cc"

Обратите внимание, что нам пришлось экранировать символ обратного слэша (т. е. мы использовали \\N вместо просто \N для экранирования обратного слэша; то же самое для \\g{N}). Указав \0, можно вставить весь шаблон в строку замены.

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

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

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

Если в качестве replacement задана пустая строка, будет возвращена subject.

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

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

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

iex> String.replace(String.normalize("é", :nfd), "e", "o")
"ó"

Однако, если "é" представлен единственным символом "e с острым" ударением, он не будет заменен вообще:

iex> String.replace(String.normalize("é", :nfc), "e", "o")
"é"

@spec replace_invalid(binary(), t()) :: t()

Возвращает новую строку, созданную путем замены всех неверных байтов на replacement (по умолчанию "�").

Примеры

iex> String.replace_invalid("asd" <> <<0xFF::8>>)
"asd�"

iex> String.replace_invalid("nem rán bề bề")
"nem rán bề bề"

iex> String.replace_invalid("nem rán b" <> <<225, 187>> <> " bề")
"nem rán b� bề"

iex> String.replace_invalid("nem rán b" <> <<225, 187>> <> " bề", "ERROR!")
"nem rán bERROR! bề"

@spec 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/3 для получения дополнительной информации и примеров.

@spec 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/3 для получения дополнительной информации и примеров.

@spec 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/3 для получения дополнительной информации и примеров.

@spec 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"

Эта функция может производить замену через границу графем. См. replace/3 для получения дополнительной информации и примеров.

@spec 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")
"è"
iex> String.reverse(String.reverse("̀e"))
"è"

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

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

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

Эта функция работает с графемами Юникода. Например, взятие первых трёх символов строки "héllo" вернёт "hél", что интерпретируется как больше трёх байт. Используйте String.byte_slice/3, если вы хотите производить срез по заданному числу байтов, сохраняя при этом границы кодовых точек. Если вы хотите работать с сырыми байтами, обратитесь к Kernel.binary_part/3 или Kernel.binary_slice/3.

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

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

Примеры

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

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

Для диапазонов, где start > stop, необходимо явно указать возрастание:

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

Вы можете использовать ../0 в качестве сокращения для 0..-1//1, которое возвращает всю строку как есть:

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

Шаг может быть любым положительным числом. Например, чтобы получить каждый 2 символ строки:

iex> String.slice("elixir", 0..-1//2)
"eii"

Если первая позиция находится после конца строки или после последней позиции диапазона, возвращается пустая строка:

iex> String.slice("elixir", 10..3//1)
""
iex> String.slice("a", 1..1500)
""

@spec slice(t(), integer(), non_neg_integer()) :: grapheme()

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

Эта функция работает с графемами Юникода. Например, взятие первых трёх символов строки "héllo" вернёт "hél", что интерпретируется как больше трёх байт. Используйте String.byte_slice/3, если вы хотите производить срез по заданному числу байтов, сохраняя при этом границы кодовых точек. Если вы хотите работать с сырыми байтами, обратитесь к Kernel.binary_part/3 или Kernel.binary_slice/3.

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

Примеры

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

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

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

Если начальная позиция отрицательна, она нормализуется относительно длины строки и ограничена 0:

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

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

Если начальная позиция больше длины строки, возвращается пустая строка:

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

@spec 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"]

Удаляет пустые строки, как при использовании trim: true в String.split/3.

iex> String.split(" ")
[]

@spec split(t(), pattern() | Regex.t(), keyword()) :: [t()]

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

Возвращает список этих частей.

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

Строка разделяется на как можно больше частей по умолчанию, но это может быть контролироваться параметром :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"]

Разделение на несуществующий шаблон возвращает исходную строку:

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

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

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

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

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

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

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

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

Примеры

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

@spec 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"]

@spec 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

Пустой список никогда не будет соответствовать:

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

iex> String.starts_with?("", [])
false

@spec to_atom(t()) :: atom()

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

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

По умолчанию максимальное количество атомов составляет 1_048_576. Этот предел можно увеличить или уменьшить с помощью параметра VM +t.

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

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

Примеры

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

@spec to_charlist(t()) :: charlist()

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

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

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

Примеры

iex> String.to_charlist("foo")
~c"foo"

@spec to_existing_atom(t()) :: atom()

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

Максимальный размер атома составляет 255 точек кода Юникода. Вызывает исключение ArgumentError, если атом не существует.

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

Примеры

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

@spec to_float(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

String.to_float(".3")
** (ArgumentError) argument error

@spec to_integer(t()) :: integer()

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

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

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

Примеры

iex> String.to_integer("123")
123

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

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

@spec to_integer(t(), 2..36) :: integer()

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

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

Примеры

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

@spec trim(t()) :: t()

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

Примеры

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

@spec trim(t(), t()) :: t()

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

Примеры

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

@spec trim_leading(t()) :: t()

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

Примеры

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

@spec trim_leading(t(), t()) :: t()

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

Примеры

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

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

@spec trim_trailing(t()) :: t()

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

Примеры

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

@spec trim_trailing(t(), t()) :: t()

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

Примеры

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

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

@spec upcase(t(), :default | :ascii | :greek | :turkic) :: t()

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

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

Примеры

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

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

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

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

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

И режим :turkic корректно обрабатывает букву i с вариантом без точки:

iex> String.upcase("ıi")
"II"

iex> String.upcase("ıi", :turkic)
"Iİ"

Также см. downcase/2 и capitalize/2 для других преобразований.

@spec valid?(t(), :default | :fast_ascii) :: boolean()

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

Алгоритм algorithm может быть :default или :fast_ascii. Оба алгоритма эквивалентны с точки зрения валидации (они всегда дают одинаковый результат), но :fast_ascii может обеспечить значительные преимущества производительности в определённых сценариях.

Если все следующие условия выполняются, вы можете попробовать использовать алгоритм :fast_ascii для повышения производительности в вашем конкретном сценарии:

• Вы используете Erlang/OTP 26 или более позднюю версию на 64-битной платформе
• Вы ожидаете, что большинство ваших строк будут длиннее ~64 байт
• Вы ожидаете, что большинство ваших строк будут содержать в основном символы ASCII

Обратите внимание, что алгоритм :fast_ascii не влияет на корректность, вы можете ожидать, что результат функции String.valid?/2 будет одинаковым независимо от алгоритма. Единственное ожидаемое различие — это производительность, которая, как ожидается, будет приблизительно линейно увеличиваться с длиной строки по сравнению с алгоритмом :default.

Примеры

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

iex> String.valid?("a", :fast_ascii)
true

iex> String.valid?(4)
** (FunctionClauseError) no function clause matching in String.valid?/2