Working with Strings

This chapter describes some of the operations that you can perform on strings in the Curl® language. In particular, this chapter describes the following operations:

Converting Strings

The Curl language offers several ways to convert a string to another type of data:

Converting to a double

Method/Procedure
Read-OnlyRead-WriteSummary
to-doubleYYMethod that returns a double from a string.
To return a double from a string, use the to-double method. The following example shows this method:

Example: Converting to a double
{value
    || Declare and initialize a string.
    let s:String = "365e-10"

    || Declare and initialize a double to hold the return
    || value from a call to "to-double".
    let number:double = {s.to-double}

    || Display the double.
    number
}

Converting to an int

Method/Procedure
Read-OnlyRead-WriteSummary
to-intYYMethod that returns an int from a string.
To return an int from a string, use the to-int method. The following example shows this method:

Example: Using the to-int Method
{value
    || Declare and initialize a string.
    let s:String = "-0X16D"

    || Declare and initialize an int to hold the return
    || value from a call to to-int.
    let number:int = {s.to-int}

    || Display the int.
    number
}

Converting to a String

Method/Procedure
Read-OnlyRead-WriteSummary
to-StringYYMethod that converts the string to a String.
Use to-String to convert a string, created using any of the string classes, to a String. The to-String method returns a String object. The following example shows this method:

Example: Converting to a String
{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}
}

Converting to a Stream

Method/Procedure
Read-OnlyRead-WriteSummary
StringInterface.to-InputStreamYYMethod that wraps the string in an input stream.
To convert a StringInterface to an TextInputStream, use the StringInterface.to-InputStream method. For information about streams, see Working with Streams. The following example shows how to use StringInterface.to-InputStream:

Example: Converting to a Stream (Part 1)
|| Declare and initialize a read-only string.
{let s:String = "Hello World"}

|| Convert the string to an input stream
{let tis:TextInputStream = {s.to-InputStream}}

|| Output the value of the input stream.
{tis.read-one-string}

|| Close the text input stream.
{tis.close}

Splitting a String

Method/Procedure
Read-OnlyRead-WriteSummary
splitYYMethod that splits a string at specified characters.
To split a string into smaller strings at each occurrence of specified characters, use the split method. By default, this method splits a string at each occurrence of whitespace. To split the string at other characters, use the split-chars keyword argument to pass a CharClass object containing the characters. See Character Classes for more information about CharClass objects. This method returns an array containing the smaller strings. The following example shows this method:

Example: Splitting a String (Part 1)
{value
    || Declare and initialize a string.
    let s:String = "www.curl.com"

    || Split the string at the periods.
    let a:StringArray = {s.split split-chars="."}

    || Declare and instantiate a VBox for displaying
    || an output message indicating the results.
    let out:VBox = {VBox}

    || For each element in the results array, add it
    || to the output message.
    {for i:int = 0 to (a.size - 1) do
        {out.add {value a[i]}}
    }

    || Display the string and the output message.
    {value out}
}
If you attempt to use a character that does not appear in the string to split it, this method returns an array containing one StringInterface. This StringInterface contains the original string. For example:

Example: Splitting a String (Part 2)
{value
    || Declare and initialize a string.
    let s:String = "www.curl.com"

    || Use the colon character (:) to split the string.
    let a:StringArray = {s.split split-chars=":"}

    || Declare and instantiate a VBox for displaying
    || an output message indicating the results.
    let out:VBox = {VBox}

    || For each element in the results array, add it
    || to the output message.
    {for i:int = 0 to (a.size - 1) do
        {out.add {value a[i]}}
    }

    || Display the string and the output message.
    {value out}
}
If you attempt to split an empty string, this method returns an array with no StringInterfaces. For example:

Example: Splitting a String (Part 3)
{value
    || Declare and initialize an empty string.
    let s:String = ""

    || Split the string.  By default, the method splits
    || at whitespace.
    let a:StringArray = {s.split}

    || Display the number of StringInterfaces in the array.
    {value a.size}
}

Comparing Strings

