WritableString (class)
public abstract WritableString {inherits StringInterface}
Package: CURL.LANGUAGE.STRINGS
Direct Known Subclasses: StringBuf

Abstract class for strings that you can read and write.

Description

WritableString provides the interface for writable string classes in Curl. In other words, WritableString provides the accessors and methods that form the basis of writable string classes in Curl.

You cannot instantiate WritableString because it is an abstract class. To create a string object, instantiate one of the string classes that inherits from WritableString.

For more information about Strings in Curl, see Curl Developer's Guide: Strings.

Notes

The hierarchy of string classes in Curl is as follows:

StringInterface
∟ SubString
∟ ReadOnlyString
∟ String
∟ WritableString
∟ StringBuf

Properties
efficient-size:Gets or sets the efficient-size of self.
accessor public inline WritableString.efficient-size:int
setter public inline WritableString.efficient-size:int
Properties inherited from StringInterface: empty?, for-loop-count, size
Methods
append:Appends a character to self.
public {WritableString.append c:char}:void
clear:Clears self.
public {WritableString.clear}:void
concat:Concatenates a StringInterface onto self.
public {WritableString.concat str:StringInterface}:void
insert:Inserts a character into self.
public abstract {WritableString.insert c:char, index:int}:void
remove:Removes specified characters from self.
public abstract {WritableString.remove
    index:int,
    length:int = 1,
    error-if-missing?:bool = true
}:void
replace:Replaces each occurrence of old with new.
public {WritableString.replace
    old:StringInterface,
    new:StringInterface,
    starting-index:int = 0
}:void
reverse:Reverses the order of the characters in self.
public {WritableString.reverse}:void
set:Replaces a character in self.
public abstract {WritableString.set index:int, c:char}:void
set-contents:Replaces the contents of self with the contents of another string.
public {WritableString.set-contents str:StringInterface}:void
splice:Inserts a StringInterface into self.
public {WritableString.splice str:StringInterface, index:int}:void
to-lower:Changes the characters in self to lowercase.
public {WritableString.to-lower}:void
to-upper:Changes the characters in self to uppercase.
public {WritableString.to-upper}:void
trim:Removes characters from the start and end of self.
public {WritableString.trim
    trim-chars:CharClass = CharClass.whitespace-chars
}:void
trim-left:Removes characters from the start of self.
public {WritableString.trim-left
    trim-chars:CharClass = CharClass.whitespace-chars
}:void
trim-right:Removes characters from the end of self.
public {WritableString.trim-right
    trim-chars:CharClass = CharClass.whitespace-chars
}:void
Methods inherited from StringInterface: clone, compare, equal?, find, find-char-class, find-string, get, prefix?, replace-clone, split, substr, suffix?, tail, to-double, to-InputStream, to-int, to-int64, to-lower-clone, to-String, to-upper-clone, trim-clone, trim-left-clone, trim-right-clone
Methods inherited from Object: object-describe, object-describe-for-debugging, object-serialize

Property Details
efficient-size (accessor)
accessor public inline WritableString.efficient-size:int
setter public inline WritableString.efficient-size:int

Gets or sets the efficient-size of self.

Description

The efficient-size is the size to which a WritableString or descendant can grow and still function efficiently. This is defined on an implementation-basis, but will generally reflect the size of underlying data structures. Growth beyond their allocated sizes will require allocating new underlying data structures and copying data from the old structures; this is what is considered inefficient.
requested-size: The requested-size is evaluated by the system and may be modified. The resulting efficient-size may be obtained from the getter, and it is guaranteed to be equal to or greater than the requested-size.

Notes

The default implementation of the efficient-size accessors will ignore the setter, and the getter will return max-int implying that all sizing operations are equally efficient.

Method Details
append (method)
public {WritableString.append c:char}:void

Appends a character to self.

c: The character that you want to append.

Description

Adds character c to the end of self.

Example


Example
{value
    || Declare and initialize a StringBuf.
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Append an exclamation mark (!).
    {sb.append '!'}

    || Display the resulting StringBuf.
    {value sb}
}

clear (method)
public {WritableString.clear}:void

Clears self.

Description

Replaces the contents of self with an empty string.

Example


Example
{value
    || Declare and initialize a StringBuf.
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Clear the StringBuf.
    {sb.clear}

    || Check if the StringBuf is empty.
    {text The assertion that the string is empty
        is... {value sb.empty?}}
}

concat (method)
public {WritableString.concat str:StringInterface}:void

Concatenates a StringInterface onto self.

str: The StringInterface that you want to concatenate. The object must have the same data type as self.

Description

Adds str to the end of self.

Example


