Strings

# Core.AbstractString — Type

The AbstractString type is the supertype of all string implementations in Julia. Strings are encodings of sequences of Unicode code points as represented by the AbstractChar type. Julia makes a few assumptions about strings:

Strings are encoded in terms of fixed-size "code units"
- Code units can be extracted with codeunit(s, i)
- The first code unit has index 1
- The last code unit has index ncodeunits(s)
- Any index i such that 1 ≤ i ≤ ncodeunits(s) is in bounds
String indexing is done in terms of these code units:
- Characters are extracted by s[i] with a valid string index i
- Each AbstractChar in a string is encoded by one or more code units
- Only the index of the first code unit of an AbstractChar is a valid index
- The encoding of an AbstractChar is independent of what precedes or follows it
- String encodings are self-synchronizing — i.e. isvalid(s, i) is O(1)

Some string functions that extract code units, characters or substrings from strings error if you pass them out-of-bounds or invalid string indices. This includes codeunit(s, i) and s[i]. Functions that do string index arithmetic take a more relaxed approach to indexing and give you the closest valid string index when in-bounds, or when out-of-bounds, behave as if there were an infinite number of characters padding each side of the string. Usually these imaginary padding characters have code unit length 1 but string types may choose different "imaginary" character sizes as makes sense for their implementations (e.g. substrings may pass index arithmetic through to the underlying string they provide a view into). Relaxed indexing functions include those intended for index arithmetic: thisind, nextind and prevind. This model allows index arithmetic to work with out-of- bounds indices as intermediate values so long as one never uses them to retrieve a character, which often helps avoid needing to code around edge cases.

# Core.AbstractChar — Type

The AbstractChar type is the supertype of all character implementations in Julia. A character represents a Unicode code point, and can be converted to an integer via the codepoint function in order to obtain the numerical value of the code point, or constructed from the same integer. These numerical values determine how characters are compared with < and ==, for example. New T <: AbstractChar types should define a codepoint(::T) method and a T(::UInt32) constructor, at minimum.

A given AbstractChar subtype may be capable of representing only a subset of Unicode, in which case conversion from an unsupported UInt32 value may throw an error. Conversely, the built-in Char type represents a superset of Unicode (in order to losslessly encode invalid byte streams), in which case conversion of a non-Unicode value to UInt32 throws an error. The isvalid function can be used to check which codepoints are representable in a given AbstractChar type.

Internally, an AbstractChar type may use a variety of encodings. Conversion via codepoint(char) will not reveal this encoding because it always returns the Unicode value of the character. print(io, c) of any c::AbstractChar produces an encoding determined by io (UTF-8 for all built-in IO types), via conversion to Char if necessary.

write(io, c), in contrast, may emit an encoding depending on typeof(c), and read(io, typeof(c)) should read the same encoding as write. New AbstractChar types must provide their own implementations of write and read.

# Core.Char — Type

Char(c::Union{Number,AbstractChar})

Char is a 32-bit AbstractChar type that is the default representation of characters in Julia. Char is the type used for character literals like 'x' and it is also the element type of String.

In order to losslessly represent arbitrary byte streams stored in a String, a Char value may store information that cannot be converted to a Unicode codepoint — converting such a Char to UInt32 will throw an error. The isvalid(c::Char) function can be used to query whether c represents a valid Unicode character.

# Base.codepoint — Function

codepoint(c::AbstractChar) -> Integer

Return the Unicode codepoint (an unsigned integer) corresponding to the character c (or throw an exception if c does not represent a valid character). For Char, this is a UInt32 value, but AbstractChar types that represent only a subset of Unicode may return a different-sized integer (e.g. UInt8).

# Base.length — Method

length(s::AbstractString) -> Int
length(s::AbstractString, i::Integer, j::Integer) -> Int

Return the number of characters in string s from indices i through j.

This is computed as the number of code unit indices from i to j which are valid character indices. With only a single string argument, this computes the number of characters in the entire string. With i and j arguments it computes the number of indices between i and j inclusive that are valid indices in the string s. In addition to in-bounds values, i may take the out-of-bounds value ncodeunits(s) + 1 and j may take the out-of-bounds value 0.

