const class sys::Str

sys::Obj
  sys::Str

Str represents a sequence of Unicode characters.

all

Bool all(Func<Bool,Int,Int> f)

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

Example:

"Bar".all |c| { c.isUpper } => false
"BAR".all |c| { c.isUpper } => true

any

Bool any(Func<Bool,Int,Int> f)

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

Example:

"Foo".any |c| { c.isUpper } => true
"foo".any |c| { c.isUpper } => false

byteLen

Int byteLen()

size of utf8

chars

Array<Int32> chars()

Get the characters in this string as a list of integer code points. Also see fromChars.

compare

virtual 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

containsChar

Bool containsChar(Int ch)

Return if this string contains the specified character.

defVal

const static Str defVal := ""

Default value is "".

each

Void each(Func<Void,Int,Int> f)

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

Example:

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

eachr

Void eachr(Func<Void,Int,Int> f)

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

Example:

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

endsWith

Bool endsWith(Str s)

Return if this Str ends with the specified Str.

equals

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

find

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

Return the first occurance of the specified substring searching forward, starting at the specified offset index. Return -1 if no occurences are found.

Examples:

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

findr

Int findr(Str s, Int offset := s.size() - 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 -1 if no occurences are found.

Examples:

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

format

static Str format(Str format, List<Obj> args)

Returns a formatted string using the specified format string and arguments.

fromCStr

static Str fromCStr(Ptr<Int8> utf8, Int byteLen := -1)

allocType: 0:copy, 1:static, 2:move

fromChars

static Str fromChars(Array<Int32> charPtr, Int offset := 0, Int len := charPtr.size())

Construct a string from a list of unicode code points. Also see chars.

fromUtf8

static new fromUtf8(Array<Int8> ba, Int offset := 0, Int len := ba.size())

get

@Operator
Int get(Int index)

Get the character at the zero based index as a Unicode code point. This method is accessed via the [] operator. Throw IndexErr if the index is out of range.

getByte

Int getByte(Int i)

Get the byte at postion

getRange

@Operator
Str getRange(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]  => ""

getSafe

Int getSafe(Int index, Int defV := 0)

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. Unlike get, this method does not throw IndexErr when the index is out or range, instead it returns def.

hash

virtual override Int hash()

The hash for a Str is platform dependent.

indexIgnoreCase

Int? indexIgnoreCase(Str s, Int offset := 0)

Find the index just like index, but ignoring case for ASCII chars only.

indexrIgnoreCase

Int? indexrIgnoreCase(Str s, Int offset := -1)

Find the index just like indexr, but ignoring case for ASCII chars only.

isAlpha

Bool isAlpha()

Return if every char is an ASCII letter.

isAlphaNum

Bool isAlphaNum()

Return if every char is an ASCII alpha-numeric.

isAscii

Bool isAscii()

Return if every character in this Str is a US-ASCII character less than 128.

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

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

@Operator
Str plus(Obj? obj)

Concat the value of obj.toStr

replace

Str replace(Str from, Str to)

Replace all occurrences of from with to.

Examples:

"hello".replace("hell", "t")  =>  "to"
"aababa".replace("ab", "-")   =>  "a--a"

size

Int size()

Return number of characters in this string.

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

List<Str> split(Int? separator := null, Bool trimmed := true)

Split a string into a list of substrings using the given separator character. If there are contiguous separators, then they are split into empty strings. If trim is true, then whitespace is trimmed from the beginning and end of the results.

If separator is null, then the string is split according to any sequence of whitespace characters (any character equal to or less than the 0x20 space character including , \r, \n, and \t).

If this is the empty string or there are no splits return a list of one item.

Examples:

// split on whitespace
"".split                   =>  [""]
"x".split                  =>  ["x"]
"x y".split                =>  ["x", "y"]
" x y ".split              =>  ["x", "y"]
" x \n y \n z ".split      =>  ["x", "y", "z"]

// split on sep with trim
"".split('|')              =>  [""]
"22".split(';')            =>  ["22"]
"22;33".split(';')         =>  ["22","33"]
"22, 33".split(',')        =>  ["22","33"]
" 22 ; 33 ".split(';')     =>  ["22","33"]

// split on sep with no trim
"22#33".split('#', false)  =>  ["22","33"]
" x ; y".split(';', false) =>  [" x "," y"]

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 Fantom 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. Control chars less than 0x20 are escaped as \uXXXX. If escapeUnicode is true then any char over 0x7F it is 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

virtual override Str toStr()

Return this.

toUtf8

Array<Int8> toUtf8()

Get this string encoded into a buffer of bytes.

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 ".trim    =>  "foo"
"  foo\n".trim  =>  "foo"
"   ".trim      =>  ""

trimEnd

Str trimEnd()

Trim whitespace only from the end of the string. See trim for definition of whitespace.

Examples:

"foo".trim    =>  "foo"
" foo ".trim  =>  " foo"

trimStart

Str trimStart()

Trim whitespace only from the beginning of the string. See trim for definition of whitespace.

Examples:

"foo".trim    =>  "foo"
" foo ".trim  =>  "foo "

trimToNull

Str? trimToNull()

Trim whitespace from the beginning and end of the string. Should the resultant string be empty, null is returned.

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".trimToNull      =>  "foo"
"  foo  ".trimToNull  =>  "foo"
"".trimToNull         =>  null
"   ".trimToNull      =>  null

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"