Example
{value
    || Declare and initialize two StringBufs.
    let sb1:StringBuf = {StringBuf "Hello World!"}
    let sb2:StringBuf = {StringBuf " Can you hear me?"}

    || Concatenate "sb2" onto "sb1".
    {sb1.concat sb2}

    || Display the resulting StringBuf.
    {value sb1}
}

insert (method)
public abstract {WritableString.insert c:char, index:int}:void

Inserts a character into self.

c: The character that you want to insert.
index: The position into which you want to insert the character. The leftmost character is at position 0. The rightmost character is at position (self.size - 1). Valid values range from 0 to self.size inclusive.

Description

Shifts all characters after position index one place to the right and inserts character c at position index.

Example


Example
{value
    || Declare and initialize a StringBuf.
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Insert a comma (,) at position 5.
    || Remember that the leftmost position
    || is 0 (zero).
    {sb.insert ',', 5}

    || Display the resulting StringBuf.
    {value sb}
}

Notes

This is an abstract method of WritableString; it is implemented by subclasses of WritableString.

remove (method)
public abstract {WritableString.remove
    index:int,
    length:int = 1,
    error-if-missing?:bool = true
}:void

Removes specified characters from self.

index: The position at which you want to start removing characters. The leftmost character is at position 0. The rightmost character is at position (self.size - 1). Valid values range from 0 to self.size inclusive.
length: The number of characters that you want to remove. By default, length is set to one. length is a keyword argument. To specify the length, make sure to assign the desired value to the keyword in the call (for example length = 6).
error-if-missing?: A Boolean flag that indicates if this method generates an error when you try to remove a character that does not exist. You can remove characters between positions 0 and self.size.

If error-if-missing? is true, this method throws an error when you try to remove a character that does not exist. An error terminates execution of the program and displays an appropriate error message. By default, error-if-missing? is true. If error-if-missing? is false, this method does not generate an error, removes the characters that are within the valid range of characters, does not remove the characters that are not in the valid range, and returns the resulting string.

error-if-missing? is a keyword argument. To specify error-if-missing?, make sure to assign the desired value to the keyword in the method call (for example error-if-missing? = false).

Description

Removes length characters from self, starting at position index.

Example


Example
{value
    || Declare and initialize a StringBuf.
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Remove 6 characters, starting at
    || position 5.
    || Remember that the leftmost position
    || is 0 (zero).
    {sb.remove 5, length = 6}

    || Display the resulting StringBuf.
    {value sb}
}

Notes

This is an abstract method of WritableString; it is implemented by subclasses of WritableString.

replace (method)
public {WritableString.replace
    old:StringInterface,
    new:StringInterface,
    starting-index:int = 0
}:void

Replaces each occurrence of old with new.

old: The substring that you want to replace with new.
new: The substring that you want to replace each occurrence of old.

Description

Searches for the substring old from left-to-right. For each occurrence it removes old, splices in new, and resumes searching after the newly inserted characters.

Example


Example
{value
    || Declare and initialize a string
    let sb:StringBuf = {StringBuf "Silly willy"}

    || Replace each occurrence of "ill" with "ick".
    {sb.replace "ill", "ick"}

    || Display the resulting StringBuf.
    sb
}

reverse (method)
public {WritableString.reverse}:void

Reverses the order of the characters in self.

Example


Example
{value
    || Declare and initialize a StringBuf
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Reverses the order of the characters
    {sb.reverse}

    || Display the resulting StringBuf
    {value sb}
}

Notes

This method reverses the order of the individual chars stored in self. Because Unicode string semantics depend on the order of the individual chars of its representation, this method does not generate a reversed version of the original string.

For example, the string represented by the character sequence "\u305D\u3099\u305F" is equivalent to "\u305E\u305F" (ZO-TA); but when reversed, becomes equivalent to "\u3060\u305D" (SO-DA).

set (method)
public abstract {WritableString.set index:int, c:char}:void

Replaces a character in self.

index: The position of the character that you want to replace. The leftmost character is at position 0. The rightmost character is at position (self.size - 1). Valid values range from 0 to (self.size - 1) inclusive.
c: The new character.

Description

Replaces the character at position index with the character c.

Example


Example
{value
    || Declare and initialize a StringBuf.
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Replace character 11 (!) with a period (.).
    || Remember that the leftmost position
    || is 0 (zero).
    {sb.set 11, '.'}

    || Display the resulting StringBuf.
    {value sb}
}

Notes

This is an abstract method of WritableString; it is implemented by subclasses of WritableString.

set-contents (method)
public {WritableString.set-contents str:StringInterface}:void

Replaces the contents of self with the contents of another string.

str: The StringInterface containing the string that replaces self.

Example


Example
{value
    || Declare and initialize a StringBuf
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Replace the contents
    {sb.set-contents {StringBuf "Here comes Curl!"}}

    || Display the StringBuf
    {value sb}
}

