6. The String library

the string lib implements string formatting and regular expression matching routines.

6.1. Squirrel API

6.1.1. Global Symbols

endswith(str, cmp)

returns true if the end of the string str matches a the string cmp otherwise returns false

ecape(str)

Returns a string with backslashes before characters that need to be escaped(”,a,b,t,n,v,f,r,\,”,’,0,xnn).

format(formatstr, ...)

Returns a string formatted according formatstr and the optional parameters following it. The format string follows the same rules as the printf family of standard C functions( the “*” is not supported).

eg.
sq> print(format("%s %d 0x%02X\n","this is a test :",123,10));
this is a test : 123 0x0A
lstrip(str)

Strips white-space-only characters that might appear at the beginning of the given string and returns the new stripped string.

rstrip(str)

Strips white-space-only characters that might appear at the end of the given string and returns the new stripped string.

split(str, separtators)

returns an array of strings split at each point where a separator character occurs in str. The separator is not returned as part of any array element. The parameter separators is a string that specifies the characters as to be used for the splitting.

eg.
local a = split("1.2-3;4/5",".-/;");
// the result will be  [1,2,3,4,5]
startswith(str, cmp)

returns true if the beginning of the string str matches a the string cmp otherwise returns false

strip(str)

Strips white-space-only characters that might appear at the beginning or end of the given string and returns the new stripped string.

6.1.2. The regexp class

class regexp(pattern)

The regexp object rapresent a precompiled regular experssion pattern. The object is created trough regexp(patern).

\ Quote the next metacharacter
^ Match the beginning of the string
. Match any character
$ Match the end of the string
| Alternation
(subexp) Grouping (creates a capture)
(?:subexp) No Capture Grouping (no capture)
[] Character class

GREEDY CLOSURES

* Match 0 or more times
+ Match 1 or more times
? Match 1 or 0 times
{n} Match exactly n times
{n,} Match at least n times
{n,m} Match at least n but not more than m times

ESCAPE CHARACTERS

\t tab (HT, TAB)
\n newline (LF, NL)
\r return (CR)
\f form feed (FF)

PREDEFINED CLASSES

\l lowercase next char
\u uppercase next char
\a letters
\A non letters
\w alphanumeric [_0-9a-zA-Z]
\W non alphanumeric [^_0-9a-zA-Z]
\s space
\S non space
\d digits
\D non nondigits
\x exadecimal digits
\X non exadecimal digits
\c control characters
\C non control characters
\p punctation
\P non punctation
\b word boundary
\B non word boundary
regexp.capture(str[, start])

returns an array of tables containing two indexs(“begin” and “end”)of the first match of the regular expression in the string str. An array entry is created for each captured sub expressions. If no match occurs returns null. The search starts from the index start of the string, if start is omitted the search starts from the beginning of the string.

the first element of the returned array(index 0) always contains the complete match.

local ex = regexp(@"(\d+) ([a-zA-Z]+)(\p)");
local string = "stuff 123 Test;";
local res = ex.capture(string);
foreach(i,val in res)
{
    print(format("match number[%02d] %s\n",
            i,string.slice(val.begin,val.end))); //prints "Test"
}

...
will print
match number[00] 123 Test;
match number[01] 123
match number[02] Test
match number[03] ;
regexp.match(str)

returns a true if the regular expression matches the string str, otherwise returns false.

regexp.search(str[, start])

returns a table containing two indexs(“begin” and “end”) of the first match of the regular expression in the string str, otherwise if no match occurs returns null. The search starts from the index start of the string, if start is omitted the search starts from the beginning of the string.

local ex = regexp("[a-zA-Z]+");
local string = "123 Test;";
local res = ex.search(string);
print(string.slice(res.begin,res.end)); //prints "Test"

6.2. C API

SQRESULT sqstd_register_stringlib(HSQUIRRELVM v)
Parameters:
  • v (HSQUIRRELVM) – the target VM
Returns:

an SQRESULT

Remarks:

