String

@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(), [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 с вариантом без точки.

Примеры

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

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

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

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

iex> String.downcase("OLÁ", :ascii)
"olÁ"

Режим :greek корректно обрабатывает контекстно-зависимую сигму в греческом языке:

iex> String.downcase("ΣΣ")
"σσ"

iex> String.downcase("ΣΣ", :greek)
"σς"

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

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

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

@spec duplicate(t(), non_neg_integer()) :: t()

Возвращает строку subject повторенную n раз.

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

Примеры

iex> String.duplicate("abc", 0)
""

iex> String.duplicate("abc", 1)
"abc"

iex> String.duplicate("abc", 2)
"abcabc"

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

Возвращает true, если string оканчивается на любой из заданных суффиксов.

suffixes может быть одним суффиксом или списком суффиксов.

Примеры

iex> String.ends_with?("language", "age")
true
iex> String.ends_with?("language", ["youth", "age"])
true
iex> String.ends_with?("language", ["youth", "elixir"])
false

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

iex> String.ends_with?("language", "")
true
iex> String.ends_with?("language", ["", "other"])
true

@spec equivalent?(t(), t()) :: boolean()

Возвращает true, если string1 канонически эквивалентно string2.

Выполняет нормализацию в форме канонического разложения (NFD) для строк перед сравнением. Эта функция эквивалентна:

String.normalize(string1, :nfd) == String.normalize(string2, :nfd)

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

Примеры

iex> String.equivalent?("abc", "abc")
true

iex> String.equivalent?("man\u0303ana", "mañana")
true

iex> String.equivalent?("abc", "ABC")
false

iex> String.equivalent?("nø", "nó")
false

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

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

Примеры

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

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

iex> String.first("")
nil

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

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

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

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

Примеры

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

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

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

@spec jaro_distance(t(), t()) :: float()

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

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

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

Примеры

iex> String.jaro_distance("Dwayne", "Duane")
0.8222222222222223
iex> String.jaro_distance("even", "odd")
0.0
iex> String.jaro_distance("same", "same")
1.0

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

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

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

Примеры

iex> String.last("")
nil

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

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

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

Возвращает количество символов Юникода в строке 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 - Нормальная форма канонического объединения. Символы разлагаются, а затем объединяются по каноническому эквиваленту.

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

• :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 в 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()

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

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

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

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

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

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

Шаблон 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"]

Обратите внимание, что эта функция может разделять внутри или через границы графем. Например, возьмём графему "é", которая состоит из символов "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 учитывает все неявные преобразования, описанные в стандарте 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İ"

Проверяет, содержит ли 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