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

Поиск строки в списке

Если вы хотите проверить, содержится ли string в списке contents, где contents — список, используйте Enum.member?(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()]

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

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

Подробные сведения о кодовых точках и графемах см. в документации модуля 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()

Возвращает количество графем Юникода в 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 в форму нормализации Юникода, идентифицируемую form.

Недействительные кодовые точки Юникода пропускаются, и оставшаяся часть строки преобразуется. Если вы хотите, чтобы алгоритм останавливался и возвращался при обнаружении недопустимой кодовой точки, используйте :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} в строке replacement для доступа к определённому захвату в регулярном выражении:

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

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

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

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

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

@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. Этот предел может быть повышен или понижен с помощью опции виртуальной машины +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, если атом не существует.

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

Атомы и модули

Поскольку Elixir — компилируемый язык, атомы, определенные в модуле, существуют только после загрузки данного модуля, что обычно происходит при выполнении любой функции в модуле. Поэтому обычно рекомендуется вызывать String.to_existing_atom/1 только для преобразования атомов, определенных в модуле, вызывающем to_existing_atom/1.

Для безопасного создания имени модуля из строки рекомендуется использовать Module.safe_concat/1.

Примеры

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

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

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

Примеры

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

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

Примеры

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

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

Примеры

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 учитывает все неявные преобразования, описанные в стандарте Юникод. Режим :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 игнорирует символы Юникода и обеспечивает более производительную реализацию, когда известно, что строка содержит только символы 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