TheAbstractString type is the supertype of all string implementations in Julia. Strings are encodings of sequences ofUnicode code points as represented by theAbstractChar type. Julia makes a few assumptions about strings:

• Strings are encoded in terms of fixed-size "code units"
  • Code units can be extracted withcodeunit(s, i)
  • The first code unit has index1
  • The last code unit has indexncodeunits(s)
  • Any indexi such that1 ≤ i ≤ ncodeunits(s) is in bounds
• String indexing is done in terms of these code units:
  • Characters are extracted bys[i] with a valid string indexi
  • EachAbstractChar in a string is encoded by one or more code units
  • Only the index of the first code unit of anAbstractChar is a valid index
  • The encoding of anAbstractChar is independent of what precedes or follows it
  • String encodings areself-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 includescodeunit(s, i) ands[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 length1 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 andprevind. 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.

See alsocodeunit,ncodeunits,thisind,nextind,prevind.

TheAbstractChar 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 thecodepoint 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. NewT <: AbstractChar types should define acodepoint(::T) method and aT(::UInt32) constructor, at minimum.

A givenAbstractChar subtype may be capable of representing only a subset of Unicode, in which case conversion from an unsupportedUInt32 value may throw an error. Conversely, the built-inChar type represents asuperset of Unicode (in order to losslessly encode invalid byte streams), in which case conversion of a non-Unicode valuetoUInt32 throws an error. Theisvalid function can be used to check which codepoints are representable in a givenAbstractChar type.

Internally, anAbstractChar type may use a variety of encodings. Conversion viacodepoint(char) will not reveal this encoding because it always returns the Unicode value of the character.print(io, c) of anyc::AbstractChar produces an encoding determined byio (UTF-8 for all built-inIO types), via conversion toChar if necessary.

write(io, c), in contrast, may emit an encoding depending ontypeof(c), andread(io, typeof(c)) should read the same encoding aswrite. NewAbstractChar types must provide their own implementations ofwrite andread.

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

Char is a 32-bitAbstractChar 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 ofString.

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

codepoint(c::AbstractChar) -> Integer

Return the Unicode codepoint (an unsigned integer) corresponding to the characterc (or throw an exception ifc does not represent a valid character). ForChar, this is aUInt32 value, butAbstractChar types that represent only a subset of Unicode may return a different-sized integer (e.g.UInt8).

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

Return the number of characters in strings from indicesi throughj.

This is computed as the number of code unit indices fromi toj which are valid character indices. With only a single string argument, this computes the number of characters in the entire string. Withi andj arguments it computes the number of indices betweeni andj inclusive that are valid indices in the strings. In addition to in-bounds values,i may take the out-of-bounds valuencodeunits(s) + 1 andj may take the out-of-bounds value0.

See alsoisvalid,ncodeunits,lastindex,thisind,nextind,prevind.

Examples

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

sizeof(str::AbstractString)

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

Examples

julia> sizeof("")0julia> sizeof("∀")3

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

Concatenate strings and/or characters, producing aString orAnnotatedString (as appropriate). This is equivalent to calling thestring orannotatedstring function on the arguments. Concatenation of built-in string types always produces a value of typeString 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"

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

Repeat a string or charactern times. This can also be written asrepeat(s, n).

See alsorepeat.

Examples

julia> "Test "^3"Test Test Test "

string(n::Integer; base::Integer = 10, pad::Integer = 1)

Convert an integern to a string in the givenbase, optionally specifying a number of digits to pad to.

See alsodigits,bitstring,count_zeros.

Examples

julia> string(5, base = 13, pad = 4)"0005"julia> string(-13, base = 5, pad = 4)"-0023"

string(xs...)

Create a string from any values using theprint function.

string should usually not be defined directly. Instead, define a methodprint(io::IO, x::MyType). Ifstring(x) for a certain type needs to be highly efficient, then it may make sense to add a method tostring and defineprint(io::IO, x::MyType) = print(io, string(x)) to ensure the functions are consistent.

See also:String,repr,sprint,show.

Examples

julia> string("a", 1, true)"a1true"

repeat(s::AbstractString, r::Integer)

Repeat a stringr times. This can be written ass^r.

See also^.

Examples

julia> repeat("ha", 3)"hahaha"

repeat(c::AbstractChar, r::Integer) -> String

Repeat a characterr times. This can equivalently be accomplished by callingc^r.

Examples

julia> repeat('A', 3)"AAA"

repr(x; context=nothing)

Create a string from any value using theshow function. You should not add methods torepr; define ashow method instead.

The optional keyword argumentcontext can be set to a:key=>value pair, a tuple of:key=>value pairs, or anIO orIOContext object whose attributes are used for the I/O stream passed toshow.

Note thatrepr(x) is usually similar to how the value ofx would be entered in Julia. See alsorepr(MIME("text/plain"), x) to instead return a "pretty-printed" version ofx designed more for human consumption, equivalent to the REPL display ofx.

Examples

julia> repr(1)"1"julia> repr(zeros(3))"[0.0, 0.0, 0.0]"julia> repr(big(1/3))"0.333333333333333314829616256247390992939472198486328125"julia> repr(big(1/3), context=:compact => true)"0.333333"

String(s::AbstractString)

Create a newString from an existingAbstractString.

SubString(s::AbstractString, i::Integer, j::Integer=lastindex(s))SubString(s::AbstractString, r::UnitRange{<:Integer})

Likegetindex, but returns a view into the parent strings within rangei:j orr respectively instead of making a copy.

The@views macro converts any string slicess[i:j] into substringsSubString(s, i, j) in a block of code.

Examples

julia> SubString("abc", 1, 2)"ab"julia> SubString("abc", 1:2)"ab"julia> SubString("abc", 2)"bc"

LazyString <: AbstractString

A lazy representation of string interpolation. This is useful when a string needs to be constructed in a context where performing the actual interpolation and string construction is unnecessary or undesirable (e.g. in error paths of functions).

This type is designed to be cheap to construct at runtime, trying to offload as much work as possible to either the macro or later printing operations.

Examples

julia> n = 5; str = LazyString("n is ", n)"n is 5"

See also@lazy_str.

Extended help

Safety properties for concurrent programs

A lazy string itself does not introduce any concurrency problems even if it is printed in multiple Julia tasks. However, ifprint methods on a captured value can have a concurrency issue when invoked without synchronizations, printing the lazy string may cause an issue. Furthermore, theprint methods on the captured values may be invoked multiple times, though only exactly one result will be returned.

lazy"str"

Create aLazyString using regular string interpolation syntax. Note that interpolations areevaluated at LazyString construction time, butprinting is delayed until the first access to the string.

SeeLazyString documentation for the safety properties for concurrent programs.

Examples

julia> n = 5; str = lazy"n is $n""n is 5"julia> typeof(str)LazyString

transcode(T, src)

Convert string data between Unicode encodings.src is either aString or aVector{UIntXX} of UTF-XX code units, whereXX is 8, 16, or 32.T indicates the encoding of the return value:String to return a (UTF-8 encoded)String orUIntXX to return aVector{UIntXX} of UTF-XX data. (The aliasCwchar_t can also be used as the integer type, for convertingwchar_t* strings used by external C libraries.)

Thetranscode function succeeds as long as the input data can be reasonably represented in the target encoding; it always succeeds for conversions between UTF-XX encodings, even for invalid Unicode data.

Only conversion to/from UTF-8 is currently supported.

Examples

julia> str = "αβγ""αβγ"julia> transcode(UInt16, str)3-element Vector{UInt16}: 0x03b1 0x03b2 0x03b3julia> transcode(String, transcode(UInt16, str))"αβγ"

unsafe_string(p::Ptr{UInt8}, [length::Integer])

Copy a string from the address of a C-style (NUL-terminated) string encoded as UTF-8. (The pointer can be safely freed afterwards.) Iflength is specified (the length of the data in bytes), the string does not have to be NUL-terminated.

This function is labeled "unsafe" because it will crash ifp is not a valid memory address to data of the requested length.

ncodeunits(s::AbstractString) -> Int

Return the number of code units in a string. Indices that are in bounds to access this string must satisfy1 ≤ i ≤ ncodeunits(s). Not all such indices are valid – they may not be the start of a character, but they will return a code unit value when callingcodeunit(s,i).

Examples

julia> ncodeunits("The Julia Language")18julia> ncodeunits("∫eˣ")6julia> ncodeunits('∫'), ncodeunits('e'), ncodeunits('ˣ')(3, 1, 2)

See alsocodeunit,checkbounds,sizeof,length,lastindex.

codeunit(s::AbstractString) -> Type{<:Union{UInt8, UInt16, UInt32}}

Return the code unit type of the given string object. For ASCII, Latin-1, or UTF-8 encoded strings, this would beUInt8; for UCS-2 and UTF-16 it would beUInt16; for UTF-32 it would beUInt32. The code unit type need not be limited to these three types, but it's hard to think of widely used string encodings that don't use one of these units.codeunit(s) is the same astypeof(codeunit(s,1)) whens is a non-empty string.

See alsoncodeunits.

codeunit(s::AbstractString, i::Integer) -> Union{UInt8, UInt16, UInt32}

Return the code unit value in the strings at indexi. Note that

codeunit(s, i) :: codeunit(s)

I.e. the value returned bycodeunit(s, i) is of the type returned bycodeunit(s).

Examples

julia> a = codeunit("Hello", 2)0x65julia> typeof(a)UInt8

See alsoncodeunits,checkbounds.

codeunits(s::AbstractString)

Obtain a vector-like object containing the code units of a string. Returns aCodeUnits wrapper by default, butcodeunits 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

ascii(s::AbstractString)

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

See also theisascii 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"

Regex(pattern[, flags]) <: AbstractPattern

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

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

@r_str -> Regex

Construct a regex, such asr"^[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 "free-spacing mode": whitespace between regex tokens is ignored except when escaped with\, and# in the regex is treated as starting a comment (which is ignored to the line ending).
• a enables ASCII mode (disablesUTF andUCP modes). 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. This includes\u also, which will emit the specified character value directly as a single byte, and not attempt to encode it into UTF-8. Importantly, this option allows matching against invalid UTF-8 strings, by treating both matcher and target as simple bytes (as if they were ISO/IEC 8859-1 / Latin-1 bytes) instead of as character encodings. In this case, this option is often combined withs. This option can be further refined by starting the pattern with (UCP) or (UTF).

SeeRegex 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.

SubstitutionString(substr) <: AbstractString

Stores the given stringsubstr as aSubstitutionString, 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}

