Home
Getting Started
Current Status
Documentation
- frostc
- Syntax
  - Keywords
  - Statements
    - Assignment
    - Method Calls
    - if
    - for
    - while
    - do
    - loop
    - break
    - continue
    - return
    - assert
    - unreachable
    - match
    - try
  - Expressions
  - Annotations
  - Comments
  - Documentation Comments
  - Error Handling
- Classes
  - Interfaces
  - Choices
  - Values
  - Immutability
  - Packages
    - Uses
  - Generics
  - Bare Code
- Methods
- Fields
- Types
- Variables and Constants
- Memory
  - Weak References
- Threads
API Documentation
- frostcollections Array Collection CollectionView CollectionWriter DefaultHashMap HashKey HashMap HashSet IdentityMap IdentitySet ImmutableArray Iterable Iterator List ListView ListWriter Map MapView MapWriter Stack core Bit Char16 Char32 Char8 Comparable Equatable Error Formattable Immutable Int Int16 Int32 Int64 Int8 Matcher Maybe MutableString Index MutableValue Object Range Real32 Real64 RegularExpression SteppedRange String Index Match System Process UInt UInt16 UInt32 UInt64 UInt8 Value Weak io ByteOrder Console File IndentedOutputStream InputStream LineNumberInputStream MemoryInputStream MemoryOutputStream OutputStream PushbackInputStream math Random XorShift128Plus threads Lock MessageQueue Notifier ScopedLock Thread time Timer unsafe Pointer UnsafeMessageQueue

frost.core

Class MutableString

└ Object

A mutable variant of String.

Source Code:: View Source

Inner Classes

MutableString.Index: Represents the position of a Unicode codepoint within a MutableString.

Initializer Summary

init(): Creates an empty MutableString.
init(s:String): Creates a MutableString initially containing the same characters as the specified String.
init(capacity:Int): Creates an empty MutableString with the specified initial capacity.

Field Summary

utf8:List<Char8>: A view of the UTF8 bytes this string contains.
length:Int: The number of Unicode codepoints this string contains.
byteLength:Int: The number of UTF8 bytes this string contains.
start:Index: An Index representing the beginning of the string.
end:Index: An Index representing the end of the string.

Inherited Fields:

toString

Instance Method Summary

append(c:Char8): Appends the specified character to the end of this string.
append(c:Char32): Appends the specified character to the end of this string.
append(s:String): Appends the specified string to the end of this string.
append(chars:Pointer<Char8>, count:Int): Appends the specified characters to the end of this string.
append(o:Object)
next(i:Index):Index: Returns the index of the Unicode codepoint after the given index.
previous(i:Index):Index: Returns the index of the Unicode codepoint before the given index.
offset(index:Index, offset:Int):Index: Returns the index offset by offset Unicode codepoints.
indexOf(s:String):Index?: Returns the index of the first occurrence of the string s within this string, or null if not found.
indexOf(s:String, start:Index):Index?: Returns the index of the first occurrence of the string s within this string, starting from the specified index, or null if not found.
contains(c:Char8):Bit: Returns true if this string contains at least one occurrence of the given character.
contains(s:String):Bit: Returns true if this string contains at least one occurrence of the given substring.
startsWith(other:String):Bit: Returns true if this string begins with other.
endsWith(other:String):Bit: Returns true if this string ends with other.
lastIndexOf(s:String):Index?: Returns the index of the last occurrence of the string s within this string, or null if not found.
lastIndexOf(s:String, start:Index):Index?: Returns the index of the last occurrence of the string s within this string, starting the search backwards from the specified index, or null if not found.
matches(regex:RegularExpression):Bit: Returns true if this string matches the given regular expression.
contains(needle:RegularExpression):Bit: Returns true if this string contains a match for the given regular expression.
trim(): Removes whitespace from the beginning and end of this string.
replace(search:RegularExpression, replacement:String)
replace(search:RegularExpression, replacement:String, allowGroupReferences:Bit)
replace(search:RegularExpression, replacement:(String)=>(Object)): Searches the string for a regular expression, replacing occurrences of the regular expression with new text determined by a function.
replace(search:RegularExpression, replacement:(String)=&>(Object))
replace(search:RegularExpression, replacement:(ListView<String?>)=>(Object)): As replace(RegularExpression, (String)=>(Object)), but the replacement function receives the capture groups from the regular expression rather than the raw matched text.
replace(search:RegularExpression, replacement:(ListView<String?>)=&>(Object))
-- index operator -- [](index:Index):Char32: Returns the Unicode codepoint at the given offset within the string.
-- index operator -- [](index:Int):Char32: Returns the Unicode codepoint at the given offset within the string.
-- index operator -- [](r:Range<Index>):String
-- index operator -- [](r:Range<Index?>):String
-- index operator -- [](r:Range<Int>):String
-- index operator -- [](r:Range<Int?>):String
-- index operator -- [](r:SteppedRange<Index?, Int>):String
-- index operator -- [](r:SteppedRange<Int?, Int>):String
-- indexed assignment operator -- []:=(index:Int, c:Char32)
-- indexed assignment operator -- []:=(index:Index, c:Char32)
-- indexed assignment operator -- []:=(r:Range<Index>, s:String)
-- indexed assignment operator -- []:=(r:Range<Int>, s:String)
-- indexed assignment operator -- []:=(r:Range<Index?>, s:String)
-- indexed assignment operator -- []:=(r:Range<Int?>, s:String)
replace(search:String, replacement:String)
clear()
finish():String: Invalidates this MutableString and returns its contents as an immutable String.

