ds@1952: /**
ds@1952:  * vim: set ts=4 :
ds@1952:  * =============================================================================
ds@1952:  * SourceMod (C)2004-2008 AlliedModders LLC.  All rights reserved.
ds@1952:  * =============================================================================
ds@1952:  *
ds@1952:  * This file is part of the SourceMod/SourcePawn SDK.
ds@1952:  *
ds@1952:  * This program is free software; you can redistribute it and/or modify it under
ds@1952:  * the terms of the GNU General Public License, version 3.0, as published by the
ds@1952:  * Free Software Foundation.
ds@1952:  * 
ds@1952:  * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1952:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1952:  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
ds@1952:  * details.
ds@1952:  *
ds@1952:  * You should have received a copy of the GNU General Public License along with
ds@1952:  * this program.  If not, see <http://www.gnu.org/licenses/>.
ds@1952:  *
ds@1952:  * As a special exception, AlliedModders LLC gives you permission to link the
ds@1952:  * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1952:  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1952:  * by the Valve Corporation.  You must obey the GNU General Public License in
ds@1952:  * all respects for all other code used.  Additionally, AlliedModders LLC grants
ds@1952:  * this exception to all derivative works.  AlliedModders LLC defines further
ds@1952:  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1952:  * or <http://www.sourcemod.net/license.php>.
ds@1952:  *
ds@1952:  * Version: $Id$
ds@1952:  */
ds@1952:  
ds@1952: #if defined _string_included
ds@1952:  #endinput
ds@1952: #endif
ds@1952: #define _string_included
ds@1952: 
ds@1952: /**
ds@1952:  * @global Unless otherwise noted, all string functions which take in a 
ds@1952:  * writable buffer and maximum length should have the null terminator INCLUDED
ds@1952:  * in the length.  This means that this is valid: 
ds@1952:  * strcopy(string, sizeof(string), ...)
ds@1952:  */
ds@1952:  
ds@1952: /**
ds@1952:  * Calculates the length of a string.
ds@1952:  *
ds@1952:  * @param str			String to check.
ds@1952:  * @return				Number of valid character bytes in the string.
ds@1952:  */
ds@1952: native strlen(const String:str[]);
ds@1952: 
ds@1952: /**
ds@1952:  * Tests whether a string is found inside another string.
ds@1952:  *
ds@1952:  * @param str			String to search in.
ds@1952:  * @param substr		Substring to find inside the original string.
ds@1952:  * @param caseSensitive	If true (default), search is case sensitive.
ds@1952:  *						If false, search is case insensitive.
ds@1952:  * @return				-1 on failure (no match found). Any other value
ds@1952:  *						indicates a position in the string where the match starts.
ds@1952:  */
ds@1952: native StrContains(const String:str[], const String:substr[], bool:caseSensitive=true);
ds@1952: 
ds@1952: /**
ds@1952:  * Compares two strings lexographically.
ds@1952:  *
ds@1952:  * @param str1			First string (left).
ds@1952:  * @param str2			Second string (right).
ds@1952:  * @param caseSensitive	If true (default), comparison is case sensitive.
ds@1952:  *						If false, comparison is case insensitive.
ds@1952:  * @return				-1 if str1 < str2
ds@1952:  *						0 if str1 == str2
ds@1952:  *						1 if str1 > str2
ds@1952:  */
ds@1952: native strcmp(const String:str1[], const String:str2[], bool:caseSensitive=true);
ds@1952: 
ds@1952: /**
ds@1952:  * Compares two strings parts lexographically.
ds@1952:  *
ds@1952:  * @param str1			First string (left).
ds@1952:  * @param str2			Second string (right).
ds@1952:  * @param num			Number of characters to compare.
ds@1952:  * @param caseSensitive	If true (default), comparison is case sensitive.
ds@1952:  *						If false, comparison is case insensitive.
ds@1952:  * @return				-1 if str1 < str2
ds@1952:  *						0 if str1 == str2
ds@1952:  *						1 if str1 > str2
ds@1952:  */
ds@1952: native strncmp(const String:str1[], const String:str2[], num, bool:caseSensitive=true);
ds@1952: 
ds@1952: /**
ds@1952:  * Backwards compatible stock - StrCompare is now strcmp
ds@1952:  * @deprecated		Renamed to strcmp
ds@1952:  */
ds@1952: #pragma deprecated Use strcmp() instead
ds@1952: stock StrCompare(const String:str1[], const String:str2[], bool:caseSensitive=true)
ds@1952: {
ds@1952: 	return strcmp(str1, str2, caseSensitive);
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Returns whether two strings are equal.
ds@1952:  *
ds@1952:  * @param str1			First string (left).
ds@1952:  * @param str2			Second string (right).
ds@1952:  * @param caseSensitive	If true (default), comparison is case sensitive.
ds@1952:  * 						If false, comparison is case insensitive.
ds@1952:  * @return				True if equal, false otherwise.
ds@1952:  */
ds@1952: stock bool:StrEqual(const String:str1[], const String:str2[], bool:caseSensitive=true)
ds@1952: {
ds@1952: 	return (strcmp(str1, str2, caseSensitive) == 0);
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Copies one string to another string.
ds@1952:  * @note If the destination buffer is too small to hold the source string, the 
ds@1952:  *       destination will be truncated.
ds@1952:  *
ds@1952:  * @param dest			Destination string buffer to copy to.
ds@1952:  * @param destlen		Destination buffer length (includes null terminator).
ds@1952:  * @param source		Source string buffer to copy from.
ds@1952:  * @return				Number of cells written.
ds@1952:  */
ds@1952: native strcopy(String:dest[], destLen, const String:source[]);
ds@1952: 
ds@1952: /**
ds@1952:  * Backwards compatibility stock - use strcopy
ds@1952:  * @deprecated			Renamed to strcopy
ds@1952:  */
ds@1952: #pragma deprecated Use strcopy() instead
ds@1952: stock StrCopy(String:dest[], destLen, const String:source[])
ds@1952: {
ds@1952: 	return strcopy(dest, destLen, source);
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Formats a string according to the SourceMod format rules (see documentation).
ds@1952:  *
ds@1952:  * @param buffer		Destination string buffer.
ds@1952:  * @param maxlength		Maximum length of output string buffer.
ds@1952:  * @param format		Formatting rules.
ds@1952:  * @param ...			Variable number of format parameters.
ds@1952:  * @return				Number of cells written.
ds@1952:  */
ds@1952: native Format(String:buffer[], maxlength, const String:format[], any:...);
ds@1952: 
ds@1952: /**
ds@1952:  * Formats a string according to the SourceMod format rules (see documentation).
ds@1952:  * @note This is the same as Format(), except none of the input buffers can 
ds@1952:  *       overlap the same memory as the output buffer.  Since this security 
ds@1952:  *       check is removed, it is slightly faster.
ds@1952:  *
ds@1952:  * @param buffer		Destination string buffer.
ds@1952:  * @param maxlength		Maximum length of output string buffer.
ds@1952:  * @param format		Formatting rules.
ds@1952:  * @param ...			Variable number of format parameters.
ds@1952:  * @return				Number of cells written.
ds@1952:  */
ds@1952: native FormatEx(String:buffer[], maxlength, const String:format[], any:...);
ds@1952: 
ds@1952: /**
ds@1952:  * Formats a string according to the SourceMod format rules (see documentation).
ds@1952:  * @note This is the same as Format(), except it grabs parameters from a 
ds@1952:  *       parent parameter stack, rather than a local.  This is useful for 
ds@1952:  *       implementing your own variable argument functions.
ds@1952:  *
ds@1952:  * @param buffer		Destination string buffer.
ds@1952:  * @param maxlength		Maximum length of output string buffer.
ds@1952:  * @param format		Formatting rules.
ds@1952:  * @param varpos		Argument number which contains the '...' symbol.
ds@1952:  *						Note: Arguments start at 1.
ds@1952:  * @return 				Number of bytes written.
ds@1952:  */
ds@1952: native VFormat(String:buffer[], maxlength, const String:format[], varpos);
ds@1952: 
ds@1952: /**
ds@1952:  * Converts a string to an integer.
ds@1952:  *
ds@1952:  * @param str			String to convert.
ds@1952:  * @param nBase			Numerical base to use.  10 is default.
ds@1952:  * @return				Integer conversion of string, or 0 on failure.
ds@1952:  */
ds@1952: native StringToInt(const String:str[], nBase=10);
ds@1952: 
ds@1952: /**
ds@1952:  * Converts a string to an integer with some more options.
ds@1952:  *
ds@1952:  * @param str			String to convert.
ds@1952:  * @param result		Variable to store the result in.
ds@1952:  * @param nBase			Numerical base to use.  10 is default.
ds@1952:  * @return				Number of characters consumed.
ds@1952:  */
ds@1952: native StringToIntEx(const String:str[], &result, nBase=10);
ds@1952: 
ds@1952: /**
ds@1952:  * Converts an integer to a string.
ds@1952:  *
ds@1952:  * @param num			Integer to convert.
ds@1952:  * @param str			Buffer to store string in.
ds@1952:  * @param maxlength		Maximum length of string buffer.
ds@1952:  * @return				Number of cells written to buffer.
ds@1952:  */
ds@1952: native IntToString(num, String:str[], maxlength);
ds@1952: 
ds@1952: /** 
ds@1952:  * Converts a string to a floating point number.
ds@1952:  *
ds@1952:  * @param str			String to convert to a foat.
ds@1952:  * @return				Floating point result, or 0.0 on error.
ds@1952:  */
ds@1952: native Float:StringToFloat(const String:str[]);
ds@1952: 
ds@1952: /** 
ds@1952:  * Converts a string to a floating point number with some more options.
ds@1952:  *
ds@1952:  * @param str			String to convert to a foat.
ds@1952:  * @param result		Variable to store result in.
ds@1952:  * @return				Number of characters consumed.
ds@1952:  */
ds@1952: native StringToFloatEx(const String:str[], &Float:result);
ds@1952: 
ds@1952: /**
ds@1952:  * Converts a floating point number to a string.
ds@1952:  *
ds@1952:  * @param num			Floating point number to convert.
ds@1952:  * @param str			Buffer to store string in.
ds@1952:  * @param maxlength		Maximum length of string buffer.
ds@1952:  * @return				Number of cells written to buffer.
ds@1952:  */
ds@1952: native FloatToString(Float:num, String:str[], maxlength);
ds@1952: 
ds@1952: /**
ds@1952:  * Finds the first "argument" in a string; either a set of space
ds@1952:  * terminated characters, or a fully quoted string.  After the 
ds@1952:  * argument is found, whitespace is read until the next portion
ds@1952:  * of the string is reached.  If nothing remains, -1 is returned.
ds@1952:  * Otherwise, the index to the first character is returned.
ds@1952:  *
ds@1952:  * @param source		Source input string.
ds@1952:  * @param arg			Stores argument read from string.
ds@1952:  * @param argLen		Maximum length of argument buffer.
ds@1952:  * @return				Index to next piece of string, or -1 if none.
ds@1952:  */
ds@1952: native BreakString(const String:source[], String:arg[], argLen);
ds@1952: 
ds@1952: /**
ds@1952:  * Backwards compatibility stock - use BreakString
ds@1952:  * @deprecated			Renamed to BreakString.
ds@1952:  */
ds@1952: #pragma deprecated Use BreakString() instead
ds@1952: stock StrBreak(const String:source[], String:arg[], argLen)
ds@1952: {
ds@1952: 	return BreakString(source, arg, argLen);
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Removes whitespace characters from the beginning and end of a string.
ds@1952:  *
ds@1952:  * @param str			The string to trim.
ds@1952:  * @return				Number of bytes written (UTF-8 safe).
ds@1952:  */
ds@1952: native TrimString(String:str[]);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns text in a string up until a certain character sequence is reached.
ds@1952:  *
ds@1952:  * @param source		Source input string.
ds@1952:  * @param split			A string which specifies a search point to break at.
ds@1952:  * @param part			Buffer to store string part.
ds@1952:  * @param partLen		Maximum length of the string part buffer.
ds@1952:  * @return				-1 if no match was found; otherwise, an index into source
ds@1952:  *						marking the first index after the searched text.  The
ds@1952:  *						index is always relative to the start of the input string.
ds@1952:  */
ds@1952: native SplitString(const String:source[], const String:split[], String:part[], partLen);
ds@1952: 
ds@1952: /**
ds@1952:  * Given a string, replaces all occurrences of a search string with a 
ds@1952:  * replacement string.
ds@1952:  *
ds@1952:  * @param text			String to perform search and replacements on.
ds@1952:  * @param maxlength		Maximum length of the string buffer.
ds@1952:  * @param search		String to search for.
ds@1952:  * @param replace		String to replace the search string with.
ds@1952:  * @return				Number of replacements that were performed.
ds@1952:  */
ds@1952: native ReplaceString(String:text[], maxlength, const String:search[], const String:replace[]);
ds@1952: 
ds@1952: /**
ds@1952:  * Given a string, replaces the first occurrence of a search string with a 
ds@1952:  * replacement string.
ds@1952:  *
ds@1952:  * @param text			String to perform search and replacements on.
ds@1952:  * @param maxlength		Maximum length of the string buffer.
ds@1952:  * @param search		String to search for.
ds@1952:  * @param replace		String to replace the search string with.
ds@1952:  * @param searchLen		If higher than -1, its value will be used instead of
ds@1952:  *						a strlen() call on the search parameter.
ds@1952:  * @param replaceLen	If higher than -1, its value will be used instead of
ds@1952:  *						a strlen() call on the replace parameter.
ds@1952:  * @return				Index into the buffer (relative to the start) from where
ds@1952:  *						the last replacement ended, or -1 if no replacements were
ds@1952:  *						made.
ds@1952:  */
ds@1952: native ReplaceStringEx(String:text[], maxlength, const String:search[], const String:replace[], searchLen=-1, replaceLen=-1);
ds@1952: 
ds@1952: /** 
ds@1952:  * Returns the number of bytes a character is using.  This is
ds@1952:  * for multi-byte characters (UTF-8).  For normal ASCII characters,
ds@1952:  * this will return 1.
ds@1952:  *
ds@1952:  * @param source		Source input string.
ds@1952:  * @return				Number of bytes the current character uses.
ds@1952:  */
ds@1952: native GetCharBytes(const String:source[]);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns whether a character is an ASCII alphabet character.
ds@1952:  *
ds@1952:  * @note Multi-byte characters will always return false.
ds@1952:  *
ds@1952:  * @param char			Character to test.
ds@1952:  * @return				True if character is alphabetical, otherwise false.
ds@1952:  */
ds@1952: native bool:IsCharAlpha(chr);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns whether a character is numeric.
ds@1952:  *
ds@1952:  * @note Multi-byte characters will always return false.
ds@1952:  *
ds@1952:  * @param char			Character to test.
ds@1952:  * @return				True if character is numeric, otherwise false.
ds@1952:  */
ds@1952: native bool:IsCharNumeric(chr);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns whether a character is whitespace.
ds@1952:  *
ds@1952:  * @note Multi-byte characters will always return false.
ds@1952:  *
ds@1952:  * @param char			Character to test.
ds@1952:  * @return				True if character is whitespace, otherwise false.
ds@1952:  */
ds@1952: native bool:IsCharSpace(chr);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns if a character is multi-byte or not.
ds@1952:  *
ds@1952:  * @param char			Character to test.
ds@1952:  * @return				0 for a normal 7-bit ASCII character,
ds@1952:  *						otherwise number of bytes in multi-byte character.
ds@1952:  */
ds@1952: native IsCharMB(chr);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns whether an alphabetic character is uppercase.
ds@1952:  *
ds@1952:  * @note Multi-byte characters will always return false.
ds@1952:  *
ds@1952:  * @param char			Character to test.
ds@1952:  * @return				True if character is uppercase, otherwise false.
ds@1952:  */
ds@1952: native bool:IsCharUpper(chr);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns whether an alphabetic character is lowercase.
ds@1952:  *
ds@1952:  * @note Multi-byte characters will always return false.
ds@1952:  *
ds@1952:  * @param char			Character to test.
ds@1952:  * @return				True if character is lowercase, otherwise false.
ds@1952:  */
ds@1952: native bool:IsCharLower(chr);
ds@1952: 
ds@1952: /**
ds@1952:  * Returns an uppercase character to a lowercase character.
ds@1952:  *
ds@1952:  * @param chr			Characer to convert.
ds@1952:  * @return				Lowercase character on success, 
ds@1952:  *						no change on failure.
ds@1952:  */
ds@1952: stock CharToUpper(chr)
ds@1952: {
ds@1952: 	if (IsCharLower(chr))
ds@1952: 	{
ds@1952: 		return (chr & ~(1<<5));
ds@1952: 	}
ds@1952: 	return chr;
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Returns a lowercase character to an uppercase character.
ds@1952:  *
ds@1952:  * @param chr			Characer to convert.
ds@1952:  * @return				Uppercase character on success, 
ds@1952:  *						no change on failure.
ds@1952:  */
ds@1952: stock CharToLower(chr)
ds@1952: {
ds@1952: 	if (IsCharUpper(chr))
ds@1952: 	{
ds@1952: 		return (chr | (1<<5));
ds@1952: 	}
ds@1952: 	return chr;
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Concatenates one string onto another.
ds@1952:  *
ds@1952:  * @param buffer		String to append to.
ds@1952:  * @param maxlength		Maximum length of entire buffer.
ds@1952:  * @param source		Source string to concatenate.
ds@1952:  * @return				Number of bytes written.
ds@1952:  */
ds@1952: stock StrCat(String:buffer[], maxlength, const String:source[])
ds@1952: {
ds@1952: 	new len = strlen(buffer);
ds@1952: 	if (len >= maxlength)
ds@1952: 	{
ds@1952: 		return 0;
ds@1952: 	}
ds@1952: 	
ds@1952: 	return Format(buffer[len], maxlength-len, "%s", source);
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Breaks a string into pieces and stores each piece into an array of buffers.
ds@1952:  *
ds@1952:  * @param text				The string to split.
ds@1952:  * @param split				The string to use as a split delimiter.
ds@1952:  * @param buffers			An array of string buffers (2D array).
ds@1952:  * @param maxStrings		Number of string buffers (first dimension size).
ds@1952:  * @param maxStringLength	Maximum length of each string buffer.
ds@1952:  * @return					Number of strings retrieved.
ds@1952:  */
ds@1952: stock ExplodeString(const String:text[], const String:split[], String:buffers[][], maxStrings, maxStringLength)
ds@1952: {
ds@1952: 	new reloc_idx, idx, total;
ds@1952: 	
ds@1952: 	if (maxStrings < 1 || split[0] == '\0')
ds@1952: 	{
ds@1952: 		return 0;
ds@1952: 	}
ds@1952: 	
ds@1952: 	while ((idx = SplitString(text[reloc_idx], split, buffers[total], maxStringLength)) != -1)
ds@1952: 	{
ds@1952: 		reloc_idx += idx;
ds@1952: 		if (text[reloc_idx] == '\0')
ds@1952: 		{
ds@1952: 			break;
ds@1952: 		}
ds@1952: 		if (++total >= maxStrings)
ds@1952: 		{
ds@1952: 			return total;
ds@1952: 		}
ds@1952: 	}
ds@1952: 	
ds@1952: 	if (text[reloc_idx] != '\0' && total <= maxStrings - 1)
ds@1952: 	{
ds@1952: 		strcopy(buffers[total++], maxStringLength, text[reloc_idx]);
ds@1952: 	}
ds@1952: 	
ds@1952: 	return total;
ds@1952: }
ds@1952: 
ds@1952: /**
ds@1952:  * Joins an array of strings into one string, with a "join" string inserted in
ds@1952:  * between each given string.  This function complements ExplodeString.
ds@1952:  *
ds@1952:  * @param strings		An array of strings.
ds@1952:  * @param numStrings	Number of strings in the array.
ds@1952:  * @param join			The join string to insert between each string.
ds@1952:  * @param buffer		Output buffer to write the joined string to.
ds@1952:  * @param maxLength		Maximum length of the output buffer.
ds@1952:  * @return				Number of bytes written to the output buffer.
ds@1952:  */
ds@1952: stock ImplodeStrings(const String:strings[][], numStrings, const String:join[], String:buffer[], maxLength)
ds@1952: {
ds@1952: 	new total, length, part_length;
ds@1952: 	new join_length = strlen(join);
ds@1952: 	for (new i=0; i<numStrings; i++)
ds@1952: 	{
ds@1952: 		length = strcopy(buffer[total], maxLength-total, strings[i]);
ds@1952: 		total += length;
ds@1952: 		if (length < part_length)
ds@1952: 		{
ds@1952: 			break;
ds@1952: 		}
ds@1952: 		if (i != numStrings - 1)
ds@1952: 		{
ds@1952: 			length = strcopy(buffer[total], maxLength-total, join);
ds@1952: 			total += length;
ds@1952: 			if (length < join_length)
ds@1952: 			{
ds@1952: 				break;
ds@1952: 			}
ds@1952: 		}
ds@1952: 	}
ds@1952: 	return total;
ds@1952: }