Using Caché ObjectScript
String Operations
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
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
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 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,Obama",",",3)
 SET y = $PIECE("Reagan,Bush,Clinton,Bush,Obama","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, suppose some code sets the first, then the fourth, then the twentieth item in a list,
 SET $PIECE(Alphalist, "^", 1) = "a"
 WRITE "First, the length of the list is ",$LENGTH(Alphalist,"^"),".",!
 SET $PIECE(Alphalist, "^", 4) = "d"
 WRITE "Then, the length of the list is ",$LENGTH(Alphalist,"^"),".",!
 SET $PIECE(Alphalist, "^", 20) = "t"
 WRITE "Finally, the length of the list is ",$LENGTH(Alphalist,"^"),".",!
 
The $LENGTH function returns a value of 1, then 4, then 20, since it creates the necessary number of delimited items. However, items 2, 3, and 5 through 19 do not have values set. Hence, if you attempt to display any of their values, nothing appears.
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.)
For more details, see the $PIECE reference page in the Caché ObjectScript Reference.
List-Structure String Operations
ObjectScript defines a special kind of string called a “list”, which consists of an encoded list of substrings, known as elements. These Caché lists can only be handled using the following list functions:
Because a list is an encoded string, Caché treats lists slightly differently than standard strings. Therefore, you should not use standard string functions on lists. Further, using most list functions on a standard 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:
For more detailed information on list functions see the corresponding reference pages in the Caché ObjectScript Reference.
Sparse Lists and Sublists
A function that adds an element value to a list by position will add enough list elements to place the value in the proper position. For example:
  SET $LIST(Alphalist,1)="a"
  SET $LIST(Alphalist,20)="t"
  WRITE $LISTLENGTH(Alphalist)
 
Because the second $LIST in this example creates list element 20, $LISTLENGTH returns a value of 20. However, elements 2 through 19 do not have values set. Hence, if you attempt to display any of their values, you will receive a <NULL VALUE> error. You can use $LISTGET to avoid this error.
An element in a list can itself 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 and Delimited Strings Compared
Advantages of Lists
Advantages of Delimited Strings