String Operations

ObjectScript provides several groups of operations related to strings, each with its own purpose and features. These are:

Basic String Operations and Functions

ObjectScript basic string operations allow you to perform various manipulations on a string. They include:

The $Length function returns the number of characters in a string: For example, the code:
```
 Write $length("How long is this?")
```
returns 17, the length of a string.
$Justify returns a right-justified string, padded on the left with spaces (and can also perform operations on numeric values). For example, the code:
```
 Write "one",!,$justify("two",8),!,"three"
```
justifies string “two” within eight characters and returns:
```
one
     two
three
```
$ZConvert converts a string from one form to another. It supports both case translations (to upper case, to lower case, or to title case) and encoding translation (between various character encoding styles). For example, the code:
```
 Write $ZConvert("cRAZy cAPs","t")
```
returns:
```
CRAZY CAPS
```
The $Find function searches for a substring of a string, and returns the position of the character following the substring. For example, the code:
```
 Write $find("Once upon a time...", "upon")
```
returns 10 character position immediately following “upon.”
The $Extract function, which returns a substring from a specified position in a string. For example, the code:
```
 Write $Extract("Nevermore"),$Extract("prediction",5),$Extract("xon/xoff",1,3)
```
returns three strings. The one-argument form returns the first character of the string; the two-argument form returns the specified character from the string; and the three-argument form returns the substring beginning and ending with specified characters, inclusive. In the example above, there are no line breaks, so the return value is:
```
Nixon
```

Advanced Features of $Extract

You can use the $Extract function in conjunction with the Set command pad a string on the left with spaces.

 Set x = "abc"
 Write x,!
 Set $Extract(y, 3) = x
 Set x = y
 Write x

This code takes the string “abc” and places at the third character of string y. Because y has no specified value, $Extract assumes that its characters are blank, which acts to pad the string.

You can also use $Extract to insert a new string at a particular point in variable. It extracts the characters specified and replaces them with the supplied substring, whether or not the lengths of the old and new strings match. For example:

 Set x = "1234"
 Write x,!
 Set $Extract(x, 3) = "abc"
 Write x,!
 Set $Extract(y, 3) = "abc"
 Write y

This code sets x to “1234”; it then extracts the third character of x using $Extract and inserts “abc” in its place, making the string “12abc4”.

Delimited Strings

Caché includes functionality that allows you to work with strings as a set of substrings. This functionality provides for the manipulation of related pieces of data that you wish to store as a single whole. These are

$Piece—Returns a specific piece of a string based on a specified delimiter. It can also return a range of pieces, as well as multiple pieces from a single string, based on multiple delimiters.
$Length—Returns the number of pieces in a string based on a specified delimiter.

The $Piece function provides uniquely important functionality because it allows you to use a single string that contains multiple substrings, with a special delimiter character (such as “^”) to separate them. The large string acts as a record, and the substrings are its fields.

The syntax for $Piece is:

 Write $Piece("ListString","QuotedDelimiter",ItemNumber)

where ListString is a quoted string that contains the full record being used; QuotedDelimiter is the specified delimited, which must appear in quotes; and ItemNumber is the specified substring to be returned. For example, to display the second item in the following space-delimited list, the syntax is:

 Write $Piece("Kennedy Johnson Nixon"," ",2)

which returns “Johnson”.

You can also return multiple members of the list, so that the following:

 Write $Piece("Nixon***Ford***Carter***Reagan","***",1,3)

returns “Nixon***Ford***Carter”. Note that both values must refer to actual substrings and the the third argument (here 1) must be a smaller value than that of the fourth argument (here 3).

The delimiter can be anything you choose, such as with the following list:

 Set x = $Piece("Reagan,Bush,Clinton,Bush",",",3)
 Set y = $Piece("Reagan,Bush,Clinton,Bush","Bush",2)
 Write x,!,y

which returns

Clinton
,Clinton,

In the first case, the delimiter is the comma; in the second, it is the string “Bush”, which is why the returned string includes the commas. To avoid any possible ambiguities related to delimiters, use the List-related functions, described in the next section.

Advanced $Piece Features

