StringPlus
The 20950 module (formerly the StrAdditions module) by monkey_05_06 includes new functions to enhance the way you use Strings in AGS.
Description
The StringPlus module includes over 40 new functions to enhance the way you use Strings in AGS. From new search methods, modifying the text in the String, and even manipulating the existing text, StringPlus really allows you to do it all!
Dependencies
AGS v3.1.2 or higher
Macros (#define-s)
StringPlus_VERSION
Defines the current version of the module. As of v3.2 this is formatted as a float.
StringPlus_VERSION_320
Defines version 3.2 of the module.
Functions
StringFromChar
String StringFromChar(char c, optional int padTo, optional bool zeroPad)
Returns a specially formatted String containing the char C. PADTO allows you to pad the String to a specific length. ZEROPAD controls whether the padding is filled with zeroes (otherwise it is filled with whitespace).
StringFromFloat
String StringFromFloat(float f, optional int precision, optional int padTo, optional bool zeroPad)
Returns a String formatted from float F. PRECISION sets the number of digits after the decimal. PADTO allows you to pad the String to a specific length. ZEROPAD controls whether the padding is zero-filled, otherwise it is space-filled.
StringFromInt
String StringFromInt(int i, optional int padTo, optional bool zeroPad)
Returns a String formatted from int I. PADTO allows you to pad the String to a specific length. ZEROPAD controls whether the padding is zero-filled, otherwise it is space-filled.
StringMergeArray
String StringMergeArray(String array[], String glue)
Returns a String filled with each item from ARRAY in order. GLUE is inserted between each item to make it stick together of course!
String.SplitByWidth
String[] String.SplitByWidth(int width, FontType font, optional String delimiters, optional bool caseSensitive)
Returns a String-array containing elements of the String which when displayed in FONT are no more than WIDTH pixels wide. DELIMITERS allows you to specify a set of characters that each segment should end with. CASESENSITIVE defaults to FALSE. The returned array has the first element formatted to contain the size of the rest of the array. For an array containing 5 elements, the first index (array[0]) would contain the text "5". This means that valid indices for the array are from 0 to (array[0].AsInt + 1).
String.SplitByString
String[] String.SplitByString(String otherString, bool caseSensitive)
Returns a String-array containing elements of the String. The String will be divided by instances of OTHERSTRING. The OTHERSTRING will not be included in any of the array elements. CASESENSITIVE is FALSE by default. For the formatting and size of the array, see String.SplitByWidth.
String.SplitByCharacterSet
String[] String.SplitByCharacterSet(String characterSet, optional bool caseSensitive)
Returns a String-array containing elements of the String. The String will be divided by any instance of the characters in CHARACTERSET, which will not be included in the array elements. CASESENSITIVE is FALSE by default. For the formatting and size of the array, see String.SplitByWidth.
String.ContainsHowManyOf
int String.ContainsHowManyOf(String characterSet, optional bool caseSensitive)
Returns how many characters in the String are within the CHARACTERSET. CASESENSITIVE is FALSE by default.
String.ContainsAllOf
bool String.ContainsAllOf(String characterSet, optional bool caseSensitive)
Returns whether the String contains all of the characters in CHARACTERSET. CASESENSITIVE is FALSE by default.
String.ContainsNOf
bool String.ContainsNOf(String characterSet, int n, optional bool caseSensitive)
Returns whether the String contains at least N instances of characters from the CHARACTERSET. CASESENSITIVE is FALSE by default.
String.ContainsOnly
bool String.ContainsOnly(String characterSet, optional bool caseSensitive)
Returns whether the String contains only the characters defined in CHARACTERSET. CASESENSITIVE is FALSE by default.
String.ContainsNoneOf
bool String.ContainsNoneOf(String characterSet, optional bool caseSensitive)
Returns whether the String contains none of the characters defined in CHARACTERSET. CASESENSITIVE is FALSE by default.
String.IndexOfCase
int String.IndexOfCase(String needle, optional bool caseSensitive)
Works the same as String.IndexOf, but allows case sensitivity. Unlike most functions in this module, CASESENSITIVE is TRUE by default. Returns the index of NEEDLE in the String.
String.IndexOfChar
int String.IndexOfChar(char c, optional bool caseSensitive)
Returns the index of char C in the String. Unlike most functions in the module, CASESENSITIVE is TRUE by default.
String.IndexOfNth
int String.IndexOfNth(String needle, int n, optional bool caseSensitive, optional Direction searchDirection, optional bool returnLast)
Returns the Nth instance of NEEDLE in the String. CASESENSITIVE is FALSE by default. SEARCHDIRECTION is eForwards by default and allows you to search the String from either end. RETURNLAST is TRUE by default and controls whether the last instance of NEEDLE should be used in place of the Nth if the String contains fewer than N instances.
String.FindNthNotOf
int String.FindNthNotOf(String characterSet, int n, optional bool caseSensitive, optional Direction searchDirection, optional bool returnLast)
Returns the index of the Nth character in this String not contained within the specified CHARACTERSET. See IndexOfNth for description of other parameters.
String.FindNthOf
int String.FindNthOf(String characterSet, int n, optional bool caseSensitive, optional Direction searchDirection, optional bool returnLast)
Returns the index of the Nth character in this String contained within the specified CHARACTERSET. See IndexOfNth for description of other parameters.
String.StartsWithAllOf
bool String.StartsWithAllOf(String characterSet, optional bool caseSensitive)
Returns whether the String starts with at least one of each of the characters in CHARACTERSET. CASESENSITIVE is FALSE by default.
String.StartsWithNOf
bool String.StartsWithNOf(String characterSet, int n, optional bool caseSensitive)
Returns whether the String starts with at least N instances of characters from the CHARACTERSET. CASESENSITIVE is FALSE by default.
String.StartsWithNoneOf
bool String.StartsWithNoneOf(String characterSet, optional bool caseSensitive)
Returns whether the String starts with none of the characters in CHARACTERSET. CASESENSITIVE is FALSE by default.
String.EndsWithAllOf
bool String.EndsWithAllOf(String characterSet, optional bool caseSensitive)
Returns whether the String ends with at least one of each of the characters in CHARACTERSET. CASESENSITIVE is FALSE by default.
String.EndsWithNOf
bool String.EndsWithNOf(String characterSet, int n, optional bool caseSensitive)
Returns whether the String ends with N instances of characters from the CHARACTERSET. CASESENSITIVE is FALSE by default.
String.EndsWithNoneOf
bool String.EndsWithNoneOf(String characterSet, optional bool caseSensitive)
Returns whether the String ends with none of the characters in CHARACTERSET. CASESENSITIVE is FALSE by default.
String.ReplaceCount
String String.ReplaceCount(String lookForText, String replaceWithText, optional int count, optional bool caseSensitive)
Replaces COUNT instances of LOOKFORTEXT with REPLACEWITHTEXT in the String and returns the result. The original String is not modified. CASESENSITIVE is FALSE by default.
String.ReplaceNth
String String.ReplaceNth(String lookForText, int n, String replaceWithText, optional bool caseSensitive, optional Direction searchDirection, optional bool useLast)
Returns a copy of the String with the Nth instance of LOOKFORTEXT replaced with REPLACEWITHTEXT. CASESENSITIVE is FALSE by default. SEARCHDIRECTION allows you to search the String from either end and defaults to eForwards. USELAST defaults to TRUE and allows you to replace the last instance of LOOKFORTEXT in the event the String contains less than N instances.
String.ReplaceSubstring
String String.ReplaceSubstring(int index, int length, String replaceWithText)
Returns a copy of the String with a substring of LENGTH characters starting from INDEX replaced by REPLACEWITHTEXT.
String.RemoveSubstring
String String.RemoveSubstring(int index, int length)
Returns a copy of the String with a substring of LENGTH characters starting from INDEX removed.
String.RemoveCharAt
String String.RemoveCharAt(int index)
Returns a copy of the String with the char at INDEX removed.
String.RemoveCharactersInSet
String String.RemoveCharactersInSet(String characterSet, optional bool caseSensitive)
Returns a copy of the String with all characters in CHARACTERSET removed. CASESENSITIVE is FALSE by default.
String.RemoveCharactersNotInSet
String String.RemoveCharactersNotInSet(String characterSet, optional bool caseSensitive)
Returns a copy of the String with all characters not in CHARACTERSET removed. CASESENSITIVE is FALSE by default.
String.StripDuplicatChars
String String.StripDuplicateChars(optional bool caseSensitive)
Returns a copy of the String with all duplicate characters removed. CASESENSITIVE is FALSE by default.
String.InsertStringAt
String String.InsertStringAt(int index, String otherString)
Returns a copy of the String with OTHERSTRING inserted at INDEX.
String.InsertCharAt
String String.InsertCharAt(int index, char newChar)
Returns a copy of the String with NEWCHAR inserted at INDEX.
String.Reverse
String String.Reverse()
Returns a copy of this String in reversed order.
String.IsLowerCase
bool String.IsLowerCase()
Returns whether all the characters in this String are lower case (TRUE if no alpha characters found).
String.IsCharLowerCase
bool String.IsCharLowerCase(int index, optional bool alphaOnly)
Returns whether the char at INDEX is lower case. ALPHAONLY is FALSE by default, but if set to TRUE then if the char is not alphabetic this will return FALSE. Otherwise it returns TRUE for non-alpha characters.
String.SetCharLowerCase
String String.SetCharLowerCase(int index)
Returns a copy of the String with the char at INDEX set to be lower case.
String.IsMixedCase
bool String.IsMixedCase()
Returns whether the String contains both upper and lower case characters.
String.IsUpperCase
bool String.IsUpperCase()
Returns whether the String contains only upper case characters (TRUE if no alpha characters found).
String.IsCharUpperCase
bool String.IsCharUpperCase(int index, optional bool alphaOnly)
Returns whether the char at INDEX is upper case. ALPHAONLY is FALSE by default and sets whether the function should interpret only alpha characters. If set to TRUE this will return FALSE for non-alpha characters, otherwise it returns TRUE.
String.SetCharUpperCase
String String.SetCharUpperCase(int index)
Returns a copy of the String with the char at INDEX set to upper case.
String.InvertCase
String String.InvertCase()
Returns a copy of the String with the case of all the alphabetic characters inverted.
String.InvertCharCase
String String.InvertCharCase(int index)
Returns a copy of the String with the case of the char at INDEX inverted.
String.IsAlphaNumeric
bool String.IsAlphaNumeric()
Returns whether the String contains only alphanumeric characters.
String.IsCharAlpha
bool String.IsCharAlpha(int index)
Returns whether the char at INDEX is alphabetic.
String.IsCharNumeric
bool String.IsCharNumeric(int index)
Returns whether the char at INDEX is numeric.
Changelog
Version 3.2
Version: 3.2
Author: monkey_05_06
Date: 17 March 2009
Description: Removed some of the previous functions. Added some new ones. I actually lost all my copies of previous versions, so I'm not certain what might have been changed. There's now over 40 functions from a previous list of about 8. So most of the functions are new. Yay! Changed the module name from StrAdditions to StringPlus. Added AGS 3.1.2+ dependency. Modified the license to reflect the fact that this is a "script module" and not "software" strictly speaking. Happy St. Patrick's Day.
Licensing
Permission is hereby granted, free of charge, to any person obtaining a copy of this script module and associated documentation files (the "Module"), to deal in the Module without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Module, and to permit persons to whom the Module is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Module.
THE MODULE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MODULE OR THE USE OR OTHER DEALINGS IN THE MODULE.