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

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

Алгоритм описан в статье "Сопоставление строк с метрическими деревьями, использующими приближенное расстояние" авторов Иларии Бартолини, Паоло Чиаччи и Марко Пателла.

Примеры

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 capitalize(t(), :default | :ascii | :greek | :turkic) :: t()

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

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

Примеры

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(), pattern()) :: boolean()

Проверяет, содержит ли string любой из заданных contents.

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

Примеры

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

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

iex> pattern = :binary.compile_pattern(["life", "death"])
iex> String.contains?("elixir of life", pattern)
true

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

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

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

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

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

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

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

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

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

Примеры

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.

Для получения подробностей о кодовых точках и графемах, см. документацию модуля 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 также предоставляет Kernel.=~/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

Преобразует все символы в 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"

@spec replace_leading(t(), t(), t()) :: t()

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

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

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

Примеры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Делит строку на части на основе шаблона.

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

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

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

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

@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("æß")
'æß'

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

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

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

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

Примеры

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 учитывает все неявные преобразования, описанные в стандарте 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İ"

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