string.txt

==========================================================
--- String.zh: string-handling constants and functions ---
==========================================================

//Updated 10th January, 2018

===============
-- Constants --
===============

//////////////////////////
/// Message ASCII Code ///
//////////////////////////
const int MSGC_LINEFEED			= 10
 * The ASCII value for '\n'

//////////////////////
/// Message Format ///
//////////////////////
const int MF_NONE				= 0
const int MF_STRING				= 1
const int MF_INT				= 2
const int MF_FLOAT				= 3
const int MF_NUM				= 4
const int MF_PTR				= 5
const int MF_CHAR				= 6
const int MF_HEXLOWER				= 7;	// '%x'
const int MF_HEXUPPER				= 8;	// '%X'
 * Entered directly into 'strcatf' and 'strncatf' as the format type for the
 * argument
 * Converted (respectively) from the '%n', '%s', '%i', '%f', '%d', '%p' and '%c'
 * format arguments in sprintf and printf (via the sprintf_MFCodeToInt function)

//////////////////
/// Characters ///
//////////////////
const int CHAR_*
 * A complete map of all ASCII characters.
 
================================
-- Single Character Functions --
================================

bool isControlCode(int chr)
 * Returns true if 'chr' is in the control code range of ascii characters

bool isNumber(int chr)
 * Returns true if 'chr' is in the range of ascii characters '0' to '9'

bool isAlphabetic(int chr)
 * Returns true if 'chr' is an alphabetic character

bool isAlphaNumeric(int chr)
 * Returns true if 'chr' is an alphanumeric character

bool isHex(int chr)
 * Returns true if 'chr' is in the set { '0'-'9', 'A'-'F' , 'a'-'f' }

bool isUpperCase(int chr)
 * Returns true if 'chr' is an upper-case character

bool isLowerCase(int chr)
 * Returns true if 'chr' is a lower-case character

int UpperToLower(int chr)
 * Converts all upper case characters to lower case, leaving non-alphabetic
 * characters unchanged

int LowerToUpper(int chr)
 * Converts all lower case characters to upper case, leaving non-alphabetic
 * characters unchanged

int ConvertCase(int chr)
 * Converts lower case to upper case and upper case to lower case
 
bool isSpace(int chr)
 * Returns true if 'chr' is a space.
 
bool isVowel(int chr)
 * Returns true if 'chr' is a vowel (a, e, i, o , u, A, E, I, O, U)
 
int IsChar(int chr) 
 * Returns the numeric value of chr.
 
bool IsChar(int chr, int compare){
 * Returns true if character chr is identical to the value specified as 'compare'.
	

=========================
-- Memory Manipulation --
=========================

//////////////////
/// Memory Set ///
//////////////////
void memset(int ptr[], int value, int n)
 * Sets block of memory of size 'n' pointed by 'ptr' to 'value'
 
void memset(int ptr, int pos, int value, int n)
 * As memset(), but with a specified starting position
 
///////////////////
/// Memory Copy ///
///////////////////
int memcpy(int dest[], int src[], int n)
 * Copys block of memory pointed by 'src' of size 'n' to 'dest' and returns
 * 'dest'
 
void memcpy(int dest, int dpos, int src, int spos, int n)
 * As memcpy(), but with a specified starting position

///////////////////
/// Memory Move ///
///////////////////
int memmove(int dest[], int src[], int n)
 * As memcpy, but uses a buffer so memory space can overlap

/////////////////
/// Array Set ///
/////////////////
void arrayset(int a[], int a0, int a1, int a2,...)
 * Assign all elements of array 'a'. Overloaded for up to 16 elements

=========================
-- String Manipulation --
=========================

///////////////////
/// String Copy ///
///////////////////
void strcpy(int dest[], int src[])
 * Copys string 'src' into string 'dest' without checking for overflow in 'dest'
 
void strcpy(int dest, int dpos, int src, int spos) 
 * As strcpy(), but with a specified starting position
 
void strncpy(int dest[], int src[], int n)
 * As strcpy, but only takes the first 'n' characters from src
 
void strncpy(int dest, int dpos, int src, int spos, int n)
 * As strcpy, but only takes the first 'n' characters from src, from a starting position.

/////////////////////////
/// Remove Characters ///
/////////////////////////
void remchr(int string[])
 * Remove all characters starting from pointer 'string'
 
void remnchr(int string[], int n)
 * Remove 'n' characters and shift the rest of the string back to pointer 'string'
 
void remnchr(int string, int pos, int n)
 * As remnchr(), but with a specified starting position

////////////////////
/// String Length///
////////////////////
int strlen(int string[])
 * Returns the length of string 'string'

//////////////////////////
/// String Concatenate ///
//////////////////////////
int strcat(int dest[], int src[])
 * Appends string 'src' onto string 'dest' (assuming dest has enough extra memory
 * allocated to allow the operation)

void strcat(int dest, int src, int spos)
 * As strcat(), but with a specified starting position
 
int strncat(int dest, int src, int n)
 * strcat for the first 'n' characters in src
 
void strncat(int dest, int src, int spos, int n)
 * As strncat(), but with a specified starting position.

======================
-- String Searching --
======================

////////////////////////
/// String Character ///
////////////////////////
int strchr(int string[], int character)
 * Returns the position of the first occurence of 'character' in 'string',
 * or -1 if none are found
 
int strchr(int string, int pos, int chr)
 * As strchr(), but with a specified starting position.
 
bool ContainsChar(int chr, int buffer)
 * Returns true is string 'buffer' contains the character 'chr'. 
 
bool ContainsChar(int chr, int pos, int buffer)
 * As ContainsChar(), but with a specified starting position.
 
int ContainsCharPos(int chr, int buffer)
* Returns the index position of the first occurrence of charcter 'chr' in string 'buffer'.
* Returns -1 if the char was not present. 

int ContainsCharPos(int chr, int pos, int buffer)
 * As ContainsCharPos(), but with a specified starting position.

int NumCharsOf(int str, int chr)
 * Returns the number of chracters of a given type in a specified string.

int NumCharsOf(int str, int pos, int chr)
 * As NumCharsOf(), but with a specified starting position.
 
int ReturnStringCharPos(int str, int chr)
 * Returns the index of the first character matching 'chr', starting at index 0.

int ReturnStringCharPos(int str, int pos, int chr)
 * As ReturnStringCharPos(), but with a specified starting position.
 
////////////////////////////////
/// String Reverse Character ///
////////////////////////////////
int strrchr(int string[], int character)
 * Returns the position of the last occurence of 'character' in 'string'
 * starting from the end, or -1 if none are found
 
int strrchr(int string, int pos, int chr)
 * As strrchr(), but with a specified starting position.
 
bool ContainsCharRev(int chr, int buffer)
 * Returns true is string 'buffer' contains the character 'chr'. 
 * Searching is reversed, starting with the end of the string. 

bool ContainsCharRev(int chr, int pos, int buffer)
 * As ContainsCharRev(), but with a specified starting position.

int ContainsCharPosRev(int chr, int buffer)
* Returns the index position of the first occurrence of charcter 'chr' in string 'buffer'.
* Returns -1 if the char was not present. 
* Searching starts on the last character of the string. 
 
int ContainsCharPosRev(int chr, int pos, int buffer)
 * As ContainsCharPosRev(), but with a specified starting position.
 
int NumCharsOfRev(int str, int chr)
 * Returns the number of chracters of a given type in a specified string.
 * Searching starts at the end of the string. 

int NumCharsOfRev(int str, int pos, int chr)
 * As NumCharsOfRev(), but with a specified starting position.
 
int ReturnStringCharPosRev(int str, int chr)
 * Returns the index of the first character matching 'chr', starting at the end of the string.
 
int ReturnStringCharPosRev(int str, int pos, int chr)
 * As ReturnStringCharPosRev(), but with a specified starting position.
 
/////////////////////////
/// String Sub-String ///
/////////////////////////
int strstr(int string[], int sub[])
 * Returns the position of the first occurence of sub-string 'sub' in 'string,
 * or -1 if sub is not found
 
int strstr(int string, int pos, int sub)
 * As strstr(), but with a specified starting position.

///////////////////
/// String Span ///
///////////////////
int strspn(int str[], int keys[])
 * Returns the length of characters in 'str' before a character not contained in
 * 'keys' is found
 
int strspn(int str, int pos, int keys)
 * As strspn(), but with a specified starting position.
 
 * String Complement Span
int strcspn(int str[], int keys[])
 * Returns the length of characters in 'str' before a character contained in
 * 'keys' is found
 
int strcspn(int str, int pos, int keys)
 * As strcspn(), but with a specified starting position.
 
=======================
-- String Comparison --
=======================

//////////////////////
/// String Compare ///
//////////////////////
int strcmp(int str1[], int str2[])
 * Iterates through str1 and str2 until a character is found which is not the same in
 * both strings, and then returns > 0 if the character is larger in str1, and < 0 if it is
 * larger in str2. Returns 0 if the strings are equal
 
int strcmp(int str1, int pos1, int str2, int pos2)
 * As strcmp(), but with a specified starting position for each string.
 
int strncmp(int str1[], int str2[], int n)
 * strcmp up to 'n' characters
 
int strncmp(int str1, int pos1, int str2, int pos2, int n)
 * As strncmp(), but with a specified starting position for each string.
 
==============================================
-- Converting between variables and strings --
==============================================

////////////////////////
/// ASCII to Integer ///
////////////////////////
int atoi(int string[])
 * Returns the decimal integer pointed by 'string'
 
int atoi(int string, int pos)
 * As atoi(), but with a specified starting position.
 
//////////////////////
/// Integer Length ///
//////////////////////
int ilen(int string[])
 * Returns the length of characters of the decimal integer pointed by 'string'

int ilen(int string, int pos)
 * As ilen(), but with a specified starting position.
 
////////////////////////////////////
/// Hexadecimal ASCII to Integer ///
////////////////////////////////////
int xtoi(int string[])
 * Returns the (positive) hexadecimal integer pointed by 'string'

int xtoi(int string, int pos)
 * As xtoi(), but with a specified starting position.
 
//////////////////////////
/// Hexadecimal Length ///
//////////////////////////
int xlen(int string[])
 * Returns the length of characters of the (positive) hexadecimal integer pointed by 'string'

int xlen(int string, int pos)
 * As xlen(), but with a specified starting position.
 
//////////////////////
/// ASCII to Float ///#
//////////////////////
float atof(int string[])
 * Returns the floating point number pointed by 'string'

float atof(int string, int pos)
 * As atof(), but with a specified starting position.
 
////////////////////
/// Float Length ///
////////////////////
int flen(int string[])
 * Returns the length of characters of the floating point number pointed by 'string'

int flen(int string, int pos)
 * As flen(), but with a specified starting position.
 
///////////////////////
/// ASCII to Number ///
///////////////////////
float aton(int string[])
 * Returns the number pointed by 'string', calling either atoi or atof depending on context

int aton(int string, int pos)
 * As aton(), but with a specified starting position.
 
/////////////////////
/// Number Length ///
/////////////////////
int nlen(int string[])
 * Returns the length of characters of the number pointed by 'string', calling either
 * ilen or flen depending on context
 
int nlen(int string, int pos)
 * As nlen(), but with a specified starting position.

////////////////////////
/// Integer to ASCII ///
////////////////////////
int itoa(int string[], int num)
 * Places integer 'num' into string 'string' without checking for overflow,
 * and returns the number of characters used
 
int itoa(int string, int pos, int num)
 * As itoa(), but with a specified starting position.

//////////////////////
/// Float to ASCII ///
//////////////////////
int ftoa(int string[], float num, bool printall)
 * Places float 'num' into string 'string' without checking for overflow,
 * and returns the number of characters used. If 'printall' is true, it will add 4 decimal places
 * regardless of the most significant digit
 
int ftoa(int string, int pos, float num, bool printall)
 * As ftoa(), but with a specified starting position.
 
int ftoa(int string, float num)
 * As ftoa(), except that 'printall' is false. 
 
int ftoa(int string, int pos, float num)
 * As ftoa(), except that 'printall' is false, with a specified starting position. 

////////////////////////////////////
/// Hexadecimal Integer to ASCII ///
////////////////////////////////////
int xtoa(int string, int num)
 * Places integer 'num' into string 'string' in base 16 without checking for overflow,
 * and returns the number of characters used
 
int xtoa(int string, int num, bool upper)
 * Converts a hexadecimal value to a string. Set bool upper to force uppercase.
 
int xtoa(int string, int pos, int num, bool upper)
 * As xtoa(), but with a specified starting position.

///////////////////////
/// Number to ASCII ///
///////////////////////
int ntoa(int string[], float num)
 * Checks whether 'num' is an integer or not, and calls the appropriate function

int ntoa(int string, int pos, float num)
 * As ntoa(), but with a specified starting position.

=======================
-- String Formatting --
=======================

/////////////////////////////////
/// String Concatenate Format ///
/////////////////////////////////
int strcatf(int dest[], int arg, int format)
 * Appends 'arg' onto 'dest' as the MF_ constant passed into 'format'
 
int strncatf(int dest[], int arg, int format, int n)
 * As strcatf, using only 'n' characters of 'arg'

///////////////////////////
/// String Print Format ///
///////////////////////////
void sprintf(int ret[], int formatstr[], int a0, int a1, int a2,...)
 * Prints string 'formatstr' into 'ret' according to the arguments inputted (see C function for reference),
 * returning the number of characters used. Does not check for overflow in 'ret'
 * Overloaded up to a maximum of 16 arguments. Enter the right number of arguments for your format string;
 * there is (currently) no way to check how many arguments have been entered or of what type they are
 * Currently supported arguments:
 * '%s' - String
 * '%i' - Integer
 * '%f' - Float
 * '%d' - Number (Integer/Float depending on context)
 * '%n' - Nothing
 * '%p' - Pointer Address
 * '%c' - Single character
 * '%x' - Hexadecimal Integer (lower case)
 * '%X' - Hexadecimal Integer (upper case)
 * '\n' places a line feed ASCII character into the string

////////////////////
/// Print Format ///
////////////////////
void printf(int formatstr[], int a0, int a1, int a2,...)
 * Uses a buffer to print the results of sprintf(formatstr,...) straight to allegro.log
 * Overloaded up to a maximum of 16 arguments

bool sprintf_isMFCode(int chr)
 * Used to determine the format from sprintf and printf.