Skip to main content

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; delimited string operations; and list-structure string operations.

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. For more details, see $LENGTH.

  • $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
    

    For more details, see $JUSTIFY.

  • $ZCONVERT converts a string from one form to another. It supports both case translations (to uppercase, to lowercase, or to title case) and encoding translation (between various character encoding styles). For example, the code:

     WRITE $ZCONVERT("cRAZy cAPs","t")

    returns:

    CRAZY CAPS
    

    For more details, see $ZCONVERT.

  • 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. For more details, see $FIND.

  • The $TRANSLATE function performs a character-by-character replacement within a string. For example, the code:

     SET text = "11/04/2008"
     WRITE $TRANSLATE(text,"/","-")

    replaces the date’s slashes with hyphens. For more details, see $TRANSLATE.

  • The $REPLACE function performs string-by-string replacement within a string; the function does not change the value of the string on which it operates. For example, the following code performs two distinct operations:

     SET text = "green leaves, brown leaves"
     WRITE text,!
     WRITE $REPLACE(text,"leaves","eyes"),!
     WRITE $REPLACE(text,"leaves","hair",15),!
     WRITE text,!

    In the first call, $REPLACE replaces the string leaves with the string eyes. In the second call, $REPLACE discards all the characters prior to the fifteenth character (specified by the fourth argument) and replaces the string leaves with the string hair. The value of the text string is not changed by either $REPLACE call. For more details, see $REPLACE.

  • 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
    

    For more details, see the next section and see $EXTRACT.

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

ObjectScript includes functions that allow you to work with strings as a set of substrings, so that you can pass related pieces of data as a single string. These are functions 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 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 $PIECE.

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 InterSystems IRIS lists can only be handled using the following list functions:

  • List creation:

    • $LISTBUILD creates a list by specifying each element as a parameter value.

    • $LISTFROMSTRING creates a list by specifying a string that contains delimiters. The function uses the delimiter to divide the string into elements.

    • $LIST creates a list by extracting it as a sublist from an existing list.

  • List data retrieval:

    • $LIST returns a list element value by position. It can count positions from the beginning or the end of the list.

    • $LISTNEXT returns list element values sequentially from the beginning of the list. While both $LIST and $LISTNEXT can be used to sequentially return elements from a list, $LISTNEXT is significantly faster when returning a large number of list elements.

    • $LISTGET returns a list element value by position, or returns a default value.

    • $LISTTOSTRING returns all of the element values in a list as a delimited string.

  • List manipulation:

    • SET $LIST inserts, updates, or deletes elements in a list. SET $LIST replaces a list element or a range of list elements with one or more values. Because SET $LIST can replace a list element with more than one element, you can use it to insert elements into a list. Because SET $LIST can replace a list element with a null string, you can use it to delete a list element or a range of list elements.

  • List evaluation:

    • $LISTVALID determines if a string is a valid list.

    • $LISTLENGTH determines the number of elements in a list.

    • $LISTDATA determines if a specified list element contains data.

    • $LISTFIND determines if a specified value is found in a list, returning the list position.

    • $LISTSAME determines if two lists are identical.

Because a list is an encoded string, InterSystems IRIS 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:

  • $LISTFIND only returns 1 (True) if the value being tested matches the list item exactly.

  • $LISTFIND and $LISTLENGTH are used in expressions.

For more detailed information on list functions see the corresponding reference pages in the 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

  • Lists do not require a designated delimiter. Though the $PIECE function allows you to manage a string containing multiple data items, it depends on setting aside a character (or character string) as a dedicated delimiter. When using delimiters, there is always the chance that one of the data items will contain the delimiter character(s) as data, which will throw off the positions of the pieces in the delimited string. A list is useful for avoiding delimiters altogether, and thus allowing any character or combination of characters to be entered as data.

  • Data elements can be retrieved faster from a list (using $LIST or $LISTNEXT) than from a delimited string (using $PIECE). For sequential data retrieval, $LISTNEXT is significantly faster than $LIST, and both are significantly faster than $PIECE.

Advantages of Delimited Strings

  • A delimited string allows you to more flexibly search the contents of data, using the $FIND function. Because $LISTFIND requires an exact match, you cannot search for partial substrings in lists. Hence, in the example above, using $LISTFIND to search for the string One in the Mail list return 0 (indicating failure), even though the address One Memorial Drive begins with the characters One.

  • Because a delimited string is a standard string, you can use all of the standard string functions on it. Because an InterSystems IRIS list is an encoded string, you can only use $List functions on an InterSystems IRIS list.

FeedbackOpens in a new tab