StringPlus

The StringPlus module (formerly the StrAdditions module) by monkey_05_06 includes new functions to enhance the way you use Strings in AGS.

Download
Mirror

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).

Example:

 String cstr = StringFromChar('A');

cstr now holds the text "A".

 cstr = StringFromChar('A', 5);

cstr now holds the text " A".

 cstr = StringFromChar('A', 5, true);

cstr now holds the text "0000A".

See Also: StringFromFloat, StringFromInt

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.

Example:

 String fstr = StringFromFloat(3.14);

fstr now holds the text "3.14".

 fstr = StringFromFloat(3.14, 3);

fstr now holds the text "3.140".

 fstr = StringFromFloat(3.14, 3, 6);

fstr now holds the text " 3.140". NOTE: The decimal point is included in calculating the length for padding.

 fst = StringFromFloat(3.14, 3, 6, true);

fstr now holds the text "03.140".

See Also: StringFromChar, StringFromInt

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.

Example:

 String istr = StringFromInt(27);

istr now holds the text "27".

 istr = StringFromInt(27, 5);

istr now holds the text " 27".

 istr = StringFromInt(27, 5, true);

istr now holds the text "00027".

See Also: StringFromChar, StringFromFloat

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!

Example:

 String sarr[] = new String[4];
 sarr[0] = "This";
 sarr[1] = "is";
 sarr[2] = "some";
 sarr[3] = "text.";
 String str = StringMergeArray(sarr, " ");

str now holds the text "This is some text.".

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).

Example:

 String str = "This is a long string we're going to split into other segments.";
 String sarr[] = str.SplitByWidth(150, Game.NormalFont);
 int i = 1;
 while (i <= sarr[0].AsInt) {
   Display(sarr[i]);
   i++;
 }

Displays "This is a long string we're", " going to split into other ", and then "segments." using the default built-in fonts.

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.

Example:

 String str = "This is some text.";
 String sarr[] = str.SplitByString(" ");
 int i = 1;
 while (i <= sarr[0].AsInt) {
   Display(sarr[i]);
   i++;
 }

Displays the following, "This", "is", "some", and then "text.".

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.

Example:

 String str = "Hello, my name is Ego. What is your name?";
 String sarr[] = str.SplitByCharacterSet(".,;:!?");
 int i = 1;
 while (i <= sarr[0].AsInt) {
   Display(sarr[i]);
   i++;
 }

Displays "Hello", " my name is Ego", and then " What is your name".

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.

Example:

 String haystack = "This is some text.";
 Display("contains %d spaces and punctuation.", haystack.ContainsHowManyOf(" .,;:!?"));

Displays "contains 4 spaces and punctuation.".

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.

Example:

 String haystack = "Hello, my name is Ego. What is your name?";
 bool result = haystack.ContainsAllOf(" .,;:!?");
 if (result) {
   Display("The haystack has all of the punctuation characters in it.");
 }
 else {
   Display("The haystack did not have all the punctuation characters in it.");
 }

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.

Example:

 String haystack = "This is some text.";
 if (haystack.ContainsNOf(" .,;:!?", 4)) {
   Display("the haystack contains at least 4 spaces and punctuation.");
 }
 else {
   Display("the haystack only contains %d spaces and punctuation.", haystack.ContainsHowManyOf(" .,;:!?"));
 }

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.

Example:

 String haystack = "This is some text.";
 if (haystack.ContainsNoneOf(" .,;:!?")) {
   Display("the haystack contains no spaces or punctuation.");
 }
 else {
   Display("the haystack contains %d spaces and punctuation.", haystack.ContainsHowManyOf(" .,;:!?"));
 }

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.

Example:

 String haystack = "This is some text.";
 if (haystack.ContainsOnly("abcdefghijklmnopqrstuvwxyz0123456789")) {
   Display("the haystack contains only alphanumeric characters.");
 }
 else {
   Display("the haystack contains non-alphanumeric characters.");
 }

