logo

const final class

sys::Str

sys::Obj
  sys::Str

Str represents a sequence of Unicode characters.

Slots

all

Bool all(|Int, Int -> Bool| c)

Return true if c returns true for all of the characters in this string. If this string is empty, return true.

Example:

"Bar".all |Int c->Bool| { return c.isUpper } => false
"BAR".any |Int c->Bool| { return c.isUpper } => true
any

Bool any(|Int, Int -> Bool| c)

Return true if c returns true for any of the characters in this string. If this string is empty, return false.

Example:

"Foo".any |Int c->Bool| { return c.isUpper } => true
"foo".any |Int c->Bool| { return c.isUpper } => false
capitalize

Str capitalize()

Return this string with the first character converted uppercase. The case conversion is for ASCII only. Also see decapitalize and localeCapitalize.

Example:

"foo".capitalize => "Foo"
compare

override Int compare(Obj obj)

Compare based on Unicode character values. Case is not not taken into account - also see compareIgnoreCase and localeCompare.

Examples:

"a".compare("b")    =>  -1
"hi".compare("hi")  =>  0
"hi".compare("HI")  =>  1
"b".compare("a")    =>  1
compareIgnoreCase

Int compareIgnoreCase(Str s)

Compare two strings without regard to case and return -1, 0, or 1 if this string is less than, equal to, or greater than the specified string. Only ASCII character case is taken into account. See localeCompare for localized case insensitive comparisions.

Examples:

"a".compareIgnoreCase("b")    =>  -1
"hi".compareIgnoreCase("HI")  =>  0
"b".compareIgnoreCase("a")    =>  1
contains

Bool contains(Str s)

Return if this string contains the specified string. Convenience for index(s) != null

decapitalize

Str decapitalize()

Return this string with the first character converted lowercase. The case conversion is for ASCII only. Also see capitalize and localeDecapitalize.

Example:

"Foo".decapitalize => "foo"
each

Void each(|Int, Int| c)

Call the specified function for every char in the starting with index 0 and incrementing up to size-1. This method is idempotent.

Example:

"abc".each |Int c| { echo(c.toChar) }
eachr

Void eachr(|Int, Int| c)

Reverse each - call the specified function for every char in the string starting with index size-1 and decrementing down to 0. This method is idempotent.

Example:

"abc".eachr |Int c| { echo(c.toChar) }
endsWith

Bool endsWith(Str s)

Return if this Str ends with the specified Str.

equals

override Bool equals(Obj obj)

Return true if a Str with exact same char sequence.

equalsIgnoreCase

Bool equalsIgnoreCase(Str s)

Convenience for compareIgnoreCase(s) == 0. Only ASCII character case is taken into account. See localeCompare for localized case insensitive comparisions.

get

Int get(Int index)

Get the character at the zero based index as a Unicode code point. Negative indexes may be used to access from the end of the string. This method is accessed via the [] operator.

hash

override Int hash()

The hash for a Str is platform dependent.

index

Int index(Str s, Int offset := 0)

Return the first occurance of the specified substring searching forward, starting at the specified offset index. A negative offset may be used to access from the end of string. Return null if no occurences are found.

Examples:

"abcabc".index("b")     => 1
"abcabc".index("b", 1)  => 1
"abcabc".index("b", 3)  => 4
"abcabc".index("b", -3) => 4
"abcabc".index("x")     => null
indexr

Int indexr(Str s, Int offset := -1)

Reverse index - return the first occurance of the specified substring searching backward, starting at the specified offset index. A negative offset may be used to access from the end of string. Return null if no occurences are found.

Examples:

"abcabc".indexr("b")     => 4
"abcabc".indexr("b", -3) => 1
"abcabc".indexr("b", 0)  => null
intern

Str intern()

Internalize this Str such that two strings which are equal via the == operator will have the same reference such that === will be true.

isEmpty

Bool isEmpty()

Return if size() == 0.

isLower

Bool isLower()

Return if every character in this Str is ASCII lowercase: a-'z'.

isSpace

Bool isSpace()

Return if every character in this Str is whitespace: space \t \n \r \f

isUpper

Bool isUpper()

Return if every character in this Str is ASCII uppercase: A-'Z'.

justl

Str justl(Int width)

