3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _string_included
19 #define _string_included
22 * @global Unless otherwise noted, all string functions which take in a writable buffer
23 * and maximum length should have the null terminator INCLUDED in the length. This means
24 * that this is valid: StrCopy(string, sizeof(string), ...)
28 * Calculates the length of a string.
30 * @param str String to check.
31 * @return Length of string, in cells (NOT characters).
33 native strlen(const String:str[]);
36 * Tests whether a string is found inside another string.
38 * @param str String to search in.
39 * @param substr Substring to find inside the original string.
40 * @param caseSensitive If true (default), search is case sensitive.
41 * If false, search is case insensitive.
42 * @return -1 on failure (no match found). Any other value
43 * indicates a position in the string where the match starts.
45 native StrContains(const String:str[], const String:substr[], bool:caseSensitive=true);
48 * Compares two strings lexographically.
50 * @param str1 First string (left).
51 * @param str2 Second string (right).
52 * @param caseSensitive If true (default), comparison is case sensitive.
53 * If false, comparison is case insensitive.
54 * @return -1 if str1 < str2
58 native StrCompare(const String:str1[], const String:str2[], bool:caseSensitive=true);
61 * Returns whether two strings are equal.
64 * @param str1 First string (left).
65 * @param str2 Second string (right).
66 * @param caseSensitive If true (default), comparison is case sensitive.
67 * If false, comparison is case insensitive.
68 * @return True if equal, false otherwise.
70 stock bool:StrEqual(const String:str1[], const String:str2[], bool:caseSensitive=true)
72 return (StrCompare(str1, str2, caseSensitive) == 0);
76 * Copies one string to another string.
77 * @note If the destination buffer is too small to hold the source string, the
78 * destination will be truncated.
80 * @param dest Destination string buffer to copy to.
81 * @param destlen Destination buffer length (includes null terminator).
82 * @param source Source string buffer to copy from.
83 * @return Number of cells written.
85 native StrCopy(String:dest[], destLen, const String:source[]);
88 * Formats a string according to the SourceMod format rules (see documentation).
90 * @param buffer Destination string buffer.
91 * @param maxlength Maximum length of output string buffer.
92 * @param format Formatting rules.
93 * @param ... Variable number of format parameters.
94 * @return Number of cells written.
96 native Format(String:buffer[], maxlength, const String:format[], any:...);
99 * Formats a string according to the SourceMod format rules (see documentation).
100 * @note This is the same as Format(), except none of the input buffers can overlap the same
101 * memory as the output buffer. Since this security check is removed, it is slightly faster.
103 * @param buffer Destination string buffer.
104 * @param maxlength Maximum length of output string buffer.
105 * @param format Formatting rules.
106 * @param ... Variable number of format parameters.
107 * @return Number of cells written.
109 native FormatEx(String:buffer[], maxlength, const String:format[], any:...);
112 * Formats a string according to the SourceMod format rules (see documentation).
113 * @note This is the same as Format(), except it grabs parameters from a parent parameter
114 * stack, rather than a local. This is useful for implementing your own variable
115 * argument functions.
117 * @param buffer Destination string buffer.
118 * @param maxlength Maximum length of output string buffer.
119 * @param format Formatting rules.
120 * @param varpos Argument number which contains the '...' symbol.
121 * Note: Arguments start at 1.
122 * @return Number of bytes written.
124 native VFormat(String:buffer[], maxlength, const String:format[], varpos);
127 * Converts a string to an integer.
129 * @param str String to convert.
130 * @param nBase Numerical base to use. 10 is default.
131 * @return Integer conversion of string, or 0 on failure.
133 native StringToInt(const String:str[], nBase=10);
136 * Converts an integer to a string.
138 * @param num Integer to convert.
139 * @param str Buffer to store string in.
140 * @param maxlength Maximum length of string buffer.
141 * @return Number of cells written to buffer.
143 native IntToString(num, String:str[], maxlength);
146 * Converts a string to a floating point number.
148 * @param str String to convert to a foat.
149 * @return Floating point result, or 0.0 on error.
151 native Float:StringToFloat(const String:str[]);
154 * Converts a floating point number to a string.
156 * @param num Floating point number to convert.
157 * @param str Buffer to store string in.
158 * @param maxlength Maximum length of string buffer.
159 * @return Number of cells written to buffer.
161 native FloatToString(Float:num, String:str[], maxlength);
164 * Finds the first "argument" in a string; either a set of space
165 * terminated characters, or a fully quoted string. After the
166 * argument is found, whitespace is read until the next portion
167 * of the string is reached. If nothing remains, -1 is returned.
168 * Otherwise, the index to the first character is returned.
170 * @param source Source input string.
171 * @param arg Stores argument read from string.
172 * @param argLen Maximum length of argument buffer.
173 * @return Index to next piece of string, or -1 if none.
175 native StrBreak(const String:source[], String:arg[], argLen);