The Curl language offers some ways to compare one string to another:
The Curl language also includes methods for checking whether a string begins or ends with specified characters. See Checking the Start of a String and Checking the End of a String for more information.

Lexicographic Comparison

Method/Procedure
Read-OnlyRead-WriteSummary
compareYYMethod that compares two strings.
StringInterface-leq?YYProcedure that checks whether one StringInterface is less than or equal to another.
String-leq?YYProcedure that checks whether one String is less than or equal to another.
To compare a string to another string, use the compare method. This method uses the Unicode value of each character when comparing the strings. That is, it performs a lexicographic comparison of the strings. Note that, in Unicode, the value of an uppercase character is lower than the value of the corresponding lowercase character. For example, the Unicode value of a is 0x0061, while the Unicode value of A is 0x0041. If you want the comparison to ignore the case of the characters, supply the ignore-case?=true keyword argument.
Supply the string to which you want to compare this string as an argument to the method. The method returns 0 if the argument is the same as the string, -1 if the argument is greater that the string, and 1 if it is less than the string. The following example shows this method:

Example: Using compare to Compare Strings
{value
    || Declare and initialize two strings.
    let s1:String = "Hello World!"
    let s2:String = "hello world!"

    || Compare the two strings and display an
    || appropriate message.
    {switch {s1.compare s2}
     case -1 do
        {text String 1 is less than String 2.}
     case 0 do
        {text String 1 is equal to String 2.}
     else
        {text String 1 is greater than String 2.}
    }
}
There are also a couple of procedures that compare strings. StringInterface-leq? checks whether one StringInterface is less than or equal to another (StringInterface is the superclass for all strings in the Curl language). You can use StringInterface-leq? to compare any two string objects in the Curl language. The String-leq? procedure, on the other hand, checks only whether one String is less than or equal to another String. For both procedures, supply the two string objects that you want to compare as arguments in the procedure call. These procedures return true if the first argument is less than or equal to the second. The following example illustrates String-leq?:

Example: Using string-leg to Compare Strings
{value
    || Declare and initialize two strings.
    let s1:String = "Hello World!"
    let s2:String = "hello world!"

    || Compare the two strings and display an
    || appropriate message.
    {if {String-leq? s1, s2} then
        {text String 1 is less than or equal to String 2.}
     else
        {text String 1 is greater than String 2.}
    }
}

Testing for Equality

To check whether the contents of a string are equal to the contents of another string, use the equal? method. Supply the string with which you want to check for equality as an argument. If you want to ignore the case of the characters, supply the ignore-case?=true keyword argument. This method returns a bool indicating whether the strings are equal. The following example shows this method:

Example: Using equal? to Compare Strings
{value
    || Declare and initialize two strings.
    let s1:String = "Hello World!"
    let s2:String = "Hello World!"

    || Test whether the contents of the two strings are
    || equal and display an appropriate message.
    {if {s1.equal? s2} then
        {text The contents of the strings are equal.}
     else
        {text The contents of the strings are NOT equal.}
    }
}
You can also use the equality (== ) or inequality (!=) operators to perform a case-sensitive, character by character comparison of two strings.

