1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
|
.. _stdlib_stdstringlib:
==================
The String library
==================
the string lib implements string formatting and regular expression matching routines.
--------------
Squirrel API
--------------
++++++++++++++
Global Symbols
++++++++++++++
.. js:function:: endswith(str, cmp)
returns `true` if the end of the string `str` matches a the string `cmp` otherwise returns `false`
.. js:function:: ecape(str)
Returns a string with backslashes before characters that need to be escaped(`\",\a,\b,\t,\n,\v,\f,\r,\\,\",\',\0,\xnn`).
.. js:function:: 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
.. js:function:: lstrip(str)
Strips white-space-only characters that might appear at the beginning of the given string
and returns the new stripped string.
.. js:function:: rstrip(str)
Strips white-space-only characters that might appear at the end of the given string
and returns the new stripped string.
.. js:function:: 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]
.. js:function:: startswith(str, cmp)
returns `true` if the beginning of the string `str` matches a the string `cmp` otherwise returns `false`
.. js:function:: 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.
++++++++++++++++++
The regexp class
++++++++++++++++++
.. js: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 |
+---------------------+--------------------------------------+
.. js:function:: 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] ;
.. js:function:: regexp.match(str)
returns a true if the regular expression matches the string
`str`, otherwise returns false.
.. js:function:: 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"
-------------
C API
-------------
.. _sqstd_register_stringlib:
.. c:function:: SQRESULT sqstd_register_stringlib(HSQUIRRELVM v)
:param HSQUIRRELVM v: 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.
+++++++++++++
Formatting
+++++++++++++
.. c:function:: SQRESULT sqstd_format(HSQUIRRELVM v, SQInteger nformatstringidx, SQInteger* outlen, SQChar** output)
:param HSQUIRRELVM v: the target VM
:param SQInteger nformatstringidx: index in the stack of the format string
:param SQInteger* outlen: a pointer to an integer that will be filled with the length of the newly created string
:param SQChar** output: 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).
++++++++++++++++++
Regular Expessions
++++++++++++++++++
.. c:function:: SQRex* sqstd_rex_compile(const SQChar *pattern, const SQChar ** error)
: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().
.. c:function:: void sqstd_rex_free(SQRex * exp)
:param SQRex* exp: the expression structure that has to be deleted.
deletes a expression structure created with sqstd_rex_compile()
.. c:function:: SQBool sqstd_rex_match(SQRex * exp,const SQChar * text)
:param SQRex* exp: a compiled expression
:param SQChar* text: 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.
.. c:function:: SQBool sqstd_rex_search(SQRex * exp, const SQChar * text, const SQChar ** out_begin, const SQChar ** out_end)
:param SQRex* exp: a compiled expression
:param SQChar* text: the string that has to be tested
:param SQChar** out_begin: a pointer to a string pointer that will be set with the beginning of the match
:param SQChar** out_end: 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.
.. c:function:: SQBool sqstd_rex_searchrange(SQRex * exp, const SQChar * text_begin, const SQChar * text_end, const SQChar ** out_begin, const SQChar ** out_end)
:param SQRex* exp: a compiled expression
:param SQChar* text_begin: a pointer to the beginnning of the string that has to be tested
:param SQChar* text_end: a pointer to the end of the string that has to be tested
:param SQChar** out_begin: a pointer to a string pointer that will be set with the beginning of the match
:param SQChar** out_end: 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.
.. c:function:: SQInteger sqstd_rex_getsubexpcount(SQRex * exp)
:param SQRex* exp: a compiled expression
:returns: the number of sub expressions matched by the expression
returns the number of sub expressions matched by the expression
.. c:function:: SQBool sqstd_rex_getsubexp(SQRex * exp, SQInteger n, SQRexMatch *subexp)
:param SQRex* exp: a compiled expression
:param SQInteger n: the index of the submatch(0 is the complete match)
:param SQRexMatch* a: 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.
|
