7. The String library

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

7.1. Squirrel API

7.1.1. Global Symbols

endswith(str, cmp)

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

escape(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).

e.g.
sq> print(format("%s %d 0x%02X\n","this is a test :",123,10));
this is a test : 123 0x0A
printf(formatstr, ...)

Just like calling print(format(formatstr as in the example above, but is more convenient AND more efficient.

e.g.
sq> printf("%s %d 0x%02X\n","this is a test :",123,10);
this is a test : 123 0x0A

Note

The following functions are also available as string default delegates.

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_by_chars(str, separators[, skipempty])

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. The parameter skipempty is a boolean (default false). If skipempty is true, empty strings are not added to array.

eg.
let a = split_by_chars("1.2-3;;4/5", ".-/;")
// the result will be  [1,2,3,,4,5]
or
let b = split_by_chars("1.2-3;;4/5", ".-/;", true)
// the result will be  [1,2,3,4,5]
startswith(str, cmp)

returns true if the beginning of the string str matches 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.

7.1.2. The regexp class

class regexp(pattern)

The regexp object represents a precompiled regular expression pattern. The object is created through regexp(pattern).

\

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 digits

\x

hexadecimal digits

\X

non hexadecimal digits

\c

control characters

\C

non control characters

\p

punctuation

\P

non punctuation

\b

word boundary

\B

non word boundary
regexp.capture(str[, start])

returns an array of tables containing two indexes (“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)
{
    println(format("match number[%02d] %s",
            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 indexes (“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"

7.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.

7.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).

7.2.2. Regular Expessions

SQRex *sqstd_rex_compile(SQAllocCtx alloc_ctx, const SQChar *pattern, const SQChar **error)

:param SQAllocCtx alloc_ctx VM memory allocation context handle :param SQChar* pattern: a pointer to a zero terminated string containing the pattern that has to be compiled. :param SQChar** error: 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 expression 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 expression in the string delimited by the parameter text_begin and text_end. if the match is found returns SQTrue and 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 a valid index; otherwise SQFalse.

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