Strings

Strings

Base.lengthMethod.
length(s::AbstractString)

The number of characters in string s.

Example

julia> length("jμΛIα")
5
source
Base.sizeofMethod.
sizeof(s::AbstractString)

The number of bytes in string s.

Example

julia> sizeof("❤")
3
source
Base.:*Method.
*(x, y...)

Multiplication operator. x*y*z*... calls this function with all arguments, i.e. *(x, y, z, ...).

source
Base.:^Method.
^(s::AbstractString, n::Integer)

Repeat n times the string s. The repeat function is an alias to this operator.

julia> "Test "^3
"Test Test Test "
source
Base.stringFunction.
string(xs...)

Create a string from any values using the print function.

julia> string("a", 1, true)
"a1true"
source
Base.reprFunction.
repr(x)

Create a string from any value using the showall function.

source
Core.StringMethod.
String(s::AbstractString)

Convert a string to a contiguous byte array representation encoded as UTF-8 bytes. This representation is often appropriate for passing strings to C.

source
Base.transcodeFunction.
transcode(T, src)

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

The transcode 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.

source
Base.unsafe_stringFunction.
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.) If length is specified (the length of the data in bytes), the string does not have to be NUL-terminated.

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

source
Base.codeunitMethod.
codeunit(s::AbstractString, i::Integer)

Get the ith code unit of an encoded string. For example, returns the ith byte of the representation of a UTF-8 string.

source
Base.asciiFunction.
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.

julia> ascii("abcdeγfgh")
ERROR: ArgumentError: invalid ASCII at index 6 in "abcdeγfgh"
Stacktrace:
 [1] ascii(::String) at ./strings/util.jl:479

julia> ascii("abcdefgh")
"abcdefgh"
source
Base.@r_strMacro.
@r_str -> Regex

Construct a regex, such as r"^[a-z]*$". 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.

For example, this regex has all three flags enabled:

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

Create an HTML object from a literal string.

source
@text_str -> Docs.Text

Create a Text object from a literal string.

source
normalize_string(s::AbstractString, normalform::Symbol)

Normalize the string s according to one of the four "normal forms" of the Unicode standard: normalform can be :NFC, :NFD, :NFKC, or :NFKD. Normal forms C (canonical composition) and D (canonical decomposition) convert different visually identical representations of the same abstract string into a single canonical form, with form C being more compact. Normal forms KC and KD additionally canonicalize "compatibility equivalents": they convert characters that are abstractly similar but visually distinct into a single canonical choice (e.g. they expand ligatures into the individual characters), with form KC being more compact.

Alternatively, finer control and additional transformations may be be obtained by calling normalize_string(s; keywords...), where any number of the following boolean keywords options (which all default to false except for compose) are specified:

  • compose=false: do not perform canonical composition

  • decompose=true: do canonical decomposition instead of canonical composition (compose=true is ignored if present)

  • compat=true: compatibility equivalents are canonicalized

  • casefold=true: perform Unicode case folding, e.g. for case-insensitive string comparison

  • newline2lf=true, newline2ls=true, or newline2ps=true: convert various newline sequences (LF, CRLF, CR, NEL) into a linefeed (LF), line-separation (LS), or paragraph-separation (PS) character, respectively

  • stripmark=true: strip diacritical marks (e.g. accents)

  • stripignore=true: strip Unicode's "default ignorable" characters (e.g. the soft hyphen or the left-to-right marker)

  • stripcc=true: strip control characters; horizontal tabs and form feeds are converted to spaces; newlines are also converted to spaces unless a newline-conversion flag was specified

  • rejectna=true: throw an error if unassigned code points are found

  • stable=true: enforce Unicode Versioning Stability

For example, NFKC corresponds to the options compose=true, compat=true, stable=true.

source
graphemes(s::AbstractString) -> GraphemeIterator

Returns an iterator over substrings of s that correspond to the extended graphemes in the string, as defined by Unicode UAX #29. (Roughly, these are what users would perceive as single characters, even though they may contain more than one codepoint; for example a letter combined with an accent mark is a single grapheme.)

source
Base.isvalidMethod.
isvalid(value) -> Bool

