String

A read-only string of characters (char).

Notes

The hierarchy of string classes in Curl is as follows:

StringInterface
∟ SubString
∟ ReadOnlyString
∟ String
∟ WritableString
∟ StringBuf

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

Programming Notes

The constructor

{String ...}

creates a String containing the concatenation of the String representations of each argument. The String representations for all of the rest arguments are concatenated to form the value for the new String object. String representations are obtained for each rest-arg by calling {format "%s", rest-arg} (or by doing something equivalent but faster).

The Curl compiler automatically creates a String when a string literal is used. For this reason, it is not necessary to write

let s:String = {String "hello world"}

. Instead, one should simply write

let s:String = "hello world"

Example

This shows the use of multiple arguments of different data types to form a String.

Example

{String "This String is created with ", 3, " arguments"}

Construct a new String. Convert any arguments into strings and concatenate the strings. Convert the result into the value of the String.

Returns a string of n c's.

A getter that the Curl compiler uses when it encounters a container for loop that iterates over a string.

Notes

Do not call this getter; it is intended only for use by the Curl compiler.

The number of characters in self.

Returns

An int indicating the number of characters.

Description

For read-only strings:

Returns the number of characters in the string.

For writable strings:

Returns the number of characters in the string.
Allows you to set the number of characters in the string.

If you set the size to be smaller than the current size of the string, Curl truncates the string. If you set the size to be larger than the current size, Curl adds the appropriate number of characters (with Unicode value 0000) to the end of the string.

Example

The following example shows size with a read-only string.

Example

{value
    || Declare and initialize a read-only string
    let s:String = "Hello World!"

    || Output a message that includes the return value of
    || a call to "size".
    || Note that you must use "value" to display the value
    || of "s.size", rather than the text "s.size".
    {text There are {value s.size} characters in the string.}
}

The following examples show size with a writable string.

Example

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

    || Set the size of the string to 5 characters.
    || The string should now contain only the first five
    || characters, "Hello".
    set sb.size = 5

    || Output a message that includes the new string
    {text If {monospace size} is set to 5, the string
        becomes: {value sb}}
}

Example

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

    || Set the size of the string to 20 characters.
    || The string should now have 8 characters
    || with the Unicode value 0000 at the end.
    set sb.size = 20

    || Output a message that includes the new string.
    {text Then, if {monospace size} is set to 20, the string
        becomes: {value sb}}
}

Notes

This is an abstract getter of StringInterface; it is implemented by subclasses of StringInterface.

This item is unsupported and reserved for internal use.

Checks if self is equal to a specified StringInterface.

str: The StringInterface with which you want to check for equality.

ignore-case?: A keyword argument that indicates if the test is to ignore the case of the characters. By default, the test does not ignore case (ignore-case? = false). In other words, by default the test is case sensitive. For example, "abcdefg" is not equal to "ABCDEFG".

ignore-case? is a keyword argument. To specify ignore-case?, make sure to assign the desired value to the keyword in the method call (for example ignore-case? = true).

If you specify ignore-case? and assign it to true, the test is not case-sensitive. In this situation, "abcdefg" is equal to "ABCDEFG".

Returns

A bool value. Returns true if each character in self is equal to the corresponding character in str. Otherwise, returns false.

Example

{value
    || Declare and initialize two strings
    let s1:String = "Hello World!"
    let s2:String = "hello world!"

    || Display the strings.
    {text
        String 1: {value s1}
        {br}String 2: {value s2}

        || Test if the two strings are equal and display
        || an appropriate message.
        {if {s1.equal? s2} then
            {text The strings are equal.}
         else
            {text The strings are NOT equal.}
        }

        || Test if the two strings are equal, this time
        || ignoring case, and display an appropriate message.
        But, if you ignore case,
        {if {s1.equal? s2, ignore-case? = true} then
            {text they are equal.}
         else
            {text they are NOT equal.}
        }
    }
}

Returns the specified character from self.

index: The position of the character that you want to return. 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.

Throws

Should throw an ArrayBoundsException if index is out of bounds.

Example

{value
    || Declare and initialize a string.
    let s:String = "Hello World!"

    || Display the string and return the
    || character at position 7.
    || Remember that the leftmost position
    || is 0 (zero).
    {text {value s}
        {br}The character at position 7 is {s.get 7}.}
}

Notes

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

Returns a specified substring of self.

start: The position in self at which the substring starts. 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.

length: The length of the substring. In other words, the number of characters in the substring.

Returns

A String containing the specified substring of self, containing length consecutive characters, beginning at position start.

Notes

If start or start + length is out of bounds this method throws an ArrayBoundsException.

Example

{value
    || Declare and initialize s1 (the original string).
    let s1:String = "Hello World!"

    || Initialize s2 with a substring of s1.  The
    || substring begins at position 6 and is 5
    || characters long ("World").
    || Remember that the leftmost position
    || is 0 (zero).
    let s2:String = {s1.substr 6, 5}

    || Display the contents of s2.
    {value s2}
}

Notes

For a detailed description of cloning, see Curl Developer's Guide: Strings: Working with String Clones.

Produces a String that is == to self.

Returns

A String containing the characters in self.

Example

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

    || Convert the StringBuf to a String.
    let s:String = {sb.to-String}

    || Display the contents of the String.
    {value s}
}