The time complexity of this operation is linear in general. That is, it will take the time proportional to the number of bytes or characters in the string because it counts the value on the fly. This is in contrast to the method for arrays, which is a constant-time operation.

Examples

julia> length("jμΛIα")
5

# Base.sizeof — Method

sizeof(str::AbstractString)

Size, in bytes, of the string str. Equal to the number of code units in str multiplied by the size, in bytes, of one code unit in str.

Examples

julia> sizeof("")
0

julia> sizeof("∀")
3

# Base.:* — Method

*(s::Union{AbstractString, AbstractChar}, t::Union{AbstractString, AbstractChar}...) -> AbstractString

Concatenate strings and/or characters, producing a String. This is equivalent to calling the string function on the arguments. Concatenation of built-in string types always produces a value of type String but other string types may choose to return a string of a different type as appropriate.

Examples

julia> "Hello " * "world"
"Hello world"

julia> 'j' * "ulia"
"julia"

# Base.:^ — Method

^(s::Union{AbstractString,AbstractChar}, n::Integer) -> AbstractString

Repeat a string or character n times. This can also be written as repeat(s, n).

See also ncodeunits, checkbounds.

# Base.codeunits — Function

codeunits(s::AbstractString)

Obtain a vector-like object containing the code units of a string. Returns a CodeUnits wrapper by default, but codeunits may optionally be defined for new string types if necessary.

Examples

julia> codeunits("Juλia")
6-element Base.CodeUnits{UInt8, String}:
 0x4a
 0x75
 0xce
 0xbb
 0x69
 0x61

# Base.ascii — Function

ascii(s::AbstractString)

Convert a string to String type and check that it contains only ASCII data, otherwise throwing an ArgumentError indicating the position of the first non-ASCII byte.

See also the isascii predicate to filter or replace non-ASCII characters.

Examples

julia> ascii("abcdeγfgh")
ERROR: ArgumentError: invalid ASCII at index 6 in "abcdeγfgh"
Stacktrace:
[...]

julia> ascii("abcdefgh")
"abcdefgh"

# Base.Regex — Type

Regex(pattern[, flags])

A type representing a regular expression. Regex objects can be used to match strings with match.

Regex objects can be created using the @r_str string macro. The Regex(pattern[, flags]) constructor is usually used if the pattern string needs to be interpolated. See the documentation of the string macro for details on flags.

To escape interpolated variables use \Q and \E (e.g. Regex("\\Q$x\\E"))

# Base.@r_str — Macro

@r_str -> Regex

