/
string.inc
593 lines (543 loc) · 20.6 KB
/
string.inc
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
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
/**
* vim: set ts=4 :
* =============================================================================
* SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
* =============================================================================
*
* This file is part of the SourceMod/SourcePawn SDK.
*
* This program is free software; you can redistribute it and/or modify it under
* the terms of the GNU General Public License, version 3.0, as published by the
* Free Software Foundation.
*
* This program is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
* details.
*
* You should have received a copy of the GNU General Public License along with
* this program. If not, see <http://www.gnu.org/licenses/>.
*
* As a special exception, AlliedModders LLC gives you permission to link the
* code of this program (as well as its derivative works) to "Half-Life 2," the
* "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
* by the Valve Corporation. You must obey the GNU General Public License in
* all respects for all other code used. Additionally, AlliedModders LLC grants
* this exception to all derivative works. AlliedModders LLC defines further
* exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
* or <http://www.sourcemod.net/license.php>.
*
* Version: $Id$
*/
#if defined _string_included
#endinput
#endif
#define _string_included
/**
* @global Unless otherwise noted, all string functions which take in a
* writable buffer and maximum length should have the null terminator INCLUDED
* in the length. This means that this is valid:
* strcopy(string, sizeof(string), ...)
*/
/**
* Calculates the length of a string.
*
* @param str String to check.
* @return Number of valid character bytes in the string.
*/
native int strlen(const char[] str);
/**
* Tests whether a string is found inside another string.
*
* @param str String to search in.
* @param substr Substring to find inside the original string.
* @param caseSensitive If true (default), search is case sensitive.
* If false, search is case insensitive.
* @return -1 on failure (no match found). Any other value
* indicates a position in the string where the match starts.
*/
native int StrContains(const char[] str, const char[] substr, bool caseSensitive=true);
/**
* Compares two strings lexographically.
*
* @param str1 First string (left).
* @param str2 Second string (right).
* @param caseSensitive If true (default), comparison is case sensitive.
* If false, comparison is case insensitive.
* @return -1 if str1 < str2
* 0 if str1 == str2
* 1 if str1 > str2
*/
native int strcmp(const char[] str1, const char[] str2, bool caseSensitive=true);
/**
* Compares two strings parts lexographically.
*
* @param str1 First string (left).
* @param str2 Second string (right).
* @param num Number of characters to compare.
* @param caseSensitive If true (default), comparison is case sensitive.
* If false, comparison is case insensitive.
* @return -1 if str1 < str2
* 0 if str1 == str2
* 1 if str1 > str2
*/
native int strncmp(const char[] str1, const char[] str2, int num, bool caseSensitive=true);
/**
* Backwards compatible stock - StrCompare is now strcmp
* @deprecated Renamed to strcmp
*/
#pragma deprecated Use strcmp() instead
stock int StrCompare(const char[] str1, const char[] str2, bool caseSensitive=true)
{
return strcmp(str1, str2, caseSensitive);
}
/**
* Returns whether two strings are equal.
*
* @param str1 First string (left).
* @param str2 Second string (right).
* @param caseSensitive If true (default), comparison is case sensitive.
* If false, comparison is case insensitive.
* @return True if equal, false otherwise.
*/
stock bool StrEqual(const char[] str1, const char[] str2, bool caseSensitive=true)
{
return (strcmp(str1, str2, caseSensitive) == 0);
}
/**
* Copies one string to another string.
* @note If the destination buffer is too small to hold the source string, the
* destination will be truncated.
*
* @param dest Destination string buffer to copy to.
* @param destLen Destination buffer length (includes null terminator).
* @param source Source string buffer to copy from.
* @return Number of characters written to the buffer,
* not including the null terminator.
*/
native int strcopy(char[] dest, int destLen, const char[] source);
/**
* Backwards compatibility stock - use strcopy
* @deprecated Renamed to strcopy
*/
#pragma deprecated Use strcopy() instead
stock int StrCopy(char[] dest, int destLen, const char[] source)
{
return strcopy(dest, destLen, source);
}
/**
* Formats a string according to the SourceMod format rules (see documentation).
*
* @param buffer Destination string buffer.
* @param maxlength Maximum length of output string buffer,
* including the null terminator.
* @param format Formatting rules.
* @param ... Variable number of format parameters.
* @return Number of characters written to the buffer,
* not including the null terminator.
*/
native int Format(char[] buffer, int maxlength, const char[] format, any ...);
/**
* Formats a string according to the SourceMod format rules (see documentation).
* @note This is the same as Format(), except none of the input buffers can
* overlap the same memory as the output buffer. Since this security
* check is removed, it is slightly faster.
*
* @param buffer Destination string buffer.
* @param maxlength Maximum length of output string buffer,
* including the null terminator.
* @param format Formatting rules.
* @param ... Variable number of format parameters.
* @return Number of characters written to the buffer,
* not including the null terminator.
*/
native int FormatEx(char[] buffer, int maxlength, const char[] format, any ...);
/**
* Formats a string according to the SourceMod format rules (see documentation).
* @note This is the same as Format(), except it grabs parameters from a
* parent parameter stack, rather than a local. This is useful for
* implementing your own variable argument functions.
*
* @param buffer Destination string buffer.
* @param maxlength Maximum length of output string buffer,
* including the null terminator.
* @param format Formatting rules.
* @param varpos Argument number which contains the '...' symbol.
* Note: Arguments start at 1.
* @return Number of bytes written.
* @error Invalid argument index.
*/
native int VFormat(char[] buffer, int maxlength, const char[] format, int varpos);
/**
* Converts a string to an integer.
*
* @param str String to convert.
* @param nBase Numerical base to use. 10 is default.
* @return Integer conversion of string, or 0 on failure.
*/
native int StringToInt(const char[] str, int nBase=10);
/**
* Converts a string to an integer with some more options.
*
* @param str String to convert.
* @param result Variable to store the result in.
* @param nBase Numerical base to use. 10 is default.
* @return Number of characters consumed.
*/
native int StringToIntEx(const char[] str, int &result, int nBase=10);
/**
* Converts a string to a 64-bit integer.
*
* @param str String to convert.
* @param result Array to store the upper and lower
* 32-bits of the 64-bit integer.
* @param nBase Numerical base to use. 10 is default.
* @return Number of characters consumed.
*/
native int StringToInt64(const char[] str, int result[2], int nBase=10);
/**
* Converts an integer to a string.
*
* @param num Integer to convert.
* @param str Buffer to store string in.
* @param maxlength Maximum length of string buffer.
* @return Number of characters written to the buffer,
* not including the null terminator.
*/
native int IntToString(int num, char[] str, int maxlength);
/**
* Converts a 64-bit integer to a string.
*
* @param num Array containing the upper and lower
* 32-bits of a 64-bit integer.
* @param str Buffer to store string in.
* @param maxlength Maximum length of string buffer.
* @return Number of characters written to the buffer,
* not including the null terminator.
*/
native int Int64ToString(const int num[2], char[] str, int maxlength);
/**
* Converts a string to a floating point number.
*
* @param str String to convert to a float.
* @return Floating point result, or 0.0 on error.
*/
native float StringToFloat(const char[] str);
/**
* Converts a string to a floating point number with some more options.
*
* @param str String to convert to a float.
* @param result Variable to store result in.
* @return Number of characters consumed.
*/
native int StringToFloatEx(const char[] str, float &result);
/**
* Converts a floating point number to a string.
*
* @param num Floating point number to convert.
* @param str Buffer to store string in.
* @param maxlength Maximum length of string buffer.
* @return Number of characters written to the buffer,
* not including the null terminator.
*/
native int FloatToString(float num, char[] str, int maxlength);
/**
* Finds the first "argument" in a string; either a set of space
* terminated characters, or a fully quoted string. After the
* argument is found, whitespace is read until the next portion
* of the string is reached. If nothing remains, -1 is returned.
* Otherwise, the index to the first character is returned.
*
* @param source Source input string.
* @param arg Stores argument read from string.
* @param argLen Maximum length of argument buffer.
* @return Index to next piece of string, or -1 if none.
*/
native int BreakString(const char[] source, char[] arg, int argLen);
/**
* Backwards compatibility stock - use BreakString
* @deprecated Renamed to BreakString.
*/
#pragma deprecated Use BreakString() instead
stock int StrBreak(const char[] source, char[] arg, int argLen)
{
return BreakString(source, arg, argLen);
}
/**
* Removes whitespace characters from the beginning and end of a string.
*
* @param str The string to trim.
* @return Number of bytes written (UTF-8 safe).
*/
native int TrimString(char[] str);
/**
* Returns text in a string up until a certain character sequence is reached.
*
* @param source Source input string.
* @param split A string which specifies a search point to break at.
* @param part Buffer to store string part.
* @param partLen Maximum length of the string part buffer.
* @return -1 if no match was found; otherwise, an index into source
* marking the first index after the searched text. The
* index is always relative to the start of the input string.
*/
native int SplitString(const char[] source, const char[] split, char[] part, int partLen);
/**
* Given a string, replaces all occurrences of a search string with a
* replacement string.
*
* @param text String to perform search and replacements on.
* @param maxlength Maximum length of the string buffer.
* @param search String to search for.
* @param replace String to replace the search string with.
* @param caseSensitive If true (default), search is case sensitive.
* @return Number of replacements that were performed.
* @error 'search' parameter is empty.
*/
native int ReplaceString(char[] text, int maxlength, const char[] search, const char[] replace, bool caseSensitive=true);
/**
* Given a string, replaces the first occurrence of a search string with a
* replacement string.
*
* @param text String to perform search and replacements on.
* @param maxlength Maximum length of the string buffer.
* @param search String to search for.
* @param replace String to replace the search string with.
* @param searchLen If higher than -1, its value will be used instead of
* a strlen() call on the search parameter.
* @param replaceLen If higher than -1, its value will be used instead of
* a strlen() call on the replace parameter.
* @param caseSensitive If true (default), search is case sensitive.
* @return Index into the buffer (relative to the start) from where
* the last replacement ended, or -1 if no replacements were
* made.
* @error 'search' parameter is empty.
*/
native int ReplaceStringEx(char[] text, int maxlength, const char[] search, const char[] replace, int searchLen=-1, int replaceLen=-1, bool caseSensitive=true);
/**
* Returns the number of bytes a character is using. This is
* for multi-byte characters (UTF-8). For normal ASCII characters,
* this will return 1.
*
* @param source Source input string.
* @return Number of bytes the current character uses.
*/
native int GetCharBytes(const char[] source);
/**
* Returns whether a character is an ASCII alphabet character.
*
* @note Multi-byte characters will always return false.
*
* @param chr Character to test.
* @return True if character is alphabetical, otherwise false.
*/
native bool IsCharAlpha(int chr);
/**
* Returns whether a character is numeric.
*
* @note Multi-byte characters will always return false.
*
* @param chr Character to test.
* @return True if character is numeric, otherwise false.
*/
native bool IsCharNumeric(int chr);
/**
* Returns whether a character is whitespace.
*
* @note Multi-byte characters will always return false.
*
* @param chr Character to test.
* @return True if character is whitespace, otherwise false.
*/
native bool IsCharSpace(int chr);
/**
* Returns if a character is multi-byte or not.
*
* @param chr Character to test.
* @return 0 for a normal 7-bit ASCII character,
* otherwise number of bytes in multi-byte character.
*/
native int IsCharMB(int chr);
/**
* Returns whether an alphabetic character is uppercase.
*
* @note Multi-byte characters will always return false.
*
* @param chr Character to test.
* @return True if character is uppercase, otherwise false.
*/
native bool IsCharUpper(int chr);
/**
* Returns whether an alphabetic character is lowercase.
*
* @note Multi-byte characters will always return false.
*
* @param chr Character to test.
* @return True if character is lowercase, otherwise false.
*/
native bool IsCharLower(int chr);
/**
* Strips a quote pair off a string if it exists. That is, the following
* replace rule is applied once: ^"(.*)"$ -> ^\1$
*
* Note that the leading and trailing quotes will only be removed if both
* exist. Otherwise, the string is left unmodified. This function should
* be considered O(k) (all characters get shifted down).
*
* @param text String to modify (in place).
* @return True if string was modified, false if there was no
* set of quotes.
*/
native bool StripQuotes(char[] text);
/**
* Converts a lowercase character to its uppercase counterpart.
*
* @param chr Character to convert.
* @return Uppercase character on success,
* no change on failure.
*/
stock int CharToUpper(int chr)
{
if (IsCharLower(chr))
{
return (chr & ~(1<<5));
}
return chr;
}
/**
* Converts an uppercase character to its lowercase counterpart.
*
* @param chr Character to convert.
* @return Lowercase character on success,
* no change on failure.
*/
stock int CharToLower(int chr)
{
if (IsCharUpper(chr))
{
return (chr | (1<<5));
}
return chr;
}
/**
* Finds the first occurrence of a character in a string.
*
* @param str String.
* @param c Character to search for.
* @param reverse False (default) to search forward, true to search
* backward.
* @return The index of the first occurrence of the character
* in the string, or -1 if the character was not found.
*/
stock int FindCharInString(const char[] str, char c, bool reverse = false)
{
int len = strlen(str);
if (!reverse)
{
for (int i = 0; i < len; i++)
{
if (str[i] == c)
{
return i;
}
}
}
else
{
for (int i = len - 1; i >= 0; i--)
{
if (str[i] == c)
{
return i;
}
}
}
return -1;
}
/**
* Concatenates one string onto another.
*
* @param buffer String to append to.
* @param maxlength Maximum length of entire buffer.
* @param source Source string to concatenate.
* @return Number of bytes written.
*/
stock int StrCat(char[] buffer, int maxlength, const char[] source)
{
int len = strlen(buffer);
if (len >= maxlength)
{
return 0;
}
return Format(buffer[len], maxlength-len, "%s", source);
}
/**
* Breaks a string into pieces and stores each piece into an array of buffers.
*
* @param text The string to split.
* @param split The string to use as a split delimiter.
* @param buffers An array of string buffers (2D array).
* @param maxStrings Number of string buffers (first dimension size).
* @param maxStringLength Maximum length of each string buffer.
* @param copyRemainder False (default) discard excess pieces, true to ignore
* delimiters after last piece.
* @return Number of strings retrieved.
*/
stock int ExplodeString(const char[] text, const char[] split, char[][] buffers, int maxStrings,
int maxStringLength, bool copyRemainder = false)
{
int reloc_idx, idx, total;
if (maxStrings < 1 || !split[0])
{
return 0;
}
while ((idx = SplitString(text[reloc_idx], split, buffers[total], maxStringLength)) != -1)
{
reloc_idx += idx;
if (++total == maxStrings)
{
if (copyRemainder)
{
strcopy(buffers[total-1], maxStringLength, text[reloc_idx-idx]);
}
return total;
}
}
strcopy(buffers[total++], maxStringLength, text[reloc_idx]);
return total;
}
/**
* Joins an array of strings into one string, with a "join" string inserted in
* between each given string. This function complements ExplodeString.
*
* @param strings An array of strings.
* @param numStrings Number of strings in the array.
* @param join The join string to insert between each string.
* @param buffer Output buffer to write the joined string to.
* @param maxLength Maximum length of the output buffer.
* @return Number of bytes written to the output buffer.
*/
stock int ImplodeStrings(const char[][] strings, int numStrings, const char[] join, char[] buffer, int maxLength)
{
int total, length, part_length;
int join_length = strlen(join);
for (int i=0; i<numStrings; i++)
{
length = strcopy(buffer[total], maxLength-total, strings[i]);
total += length;
if (length < part_length)
{
break;
}
if (i != numStrings - 1)
{
length = strcopy(buffer[total], maxLength-total, join);
total += length;
if (length < join_length)
{
break;
}
}
}
return total;
}