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

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

Примеры

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

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

@spec chunk(t(), :valid | :printable) :: [t()]

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

Свойство может быть одним из двух:

• :valid — строка разделяется на блоки допустимых и недопустимых последовательностей символов

• :printable — строка разделяется на блоки печатаемых и непечатаемых последовательностей символов

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

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

Примеры

iex> String.chunk(<<?a, ?b, ?c, 0>>, :valid)
["abc\0"]

iex> String.chunk(<<?a, ?b, ?c, 0, 0xFFFF::utf16>>, :valid)
["abc\0", <<0xFFFF::utf16>>]

iex> String.chunk(<<?a, ?b, ?c, 0, 0x0FFFF::utf8>>, :printable)
["abc", <<0, 0x0FFFF::utf8>>]

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

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

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

Примеры

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

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

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

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

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

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

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

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

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

Если нужно проверить, находится ли string в списке contents, где contents — список, используйте Enum.member?(contents, string).

Примеры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

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

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

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

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

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

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

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

Формы

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

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

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

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

• :nfkc - Форма нормализации объединения совместимости. Символы разлагаются, а затем объединяются по эквиваленту совместимости.

Примеры

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

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

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

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

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

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

Передача списка строк в качестве padding приведет к взятию одного элемента из списка для каждого недостающего элемента. Если список короче, чем количество вставок, заполнение начнется снова с начала списка. Передача строки padding эквивалентна передаче списка графем в ней. Если padding не задан, он по умолчанию равен пробелам.

Когда count меньше или равно длине string, возвращается string.

Вызывает ArgumentError, если заданный padding содержит элемент, не являющийся строкой.

Примеры

iex> String.pad_leading("abc", 5)
"  abc"

iex> String.pad_leading("abc", 4, "12")
"1abc"

iex> String.pad_leading("abc", 6, "12")
"121abc"

iex> String.pad_leading("abc", 5, ["1", "23"])
"123abc"

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

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

Передача списка строк в качестве padding приведет к взятию одного элемента из списка для каждого недостающего элемента. Если список короче, чем количество вставок, заполнение начнется снова с начала списка. Передача строки padding эквивалентна передаче списка графем в ней. Если padding не задан, он по умолчанию равен пробелам.

Когда count меньше или равно длине string, возвращается string.

Вызывает ArgumentError, если заданный padding содержит элемент, не являющийся строкой.

Примеры

iex> String.pad_trailing("abc", 5)
"abc  "

iex> String.pad_trailing("abc", 4, "12")
"abc1"

iex> String.pad_trailing("abc", 6, "12")
"abc121"

iex> String.pad_trailing("abc", 5, ["1", "23"])
"abc123"

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

@spec printable?(t(), pos_integer() | :infinity) :: boolean()

Проверяет, содержит ли строка только печатаемые символы до character_limit.

Принимает необязательный character_limit в качестве второго аргумента. Если character_limit равен 0, эта функция вернет true.

Примеры

iex> String.printable?("abc")
true

iex> String.printable?("abc" <> <<0>>)
false

iex> String.printable?("abc" <> <<0>>, 2)
true

iex> String.printable?("abc" <> <<0>>, 0)
true

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

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

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

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

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

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

Опции

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

Примеры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

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

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

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

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

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

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

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

Примеры

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

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

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

@spec replace_prefix(t(), t(), t()) :: t()

Заменяет префикс в string на replacement, если он совпадает с match.

Возвращает строку без изменений, если совпадения нет. Если match — пустая строка (""), replacement просто добавляется в начало string.

Примеры

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

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

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

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

@spec replace_suffix(t(), t(), t()) :: t()

Заменяет суффикс в string на replacement, если он совпадает с match.

Возвращает строку без изменений, если совпадения нет. Если match — пустая строка (""), replacement просто добавляется в конец string.

Примеры

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

iex> String.replace_suffix("hello", " world", " mundo")
"hello"
iex> String.replace_suffix("hello world", " world", " mundo")
"hello mundo"
iex> String.replace_suffix("hello world world", " world", " mundo")
"hello world mundo"

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

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

@spec replace_trailing(t(), t(), t()) :: t()

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

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

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

Примеры

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

iex> String.replace_trailing("hello world", " world", " mundo")
"hello mundo"
iex> String.replace_trailing("hello world world", " world", " mundo")
"hello mundo mundo"

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

@spec reverse(t()) :: t()

Инвертирует графемы в заданной строке.

Примеры

iex> String.reverse("abcd")
"dcba"

iex> String.reverse("hello world")
"dlrow olleh"

iex> String.reverse("hello ∂og")
"go∂ olleh"

Обратите внимание, что повторное обращение к той же строке не обязательно приводит к исходной строке:

iex> "̀e"
"̀e"
iex> String.reverse("̀e")
"è"
iex> String.reverse(String.reverse("̀e"))
"è"

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

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

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

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

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

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

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

Примеры

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

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

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