Construct a regex, such as r"^[a-z]*$", without interpolation and unescaping (except for quotation mark " which still has to be escaped). The regex also accepts one or more flags, listed after the ending quote, to change its behaviour:

i enables case-insensitive matching
m treats the ^ and $ tokens as matching the start and end of individual lines, as opposed to the whole string.
s allows the . modifier to match newlines.
x enables "comment mode": whitespace is enabled except when escaped with \, and # is treated as starting a comment.
a disables UCP mode (enables ASCII mode). By default \B, \b, \D, \d, \S, \s, \W, \w, etc. match based on Unicode character properties. With this option, these sequences only match ASCII characters.

See Regex if interpolation is needed.

Examples

julia> match(r"a+.*b+.*?d$"ism, "Goodbye,\nOh, angry,\nBad world\n")
RegexMatch("angry,\nBad world")

This regex has the first three flags enabled.

# Base.SubstitutionString — Type

SubstitutionString(substr)

Stores the given string substr as a SubstitutionString, for use in regular expression substitutions. Most commonly constructed using the @s_str macro.

Examples

julia> SubstitutionString("Hello \\g<name>, it's \\1")
s"Hello \g<name>, it's \1"

julia> subst = s"Hello \g<name>, it's \1"
s"Hello \g<name>, it's \1"

julia> typeof(subst)
SubstitutionString{String}

# Base.@s_str — Macro

@s_str -> SubstitutionString

Construct a substitution string, used for regular expression substitutions. Within the string, sequences of the form \N refer to the Nth capture group in the regex, and \g<groupname> refers to a named capture group with name groupname.

Examples

julia> msg = "#Hello# from Julia";

julia> replace(msg, r"#(.+)# from (?<from>\w+)" => s"FROM: \g<from>; MESSAGE: \1")
"FROM: Julia; MESSAGE: Hello"

# Base.@raw_str — Macro

@raw_str -> String

Create a raw string without interpolation and unescaping. The exception is that quotation marks still must be escaped. Backslashes escape both quotation marks and other backslashes, but only when a sequence of backslashes precedes a quote character. Thus, 2n backslashes followed by a quote encodes n backslashes and the end of the literal while 2n+1 backslashes followed by a quote encodes n backslashes followed by a quote character.

Examples

julia> println(raw"\ $x")
\ $x

julia> println(raw"\"")
"

julia> println(raw"\\\"")
\"

julia> println(raw"\\x \\\"")
\\x \"

# Base.@b_str — Macro

@b_str

Create an immutable byte (UInt8) vector using string syntax.

Examples

julia> v = b"12\x01\x02"
4-element Base.CodeUnits{UInt8, String}:
 0x31
 0x32
 0x01
 0x02

julia> v[2]
0x32

# Base.Docs.@html_str — Macro

@html_str -> Docs.HTML

Create an HTML object from a literal string.

Examples

julia> html"Julia"
HTML{String}("Julia")

# Base.Docs.@text_str — Macro

@text_str -> Docs.Text

Create a Text object from a literal string.

Examples

julia> text"Julia"
Julia

# Base.isvalid — Method

isvalid(value) -> Bool

Return true if the given value is valid for its type, which currently can be either AbstractChar or String or SubString{String}.

Examples

julia> isvalid(Char(0xd800))
false

julia> isvalid(SubString(String(UInt8[0xfe,0x80,0x80,0x80,0x80,0x80]),1,2))
false

julia> isvalid(Char(0xd799))
true

# Base.isvalid — Method

isvalid(T, value) -> Bool

Return true if the given value is valid for that type. Types currently can be either AbstractChar or String. Values for AbstractChar can be of type AbstractChar or UInt32. Values for String can be of that type, SubString{String}, Vector{UInt8}, or a contiguous subarray thereof.

Examples

julia> isvalid(Char, 0xd800)
false

julia> isvalid(String, SubString("thisisvalid",1,5))
true

julia> isvalid(Char, 0xd799)
true

Compatibility: Julia 1.6

Support for subarray values was added in Julia 1.6.

# Base.isvalid — Method

isvalid(s::AbstractString, i::Integer) -> Bool

Predicate indicating whether the given index is the start of the encoding of a character in s or not. If isvalid(s, i) is true then s[i] will return the character whose encoding starts at that index, if it’s false, then s[i] will raise an invalid index error or a bounds error depending on if i is in bounds. In order for isvalid(s, i) to be an O(1) function, the encoding of s must be self-synchronizing. This is a basic assumption of Julia’s generic string support.

Examples

julia> str = "αβγdef";

julia> isvalid(str, 1)
true

julia> str[1]
'α': Unicode U+03B1 (category Ll: Letter, lowercase)

julia> isvalid(str, 2)
false

julia> str[2]
ERROR: StringIndexError: invalid index [2], valid nearby indices [1]=>'α', [3]=>'β'
Stacktrace:
[...]

# Base.match — Function

match(r::Regex, s::AbstractString[, idx::Integer[, addopts]])

Search for the first match of the regular expression r in s and return a RegexMatch object containing the match, or nothing if the match failed. The matching substring can be retrieved by accessing m.match and the captured sequences can be retrieved by accessing m.captures The optional idx argument specifies an index at which to start the search.

Examples

julia> rx = r"a(.)a"
r"a(.)a"

julia> m = match(rx, "cabac")
RegexMatch("aba", 1="b")

julia> m.captures
1-element Vector{Union{Nothing, SubString{String}}}:
 "b"

julia> m.match
"aba"

julia> match(rx, "cabac", 3) === nothing
true

# Base.eachmatch — Function

eachmatch(r::Regex, s::AbstractString; overlap::Bool=false)

Search for all matches of the regular expression r in s and return an iterator over the matches. If overlap is true, the matching sequences are allowed to overlap indices in the original string, otherwise they must be from distinct character ranges.

Examples

julia> rx = r"a.a"
r"a.a"

julia> m = eachmatch(rx, "a1a2a3a")
Base.RegexMatchIterator(r"a.a", "a1a2a3a", false)

julia> collect(m)
2-element Vector{RegexMatch}:
 RegexMatch("a1a")
 RegexMatch("a3a")

julia> collect(eachmatch(rx, "a1a2a3a", overlap = true))
3-element Vector{RegexMatch}:
 RegexMatch("a1a")
 RegexMatch("a2a")
 RegexMatch("a3a")

# Base.RegexMatch — Type

RegexMatch

A type representing a single match to a Regex found in a string. Typically created from the match function.

The match field stores the substring of the entire matched string. The captures field stores the substrings for each capture group, indexed by number. To index by capture group name, the entire match object should be indexed instead, as shown in the examples. The location of the start of the match is stored in the offset field. The offsets field stores the locations of the start of each capture group, with 0 denoting a group that was not captured.

This type can be used as an iterator over the capture groups of the Regex, yielding the substrings captured in each group. Because of this, the captures of a match can be destructured. If a group was not captured, nothing will be yielded instead of a substring.

Methods that accept a RegexMatch object are defined for iterate, length, eltype, keys, haskey, and getindex, where keys are the the names or numbers of a capture group. See keys for more information.

Examples

julia> m = match(r"(?<hour>\d+):(?<minute>\d+)(am|pm)?", "11:30 in the morning")
RegexMatch("11:30", hour="11", minute="30", 3=nothing)

julia> hr, min, ampm = m;

julia> hr
"11"

julia> m["minute"]
"30"

julia> m.match
"11:30"

# Base.keys — Method

keys(m::RegexMatch) -> Vector

Return a vector of keys for all capture groups of the underlying regex. A key is included even if the capture group fails to match. That is, idx will be in the return value even if m[idx] == nothing.

Unnamed capture groups will have integer keys corresponding to their index. Named capture groups will have string keys.

Compatibility: Julia 1.7

This method was added in Julia 1.7

Examples

julia> keys(match(r"(?<hour>\d+):(?<minute>\d+)(am|pm)?", "11:30"))
3-element Vector{Any}:
  "hour"
  "minute"
 3

# Base.isless — Method

isless(a::AbstractString, b::AbstractString) -> Bool

Test whether string a comes before string b in alphabetical order (technically, in lexicographical order by Unicode code points).

Examples

julia> isless("a", "b")
true

julia> isless("β", "α")
false

julia> isless("a", "a")
false

# Base.:== — Method

==(a::AbstractString, b::AbstractString) -> Bool

Test whether two strings are equal character by character (technically, Unicode code point by code point).

Examples

julia> "abc" == "abc"
true

julia> "abc" == "αβγ"
false

# Base.cmp — Method

cmp(a::AbstractString, b::AbstractString) -> Int

Compare two strings. Return 0 if both strings have the same length and the character at each index is the same in both strings. Return -1 if a is a prefix of b, or if a comes before b in alphabetical order. Return 1 if b is a prefix of a, or if b comes before a in alphabetical order (technically, lexicographical order by Unicode code points).

Examples

julia> cmp("abc", "abc")
0

julia> cmp("ab", "abc")
-1

julia> cmp("abc", "ab")
1

julia> cmp("ab", "ac")
-1

julia> cmp("ac", "ab")
1

julia> cmp("α", "a")
1

julia> cmp("b", "β")
-1

# Base.lpad — Function

lpad(s, n::Integer, p::Union{AbstractChar,AbstractString}=' ') -> String

Stringify s and pad the resulting string on the left with p to make it n characters (in textwidth) long. If s is already n characters long, an equal string is returned. Pad with spaces by default.

Examples

julia> lpad("March", 10)
"     March"

Compatibility: Julia 1.7

In Julia 1.7, this function was changed to use textwidth rather than a raw character (codepoint) count.

# Base.rpad — Function

rpad(s, n::Integer, p::Union{AbstractChar,AbstractString}=' ') -> String

Stringify s and pad the resulting string on the right with p to make it n characters (in textwidth) long. If s is already n characters long, an equal string is returned. Pad with spaces by default.

Examples

julia> rpad("March", 20)
"March               "

Compatibility: Julia 1.7

In Julia 1.7, this function was changed to use textwidth rather than a raw character (codepoint) count.

# Base.findfirst — Method

findfirst(pattern::AbstractString, string::AbstractString)
findfirst(pattern::AbstractPattern, string::String)

Find the first occurrence of pattern in string. Equivalent to findnext(pattern, string, firstindex(s)).

Examples

julia> findfirst("z", "Hello to the world") # returns nothing, but not printed in the REPL

julia> findfirst("Julia", "JuliaLang")
1:5

# Base.findnext — Method

findnext(pattern::AbstractString, string::AbstractString, start::Integer)
findnext(pattern::AbstractPattern, string::String, start::Integer)

Find the next occurrence of pattern in string starting at position start. pattern can be either a string, or a regular expression, in which case string must be of type String.

The return value is a range of indices where the matching sequence is found, such that s[findnext(x, s, i)] == x:

findnext("substring", string, i) == start:stop such that string[start:stop] == "substring" and i <= start, or nothing if unmatched.

Examples

julia> findnext("z", "Hello to the world", 1) === nothing
true

julia> findnext("o", "Hello to the world", 6)
8:8

julia> findnext("Lang", "JuliaLang", 2)
6:9

# Base.findnext — Method

findnext(ch::AbstractChar, string::AbstractString, start::Integer)

Find the next occurrence of character ch in string starting at position start.

Compatibility: Julia 1.3

This method requires at least Julia 1.3.

Examples

julia> findnext('z', "Hello to the world", 1) === nothing
true

julia> findnext('o', "Hello to the world", 6)
8

# Base.findlast — Method

findlast(pattern::AbstractString, string::AbstractString)

Find the last occurrence of pattern in string. Equivalent to findprev(pattern, string, lastindex(string)).

Examples

julia> findlast("o", "Hello to the world")
15:15

julia> findfirst("Julia", "JuliaLang")
1:5

# Base.findlast — Method

findlast(ch::AbstractChar, string::AbstractString)

Find the last occurrence of character ch in string.

Compatibility: Julia 1.3

This method requires at least Julia 1.3.

Examples

julia> findlast('p', "happy")
4

julia> findlast('z', "happy") === nothing
true

# Base.findprev — Method

findprev(pattern::AbstractString, string::AbstractString, start::Integer)

Find the previous occurrence of pattern in string starting at position start.

The return value is a range of indices where the matching sequence is found, such that s[findprev(x, s, i)] == x:

findprev("substring", string, i) == start:stop such that string[start:stop] == "substring" and stop <= i, or nothing if unmatched.

Examples

julia> findprev("z", "Hello to the world", 18) === nothing
true

julia> findprev("o", "Hello to the world", 18)
15:15

julia> findprev("Julia", "JuliaLang", 6)
1:5

# Base.occursin — Function

occursin(needle::Union{AbstractString,AbstractPattern,AbstractChar}, haystack::AbstractString)

Determine whether the first argument is a substring of the second. If needle is a regular expression, checks whether haystack contains a match.

Examples

julia> occursin("Julia", "JuliaLang is pretty cool!")
true

julia> occursin('a', "JuliaLang is pretty cool!")
true

julia> occursin(r"a.a", "aba")
true

julia> occursin(r"a.a", "abba")
false