Example: Using the equality operator == to Compare Strings
{value
    || Declare and initialize two strings.
    let s1:String = "Hello World!"
    let s2:String = "Hello World!"

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

Searching Strings

The Curl language offers some ways to search for substrings within strings:
The Curl language also includes methods for checking whether a string begins or ends with specified characters. See Checking the Start of a String and Checking the End of a String for more information.

Regular Expressions

The Curl language includes a regular expressions library that allows you to perform sophisticated pattern matching operations with strings. See Regular Expressions for more information.

Pattern Matching

Method/Procedure
Read-OnlyRead-WriteSummary
findYYMethod that finds the first occurrence of a specified character.
find-stringYYMethod that finds the first occurrence of a specified sub-string.
find-char-classYYMethod that finds the first occurrence of characters in a specified CharClass.
For more information, see the API Reference information for StringInterface.find, StringInterface.find-string, and StringInterface.find-char-class.

Miscellaneous Tasks

You can also perform the following tasks with strings in the Curl language:

Displaying Strings

You can use the format macro to control the output of a string. The format macro supports the C programming language formatting codes. For more information, see the API Reference Manual documentation for format.

Testing Whether a String is Empty

Method/Procedure
Read-OnlyRead-WriteSummary
empty?YYAccessor that indicates whether a string is empty.
To determine whether a string is empty, use the empty? accessor. This accessor returns a bool that indicates whether the string is empty. The following example shows this accessor:

Example: Testing if a String is Empty
{value
    || Declare and initialize an empty string.
    let s:String = ""

    || Check whether the string is empty and display an
    || appropriate message.
    {if s.empty? then
        {text The string is empty!}
     else
        {text The string has characters!}
    }
}

Getting the Size of a String

Method/Procedure
Read-OnlyRead-WriteSummary
sizeYYAccessor that indicates the size of the string.
For read-only strings, size returns the number of characters in the string. The following example shows this accessor with a read-only string:

Example: Getting the Size of a String
{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".
    {text There are {value s.size} characters in the string.}
}

Setting the Size of a String

Method/Procedure
Read-OnlyRead-WriteSummary
sizeNYAccessor that indicates the size of the string.
For read-write strings, size:
If you set the size to be smaller than the current size of the string, the Curl® Runtime Environment (RTE) truncates the string. If you set the size to be larger than the current size, the runtime adds the appropriate number of characters (with Unicode hexadecimal value 0000) to the end of the string. The following example shows this accessor with a read-write string:

Example: Setting the Size of a String
|| Declare and initialize a read-write 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 size is set to 5, the string
    becomes: {value sb}}

|| Set the size of the string to 10 characters.
|| The string should now have 5 characters
|| with the Unicode (hexadecimal) value 0000 at the end.
{set sb.size = 10}

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

Checking the Start of a String

Method/Procedure
Read-OnlyRead-WriteSummary
prefix?YYMethod that determines whether a string begins with specified characters.
To determine whether a string begins with specified characters, use the prefix? method. Supply a string containing the characters that you want to check for as an argument to the method call. By default, when this method compares the characters to those at the beginning of the string, it performs a case-sensitive comparison. To ignore case, specify the ignore-case?=true keyword argument. The following example shows this method:

Example: Checking the Start of a String
|| Declare and initialize a string.
{let s:String = "Hello World!"}

|| Check whether the string begins with "Hello" (case sensitive).
{value
    {s.prefix? "Hello"}
}

|| Check whether the string begins with "hello" (case sensitive).
{value
    {s.prefix? "hello"}
}

|| Check whether the string begins with "hello" (not case sensitive).
{value
    {s.prefix? "hello", ignore-case?=true}
}

Checking the End of a String

Method/Procedure
Read-OnlyRead-WriteSummary
suffix?YYMethod that determines whether a string ends with specified characters.
To determine whether a string ends with specified characters, use the suffix? method. Supply a string containing the characters that you want to check for as an argument to the method call. By default, when this method compares the characters to those at the end of the string, it performs a case-sensitive comparison. To ignore case, specify the ignore-case?=true keyword argument. The following example shows this method:

Example: Checking the End of a String
|| Declare and initialize a string.
{let s:String = "Hello World!"}

|| Check whether the string ends with "World!" (case sensitive).
{value
    {s.suffix? "World!"}
}

|| Check whether the string ends with "world!" (case sensitive).
{value
    {s.suffix? "world!"}
}

|| Check whether the string ends with "world!" (not case sensitive).
{value
    {s.suffix? "world!", ignore-case?=true}
}
Copyright © 1998-2019 SCSK Corporation. All rights reserved.
Curl, the Curl logo, Surge, and the Surge logo are trademarks of SCSK Corporation. that are registered in the United States. Surge Lab, the Surge Lab logo, and the Surge Lab Visual Layout Editor (VLE) logo are trademarks of SCSK Corporation.