Initializers


init
()

Creates an empty MutableString.


init
(s:String)

Creates a MutableString initially containing the same characters as the specified String.

Parameters:: s - value of type String


init
(capacity:Int)

Creates an empty MutableString with the specified initial capacity. The MutableString will contain zero characters, but allocate enough storage to hold capacity characters, and thus not need to perform any reallocation until reaching that size.

Parameters:: capacity - value of type Int

Fields

property utf8:List<Char8>

A view of the UTF8 bytes this string contains.

property length:Int

The number of Unicode codepoints this string contains. As the string is internally stored in the variable-width UTF8 format, determining the length of the string takes an amount of time proportional to the number of characters it contains.

property byteLength:Int

The number of UTF8 bytes this string contains.

property start:Index

An Index representing the beginning of the string.

property end:Index

An Index representing the end of the string.

Instance Methods


method append

(c:Char8)

Appends the specified character to the end of this string.

Parameters:: c - value of type Char8


method append

(c:Char32)

Appends the specified character to the end of this string.

Parameters:: c - value of type Char32


method append

(s:String)

Appends the specified string to the end of this string.

Parameters:: s - value of type String


method append

(chars:Pointer<Char8>,
 count:Int)

Appends the specified characters to the end of this string.

Parameters:: chars - value of type Pointer<Char8>
count - value of type Int


method append

(o:Object)

Parameters:: o - value of type Object


function next

(i:Index
):Index

Returns the index of the Unicode codepoint after the given index. It is an error to call next() when already at the end of the string. Note that because a logical character can consist of multiple Unicode codepoints (such as LATIN SMALL LETTER A followed by COMBINING ACUTE ACCENT), this may return an index in the middle of such a compound character.

Parameters:: i - value of type Index


function previous

(i:Index
):Index

Returns the index of the Unicode codepoint before the given index. It is an error to call previous() when already at the beginning of the string. Note that because a logical character can consist of multiple Unicode codepoints (such as LATIN SMALL LETTER A followed by COMBINING ACUTE ACCENT), this may return an index in the middle of such a compound character.

Parameters:: i - value of type Index


function offset

(index:Index,
 offset:Int
):Index

Returns the index offset by offset Unicode codepoints. It is an error to index before the beginning or after the end of the string. Note that because a logical character can consist of multiple Unicode codepoints (such as LATIN SMALL LETTER A followed by COMBINING ACUTE ACCENT), this may return an index in the middle of such a compound character.

Parameters:: index - value of type Index
offset - value of type Int


function indexOf

(s:String
):Index?

Returns the index of the first occurrence of the string s within this string, or null if not found.

Parameters:: s - the string to search for

Returns:: the index of the match, or null if not found


function indexOf

(s:String,
 start:Index
):Index?

Returns the index of the first occurrence of the string s within this string, starting from the specified index, or null if not found.

Parameters:: s - the string to search for
start - the index to begin searching from

Returns:: the index of the match, or null if not found


function contains

(c:Char8
):Bit

Returns true if this string contains at least one occurrence of the given character.

Parameters:: c - value of type Char8


function contains

(s:String
):Bit

Returns true if this string contains at least one occurrence of the given substring.

Parameters:: s - value of type String


function startsWith

(other:String
):Bit

Returns true if this string begins with other.

Parameters:: other - value of type String


function endsWith

(other:String
):Bit

Returns true if this string ends with other.

Parameters:: other - value of type String


function lastIndexOf

(s:String
):Index?

Returns the index of the last occurrence of the string s within this string, or null if not found.

Parameters:: s - the string to search for

Returns:: the index of the match, or null if not found


function lastIndexOf

(s:String,
 start:Index
):Index?

Returns the index of the last occurrence of the string s within this string, starting the search backwards from the specified index, or null if not found.

Parameters:: s - the string to search for
start - the index to begin searching from

Returns:: the index of the match, or null if not found


function matches

(regex:RegularExpression
):Bit