Returns true if the given value is valid for its type, which currently can be either Char or String.

source
Base.isvalidMethod.
isvalid(T, value) -> Bool

Returns true if the given value is valid for that type. Types currently can be either Char or String. Values for Char can be of type Char or UInt32. Values for String can be of that type, or Vector{UInt8}.

source
Base.isvalidMethod.
isvalid(str::AbstractString, i::Integer)

Tells whether index i is valid for the given string.

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: UnicodeError: invalid character index
[...]
source
is_assigned_char(c) -> Bool

Returns true if the given char or integer is an assigned Unicode code point.

source
Base.ismatchFunction.
ismatch(r::Regex, s::AbstractString) -> Bool

Test whether a string contains a match of the given regular expression.

source
Base.matchFunction.
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.

source
Base.eachmatchFunction.
eachmatch(r::Regex, s::AbstractString[, overlap::Bool=false])

Search for all matches of a the regular expression r in s and return a 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.

source
Base.matchallFunction.
matchall(r::Regex, s::AbstractString[, overlap::Bool=false]) -> Vector{AbstractString}

Return a vector of the matching substrings from eachmatch.

source
Base.lpadFunction.
lpad(s, n::Integer, p::AbstractString=" ")

Make a string at least n columns wide when printed by padding s on the left with copies of p.

julia> lpad("March",10)
"     March"
source
Base.rpadFunction.
rpad(s, n::Integer, p::AbstractString=" ")

Make a string at least n columns wide when printed by padding s on the right with copies of p.

julia> rpad("March",20)
"March               "
source
Base.searchFunction.
search(string::AbstractString, chars::Chars, [start::Integer])

Search for the first occurrence of the given characters within the given string. The second argument may be a single character, a vector or a set of characters, a string, or a regular expression (though regular expressions are only allowed on contiguous strings, such as ASCII or UTF-8 strings). The third argument optionally specifies a starting index. The return value is a range of indexes where the matching sequence is found, such that s[search(s,x)] == x:

search(string, "substring") = start:end such that string[start:end] == "substring", or 0:-1 if unmatched.

search(string, 'c') = index such that string[index] == 'c', or 0 if unmatched.

julia> search("Hello to the world", "z")
0:-1

julia> search("JuliaLang","Julia")
1:5
source
Base.rsearchFunction.
rsearch(s::AbstractString, chars::Chars, [start::Integer])

Similar to search, but returning the last occurrence of the given characters within the given string, searching in reverse from start.

julia> rsearch("aaabbb","b")
6:6
source
Base.searchindexFunction.
searchindex(s::AbstractString, substring, [start::Integer])

Similar to search, but return only the start index at which the substring is found, or 0 if it is not.

julia> searchindex("Hello to the world", "z")
0

julia> searchindex("JuliaLang","Julia")
1

julia> searchindex("JuliaLang","Lang")
6
source
Base.rsearchindexFunction.
rsearchindex(s::AbstractString, substring, [start::Integer])

Similar to rsearch, but return only the start index at which the substring is found, or 0 if it is not.

julia> rsearchindex("aaabbb","b")
6

julia> rsearchindex("aaabbb","a")
3
source
Base.containsMethod.
contains(haystack::AbstractString, needle::AbstractString)

Determine whether the second argument is a substring of the first.

julia> contains("JuliaLang is pretty cool!", "Julia")
true
source
Base.reverseMethod.
reverse(s::AbstractString) -> AbstractString

Reverses a string.

julia> reverse("JuliaLang")
"gnaLailuJ"
source
Base.replaceFunction.
replace(string::AbstractString, pat, r[, n::Integer=0])

Search for the given pattern pat, and replace each occurrence with r. If n is provided, replace at most n occurrences. As with search, the second argument may be a single character, a vector or a set of characters, a string, or a regular expression. If r is a function, each occurrence is replaced with r(s) where s is the matched substring. If pat is a regular expression and r is a SubstitutionString, then capture group references in r are replaced with the corresponding matched text.

source
Base.splitFunction.
split(s::AbstractString, [chars]; limit::Integer=0, keep::Bool=true)

Return an array of substrings by splitting the given string on occurrences of the given character delimiters, which may be specified in any of the formats allowed by search's second argument (i.e. a single character, collection of characters, string, or regular expression). If chars is omitted, it defaults to the set of all space characters, and keep is taken to be false. The two keyword arguments are optional: they are a maximum size for the result and a flag determining whether empty fields should be kept in the result.

julia> a = "Ma.rch"
"Ma.rch"

julia> split(a,".")
2-element Array{SubString{String},1}:
 "Ma"
 "rch"
source
Base.rsplitFunction.
rsplit(s::AbstractString, [chars]; limit::Integer=0, keep::Bool=true)

Similar to split, but starting from the end of the string.

julia> a = "M.a.r.c.h"
"M.a.r.c.h"

julia> rsplit(a,".")
5-element Array{SubString{String},1}:
 "M"
 "a"
 "r"
 "c"
 "h"

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

julia> rsplit(a,".";limit=2)
2-element Array{SubString{String},1}:
 "M.a.r.c"
 "h"
source
Base.stripFunction.
strip(s::AbstractString, [chars::Chars])

Return s with any leading and trailing whitespace removed. If chars (a character, or vector or set of characters) is provided, instead remove characters contained in it.

julia> strip("{3, 5}\n", ['{', '}', '\n'])
"3, 5"
source
Base.lstripFunction.
lstrip(s::AbstractString[, chars::Chars])

Return s with any leading whitespace and delimiters removed. The default delimiters to remove are ' ', \t, \n, \v, \f, and \r. If chars (a character, or vector or set of characters) is provided, instead remove characters contained in it.

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

julia> lstrip(a)
"March"
source
Base.rstripFunction.
rstrip(s::AbstractString[, chars::Chars])

Return s with any trailing whitespace and delimiters removed. The default delimiters to remove are ' ', \t, \n, \v, \f, and \r. If chars (a character, or vector or set of characters) is provided, instead remove characters contained in it.

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

julia> rstrip(a)
"March"
source
Base.startswithFunction.
startswith(s::AbstractString, prefix::AbstractString)

Returns true if s starts with prefix. If prefix is a vector or set of characters, tests whether the first character of s belongs to that set.

See also endswith.

julia> startswith("JuliaLang", "Julia")
true
source
Base.endswithFunction.
endswith(s::AbstractString, suffix::AbstractString)

Returns true if s ends with suffix. If suffix is a vector or set of characters, tests whether the last character of s belongs to that set.

See also startswith.

julia> endswith("Sunday", "day")
true
source
Base.uppercaseFunction.
uppercase(s::AbstractString)

Returns s with all characters converted to uppercase.

Example

julia> uppercase("Julia")
"JULIA"
source
Base.lowercaseFunction.
lowercase(s::AbstractString)

Returns s with all characters converted to lowercase.

Example

julia> lowercase("STRINGS AND THINGS")
"strings and things"
source
Base.titlecaseFunction.
titlecase(s::AbstractString)

Capitalizes the first character of each word in s.

Example

julia> titlecase("the julia programming language")
"The Julia Programming Language"
source
Base.ucfirstFunction.
ucfirst(s::AbstractString)

Returns string with the first character converted to uppercase.

Example

julia> ucfirst("python")
"Python"
source
Base.lcfirstFunction.
lcfirst(s::AbstractString)

Returns string with the first character converted to lowercase.

Example

julia> lcfirst("Julia")
"julia"
source
Base.joinFunction.
join(io::IO, strings, delim, [last])

Join an array of strings into a single string, inserting the given delimiter between adjacent strings. If last is given, it will be used instead of delim between the last two strings. For example,

julia> join(["apples", "bananas", "pineapples"], ", ", " and ")
"apples, bananas and pineapples"

strings can be any iterable over elements x which are convertible to strings via print(io::IOBuffer, x). strings will be printed to io.

source
Base.chopFunction.
chop(s::AbstractString)

Remove the last character from s.

julia> a = "March"
"March"

julia> chop(a)
"Marc"
source
Base.chompFunction.
chomp(s::AbstractString)

Remove a single trailing newline from a string.

julia> chomp("Hello\n")
"Hello"
source
Base.ind2chrFunction.
ind2chr(s::AbstractString, i::Integer)

Convert a byte index i to a character index with respect to string s.

See also chr2ind.

Example

julia> str = "αβγdef";

julia> ind2chr(str, 3)
2

julia> chr2ind(str, 2)
3
source
Base.chr2indFunction.
chr2ind(s::AbstractString, i::Integer)

Convert a character index i to a byte index.

See also ind2chr.

Example

julia> str = "αβγdef";

julia> chr2ind(str, 2)
3

julia> ind2chr(str, 3)
2
source
Base.nextindFunction.
nextind(str::AbstractString, i::Integer)

Get the next valid string index after i. Returns a value greater than endof(str) at or after the end of the string.

Examples

julia> str = "αβγdef";

julia> nextind(str, 1)
3

julia> endof(str)
9

julia> nextind(str, 9)
10
source
Base.previndFunction.
prevind(str::AbstractString, i::Integer)

Get the previous valid string index before i. Returns a value less than 1 at the beginning of the string.

Examples

julia> prevind("αβγdef", 3)
1

julia> prevind("αβγdef", 1)
0
source
randstring([rng,] len=8)

Create a random ASCII string of length len, consisting of upper- and lower-case letters and the digits 0-9. The optional rng argument specifies a random number generator, see Random Numbers.

Example

julia> rng = MersenneTwister(1234);

julia> randstring(rng, 4)
"mbDd"
source
charwidth(c)

Gives the number of columns needed to print a character.

source
Base.strwidthFunction.
strwidth(s::AbstractString)

Gives the number of columns needed to print a string.

Example

julia> strwidth("March")
5
source
Base.UTF8proc.isalnumFunction.
isalnum(c::Char) -> Bool

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

source
Base.UTF8proc.isalphaFunction.
isalpha(c::Char) -> Bool

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

source
Base.isasciiFunction.
isascii(c::Union{Char,AbstractString}) -> Bool

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

source
Base.UTF8proc.iscntrlFunction.
iscntrl(c::Char) -> Bool

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

source
Base.UTF8proc.isdigitFunction.
isdigit(c::Char) -> Bool

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

source
Base.UTF8proc.isgraphFunction.
isgraph(c::Char) -> Bool

Tests whether a character is printable, and not a space. Any character that would cause a printer to use ink should be classified with isgraph(c)==true.

source
Base.UTF8proc.islowerFunction.
islower(c::Char) -> Bool

Tests whether a character is a lowercase letter. A character is classified as lowercase if it belongs to Unicode category Ll, Letter: Lowercase.

source
isnumber(c::Char) -> 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'.

source
Base.UTF8proc.isprintFunction.
isprint(c::Char) -> Bool

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

source
Base.UTF8proc.ispunctFunction.
ispunct(c::Char) -> Bool

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

source
Base.UTF8proc.isspaceFunction.
isspace(c::Char) -> 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.

source
Base.UTF8proc.isupperFunction.
isupper(c::Char) -> Bool

Tests whether a character is an uppercase letter. A character is classified as uppercase if it belongs to Unicode category Lu, Letter: Uppercase, or Lt, Letter: Titlecase.

source
Base.isxdigitFunction.
isxdigit(c::Char) -> Bool

Tests whether a character is a valid hexadecimal digit. Note that this does not include x (as in the standard 0x prefix).

Example

julia> isxdigit('a')
true

julia> isxdigit('x')
false
source
Core.SymbolType.
Symbol(x...) -> Symbol

Create a Symbol by concatenating the string representations of the arguments together.

source
Base.escape_stringFunction.
escape_string([io,] str::AbstractString[, esc::AbstractString]) -> AbstractString

General escaping of traditional C and Unicode escape sequences. Any characters in esc are also escaped (with a backslash). See also unescape_string.

source
Base.unescape_stringFunction.
unescape_string([io,] s::AbstractString) -> AbstractString

General unescaping of traditional C and Unicode escape sequences. Reverse of escape_string.

source