If size is less than width, then add spaces to the right to create a left justified string.

Examples:

"xyz".justl(2) => "xyz"
"xyz".justl(4) => "xyz "
justr

Str justr(Int width)

If size is less than width, then add spaces to the left to create a right justified string.

Examples:

"xyz".justr(2) => "xyz"
"xyz".justr(4) => " xyz"
localeCapitalize

Str localeCapitalize()

Return this string with the first character converted to uppercase using the current locale. Also see localeDecapitalize and capitalize.

localeCompare

Int localeCompare(Str s)

Compare two strings without regard to case according to the current locale. Return -1, 0, or 1 if this string is less than, equal to, or greater than the specified string.

Examples (assuming English locale):

"a".localeCompare("b")   =>  -1
"hi".localeCompare("HI") =>  0
"b".localeCompare("A")   =>  1
localeDecapitalize

Str localeDecapitalize()

Return this string with the first character converted to lowercase using the current locale. Also see localeCapitalize and decapitalize.

localeLower

Str localeLower()

Return this string with all uppercase characters replaced to lowercase using the current locale. Also see localeUpper, lower, and Int.localeLower.

localeUpper

Str localeUpper()

Return this string with all lowercase characters replaced to uppercase using the current locale. Also see localeLower, upper, and Int.localeUpper.

lower

Str lower()

Return this string with all uppercase characters replaced to lowercase. The case conversion is for ASCII only. Also see upper, localeLower, Int.lower, Int.localeLower.

Example:

"Apple".lower => "apple"
plus

Str plus(Obj obj)

Concat the value of obj.toStr

replace

Str replace(Str from, Str to)

Replace all occurances of from with to. TODO: just temp hack

reverse

Str reverse()

Reverse the contents of this string.

Example:

"stressed".reverse => "desserts"
size

Int size()

Return number of characters in this string.

slice

Str slice(Range range)

Return a substring based on the specified range. Negative indexes may be used to access from the end of the string. This method is accessed via the [] operator. Throw IndexErr if range illegal.

Examples:

"abcd"[0..2]   => "abc"
"abcd"[3..3]   => "d"
"abcd"[-2..-1] => "cd"
"abcd"[0...2]  => "ab"
"abcd"[1..-2]  => "bc"
"abcd"[4..-1]  => ""
spaces

static Str spaces(Int n)

Get the a Str containing the specified number of spaces. Also see justl and justr to justify an existing string.

Examples:

Str.spaces(1)  =>  " "
Str.spaces(2)  =>  "  "
split

Str[] split(Str separators)

Split a string into a list of substrings using the given separators TODO: just temp hack

startsWith

Bool startsWith(Str s)

Return if this Str starts with the specified Str.

toBool

Bool toBool(Bool checked := true)

Convenience for Bool.fromStr using this string.

toCode

Str toCode(Int quote := 34, Bool escapeUnicode := false)

Return this string as its Fan source code and serialization representation surrounded by the specified quote character (which defaults to "). If quote is null then the return is unquoted. This method will backslash escape the following characters: \n \r \f \t \\ $. If the quote character is the double quote, single quote, or backtick then it is escaped too. If escapeUnicode is true then any character over 127 is also escaped as \uXXXX.

toFloat

Float toFloat(Bool checked := true)

Convenience for Float.fromStr using this string.

toInt

Int toInt(Int radix := 10, Bool checked := true)

Convenience for Int.fromStr using this string.

toStr

override Str toStr()

Return this.

toUri

Uri toUri()

Convenience for Uri.fromStr using this string.

toXml

Str toXml()

Return this string as valid XML text. The special control characters amp, lt, apos and quot are always escaped. The gt char is escaped only if it is the first char or if preceeded by the ] char. Also see web::WebOutStream.esc.

trim

Str trim()

Trim whitespace from the beginning and end of the string. For the purposes of this method, whitespace is defined as any character equal to or less than the 0x20 space character (including , \r, \n, and \t).

Examples:

"foo".trim => "foo"
"  foo".trim => "foo"
"  foo\n".trim => "foo"
upper

Str upper()

Return this string with all lowercase characters replaced to uppercase. The case conversion is for ASCII only. Also see lower, localeUpper, Int.upper, Int.localeUpper.

Example:

"Foo Bar".upper => "FOO BAR"