Returns true if this string matches the given regular expression. The regular expression must match the entire string.

Parameters:: regex - the regular expression to compare against

Returns:: true if the string matches


function contains

(needle:RegularExpression
):Bit

Returns true if this string contains a match for the given regular expression. The regular expression may match zero or more characters of the string, starting at any point.

Parameters:: needle - the regular expression to search for

Returns:: true if the string contains a match


method trim

()

Removes whitespace from the beginning and end of this string.


method replace

(search:RegularExpression,
 replacement:String)

Parameters:: search - value of type RegularExpression
replacement - value of type String


method replace

(search:RegularExpression,
 replacement:String,
 allowGroupReferences:Bit)

Parameters:: search - value of type RegularExpression
replacement - value of type String
allowGroupReferences - value of type Bit


method replace

(search:RegularExpression,
 replacement:(String)=>(Object))

Searches the string for a regular expression, replacing occurrences of the regular expression with new text determined by a function. For instance, given:

"This is a test!".replace(/\w+/, word => word.length)

Try it!

The regular expression /\w+/ matches sequences of one or more word characters; in other words, it matches all words occurring in the string. The replacement function word => word.length replaces each matched sequence with the number of characters in the sequence, resulting in the text:

4 2 1 4!

Parameters:: search - the regular expression to match the string with
replacement - a function generating the replacement text


method replace

(search:RegularExpression,
 replacement:(String)=&>(Object))

Parameters:: search - value of type RegularExpression
replacement - value of type (String)=&>(Object)


method replace

(search:RegularExpression,
 replacement:(ListView<String?>)=>(Object))

As replace(RegularExpression, (String)=>(Object)), but the replacement function receives the capture groups from the regular expression rather than the raw matched text. The groups list includes the special whole-match group at index 0, with the first set of parentheses in the regular expression corresponding to index 1.

Parameters:: search - the regular expression to match the string with
replacement - a function generating the replacement text


method replace

(search:RegularExpression,
 replacement:(ListView<String?>)=&>(Object))

Parameters:: search - value of type RegularExpression
replacement - value of type (ListView<String?>)=&>(Object)

-- index operator --

function []

(index:Index
):Char32

Returns the Unicode codepoint at the given offset within the string.

Parameters:: index - value of type Index

-- index operator --

function []

(index:Int
):Char32

Returns the Unicode codepoint at the given offset within the string. This overload of the [] operator is slower than the overload that accepts an Index parameter, as it must scan the (internally UTF-8) string from the beginning to find the correct index.

Parameters:: index - value of type Int

-- index operator --

function []

(r:Range<Index>
):String

Parameters:: r - value of type Range<Index>

-- index operator --

function []

(r:Range<Index?>
):String

Parameters:: r - value of type Range<Index?>

-- index operator --

function []

(r:Range<Int>
):String

Parameters:: r - value of type Range<Int>

-- index operator --

function []

(r:Range<Int?>
):String

Parameters:: r - value of type Range<Int?>

-- index operator --

function []

(r:SteppedRange<Index?, Int>
):String

Parameters:: r - value of type SteppedRange<Index?, Int>

-- index operator --

function []

(r:SteppedRange<Int?, Int>
):String

Parameters:: r - value of type SteppedRange<Int?, Int>

-- indexed assignment operator --

method []:=

(index:Int,
 c:Char32)

Parameters:: index - value of type Int
c - value of type Char32

-- indexed assignment operator --

method []:=

(index:Index,
 c:Char32)

Parameters:: index - value of type Index
c - value of type Char32

-- indexed assignment operator --
@pre(r.max >= r.min &
                     ((r.inclusive & r.min.byteOffset < _length & r.max.byteOffset < _length) |
                     (!r.inclusive & r.min.byteOffset <= _length & r.max.byteOffset <= _length)))

method []:=

(r:Range<Index>,
 s:String)

Parameters:: r - value of type Range<Index>
s - value of type String

-- indexed assignment operator --

method []:=

(r:Range<Int>,
 s:String)

Parameters:: r - value of type Range<Int>
s - value of type String

-- indexed assignment operator --

method []:=

(r:Range<Index?>,
 s:String)

Parameters:: r - value of type Range<Index?>
s - value of type String

-- indexed assignment operator --

method []:=

(r:Range<Int?>,
 s:String)

Parameters:: r - value of type Range<Int?>
s - value of type String


method replace

(search:String,
 replacement:String)

Parameters:: search - value of type String
replacement - value of type String


method clear

()


method finish

():String

Invalidates this MutableString and returns its contents as an immutable String. This is generally preferable to toString, as it does not copy the string's contents. Interacting in any way with a MutableString after finishing will cause precondition violations (or, if safety checks are disabled, undefined behavior).