The function aspects a table on top of the stack where to register the global library functions.

initialize and register the string library in the given VM.

6.2.1. Formatting

SQRESULT sqstd_format(HSQUIRRELVM v, SQInteger nformatstringidx, SQInteger* outlen, SQChar** output)
Parameters:
  • v (HSQUIRRELVM) – the target VM
  • nformatstringidx (SQInteger) – index in the stack of the format string
  • outlen (SQInteger*) – a pointer to an integer that will be filled with the length of the newly created string
  • output (SQChar**) – a pointer to a string pointer that will receive the newly created string
Returns:

an SQRESULT

Remarks:

the newly created string is allocated in the scratchpad memory.

creates a new string formatted according to the object at position nformatstringidx and the optional parameters following it. The format string follows the same rules as the printf family of standard C functions( the “*” is not supported).

6.2.2. Regular Expessions

SQRex* sqstd_rex_compile(const SQChar *pattern, const SQChar ** error)
Parameters:
  • pattern (SQChar*) – a pointer to a zero terminated string containing the pattern that has to be compiled.
  • error (SQChar**) – a pointer to a string pointer that will be set with an error string in case of failure.
Returns:

a pointer to the compiled pattern

compiles an expression and returns a pointer to the compiled version. in case of failure returns NULL.The returned object has to be deleted through the function sqstd_rex_free().

void sqstd_rex_free(SQRex * exp)
Parameters:
  • exp (SQRex*) – the expression structure that has to be deleted.

deletes a expression structure created with sqstd_rex_compile()

SQBool sqstd_rex_match(SQRex * exp, const SQChar * text)
Parameters:
  • exp (SQRex*) – a compiled expression
  • text (SQChar*) – the string that has to be tested
Returns:

SQTrue if successful otherwise SQFalse

returns SQTrue if the string specified in the parameter text is an exact match of the expression, otherwise returns SQFalse.

Parameters:
  • exp (SQRex*) – a compiled expression
  • text (SQChar*) – the string that has to be tested
  • out_begin (SQChar**) – a pointer to a string pointer that will be set with the beginning of the match
  • out_end (SQChar**) – a pointer to a string pointer that will be set with the end of the match
Returns:

SQTrue if successful otherwise SQFalse

searches the first match of the expressin in the string specified in the parameter text. if the match is found returns SQTrue and the sets out_begin to the beginning of the match and out_end at the end of the match; otherwise returns SQFalse.

SQBool sqstd_rex_searchrange(SQRex * exp, const SQChar * text_begin, const SQChar * text_end, const SQChar ** out_begin, const SQChar ** out_end)
Parameters:
  • exp (SQRex*) – a compiled expression
  • text_begin (SQChar*) – a pointer to the beginnning of the string that has to be tested
  • text_end (SQChar*) – a pointer to the end of the string that has to be tested
  • out_begin (SQChar**) – a pointer to a string pointer that will be set with the beginning of the match
  • out_end (SQChar**) – a pointer to a string pointer that will be set with the end of the match
Returns:

SQTrue if successful otherwise SQFalse

searches the first match of the expressin in the string delimited by the parameter text_begin and text_end. if the match is found returns SQTrue and the sets out_begin to the beginning of the match and out_end at the end of the match; otherwise returns SQFalse.

SQInteger sqstd_rex_getsubexpcount(SQRex * exp)
Parameters:
  • exp (SQRex*) – a compiled expression
Returns:

the number of sub expressions matched by the expression

returns the number of sub expressions matched by the expression

SQBool sqstd_rex_getsubexp(SQRex * exp, SQInteger n, SQRexMatch *subexp)
Parameters:
  • exp (SQRex*) – a compiled expression
  • n (SQInteger) – the index of the submatch(0 is the complete match)
  • a (SQRexMatch*) – pointer to structure that will store the result
Returns:

the function returns SQTrue if n is valid index otherwise SQFalse.

retrieve the begin and and pointer to the length of the sub expression indexed by n. The result is passed trhough the struct SQRexMatch.