splice (method)
public {WritableString.splice str:StringInterface, index:int}:void

Inserts a StringInterface into self.

str: The StringInterface that you want to insert. The object must have the same data type as self.
index: The position into which you want to insert the StringInterface. The leftmost character is at position 0. The rightmost character is at position (self.size - 1). Valid values range from 0 to self.size inclusive.

Description

At position index, shifts all remaining characters of self by the number of characters in str and then inserts str at position index.

Example


Example
{value
    || Declare and initialize two StringBufs.
    let sb1:StringBuf = {StringBuf "Hello World!"}
    let sb2:StringBuf = {StringBuf ", can you hear me,"}

    || Insert "sb2" into "sb1" at position 5.
    || Remember that the leftmost position
    || is 0 (zero).
    {sb1.splice sb2, 5}

    || Display the resulting StringBuf.
    {value sb1}
}

to-lower (method)
public {WritableString.to-lower}:void

Changes the characters in self to lowercase.

Example


Example
{value
    || Declare and initialize a StringBuf
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Change the characters to lowercase
    {sb.to-lower}

    || Display the resulting StringBuf
    {value sb}
}

to-upper (method)
public {WritableString.to-upper}:void

Changes the characters in self to uppercase.

Example


Example
{value
    || Declare and initialize a StringBuf
    let sb:StringBuf = {StringBuf "Hello World!"}

    || Change the characters to uppercase
    {sb.to-upper}

    || Display the resulting StringBuf
    {value sb}
}

trim (method)
public {WritableString.trim
    trim-chars:CharClass = CharClass.whitespace-chars
}:void

Removes characters from the start and end of self.

trim-chars: The characters that you want to remove. The default value of trim-chars is the set of characters that comprise whitespace for the current locale, as defined by CharClass.whitespace-chars. To specify different trim characters for a call to this method, specify a CharClass containing the characters. trim-chars is a keyword argument. To specify trim-chars, make sure to assign the desired value to the keyword in the method call (for example trim-chars = {CharClass " .,;:"}).

Description

Moves from the left end of self, removing the characters indicated in trim-chars until it encounters a character that is not in trim-chars. Repeats this process from the right end of self.

Note that characters in trim-chars that appear between non-trim characters are not removed. For example, if the trim characters include a space, spaces will be removed at the beginning of the string and at the end of the string, but not between words in the string.

Example


Example
{value
    || Declare and initialize a string.
    let sb:StringBuf = {StringBuf "  Hello World!  "}

    || Trim whitespace characters from the
    || start and the end.
    {sb.trim}

    || Display the resulting StringBuf.
    || The # characters are used to indicate
    || beginning and end of the string.
    {pre #{value sb}#}
}

trim-left (method)
public {WritableString.trim-left
    trim-chars:CharClass = CharClass.whitespace-chars
}:void

Removes characters from the start of self.

trim-chars: The characters that you want to remove. The default value of trim-chars is the set of characters that comprise whitespace for the current locale, as defined by CharClass.whitespace-chars. To specify different trim characters for a call to this method, specify a CharClass containing the characters. trim-chars is a keyword argument. To specify trim-chars, make sure to assign the desired value to the keyword in the method call (for example trim-chars = {CharClass " .,;:"}).

Description

Moves from the left end of self, removing the characters indicated in trim-chars until it encounters a character that is not in trim-chars.

Example


Example
{value
    || Declare and initialize a string
    let sb:StringBuf = {StringBuf "  Hello World!  "}

    || Trim whitespace characters from the start.
    {sb.trim-left}

    || Display the resulting StringBuf
    || The # characters are used to indicate
    || beginning and end of the string
    {pre #{value sb}#}
}

trim-right (method)
public {WritableString.trim-right
    trim-chars:CharClass = CharClass.whitespace-chars
}:void

Removes characters from the end of self.

trim-chars: The characters that you want to remove. The default value of trim-chars is the set of characters that comprise whitespace for the current locale, as defined by CharClass.whitespace-chars. To specify different trim characters for a call to this method, specify a CharClass containing the characters. trim-chars is a keyword argument. To specify trim-chars, make sure to assign the desired value to the keyword in the method call (for example trim-chars = {CharClass " .,;:"}).

Description

Moves from the right end of self, removing the characters indicated in trim-chars until it encounters a character that is not in trim-chars.

Example


Example
{value
    || Declare and initialize a string
    let sb:StringBuf = {StringBuf "  Hello World!  "}

    || Trim whitespace characters from the end.
    {sb.trim-right}

    || Display the resulting StringBuf
    || The # characters are used to indicate
    || beginning and end of the string
    {pre #{value sb}#}
}