2 * ===============================================================
3 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
4 * ===============================================================
6 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
7 * or modified under the Terms and Conditions of its License Agreement, which is found
8 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
9 * may change at any time. To view the latest information, see:
10 * http://www.sourcemod.net/license.php
15 #if defined _string_included
18 #define _string_included
22 * Unless otherwise noted, all string functions which take in a writable buffer and maximum length
23 * should have the null terminator INCLUDED in the length. This means that this is valid:
24 * 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,
78 * the 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[], {Handle,Float,String,_}:...);
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[], {Handle,Float,String,_}:...);
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 argument
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 str Buffer to store string in.
139 * @param maxlength Maximum length of string buffer.
140 * @param num Integer to convert.
141 * @return Number of cells written to buffer.
143 native IntToString(String:str[], maxlength, num);
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 str Buffer to store string in.
157 * @param maxlength Maximum length of string buffer.
158 * @param num Floating point number to convert.
159 * @return Number of cells written to buffer.
161 native FloatToString(String:str[], maxlength, Float:num);
