String

Including Code

include "include/string";

CONST

const CONST_EMPTY := { };
const CONST_NULL := "";

// Constants for the RemoveSpaces() function.
const CLR_LEADING_SPACES 	:= 0x1;
const CLR_TRAILING_SPACES 	:= 0x2;
const CLR_DOUBLE_SPACES		:= 0x4;
const CLR_ALL_SPACES		:= 0x8;

// Constants for the RemoveFromString() function.
CONST STR_DEL_ONCE		:= 0x1;
CONST STR_DEL_ALL		:= 0x2;
CONST STR_DEL_LEADING		:= 0x4;
CONST STR_DEL_TRAILING		:= 0x8;

TruncateArticle()

This function will remove an indefinite article ("a" or "an"). from a string "str", returning the rest of the string. If there is no article, it returns the original string "str".

TruncateArticle(str);

AddArticle()

This function will prefix an indefinite article ("a" or "an") in front of a string. If the string begins with a consonant, it uses "a", and if the string begins with a vowel it will use "an".

AddArticle(str);

Note, this will occasionally produce grammatically incorrect phrases involving strings beginning with "h" or glided "u" sounds, such as "a hour", "an unit", or "a eunuch". For the curious, the "a" is used before consonants, including the "y" sound in some phoenemes of "u". The "an" article is used before a vowel sound, or before an "h" in words where the accent falls on any syllable other than the first (like "historic").

CreateArrayIndex()

This function will sort an array, and create an index of the original positions for each element. This index can then be used to sort other arrays in the same order as the first one.

Function

CreateArrayIndex( MainArray );

Example

// For example, if you have the array:
var myarray := { 4, 5, 9, 0, 100, 22, 7 };

// the function will return the following:
result := CreateArrayIndex(myarray);
SortedArray := result[1];  // { 0, 4, 5, 7, 9, 22, 100 }
IndexArray := result[2];   // { 4, 1, 2, 7, 3, 6, 5}

This function is useful for preserving information across multiple arrays when you need to sort one of them.

SortArrayByIndex()

This function will sort "OldArray" by the order outlined in "IndexArray", where "IndexArray" is an array of sequential numbers equal to { 1, 2, 3, ... , len(OldArray) }. If the IndexArray is a different size than OldArray, or if the sequence is broken, then the function will return 0.

SortArrayByIndex( OldArray, IndexArray );

SortMultiArrayByIndex()

This function will sort an array of arrays (or structures) by the contents of the sub-index provided. So, if you have an array (zCoords) of [x,y,z] structures, calling the function with 'fn(zCoords,2)' will sort by the second sub-index... that is, the 'y' member. Returns '0' if the SubIndex is invalid (only checks against the first index).

SortMultiArrayByIndex( MultiArray, SubIndex );

PadString()

This function will pad a string "str" with enough spaces to reach a length indicated by "stringlength". If the string is already longer than stringlength, the function will return 0.

PadString( str, stringlength );

PadArray()

This function will pad an array "arry" with enough 0s to reach length specified in "arraylength". If the length of the array is already greater than arraylength, the function will return 0.

PadArray(arry, arraylength);

ReturnIndex()

This function will return the index (location within an array) of an element. If the element is not found, then the function will return 0.

ReturnIndex( myarray, elementvalue );

UCFirst()

Makes the string lowercase, then capitalizes the first letter.

UCFirst( text );

LCFirst()

Makes the first letter of the string lowercase.

LCFirst( text );

RemoveSpaces()

Removes spaces from a string based on the flags passed.

RemoveSpaces( text, flags:=CLR_LEADING_SPACES );

RemoveFromString()

Removes the value passed in "remove" from a string passed // in "text" based on flags passed.

RemoveFromString( text, remove, flags:=STR_DEL_ALL );

Flags	Description
STR_DEL_ONCE
STR_DEL_ALL
STR_DEL_LEADING
STR_DEL_TRAILING

Return value: modified string.

AppendArray()

Append Arry2 to the end of Arry1.

AppendArray( arry1, arry2 );

Return value: Arry1 with Array2 appended.

Check_ValidChar()

Check_ValidChar( text, allow_space:=0 );

AddCommas()

To return a string representation of an integer formatted with commas at three digit intervals.

Function

AddCommas( number );

Example

// Input:
An integer in the range 0 to 2147483647 decimal or 0x0 to 0x7FFFFFFF hex.

// Returns:
A string representaton of a decimal integer with commas inserted appropriately.

// Example: 
"2,147,483,647" or -1 if the integer exceeds 2147483647 decimal.

SortArrayABC()

Sorted as array alphabetically.

SortArrayABC( arr, dir := 1, subindex := 0 );

Parameters	Description
arr	array()
dir	1 = ascending, 0 = descending
subindex	Which Subarray/substructing element to sort by

ValidateStringInteger()

Strips leading zeros from a string except for "0x". This is needed because POL assumes a leading zero on a string representation of an integer is octal notation. If you send such a string to the CInt() function, you will get back an integer but it will be the base 10 conversion of an octal value.

ValidateStringInteger( str );

Returns: A string representation of a hexadecimal integer if the first 2 characters were "0x" or a string representation of a decimal number with leading zeros, if any, removed or an error if the string contains any characters that are not valid integer digits.

Note: Validation is performed for valid hexadecimal and decimal string representations of integers.