Displays that the haystack string is not alphanumeric. The String.IsAlphaNumeric function is an easier way to perform this same test.

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.

Example:

 String haystack = "String haystack = "The haystack had a needle in it somewhere.";
 int noCase = haystack.IndexOf("A NEEDLE");
 int case = haystack.IndexOfCase("A NEEDLE");
 if (noCase == -1) {
   Display("The string didn't contain the needle (without case sensitivity).");
 }
 else {
   Display("a needle was found (without case sensitivity) starting at character %d in the string.", noCase);
 }
 if (case == -1) {
   Display("The string didn't contain the needle (with case sensitivity).");
 }
 else {
   Display("a needle was found (with case sensitivity) starting at character %d in the string.", noCase);
 }

Displays "a needle was found (without case sensitivity) starting at character 17 in the string." and then "The string didn't contain the needle (with case sensitivity).".

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.

Example:

 String haystack = "This is some text.";
 int result = haystack.IndexOfChar('x');
 if (result == -1) {
   Display("the haystack did not contain the character 'x'.");
 }
 else {
   Display("the character 'x' was found at index %d.", result);
 }

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.

Example:

 String haystack = "Needles? We don't need no stinkin' needles!";
 int result = haystack.IndexOfNth("needle", 2, false, eForwards, false); // let's make sure we really have 2 instances
 if (result == -1) {
   Display("There were fewer than 2 instances of needle in the haystack.");
 }
 else {
   Display("The second needle appears at index %d.", result);
 }

Displays "The second needle appears at index 35.". By passing FALSE for returnLast we can ensure that there are at least 2 instances of "needle" in the haystack string; otherwise if it contained any instances it would return the last instance.

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.

Example:

 String haystack = "This is some text.";
 int result = haystack.FindNthNotOf(" .,;:!?", 8);
 if (result != -1) {
   Display("the 8th non-space, non-punctuation character is at index %d", result);
 }

Will display "the 8th non-space, non-punctuation character is at index 9".

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.

Example:

 String haystack = "This is some text.";
 int result = haystack.FindNthOf(" .,;:!?", 8);
 if (result != -1) {
   Display("the 8th space or punctuation character is at index %d", result);
 }

Will display "the 8th space or punctuation character is at index 17". Since returnLast defaults to true we here see the last character from the characterSet which is actually the 4th instance, not the 8th. If we had specified returnLast as false then this function would have returned -1.

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.

StringPlus

Description

Dependencies

Macros (#define-s)

StringPlus_VERSION

StringPlus_VERSION_320

Functions

StringFromChar

StringFromFloat

StringFromInt

StringMergeArray

String.SplitByWidth

String.SplitByString

String.SplitByCharacterSet

String.ContainsHowManyOf

String.ContainsAllOf

String.ContainsNOf

String.ContainsNoneOf

String.ContainsOnly

String.IndexOfCase

String.IndexOfChar

String.IndexOfNth

String.FindNthNotOf

String.FindNthOf

String.StartsWithAllOf

String.StartsWithNOf

String.StartsWithNoneOf

String.EndsWithAllOf

String.EndsWithNOf

String.EndsWithNoneOf

String.ReplaceCount

String.ReplaceNth

String.ReplaceSubstring

String.RemoveSubstring

String.RemoveCharAt

String.RemoveCharactersInSet

String.RemoveCharactersNotInSet

String.StripDuplicatChars

String.InsertStringAt

String.InsertCharAt

String.Reverse

String.IsLowerCase

String.IsCharLowerCase

String.SetCharLowerCase

String.IsMixedCase

String.IsUpperCase

String.IsCharUpperCase

String.SetCharUpperCase

String.InvertCase

String.InvertCharCase

String.IsAlphaNumeric

String.IsCharAlpha

String.IsCharNumeric

Changelog

Version 3.2

Licensing

Navigation menu

Search