@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 namegroupname.

Examples

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

@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")\ $xjulia> println(raw"\"")"julia> println(raw"\\\"")\"julia> println(raw"\\x \\\"")\\x \"

@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 0x02julia> v[2]0x32

@html_str -> Docs.HTML

Create anHTML object from a literal string.

Examples

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

@text_str -> Docs.Text

Create aText object from a literal string.

Examples

julia> text"Julia"Julia

isvalid(value) -> Bool

Returntrue if the given value is valid for its type, which currently can be eitherAbstractChar orString orSubString{String}.

Examples

julia> isvalid(Char(0xd800))falsejulia> isvalid(SubString(String(UInt8[0xfe,0x80,0x80,0x80,0x80,0x80]),1,2))falsejulia> isvalid(Char(0xd799))true

isvalid(T, value) -> Bool

Returntrue if the given value is valid for that type. Types currently can be eitherAbstractChar orString. Values forAbstractChar can be of typeAbstractChar orUInt32. Values forString can be of that type,SubString{String},Vector{UInt8}, or a contiguous subarray thereof.

Examples

julia> isvalid(Char, 0xd800)falsejulia> isvalid(String, SubString("thisisvalid",1,5))truejulia> isvalid(Char, 0xd799)true

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

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

See alsogetindex,iterate,thisind,nextind,prevind,length.

Examples

julia> str = "αβγdef";julia> isvalid(str, 1)truejulia> str[1]'α': Unicode U+03B1 (category Ll: Letter, lowercase)julia> isvalid(str, 2)falsejulia> str[2]ERROR: StringIndexError: invalid index [2], valid nearby indices [1]=>'α', [3]=>'β'Stacktrace:[...]

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

Search for the first match of the regular expressionr ins and return aRegexMatch object containing the match, or nothing if the match failed. The matching substring can be retrieved by accessingm.match and the captured sequences can be retrieved by accessingm.captures The optionalidx 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.captures1-element Vector{Union{Nothing, SubString{String}}}: "b"julia> m.match"aba"julia> match(rx, "cabac", 3) === nothingtrue

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

Search for all matches of the regular expressionr ins and return an iterator over the matches. Ifoverlap istrue, 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{String}(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")

RegexMatch <: AbstractMatch

A type representing a single match to aRegex found in a string. Typically created from thematch function.

Thematch field stores the substring of the entire matched string. Thecaptures 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 theoffset field. Theoffsets 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 theRegex, 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 aRegexMatch object are defined foriterate,length,eltype,keys,haskey, andgetindex, where keys are the the names or numbers of a capture group. Seekeys 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> m.match"11:30"julia> m.captures3-element Vector{Union{Nothing, SubString{String}}}: "11" "30" nothingjulia> m["minute"]"30"julia> hr, min, ampm = m; # destructure capture groups by iterationjulia> hr"11"

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 ifm[idx] == nothing.

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

Examples

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

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

Test whether stringa comes before stringb in alphabetical order (technically, in lexicographical order by Unicode code points).

Examples

julia> isless("a", "b")truejulia> isless("β", "α")falsejulia> isless("a", "a")false

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

Test whether two strings are equal character by character (technically, Unicode code point by code point). Should either string be aAnnotatedString the string properties must match too.

Examples

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

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

Compare two strings. Return0 if both strings have the same length and the character at each index is the same in both strings. Return-1 ifa is a prefix ofb, or ifa comes beforeb in alphabetical order. Return1 ifb is a prefix ofa, or ifb comes beforea in alphabetical order (technically, lexicographical order by Unicode code points).

Examples

julia> cmp("abc", "abc")0julia> cmp("ab", "abc")-1julia> cmp("abc", "ab")1julia> cmp("ab", "ac")-1julia> cmp("ac", "ab")1julia> cmp("α", "a")1julia> cmp("b", "β")-1

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

Stringifys and pad the resulting string on the left withp to make itn characters (intextwidth) long. Ifs is alreadyn characters long, an equal string is returned. Pad with spaces by default.

Examples

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

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

Stringifys and pad the resulting string on the right withp to make itn characters (intextwidth) long. Ifs is alreadyn characters long, an equal string is returned. Pad with spaces by default.

Examples

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

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

Find the first occurrence ofpattern instring. Equivalent tofindnext(pattern, string, firstindex(s)).

Examples

julia> findfirst("z", "Hello to the world") # returns nothing, but not printed in the REPLjulia> findfirst("Julia", "JuliaLang")1:5

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

Find the next occurrence ofpattern instring starting at positionstart.pattern can be either a string, or a regular expression, in which casestring must be of typeString.

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

findnext("substring", string, i) ==start:stop such thatstring[start:stop] == "substring" andi <= start, ornothing if unmatched.

Examples

julia> findnext("z", "Hello to the world", 1) === nothingtruejulia> findnext("o", "Hello to the world", 6)8:8julia> findnext("Lang", "JuliaLang", 2)6:9

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

Find the next occurrence of characterch instring starting at positionstart.

Examples

julia> findnext('z', "Hello to the world", 1) === nothingtruejulia> findnext('o', "Hello to the world", 6)8

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

Find the last occurrence ofpattern instring. Equivalent tofindprev(pattern, string, lastindex(string)).

Examples

julia> findlast("o", "Hello to the world")15:15julia> findfirst("Julia", "JuliaLang")1:5

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

Find the last occurrence of characterch instring.

Examples

julia> findlast('p', "happy")4julia> findlast('z', "happy") === nothingtrue

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

Find the previous occurrence ofpattern instring starting at positionstart.

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

findprev("substring", string, i) ==start:stop such thatstring[start:stop] == "substring" andstop <= i, ornothing if unmatched.

Examples

julia> findprev("z", "Hello to the world", 18) === nothingtruejulia> findprev("o", "Hello to the world", 18)15:15julia> findprev("Julia", "JuliaLang", 6)1:5

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

Determine whether the first argument is a substring of the second. Ifneedle is a regular expression, checks whetherhaystack contains a match.

Examples

julia> occursin("Julia", "JuliaLang is pretty cool!")truejulia> occursin('a', "JuliaLang is pretty cool!")truejulia> occursin(r"a.a", "aba")truejulia> occursin(r"a.a", "abba")false

See alsocontains.

occursin(haystack)

Create a function that checks whether its argument occurs inhaystack, i.e. a function equivalent toneedle -> occursin(needle, haystack).

The returned function is of typeBase.Fix2{typeof(occursin)}.

Examples

julia> search_f = occursin("JuliaLang is a programming language");julia> search_f("JuliaLang")truejulia> search_f("Python")false

reverse(s::AbstractString) -> AbstractString

Reverses a string. Technically, this function reverses the codepoints in a string and its main utility is for reversed-order string processing, especially for reversed regular-expression searches. See alsoreverseind to convert indices ins to indices inreverse(s) and vice-versa, andgraphemes from moduleUnicode to operate on user-visible "characters" (graphemes) rather than codepoints. See alsoIterators.reverse for reverse-order iteration without making a copy. Custom string types must implement thereverse function themselves and should typically return a string with the same type and encoding. If they return a string with a different encoding, they must also overridereverseind for that string type to satisfys[reverseind(s,i)] == reverse(s)[i].

Examples

julia> reverse("JuliaLang")"gnaLailuJ"

Combining characters can lead to surprising results:

julia> reverse("ax̂e") # hat is above x in the input, above e in the output"êxa"julia> using Unicodejulia> join(reverse(collect(graphemes("ax̂e")))) # reverses graphemes; hat is above x in both in- and output"ex̂a"

replace([io::IO], s::AbstractString, pat=>r, [pat2=>r2, ...]; [count::Integer])

Search for the given patternpat ins, and replace each occurrence withr. Ifcount is provided, replace at mostcount occurrences.pat may be a single character, a vector or a set of characters, a string, or a regular expression. Ifr is a function, each occurrence is replaced withr(s) wheres is the matched substring (whenpat is aAbstractPattern orAbstractString) or character (whenpat is anAbstractChar or a collection ofAbstractChar). Ifpat is a regular expression andr is aSubstitutionString, then capture group references inr are replaced with the corresponding matched text. To remove instances ofpat fromstring, setr to the emptyString ("").

The return value is a new string after the replacements. If theio::IO argument is supplied, the transformed string is instead written toio (returningio). (For example, this can be used in conjunction with anIOBuffer to re-use a pre-allocated buffer array in-place.)

Multiple patterns can be specified, and they will be applied left-to-right simultaneously, so only one pattern will be applied to any character, and the patterns will only be applied to the input text, not the replacements.

Examples

julia> replace("Python is a programming language.", "Python" => "Julia")"Julia is a programming language."julia> replace("The quick foxes run quickly.", "quick" => "slow", count=1)"The slow foxes run quickly."julia> replace("The quick foxes run quickly.", "quick" => "", count=1)"The  foxes run quickly."julia> replace("The quick foxes run quickly.", r"fox(es)?" => s"bus\1")"The quick buses run quickly."julia> replace("abcabc", "a" => "b", "b" => "c", r".+" => "a")"bca"

eachsplit(str::AbstractString, dlm; limit::Integer=0, keepempty::Bool=true)eachsplit(str::AbstractString; limit::Integer=0, keepempty::Bool=false)

Splitstr on occurrences of the delimiter(s)dlm and return an iterator over the substrings.dlm can be any of the formats allowed byfindnext's first argument (i.e. as a string, regular expression or a function), or as a single character or collection of characters.

Ifdlm is omitted, it defaults toisspace.

The optional keyword arguments are:

• limit: the maximum size of the result.limit=0 implies no maximum (default)
• keepempty: whether empty fields should be kept in the result. Default isfalse without adlm argument,true with adlm argument.

See alsosplit.

Examples

julia> a = "Ma.rch""Ma.rch"julia> b = eachsplit(a, ".")Base.SplitIterator{String, String}("Ma.rch", ".", 0, true)julia> collect(b)2-element Vector{SubString{String}}: "Ma" "rch"

eachrsplit(str::AbstractString, dlm; limit::Integer=0, keepempty::Bool=true)eachrsplit(str::AbstractString; limit::Integer=0, keepempty::Bool=false)

Return an iterator overSubStrings ofstr, produced when splitting on the delimiter(s)dlm, and yielded in reverse order (from right to left).dlm can be any of the formats allowed byfindprev's first argument (i.e. a string, a single character or a function), or a collection of characters.

Ifdlm is omitted, it defaults toisspace, andkeepempty default tofalse.

The optional keyword arguments are:

• Iflimit > 0, the iterator will split at mostlimit - 1 times before returning the rest of the string unsplit.limit < 1 implies no cap to splits (default).
• keepempty: whether empty fields should be returned when iterating Default isfalse without adlm argument,true with adlm argument.

Note that unlikesplit,rsplit andeachsplit, this function iterates the substrings right to left as they occur in the input.

See alsoeachsplit,rsplit.

Examples

julia> a = "Ma.r.ch";julia> collect(eachrsplit(a, ".")) == ["ch", "r", "Ma"]truejulia> collect(eachrsplit(a, "."; limit=2)) == ["ch", "Ma.r"]true

split(str::AbstractString, dlm; limit::Integer=0, keepempty::Bool=true)split(str::AbstractString; limit::Integer=0, keepempty::Bool=false)

Splitstr into an array of substrings on occurrences of the delimiter(s)dlm.dlm can be any of the formats allowed byfindnext's first argument (i.e. as a string, regular expression or a function), or as a single character or collection of characters.

Ifdlm is omitted, it defaults toisspace.

The optional keyword arguments are:

• limit: the maximum size of the result.limit=0 implies no maximum (default)
• keepempty: whether empty fields should be kept in the result. Default isfalse without adlm argument,true with adlm argument.

See alsorsplit,eachsplit.

Examples

julia> a = "Ma.rch""Ma.rch"julia> split(a, ".")2-element Vector{SubString{String}}: "Ma" "rch"

rsplit(s::AbstractString; limit::Integer=0, keepempty::Bool=false)rsplit(s::AbstractString, chars; limit::Integer=0, keepempty::Bool=true)

Similar tosplit, but starting from the end of the string.

Examples

julia> a = "M.a.r.c.h""M.a.r.c.h"julia> rsplit(a, ".")5-element Vector{SubString{String}}: "M" "a" "r" "c" "h"julia> rsplit(a, "."; limit=1)1-element Vector{SubString{String}}: "M.a.r.c.h"julia> rsplit(a, "."; limit=2)2-element Vector{SubString{String}}: "M.a.r.c" "h"

strip([pred=isspace,] str::AbstractString) -> SubStringstrip(str::AbstractString, chars) -> SubString

Remove leading and trailing characters fromstr, either those specified bychars or those for which the functionpred returnstrue.

The default behaviour is to remove leading and trailing whitespace and delimiters: seeisspace for precise details.

The optionalchars argument specifies which characters to remove: it can be a single character, vector or set of characters.

See alsolstrip andrstrip.

Examples

julia> strip("{3, 5}\n", ['{', '}', '\n'])"3, 5"

lstrip([pred=isspace,] str::AbstractString) -> SubStringlstrip(str::AbstractString, chars) -> SubString

Remove leading characters fromstr, either those specified bychars or those for which the functionpred returnstrue.

The default behaviour is to remove leading whitespace and delimiters: seeisspace for precise details.

The optionalchars argument specifies which characters to remove: it can be a single character, or a vector or set of characters.

See alsostrip andrstrip.

Examples

julia> a = lpad("March", 20)"               March"julia> lstrip(a)"March"

rstrip([pred=isspace,] str::AbstractString) -> SubStringrstrip(str::AbstractString, chars) -> SubString

Remove trailing characters fromstr, either those specified bychars or those for which the functionpred returnstrue.

The default behaviour is to remove trailing whitespace and delimiters: seeisspace for precise details.

The optionalchars argument specifies which characters to remove: it can be a single character, or a vector or set of characters.

See alsostrip andlstrip.

Examples

julia> a = rpad("March", 20)"March               "julia> rstrip(a)"March"

startswith(s::AbstractString, prefix::Union{AbstractString,Base.Chars})

Returntrue ifs starts withprefix, which can be a string, a character, or a tuple/vector/set of characters. Ifprefix is a tuple/vector/set of characters, test whether the first character ofs belongs to that set.

See alsoendswith,contains.

Examples

julia> startswith("JuliaLang", "Julia")true

startswith(io::IO, prefix::Union{AbstractString,Base.Chars})

Check if anIO object starts with a prefix, which can be either a string, a character, or a tuple/vector/set of characters. See alsopeek.

startswith(prefix)

Create a function that checks whether its argument starts withprefix, i.e. a function equivalent toy -> startswith(y, prefix).

The returned function is of typeBase.Fix2{typeof(startswith)}, which can be used to implement specialized methods.

Examples

julia> startswith("Julia")("JuliaLang")truejulia> startswith("Julia")("Ends with Julia")false

startswith(s::AbstractString, prefix::Regex)

Returntrue ifs starts with the regex pattern,prefix.

See alsooccursin andendswith.

Examples

julia> startswith("JuliaLang", r"Julia|Romeo")true

endswith(s::AbstractString, suffix::Union{AbstractString,Base.Chars})

Returntrue ifs ends withsuffix, which can be a string, a character, or a tuple/vector/set of characters. Ifsuffix is a tuple/vector/set of characters, test whether the last character ofs belongs to that set.

See alsostartswith,contains.

Examples

julia> endswith("Sunday", "day")true

endswith(suffix)

Create a function that checks whether its argument ends withsuffix, i.e. a function equivalent toy -> endswith(y, suffix).

The returned function is of typeBase.Fix2{typeof(endswith)}, which can be used to implement specialized methods.

Examples

julia> endswith("Julia")("Ends with Julia")truejulia> endswith("Julia")("JuliaLang")false

endswith(s::AbstractString, suffix::Regex)

Returntrue ifs ends with the regex pattern,suffix.

See alsooccursin andstartswith.

Examples

julia> endswith("JuliaLang", r"Lang|Roberts")true

contains(haystack::AbstractString, needle)

Returntrue ifhaystack containsneedle. This is the same asoccursin(needle, haystack), but is provided for consistency withstartswith(haystack, needle) andendswith(haystack, needle).

See alsooccursin,in,issubset.

Examples

julia> contains("JuliaLang is pretty cool!", "Julia")truejulia> contains("JuliaLang is pretty cool!", 'a')truejulia> contains("aba", r"a.a")truejulia> contains("abba", r"a.a")false

contains(needle)

Create a function that checks whether its argument containsneedle, i.e. a function equivalent tohaystack -> contains(haystack, needle).

The returned function is of typeBase.Fix2{typeof(contains)}, which can be used to implement specialized methods.

first(s::AbstractString, n::Integer)

Get a string consisting of the firstn characters ofs.

Examples

julia> first("∀ϵ≠0: ϵ²>0", 0)""julia> first("∀ϵ≠0: ϵ²>0", 1)"∀"julia> first("∀ϵ≠0: ϵ²>0", 3)"∀ϵ≠"

last(s::AbstractString, n::Integer)

Get a string consisting of the lastn characters ofs.

Examples

julia> last("∀ϵ≠0: ϵ²>0", 0)""julia> last("∀ϵ≠0: ϵ²>0", 1)"0"julia> last("∀ϵ≠0: ϵ²>0", 3)"²>0"

uppercase(c::AbstractChar)

Convertc to uppercase.

See alsolowercase,titlecase.

Examples

julia> uppercase('a')'A': ASCII/Unicode U+0041 (category Lu: Letter, uppercase)julia> uppercase('ê')'Ê': Unicode U+00CA (category Lu: Letter, uppercase)

uppercase(s::AbstractString)

Returns with all characters converted to uppercase.

See alsolowercase,titlecase,uppercasefirst.

Examples

julia> uppercase("Julia")"JULIA"

lowercase(c::AbstractChar)

Convertc to lowercase.

See alsouppercase,titlecase.

Examples

julia> lowercase('A')'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)julia> lowercase('Ö')'ö': Unicode U+00F6 (category Ll: Letter, lowercase)

lowercase(s::AbstractString)

Returns with all characters converted to lowercase.

See alsouppercase,titlecase,lowercasefirst.

Examples

julia> lowercase("STRINGS AND THINGS")"strings and things"

titlecase(c::AbstractChar)

Convertc to titlecase. This may differ from uppercase for digraphs, compare the example below.

See alsouppercase,lowercase.

Examples

julia> titlecase('a')'A': ASCII/Unicode U+0041 (category Lu: Letter, uppercase)julia> titlecase('dž')'Dž': Unicode U+01C5 (category Lt: Letter, titlecase)julia> uppercase('dž')'DŽ': Unicode U+01C4 (category Lu: Letter, uppercase)

titlecase(s::AbstractString; [wordsep::Function], strict::Bool=true) -> String

Capitalize the first character of each word ins; ifstrict is true, every other character is converted to lowercase, otherwise they are left unchanged. By default, all non-letters beginning a new grapheme are considered as word separators; a predicate can be passed as thewordsep keyword to determine which characters should be considered as word separators. See alsouppercasefirst to capitalize only the first character ins.

See alsouppercase,lowercase,uppercasefirst.

Examples

julia> titlecase("the JULIA programming language")"The Julia Programming Language"julia> titlecase("ISS - international space station", strict=false)"ISS - International Space Station"julia> titlecase("a-a b-b", wordsep = c->c==' ')"A-a B-b"

uppercasefirst(s::AbstractString) -> String

Returns with the first character converted to uppercase (technically "title case" for Unicode). See alsotitlecase to capitalize the first character of every word ins.

See alsolowercasefirst,uppercase,lowercase,titlecase.

Examples

julia> uppercasefirst("python")"Python"

lowercasefirst(s::AbstractString)

Returns with the first character converted to lowercase.

See alsouppercasefirst,uppercase,lowercase,titlecase.

Examples

julia> lowercasefirst("Julia")"julia"

join([io::IO,] iterator [, delim [, last]])

Join anyiterator into a single string, inserting the given delimiter (if any) between adjacent items. Iflast is given, it will be used instead ofdelim between the last two items. Each item ofiterator is converted to a string viaprint(io::IOBuffer, x). Ifio is given, the result is written toio rather than returned as aString.

Examples

julia> join(["apples", "bananas", "pineapples"], ", ", " and ")"apples, bananas and pineapples"julia> join([1,2,3,4,5])"12345"

chop(s::AbstractString; head::Integer = 0, tail::Integer = 1)

Remove the firsthead and the lasttail characters froms. The callchop(s) removes the last character froms. If it is requested to remove more characters thanlength(s) then an empty string is returned.

See alsochomp,startswith,first.

Examples

julia> a = "March""March"julia> chop(a)"Marc"julia> chop(a, head = 1, tail = 2)"ar"julia> chop(a, head = 5, tail = 5)""

chopprefix(s::AbstractString, prefix::Union{AbstractString,Regex}) -> SubString

Remove the prefixprefix froms. Ifs does not start withprefix, a string equal tos is returned.

See alsochopsuffix.

Examples

julia> chopprefix("Hamburger", "Ham")"burger"julia> chopprefix("Hamburger", "hotdog")"Hamburger"

chopsuffix(s::AbstractString, suffix::Union{AbstractString,Regex}) -> SubString

Remove the suffixsuffix froms. Ifs does not end withsuffix, a string equal tos is returned.

See alsochopprefix.

Examples

julia> chopsuffix("Hamburger", "er")"Hamburg"julia> chopsuffix("Hamburger", "hotdog")"Hamburger"

chomp(s::AbstractString) -> SubString

Remove a single trailing newline from a string.

See alsochop.

Examples

julia> chomp("Hello\n")"Hello"

thisind(s::AbstractString, i::Integer) -> Int

Ifi is in bounds ins return the index of the start of the character whose encoding code uniti is part of. In other words, ifi is the start of a character, returni; ifi is not the start of a character, rewind until the start of a character and return that index. Ifi is equal to 0 orncodeunits(s)+1 returni. In all other cases throwBoundsError.

Examples

julia> thisind("α", 0)0julia> thisind("α", 1)1julia> thisind("α", 2)1julia> thisind("α", 3)3julia> thisind("α", 4)ERROR: BoundsError: attempt to access 2-codeunit String at index [4][...]julia> thisind("α", -1)ERROR: BoundsError: attempt to access 2-codeunit String at index [-1][...]

nextind(str::AbstractString, i::Integer, n::Integer=1) -> Int

• Casen == 1

  Ifi is in bounds ins return the index of the start of the character whose encoding starts after indexi. In other words, ifi is the start of a character, return the start of the next character; ifi is not the start of a character, move forward until the start of a character and return that index. Ifi is equal to0 return1. Ifi is in bounds but greater or equal tolastindex(str) returnncodeunits(str)+1. Otherwise throwBoundsError.

• Casen > 1

  Behaves like applyingn timesnextind forn==1. The only difference is that ifn is so large that applyingnextind would reachncodeunits(str)+1 then each remaining iteration increases the returned value by1. This means that in this casenextind can return a value greater thanncodeunits(str)+1.

• Casen == 0

  Returni only ifi is a valid index ins or is equal to0. OtherwiseStringIndexError orBoundsError is thrown.

Examples

julia> nextind("α", 0)1julia> nextind("α", 1)3julia> nextind("α", 3)ERROR: BoundsError: attempt to access 2-codeunit String at index [3][...]julia> nextind("α", 0, 2)3julia> nextind("α", 1, 2)4

prevind(str::AbstractString, i::Integer, n::Integer=1) -> Int

• Casen == 1

  Ifi is in bounds ins return the index of the start of the character whose encoding starts before indexi. In other words, ifi is the start of a character, return the start of the previous character; ifi is not the start of a character, rewind until the start of a character and return that index. Ifi is equal to1 return0. Ifi is equal toncodeunits(str)+1 returnlastindex(str). Otherwise throwBoundsError.

• Casen > 1

  Behaves like applyingn timesprevind forn==1. The only difference is that ifn is so large that applyingprevind would reach0 then each remaining iteration decreases the returned value by1. This means that in this caseprevind can return a negative value.

• Casen == 0

  Returni only ifi is a valid index instr or is equal toncodeunits(str)+1. OtherwiseStringIndexError orBoundsError is thrown.

Examples

julia> prevind("α", 3)1julia> prevind("α", 1)0julia> prevind("α", 0)ERROR: BoundsError: attempt to access 2-codeunit String at index [0][...]julia> prevind("α", 2, 2)0julia> prevind("α", 2, 3)-1

textwidth(c)

Give the number of columns needed to print a character.

Examples

julia> textwidth('α')1julia> textwidth('⛵')2

textwidth(s::AbstractString)

Give the number of columns needed to print a string.

Examples

julia> textwidth("March")5

isascii(c::Union{AbstractChar,AbstractString}) -> Bool

Test whether a character belongs to the ASCII character set, or whether this is true for all elements of a string.

Examples

julia> isascii('a')truejulia> isascii('α')falsejulia> isascii("abc")truejulia> isascii("αβγ")false

For example,isascii can be used as a predicate function forfilter orreplace to remove or replace non-ASCII characters, respectively:

julia> filter(isascii, "abcdeγfgh") # discard non-ASCII chars"abcdefgh"julia> replace("abcdeγfgh", !isascii=>' ') # replace non-ASCII chars with spaces"abcde fgh"

isascii(cu::AbstractVector{CU}) where {CU <: Integer} -> Bool

Test whether all values in the vector belong to the ASCII character set (0x00 to 0x7f). This function is intended to be used by other string implementations that need a fast ASCII check.

iscntrl(c::AbstractChar) -> Bool

Tests whether a character is a control character. Control characters are the non-printing characters of the Latin-1 subset of Unicode.

Examples

julia> iscntrl('\x01')truejulia> iscntrl('a')false

isdigit(c::AbstractChar) -> Bool

Tests whether a character is a decimal digit (0-9).

See also:isletter.

Examples

julia> isdigit('❤')falsejulia> isdigit('9')truejulia> isdigit('α')false

isletter(c::AbstractChar) -> Bool

Test whether a character is a letter. A character is classified as a letter if it belongs to the Unicode general category Letter, i.e. a character whose category code begins with 'L'.

See also:isdigit.

Examples

julia> isletter('❤')falsejulia> isletter('α')truejulia> isletter('9')false

islowercase(c::AbstractChar) -> Bool

Tests whether a character is a lowercase letter (according to the Unicode standard'sLowercase derived property).

See alsoisuppercase.

Examples

julia> islowercase('α')truejulia> islowercase('Γ')falsejulia> islowercase('❤')false

isnumeric(c::AbstractChar) -> Bool

Tests whether a character is numeric. A character is classified as numeric if it belongs to the Unicode general category Number, i.e. a character whose category code begins with 'N'.

Note that this broad category includes characters such as ¾ and ௰. Useisdigit to check whether a character is a decimal digit between 0 and 9.

Examples

julia> isnumeric('௰')truejulia> isnumeric('9')truejulia> isnumeric('α')falsejulia> isnumeric('❤')false

isprint(c::AbstractChar) -> Bool

Tests whether a character is printable, including spaces, but not a control character.

Examples

julia> isprint('\x01')falsejulia> isprint('A')true

ispunct(c::AbstractChar) -> Bool

Tests whether a character belongs to the Unicode general category Punctuation, i.e. a character whose category code begins with 'P'.

Examples

julia> ispunct('α')falsejulia> ispunct('/')truejulia> ispunct(';')true

isspace(c::AbstractChar) -> Bool

Tests whether a character is any whitespace character. Includes ASCII characters '\t', '\n', '\v', '\f', '\r', and ' ', Latin-1 character U+0085, and characters in Unicode category Zs.

Examples

julia> isspace('\n')truejulia> isspace('\r')truejulia> isspace(' ')truejulia> isspace('\x20')true

isuppercase(c::AbstractChar) -> Bool

Tests whether a character is an uppercase letter (according to the Unicode standard'sUppercase derived property).

See alsoislowercase.

Examples

julia> isuppercase('γ')falsejulia> isuppercase('Γ')truejulia> isuppercase('❤')false

isxdigit(c::AbstractChar) -> Bool

Test whether a character is a valid hexadecimal digit. Note that this does not includex (as in the standard0x prefix).

Examples

julia> isxdigit('a')truejulia> isxdigit('x')false

escape_string(str::AbstractString[, esc]; keep = ())::AbstractStringescape_string(io, str::AbstractString[, esc]; keep = ())::Nothing

General escaping of traditional C and Unicode escape sequences. The first form returns the escaped string, the second prints the result toio.

Backslashes (\) are escaped with a double-backslash ("\\"). Non-printable characters are escaped either with their standard C escape codes,"\0" for NUL (if unambiguous), unicode code point ("\u" prefix) or hex ("\x" prefix).

The optionalesc argument specifies any additional characters that should also be escaped by a prepending backslash (" is also escaped by default in the first form).

The argumentkeep specifies a collection of characters which are to be kept as they are. Notice thatesc has precedence here.

See alsounescape_string for the reverse operation.

Examples

julia> escape_string("aaa\nbbb")"aaa\\nbbb"julia> escape_string("aaa\nbbb"; keep = '\n')"aaa\nbbb"julia> escape_string("\xfe\xff") # invalid utf-8"\\xfe\\xff"julia> escape_string(string('\u2135','\0')) # unambiguous"ℵ\\0"julia> escape_string(string('\u2135','\0','0')) # \0 would be ambiguous"ℵ\\x000"

escape_raw_string(s::AbstractString, delim='"') -> AbstractStringescape_raw_string(io, s::AbstractString, delim='"')

Escape a string in the manner used for parsing raw string literals. For each double-quote (") character in input strings (ordelim if specified), this function counts the numbern of preceding backslash (\) characters, and then increases there the number of backslashes fromn to 2n+1 (even forn = 0). It also doubles a sequence of backslashes at the end of the string.

This escaping convention is used in raw strings and other non-standard string literals. (It also happens to be the escaping convention expected by the Microsoft C/C++ compiler runtime when it parses a command-line string into the argv[] array.)

See alsoescape_string.

unescape_string(str::AbstractString, keep = ())::AbstractStringunescape_string(io, s::AbstractString, keep = ())::Nothing

General unescaping of traditional C and Unicode escape sequences. The first form returns the escaped string, the second prints the result toio. The argumentkeep specifies a collection of characters which (along with backlashes) are to be kept as they are.

The following escape sequences are recognised:

• Escaped backslash (\\)
• Escaped double-quote (\")
• Standard C escape sequences (\a,\b,\t,\n,\v,\f,\r,\e)
• Unicode BMP code points (\u with 1-4 trailing hex digits)
• All Unicode code points (\U with 1-8 trailing hex digits; max value = 0010ffff)
• Hex bytes (\x with 1-2 trailing hex digits)
• Octal bytes (\ with 1-3 trailing octal digits)

See alsoescape_string.

Examples

julia> unescape_string("aaa\\nbbb") # C escape sequence"aaa\nbbb"julia> unescape_string("\\u03c0") # unicode"π"julia> unescape_string("\\101") # octal"A"julia> unescape_string("aaa \\g \\n", ['g']) # using `keep` argument"aaa \\g \n"

AnnotatedString{S <: AbstractString} <: AbstractString

A string with metadata, in the form of annotated regions.

More specifically, this is a simple wrapper around any otherAbstractString that allows for regions of the wrapped string to be annotated with labeled values.

                           C                    ┌──────┸─────────┐  "this is an example annotated string"  └──┰────────┼─────┘         │     A        └─────┰─────────┘                    B

The above diagram represents aAnnotatedString where three ranges have been annotated (labeledA,B, andC). Each annotation holds a label (Symbol) and a value (Any). These three pieces of information are held as a@NamedTuple{region::UnitRange{Int64}, label::Symbol, value}.

Labels do not need to be unique, the same region can hold multiple annotations with the same label.

Code written forAnnotatedStrings in general should conserve the following properties:

• Which characters an annotation is applied to
• The order in which annotations are applied to each character

Additional semantics may be introduced by specific uses ofAnnotatedStrings.

A corollary of these rules is that adjacent, consecutively placed, annotations with identical labels and values are equivalent to a single annotation spanning the combined range.

See alsoAnnotatedChar,annotatedstring,annotations, andannotate!.

Constructors

AnnotatedString(s::S<:AbstractString) -> AnnotatedString{S}AnnotatedString(s::S<:AbstractString, annotations::Vector{@NamedTuple{region::UnitRange{Int64}, label::Symbol, value}})

A AnnotatedString can also be created withannotatedstring, which acts much likestring but preserves any annotations present in the arguments.

Examples

julia> AnnotatedString("this is an example annotated string",                    [(1:18, :A => 1), (12:28, :B => 2), (18:35, :C => 3)])"this is an example annotated string"

AnnotatedChar{S <: AbstractChar} <: AbstractChar

A Char with annotations.

More specifically, this is a simple wrapper around any otherAbstractChar, which holds a list of arbitrary labelled annotations (@NamedTuple{label::Symbol, value}) with the wrapped character.

See also:AnnotatedString,annotatedstring,annotations, andannotate!.

Constructors

AnnotatedChar(s::S) -> AnnotatedChar{S}AnnotatedChar(s::S, annotations::Vector{@NamedTuple{label::Symbol, value}})

Examples

julia> AnnotatedChar('j', :label => 1)'j': ASCII/Unicode U+006A (category Ll: Letter, lowercase)

annotatedstring(values...)

Create aAnnotatedString from any number ofvalues using theirprinted representation.

This acts likestring, but takes care to preserve any annotations present (in the form ofAnnotatedString orAnnotatedChar values).

See alsoAnnotatedString andAnnotatedChar.

Examples

julia> annotatedstring("now a AnnotatedString")"now a AnnotatedString"julia> annotatedstring(AnnotatedString("annotated", [(1:9, :label => 1)]), ", and unannotated")"annotated, and unannotated"

annotations(str::Union{AnnotatedString, SubString{AnnotatedString}},            [position::Union{Integer, UnitRange}]) ->    Vector{@NamedTuple{region::UnitRange{Int64}, label::Symbol, value}}

Get all annotations that apply tostr. Shouldposition be provided, only annotations that overlap withposition will be returned.

Annotations are provided together with the regions they apply to, in the form of a vector of region–annotation tuples.

In accordance with the semantics documented inAnnotatedString, the order of annotations returned matches the order in which they were applied.

See also:annotate!.

annotations(chr::AnnotatedChar) -> Vector{@NamedTuple{label::Symbol, value}}

Get all annotations ofchr, in the form of a vector of annotation pairs.

annotate!(str::AnnotatedString, [range::UnitRange{Int}], label::Symbol, value)annotate!(str::SubString{AnnotatedString}, [range::UnitRange{Int}], label::Symbol, value)

Annotate arange ofstr (or the entire string) with a labeled value (label =>value). To remove existinglabel annotations, use a value ofnothing.

The order in which annotations are applied tostr is semantically meaningful, as described inAnnotatedString.

annotate!(char::AnnotatedChar, label::Symbol, value::Any)

Annotatechar with the pairlabel => value.