@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 учитывает все неявные преобразования, описанные в стандарте Юникод. Режим :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(), [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 учитывает все неявные преобразования, описанные в стандарте Юникод. Режим :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 игнорирует символы Юникода и обеспечивает более высокую производительность, когда вы знаете, что строка содержит только символы 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 #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 также предоставляет текстовый оператор соответствия =~/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"

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

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

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

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

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

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

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

Если 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()

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

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

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

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

Примеры

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)
""
iex> String.slice("a", 1..1500)
""

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

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

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

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

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

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

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

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

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

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

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

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

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

Поскольку Elixir — это компилируемый язык, атомы, определенные в модуле, будут существовать только после загрузки указанного модуля, что обычно происходит всякий раз, когда выполняется функция в модуле. Поэтому рекомендуется вызывать String.to_existing_atom/1 только для преобразования атомов, определенных в модуле, вызывающем функцию to_existing_atom/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()

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

Примеры

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