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 * Converts a string to an integer.
114 * @param str String to convert.
115 * @param nBase Numerical base to use. 10 is default.
116 * @return Integer conversion of string, or 0 on failure.
118 native StringToInt(const String:str[], nBase=10);
121 * Converts an integer to a string.
123 * @param str Buffer to store string in.
124 * @param maxlength Maximum length of string buffer.
125 * @param num Integer to convert.
126 * @return Number of cells written to buffer.
128 native IntToString(String:str[], maxlength, num);
131 * Converts a string to a floating point number.
133 * @param str String to convert to a foat.
134 * @return Floating point result, or 0.0 on error.
136 native Float:StringToFloat(const String:str[]);
139 * Converts a floating point number to a string.
141 * @param str Buffer to store string in.
142 * @param maxlength Maximum length of string buffer.
143 * @param num Floating point number to convert.
144 * @return Number of cells written to buffer.
146 native FloatToString(String:str[], maxlength, Float:num);
