String Manipulation

XSB has a number of powerful builtins that simplify the job of string manipulation. These builting are especially powerful when they are combined with pattern-matching facilities provided by the regmatch package described in Chapter 4.

str_sub(+Sub, +Str, ?Pos)

string

Succeeds if Sub is a substring of Str. In that case, Pos unifies with the position where the match occurred.

str_cat(+Str1, +Str2, ?Result)

string

Concatenates Str1 with Str2. Unifies the result with Result.

In addition to this, the predicate fmt_write_string/3 described in Section 1.5 can be used to concatenate strings and do much more. However, for simple string concatenation, str_cat/3 is more efficient.

str_length(+Str, ?Result)

string

Unifies the Result with the length of Str.

substring(+String, +BeginOffset, +EndOffset, -Result)

string
String can be an atom or a list of characters, and the offsets must be integers. If EndOffset is negative, endof( String)+ EndOffset is assumed. If EndOffset is an unbound variable, then end of string is assumed. If BeginOffset is less than 0, then 0 is assumed; if it is greater than the length of the string, then string end is assumed. If EndOffset is non-negative, but is less than BeginOffset, then empty string is returned.

The result returned in the fourth argument is a string, if String is an atom, or a list of characters, if so is String.

The substring/4 predicate always succeeds (unless there is an error, such as wrong argument type).

Here are some examples:

| ?- substring('abcdefg', 3, 5, L).

L = de

| ?- substring("abcdefg", 4, -1, L).

L = [101,102]

( i.e., L = ef represented using ASCII codes).

string_substitute(+String, +SubstrList, +SubstitutionList, -OutStr)

string

InputStr can an atom or a list of characters. SubstrList must be a list of terms of the form s(BegOffset, EndOffset), where the name of the functor is immaterial. The meaning of the offsets is the same as for re_substring/4. Each such term specifies a substring (between BegOffset and EndOffset; negative EndOffset stands for the end of string) to be replaced. SubstitutionList must be a list of atoms or character lists.

This predicate replaces the substrings specified in SubstrList with the corresponding strings from SubstitutionList. The result is returned in OutStr. OutStr is a list of characters, if so is InputStr; otherwise, it is an atom.

If SubstitutionList is shorter than SubstrList then the last string in SubstitutionList is used for substituting the extra substrings specified in SubstitutionList. As a special case, this makes it possible to replace all specified substrings with a single string.

As in the case of re_substring/4, if OutStr is an atom, it is not interned. The user should either intern this string or convert it into a list, as explained previously.

The string_substitute/4 predicate always succeeds.

Here are some examples:

| ?- string_substitute('qaddf', [s(2,4)], ['123'] ,L).

L = qa123f

| ?- string_substitute('qaddf', [s(2,-1)], ['123'] ,L).

L = qa123

| ?- string_substitute("abcdefg", [s(4,-1)], ["123"],L).

L = [97,98,99,100,49,50,51]

| ?- string_substitute('1234567890123', [f(1,5),f(5,7),f(9,-2)], ["pppp", lll],X).

X = 1pppplll89lll

| ?- string_substitute('1234567890123', [f(1,5),f(6,7),f(9,-2)], ['---'],X).

X = 1---6---89---