A call to $Piece that sets the value of a delimited element in a list will add enough list items so that it can place the substring as the proper item in an otherwise empty list. For instance, if you set the fourth item in a list,

 Set $Piece(Alphalist, "^", 1) = "a"
 Set $Piece(Alphalist, "^", 20) = "t"
 Write $Length(Alphalist,"^")

will return a value of 20, since it creates twenty delimited items. However, items 2 through 19, in this example, will not have values set. Hence, if you attempt to display any of their values, nothing will appear.

A delimited string item can also contain a delimited string. To retrieve a value from a sublist such as this, nest $Piece function calls, as in the following code:

 Set $Piece(Powers, "^", 1) = "1::1::1::1::1"
 Set $Piece(Powers, "^", 2) = "2::4::8::16::32" 
 Set $Piece(Powers, "^", 3) = "3::9::27::81::243"
 Write Powers,!
 Write $Piece( $Piece(Powers, "^", 2), "::", 3)

This code returns two lines of output: the first is the string Powers, including all its delimiters; the second is 8, which is the value of the third element in the sublist contained by the second element in Powers. (In the Powers list, the nth item is a sublist of two raised to the first through fifth powers, so that the first item in the sublist is n to the first power, and so on.)

List-Structure String Operations

ObjectScript defines a special kind of string called a “list”, which consists of a list of substrings. There are a set of functions for manipulating lists, which are:

$ListBuild—Returns a list built from substrings.
$List—Returns a specific item in the list.
$ListLength—Returns the number of items in the list.
$ListFind—Searches the list for a substring and returns its item number.

Though consisting of standard strings, Caché treats lists slightly differently than standard strings. Because of this, you should not use standard string functions on lists. Further, using a list function on a regular string generates a <LIST> error.

The following procedure demonstrates the use of the various list functions:

ListTest() PUBLIC {
    // set values for list elements
    Set Addr = "One Memorial Drive"
    Set City = "Cambridge"
    Set State = "MA"
    Set Zip = "02142"
    // create list
    Set Mail = $ListBuild(Addr, City, State, Zip)
 
    // get user input
    Read "Enter a string: ",input,!,!
 
    // if user input is part of the list, print the list's content
    if $ListFind(Mail, input) {
        for i=1:1:$ListLength(Mail) {
            Write $List(Mail, i),!
        }
     }
}

This procedure demonstrates several notable aspects of lists:

$ListFind only returns true if the value being tested matches the list item exactly.
$ListFind and $ListLength are used in expressions.

Advanced List Features

A call that sets the value of an element in a list will add enough list items so that it can place the substring as the proper item in an otherwise empty list. For instance, if you set the fourth item in a list,

 Set $List(Alphalist, 1) = "a"
 Set $List(Alphalist, 20) = "t"
 Write $Listlength(Alphalist)

will return a value of 20, since it creates twenty items for the list. However, items 2 through 19, in this example, will not have values set. Hence, if you attempt to display any of their values, you will receive a <NULL VALUE> error.

A list item can also be a list. To retrieve a value from a sublist such as this, nest $List function calls, as in the following code:

 Set $List(Powers, 2)=$ListBuild(2,4,8,16,32)
 Write $List( $List(Powers, 2), 5)

This code returns 32, which is the value of the fifth element in the sublist contained by the second element in the Powers list. (In the Powers list, the second item is a sublist of two raised to the first through fifth powers, so that the first item in the sublist is two to the first power, and so on.)

Lists Versus $Piece and Strings

Though the $Piece function allows you to manage lists, it depends on delimiters; a list is useful for avoiding delimiters altogether. With delimiters, there's always the chance that one of the substrings will contain the delimiter character(s), which will throw off the positions of the pieces in the list. Lists prevent this.

One possible benefit of the $Piece-oriented approach is that it allows you to more flexibly search its content, using the $Find function. Because $ListFind requires an exact match, you cannot search for random substrings in lists. Hence, in the example above, searching on the string “One” will return Zero, indicating failure, even though the address begins with the characters “One”. At the same time, this potential benefit must be weighed against the ease of use of the list features as a whole.