dvander@233: /**
ds@475:  * vim: set ts=4 :
dvander@374:  * ===============================================================
dvander@374:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
dvander@374:  * ===============================================================
dvander@374:  *
dvander@374:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
dvander@374:  * or modified under the Terms and Conditions of its License Agreement, which is found 
dvander@374:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
dvander@374:  * may change at any time.  To view the latest information, see:
dvander@374:  *   http://www.sourcemod.net/license.php
dvander@374:  *
dvander@374:  * Version: $Id$
dvander@233:  */
dvander@374:  
dvander@233: #if defined _string_included
dvander@233:  #endinput
dvander@233: #endif
dvander@233: #define _string_included
dvander@233: 
dvander@233: /**
dvander@748:  * @global Unless otherwise noted, all string functions which take in a 
dvander@748:  * writable buffer and maximum length should have the null terminator INCLUDED
dvander@748:  * in the length.  This means that this is valid: 
dvander@748:  * StrCopy(string, sizeof(string), ...)
dvander@233:  */
dvander@631:  
dvander@233: /**
dvander@233:  * Calculates the length of a string.
dvander@233:  *
ds@475:  * @param str			String to check.
ds@475:  * @return				Length of string, in cells (NOT characters).
dvander@233:  */
dvander@233: native strlen(const String:str[]);
dvander@233: 
dvander@233: /**
dvander@233:  * Tests whether a string is found inside another string.
dvander@233:  *
dvander@233:  * @param str			String to search in.
dvander@233:  * @param substr		Substring to find inside the original string.
dvander@233:  * @param caseSensitive	If true (default), search is case sensitive.
ds@475:  *						If false, search is case insensitive.
ds@475:  * @return				-1 on failure (no match found). Any other value
ds@475:  *						indicates a position in the string where the match starts.
dvander@233:  */
dvander@233: native StrContains(const String:str[], const String:substr[], bool:caseSensitive=true);
dvander@233: 
dvander@233: /**
dvander@233:  * Compares two strings lexographically.
dvander@233:  *
dvander@233:  * @param str1			First string (left).
dvander@233:  * @param str2			Second string (right).
dvander@233:  * @param caseSensitive	If true (default), comparison is case sensitive.
ds@475:  *						If false, comparison is case insensitive.
ds@475:  * @return				-1 if str1 < str2
ds@475:  *						0 if str1 == str2
ds@475:  *						1 if str1 > str2
dvander@233:  */
dvander@680: native strcmp(const String:str1[], const String:str2[], bool:caseSensitive=true);
dvander@680: 
dvander@680: /**
dvander@680:  * Compares two strings parts lexographically.
dvander@680:  *
dvander@680:  * @param str1			First string (left).
dvander@680:  * @param str2			Second string (right).
dvander@680:  * @param num			Number of characters to compare.
dvander@680:  * @param caseSensitive	If true (default), comparison is case sensitive.
dvander@680:  *						If false, comparison is case insensitive.
dvander@680:  * @return				-1 if str1 < str2
dvander@680:  *						0 if str1 == str2
dvander@680:  *						1 if str1 > str2
dvander@680:  */
dvander@680: native strncmp(const String:str1[], const String:str2[], num, bool:caseSensitive=true);
dvander@680: 
dvander@680: /**
dvander@680:  * Backwards compatible stock - StrCompare is now strcmp
dvander@681:  * @deprecated		Renamed to strcmp
dvander@680:  */
dvander@680: stock StrCompare(const String:str1[], const String:str2[], bool:caseSensitive=true)
dvander@680: {
dvander@680: 	return strcmp(str1, str2, caseSensitive);
dvander@680: }
dvander@233: 
dvander@233: /**
dvander@233:  * Returns whether two strings are equal.
dvander@233:  *
dvander@233:  *
dvander@233:  * @param str1			First string (left).
dvander@233:  * @param str2			Second string (right).
dvander@233:  * @param caseSensitive	If true (default), comparison is case sensitive.
dvander@412:  * 						If false, comparison is case insensitive.
dvander@412:  * @return				True if equal, false otherwise.
dvander@233:  */
faluco@234: stock bool:StrEqual(const String:str1[], const String:str2[], bool:caseSensitive=true)
dvander@233: {
faluco@234: 	return (StrCompare(str1, str2, caseSensitive) == 0);
dvander@233: }
dvander@233: 
dvander@233: /**
dvander@233:  * Copies one string to another string.
dvander@619:  * @note If the destination buffer is too small to hold the source string, the 
dvander@619:  *       destination will be truncated.
dvander@233:  *
dvander@233:  * @param dest			Destination string buffer to copy to.
dvander@233:  * @param destlen		Destination buffer length (includes null terminator).
dvander@233:  * @param source		Source string buffer to copy from.
dvander@412:  * @return				Number of cells written.
dvander@233:  */
dvander@681: native strcopy(String:dest[], destLen, const String:source[]);
dvander@681: 
dvander@681: /**
dvander@681:  * Backwards compatibility stock - use strcopy
dvander@681:  * @deprecated			Renamed to strcopy
dvander@681:  */
dvander@681: stock StrCopy(String:dest[], destLen, const String:source[])
dvander@681: {
dvander@681: 	return strcopy(dest, destLen, source);
dvander@681: }
dvander@233: 
dvander@233: /**
dvander@257:  * Formats a string according to the SourceMod format rules (see documentation).
dvander@257:  *
dvander@257:  * @param buffer		Destination string buffer.
dvander@257:  * @param maxlength		Maximum length of output string buffer.
dvander@257:  * @param format		Formatting rules.
dvander@257:  * @param ...			Variable number of format parameters.
dvander@412:  * @return				Number of cells written.
dvander@257:  */
ds@634: native Format(String:buffer[], maxlength, const String:format[], any:...);
dvander@257: 
dvander@257: /**
dvander@257:  * Formats a string according to the SourceMod format rules (see documentation).
dvander@748:  * @note This is the same as Format(), except none of the input buffers can 
dvander@748:  *       overlap the same memory as the output buffer.  Since this security 
dvander@748:  *       check is removed, it is slightly faster.
dvander@257:  *
dvander@257:  * @param buffer		Destination string buffer.
dvander@257:  * @param maxlength		Maximum length of output string buffer.
dvander@257:  * @param format		Formatting rules.
dvander@257:  * @param ...			Variable number of format parameters.
dvander@412:  * @return				Number of cells written.
dvander@257:  */
ds@634: native FormatEx(String:buffer[], maxlength, const String:format[], any:...);
dvander@257: 
dvander@257: /**
dvander@412:  * Formats a string according to the SourceMod format rules (see documentation).
dvander@748:  * @note This is the same as Format(), except it grabs parameters from a 
dvander@748:  *       parent parameter stack, rather than a local.  This is useful for 
dvander@748:  *       implementing your own variable argument functions.
dvander@412:  *
dvander@412:  * @param buffer		Destination string buffer.
dvander@412:  * @param maxlength		Maximum length of output string buffer.
dvander@412:  * @param format		Formatting rules.
dvander@412:  * @param varpos		Argument number which contains the '...' symbol.
dvander@412:  *						Note: Arguments start at 1.
dvander@412:  * @return 				Number of bytes written.
dvander@412:  */
dvander@412: native VFormat(String:buffer[], maxlength, const String:format[], varpos);
dvander@412: 
dvander@412: /**
dvander@233:  * Converts a string to an integer.
dvander@233:  *
dvander@233:  * @param str			String to convert.
dvander@412:  * @param nBase			Numerical base to use.  10 is default.
dvander@412:  * @return				Integer conversion of string, or 0 on failure.
dvander@233:  */
dvander@233: native StringToInt(const String:str[], nBase=10);
dvander@233: 
dvander@233: /**
dvander@233:  * Converts an integer to a string.
dvander@233:  *
dvander@451:  * @param num			Integer to convert.
dvander@233:  * @param str			Buffer to store string in.
dvander@233:  * @param maxlength		Maximum length of string buffer.
dvander@412:  * @return				Number of cells written to buffer.
dvander@233:  */
dvander@451: native IntToString(num, String:str[], maxlength);
dvander@233: 
dvander@233: /** 
dvander@233:  * Converts a string to a floating point number.
dvander@233:  *
dvander@233:  * @param str			String to convert to a foat.
dvander@412:  * @return				Floating point result, or 0.0 on error.
dvander@233:  */
dvander@233: native Float:StringToFloat(const String:str[]);
dvander@233: 
dvander@233: /**
dvander@233:  * Converts a floating point number to a string.
dvander@233:  *
ds@454:  * @param num			Floating point number to convert.
dvander@233:  * @param str			Buffer to store string in.
dvander@233:  * @param maxlength		Maximum length of string buffer.
dvander@412:  * @return				Number of cells written to buffer.
dvander@233:  */
ds@454: native FloatToString(Float:num, String:str[], maxlength);
dvander@631: 
dvander@631: /**
dvander@631:  * Finds the first "argument" in a string; either a set of space
dvander@631:  * terminated characters, or a fully quoted string.  After the 
dvander@631:  * argument is found, whitespace is read until the next portion
dvander@631:  * of the string is reached.  If nothing remains, -1 is returned.
dvander@631:  * Otherwise, the index to the first character is returned.
dvander@631:  *
dvander@631:  * @param source		Source input string.
dvander@631:  * @param arg			Stores argument read from string.
dvander@631:  * @param argLen		Maximum length of argument buffer.
dvander@631:  * @return				Index to next piece of string, or -1 if none.
dvander@631:  */
ds@634: native StrBreak(const String:source[], String:arg[], argLen);
dvander@748: 
dvander@748: /** 
dvander@748:  * Returns the number of bytes a character is using.  This is
dvander@748:  * for multi-byte characters (UTF-8).  For normal ASCII characters,
dvander@748:  * this will return 1.
dvander@748:  *
dvander@748:  * @param source		Source input string.
dvander@748:  * @return				Number of bytes the current character uses.
dvander@748:  */
dvander@748: native GetCharBytes(const String:source[]);
dvander@748: 
dvander@748: /**
dvander@748:  * Returns whether a character is an ASCII alphabet character.
dvander@748:  *
dvander@748:  * @note Multi-byte characters will always return false.
dvander@748:  *
dvander@748:  * @param char			Character to test.
dvander@748:  * @return				True if character is alphabetical, otherwise false.
dvander@748:  */
dvander@748: native bool:IsCharAlpha(chr);
dvander@748: 
dvander@748: /**
dvander@748:  * Returns whether a character is numeric.
dvander@748:  *
dvander@748:  * @note Multi-byte characters will always return false.
dvander@748:  *
dvander@748:  * @param char			Character to test.
dvander@748:  * @return				True if character is numeric, otherwise false.
dvander@748:  */
dvander@748: native bool:IsCharNumeric(chr);
dvander@748: 
dvander@748: /**
dvander@748:  * Returns whether a character is whitespace.
dvander@748:  *
dvander@748:  * @note Multi-byte characters will always return false.
dvander@748:  *
dvander@748:  * @param char			Character to test.
dvander@748:  * @return				True if character is whitespace, otherwise false.
dvander@748:  */
dvander@748: native bool:IsCharSpace(chr);
dvander@748: 
dvander@748: /**
dvander@748:  * Returns if a character is multi-byte or not.
dvander@748:  *
dvander@748:  * @param char			Character to test.
dvander@748:  * @return				0 for a normal 7-bit ASCII character,
dvander@748:  *						otherwise number of bytes in multi-byte character.
dvander@748:  */
dvander@748: native IsCharMB(chr);
dvander@748: 
dvander@748: /**
dvander@748:  * Returns whether an alphabetic character is uppercase.
dvander@748:  *
dvander@748:  * @note Multi-byte characters will always return false.
dvander@748:  *
dvander@748:  * @param char			Character to test.
dvander@748:  * @return				True if character is uppercase, otherwise false.
dvander@748:  */
dvander@748: native bool:IsCharUpper(chr);
dvander@748: 
dvander@748: /**
dvander@748:  * Returns whether an alphabetic character is lowercase.
dvander@748:  *
dvander@748:  * @note Multi-byte characters will always return false.
dvander@748:  *
dvander@748:  * @param char			Character to test.
dvander@748:  * @return				True if character is lowercase, otherwise false.
dvander@748:  */
dvander@748: native bool:IsCharLower(chr);
dvander@748: 
dvander@748: /**
dvander@748:  * Returns an uppercase character to a lowercase character.
dvander@748:  *
dvander@748:  * @param chr			Characer to convert.
dvander@748:  * @return				Lowercase character on success, 
dvander@748:  *						no change on failure.
dvander@748:  */
dvander@748: stock CharToUpper(chr)
dvander@748: {
dvander@748: 	if (IsCharLower(chr))
dvander@748: 	{
dvander@748: 		return (chr & ~(1<<5));
dvander@748: 	}
dvander@748: 	return chr;
dvander@748: }
dvander@748: 
dvander@748: /**
dvander@748:  * Returns a lowercase character to an uppercase character.
dvander@748:  *
dvander@748:  * @param chr			Characer to convert.
dvander@748:  * @return				Uppercase character on success, 
dvander@748:  *						no change on failure.
dvander@748:  */
dvander@748: stock CharToLower(chr)
dvander@748: {
dvander@748: 	if (IsCharUpper(chr))
dvander@748: 	{
dvander@748: 		return (chr | (1<<5));
dvander@748: 	}
dvander@748: 	return chr;
dvander@748: }
dvander@748: 
dvander@748: