/*
 {"description" : "Inspect and transform strings."}
*/


uses data.String

interface StringUtil{
	
	/* {"@description" : "This is returned by search functions when the search term is not found in the string."} */
	const int NOT_FOUND = INT_MAX
	
	/*
	 {"@description" : "Return a sub-string of the given string."
			"string" : "The string from which to return a sub-string.",
			"start" : "The index into string from which to begin retrieving a sub-string.",
			"length" : "The length of the sub-string to return."}
	*/
	char[] subString(char string[], int start, int length)
	
	/* {"@description" : "Return the given string with all white space removed from the start."} */
	char[] ltrim(char string[])
	
	/* {"@description" : "Return the given string with all white space removed from the end."} */
	char[] rtrim(char string[])
	
	/* {"@description" : "Return the given string with all white space removed from the start and end."} */
	char[] trim(char string[])
	
	/* {"@description" : "Return the given string with all alphabetical characters converted to upper case."} */
	char[] uppercase(char string[])
	
	/* {"@description" : "Return the given string with all alphabetical characters converted to lower case."} */
	char[] lowercase(char string[])
	
	/* {"@description" : "Compare two strings, ignoring their case."} */
	bool iequal(char a[], char b[])
	
	/*
	 {"@description" : "Find searchTerm within the string 'in'."
			"@return" : "The index of the string being searched for, or NOT_FOUND if the string does not exist."}
	*/
	int find(char in[], char searchTerm[], opt int startIndex)
	
	/*
	 {"@description" : "Find searchTerm within the string 'in', ignoring case differences."
			"@return" : "The index of the string being searched for, or NOT_FOUND if the string does not exist."}
	*/
	int ifind(char in[], char searchTerm[], opt int startIndex)
	
	/*
	 {"@description" : "Find searchTerm within the string 'in', starting from the end of the other string."
			"@return" : "The index of the string being searched for, or NOT_FOUND if the string does not exist."}
	*/
	int rfind(char in[], char searchTerm[], opt int startIndex)
	
	/*
	 {"@description" : "Find searchTerm within the string 'in', starting from the end of the other string, ignoring case differences."
			"@return" : "The index of the string being searched for, or NOT_FOUND if the string does not exist."}
	*/
	int irfind(char in[], char searchTerm[], opt int startIndex)
	
	/*
	 {"@description" : "Tokenise a string using the given list of tokens."
			"@return" : "An array of tokens."}
	*/
	String[] explode(char str[], char tokens[])
	
	/*
	 {"@description" : "Glue an array of strings together into a single string, using a glue string between each string in the original array. Null array cells are ignored, such that a single instance of the glue string is added between each non-null pair of cells."
			"@return" : "A string."}
	*/
	char[] implode(String parts[], char glue[])
	
	/*
	 {"@description" : "Check if a string is comprised only of numbers."
			"@return" : "True if the string is comprised only of numerical characters, false otherwise."}
	*/
	bool isNumeric(char str[])
	
	/*
	 {"@description" : "Check if a string starts with another string."
			"@return" : "True if the string starts with the given string of characters, false otherwise."}
	*/
	bool startsWith(char str[], char with[])
	
	/*
	 {"@description" : "Check if a string ends with another string."
			"@return" : "True if the string ends with the given string of characters, false otherwise."}
	*/
	bool endsWith(char str[], char with[])

	/*
	 {"@description" : "Split a string into two halves at the first occurance of a given search string."
			"@return" : "The left and right parts of the string, both of which exclude the search string, or null if the search term wasn't found."}
	*/
	String[] lsplit(char str[], char searchStr[])

	/*
	 {"@description" : "Split a string into two halves at the last occurance of a given search string."
			"@return" : "The left and right parts of the string, both of which exclude the search string, or null if the search term wasn't found."}
	*/
	String[] rsplit(char str[], char searchStr[])
	}