Returns the grapheme at the position of the given utf8 string. If position is greater than string length, then it returns nil.

Examples

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

Converts the first character in the given string to uppercase and the remainder to lowercase.

This relies on the titlecase information provided by the Unicode Standard. Note this function makes no attempt to capitalize all words in the string (usually known as titlecase).

Examples

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

iex> String.capitalize("fin")
"Fin"

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

Splits the string into chunks of characters that share a common trait.

The trait can be one of two options:

• :valid - the string is split into chunks of valid and invalid character sequences

• :printable - the string is split into chunks of printable and non-printable character sequences

Returns a list of binaries each of which contains only one kind of characters.

If the given string is empty, an empty list is returned.

Examples

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

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

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

Returns all codepoints in the string.

For details about codepoints and graphemes, see the String module documentation.

Examples

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

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

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

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

iex> String.codepoints("é")
["e", "́"]

Checks if string contains any of the given contents.

contents can be either a single string or a list of strings.

Examples

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

The argument can also be a precompiled pattern:

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

Converts all characters in the given string to lowercase.

Examples

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

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

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

Returns a binary subject duplicated n times.

Examples

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

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

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

Returns true if string ends with any of the suffixes given, otherwise returns false. suffixes can be either a single suffix or a list of suffixes.

Examples

iex> String.ends_with? "language", "age"
true

iex> String.ends_with? "language", ["youth", "age"]
true

iex> String.ends_with? "language", ["youth", "elixir"]
false

Returns true if binary is canonically equivalent to ‘another_binary’.

It performs Normalization Form Canonical Decomposition (NFD) on the strings before comparing them. This function is equivalent to:

String.normalize(left, :nfd) == String.normalize(right, :nfd)

Therefore, if you plan to compare multiple strings, multiple times in a row, you may normalize them upfront and compare them directly to avoid multiple normalization passes.

Examples

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

Returns the first grapheme from a utf8 string, nil if the string is empty.

Examples

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

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

Returns Unicode graphemes in the string as per Extended Grapheme Cluster algorithm outlined in the Unicode Standard Annex #29, Unicode Text Segmentation.

For details about codepoints and graphemes, see the String module documentation.

Examples

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

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

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

Returns a float value between 0 (equates to no similarity) and 1 (is an exact match) representing Jaro distance between string1 and string2.

The Jaro distance metric is designed and best suited for short strings such as person names.

Examples

iex> String.jaro_distance("dwayne", "duane")
0.8222222222222223
iex> String.jaro_distance("even", "odd")
0.0

Returns the last grapheme from a utf8 string, nil if the string is empty.

Examples

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

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

Returns the number of Unicode graphemes in a utf8 string.

Examples

iex> String.length("elixir")
6

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

Returns a string where all leading Unicode whitespaces have been removed.

Examples

iex> String.lstrip("   abc  ")
"abc  "

Returns a string where all leading chars have been removed.

Examples

iex> String.lstrip("_  abc  _", ?_)
"  abc  _"

Checks if string matches the given regular expression.

Examples

iex> String.match?("foo", ~r/foo/)
true

iex> String.match?("bar", ~r/foo/)
false

Returns the next codepoint in a String.

The result is a tuple with the codepoint and the remainder of the string or nil in case the string reached its end.

As with other functions in the String module, this function does not check for the validity of the codepoint. That said, if an invalid codepoint is found, it will be returned by this function.

Examples

iex> String.next_codepoint("olá")
{"o", "lá"}

Returns the next grapheme in a string.

The result is a tuple with the grapheme and the remainder of the string or nil in case the String reached its end.

Examples

iex> String.next_grapheme("olá")
{"o", "lá"}

Returns the size of the next grapheme.

The result is a tuple with the next grapheme size and the remainder of the string or nil in case the string reached its end.

Examples

iex> String.next_grapheme_size("olá")
{1, "lá"}

Converts all characters in binary to Unicode normalization form identified by form.

Forms

The supported forms are:

• :nfd - Normalization Form Canonical Decomposition. Characters are decomposed by canonical equivalence, and multiple combining characters are arranged in a specific order.

• :nfc - Normalization Form Canonical Composition. Characters are decomposed and then recomposed by canonical equivalence.

Examples

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

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

Checks if a string is printable considering it is encoded as UTF-8. Returns true if so, false otherwise.

Examples

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

Replaces all leading occurences of match by replacement of match in string.

Returns the string untouched if there are no occurrences.

Examples

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"

Replaces prefix in string by replacement if it matches match.

Returns the string untouched if there is no match.

Examples

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"

Replaces suffix in string by replacement if it matches match.

Returns the string untouched if there is no match.

Examples

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"

Replaces all trailing occurences of match by replacement in string.

Returns the string untouched if there are no occurrences.

Examples

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"

Reverses the graphemes in given string.

Examples

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

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

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

Keep in mind reversing the same string twice does not necessarily yield the original string:

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

In the first example the accent is before the vowel, so it is considered two graphemes. However, when you reverse it once, you have the vowel followed by the accent, which becomes one grapheme. Reversing it again will keep it as one single grapheme.

Returns a string where all trailing Unicode whitespaces has been removed.

Examples

iex> String.rstrip("   abc  ")
"   abc"

Returns a string where all trailing chars have been removed.

Examples

iex> String.rstrip("   abc _", ?_)
"   abc "

Returns a substring from the offset given by the start of the range to the offset given by the end of the range.

If the start of the range is not a valid offset for the given string or if the range is in reverse order, returns "".

If the start or end of the range is negative, the whole string is traversed first in order to convert the negative indices into positive ones.

Remember this function works with Unicode codepoints and considers the slices to represent codepoints offsets. If you want to split on raw bytes, check Kernel.binary_part/3 instead.

Examples

iex> String.slice("elixir", 1..3)
"lix"

iex> String.slice("elixir", 1..10)
"lixir"

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

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

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

iex> String.slice("elixir", -4..6)
"ixir"

iex> String.slice("elixir", -1..-4)
""

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

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

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

Returns a substring starting at the offset start, and of length len.

If the offset is greater than string length, then it returns "".

Remember this function works with Unicode graphemes and considers the slices to represent grapheme offsets. If you want to split on raw bytes, check Kernel.binary_part/3 instead.

Examples

iex> String.slice("elixir", 1, 3)
"lix"

iex> String.slice("elixir", 1, 10)
"lixir"

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

iex> String.slice("elixir", -4, 4)
"ixir"

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

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

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

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

Divides a string into substrings at each Unicode whitespace occurrence with leading and trailing whitespace ignored. Groups of whitespace are treated as a single occurrence. Divisions do not occur on non-breaking whitespace.

Examples

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

Splits a string into two at the specified offset. When the offset given is negative, location is counted from the end of the string.

The offset is capped to the length of the string. Returns a tuple with two elements.

Note: keep in mind this function splits on graphemes and for such it has to linearly traverse the string. If you want to split a string or a binary based on the number of bytes, use Kernel.binary_part/3 instead.

Examples

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

Returns true if string starts with any of the prefixes given, otherwise returns false. prefixes can be either a single prefix or a list of prefixes.

Examples

iex> String.starts_with? "elixir", "eli"
true

iex> String.starts_with? "elixir", ["erlang", "elixir"]
true

iex> String.starts_with? "elixir", ["erlang", "ruby"]
false

Returns a string where all leading and trailing Unicode whitespaces have been removed.

Examples

iex> String.strip("   abc  ")
"abc"

Returns a string where all leading and trailing chars have been removed.

Examples

iex> String.strip("a  abc  a", ?a)
"  abc  "

Converts a string to an atom.

Currently Elixir does not support the conversion of strings that contain Unicode codepoints greater than 0xFF.

Inlined by the compiler.

Examples

iex> String.to_atom("my_atom")
:my_atom

Converts a string into a char list.

Specifically, this functions takes a UTF-8 encoded binary and returns a list of its integer codepoints. It is similar to codepoints/1 except that the latter returns a list of codepoints as strings.

In case you need to work with bytes, take a look at the :binary module.

Examples

iex> String.to_char_list("æß")
'æß'

Converts a string to an existing atom.

Currently Elixir does not support the conversion of strings that contain Unicode codepoints greater than 0xFF.

Inlined by the compiler.

Examples

iex> _ = :my_atom
iex> String.to_existing_atom("my_atom")
:my_atom

iex> String.to_existing_atom("this_atom_will_never_exist")
** (ArgumentError) argument error

Returns a float whose text representation is string.

string must be the string representation of a float. If a string representation of an integer wants to be used, then Float.parse/1 should be used instead, otherwise an argument error will be raised.

Inlined by the compiler.

Examples

iex> String.to_float("2.2017764e+0")
2.2017764

iex> String.to_float("3.0")
3.0

Returns an integer whose text representation is string.

Inlined by the compiler.

Examples

iex> String.to_integer("123")
123

Returns an integer whose text representation is string in base base.

Inlined by the compiler.

Examples

iex> String.to_integer("3FF", 16)
1023

Converts all characters in the given string to uppercase.

Examples

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

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

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

Checks whether string contains only valid characters.

Examples

iex> String.valid?("a")
true

iex> String.valid?("ø")
true

iex> String.valid?(<<0xffff :: 16>>)
false

iex> String.valid?("asd" <> <<0xffff :: 16>>)
false

Checks whether string is a valid character.

All characters are codepoints, but some codepoints are not valid characters. They may be reserved, private, or other.

More info at: Non-characters – Wikipedia

Examples

iex> String.valid_character?("a")
true

iex> String.valid_character?("ø")
true

iex> String.valid_character?("\uFFFF")
false