The Main Module Documentation⚓︎

Overview⚓︎

The Main Module, also referred to as the Root Module, contains most of the functions in the library.

Configurable Variables⚓︎

MockupStandardLibrary boolean⚓︎

Default: false

The MockupStandardLibrary boolean determines whether or not to include the standard string library functions in the StringPlus library. This can be useful if you want to use the StringPlus library as your main string manipulation library, but still want access to the functions provided by the standard string library.

By default, this boolean is set to false, meaning that the standard string library functions are not included as mockups in the StringPlus library. If you set the boolean to true, the standard string library functions will be included in the library and will behave similarly to their counterparts in the standard string library.

FunctionNamesCase string⚓︎

Default: "PascalCase"

Possible Values: "PascalCase", "LowerCase", "CamelCase", "SnakeCase"

The FunctionNamesCase variable allows you to change the naming style of the functions in the StringPlus library. By default, the functions are named in PascalCase style (e.g. "TransformString"), but this variable does allow to change the naming style to camelCase (e.g. "transformString"), snake_case (e.g. "transform_string"), or lower (e.g. "transformstring").

To change the naming style of the functions, simply set the variable to one of the possible values listed above. The new naming style will be applied to all functions in the StringPlus library, including both the main functions and the mockup functions (if enabled).

IncludeSubLibrariesFunctions boolean⚓︎

Default: true

This boolean variable determines whether to include the functions from the sub-modules of the StringPlus library directly in the main module. When set to true, the functions from the sub-modules will be included in the main module and can be called directly, just like any other function in the module.

By default, this variable is set to true, meaning that the functions from the sub-modules are included directly in the main module. If you set the variable to false, the functions from the sub-modules will still be available in the main module, but they will be accessed as tables rather than functions.

SolveIndexing boolean⚓︎

Default: false

The SolveIndexing variable determines whether the StringPlus library should attempt to solve incorrect indexing when accessing functions in the library. This can be useful if the developer has changed the naming style of the functions using the FunctionNamesCase variable (e.g. from PascalCase to CamelCase) and wants to ensure that the functions can still be accessed without any issues.

By default, this variable is set to false, meaning that the library will not attempt to solve incorrect indexing when accessing functions. If you set the variable to true, the library will attempt to solve incorrect indexing and will return functions that match the specified name if they exist, regardless of the naming style set by the FunctionNamesCase variable.

Functions⚓︎

Escape⚓︎

Purpose⚓︎

Escapes any character in the given string that is considered a magic character by adding an additional percent sign "%" before them.

Syntax⚓︎

Escape(Str: string): string

Parameters⚓︎

• Str: string
  The string to be escaped.

Returns⚓︎

• string
  The escaped version of the given string.

Examples⚓︎

1
2
3
4
5

local Escaped = StringPlus.Escape("Hello + World")
print(Escaped)

local Escaped = StringPlus.Escape("Those are escaped brackets: ()")
print(Escaped)

1
2

Hello %+ World
Those are escaped brackets: %(%)

EqualsIgnoreCase⚓︎

Purpose⚓︎

Compares two strings and returns true if they are equal, ignoring the case of the characters in the strings.

Syntax⚓︎

EqualsIgnoreCase(Str_1: string, Str_2: string): boolean

Parameters⚓︎

• Str_1: string
  The first string to be compared.
• Str_1: string
  The second string to be compared.

Returns⚓︎

• boolean
  true if the given strings are equal, ignoring the case of the characters; false otherwise.

Examples⚓︎

1
2
3
4
5

local Equal = StringPlus.EqualsIgnoreCase("Hello", "hello")
print(Equal)

local Equal = StringPlus.EqualsIgnoreCase("Hello", "hellooo")
print(Equal)

1
2

true
false

RemoveVowels⚓︎

Purpose⚓︎

Removes all vowels from a string and replaces them with a specified replacement string if it was provided.

Syntax⚓︎

RemoveVowels(Str: string, Replacement: string?): string

Parameters⚓︎

• Str: string
  The input string from which to remove the vowels.
• Replacement: string Optional
  The replacement string to use in place of the removed vowels. If not provided, the vowels are simply removed without being replaced.

Returns⚓︎

• string: The input string with all vowels removed and replaced, if specified.

Examples⚓︎

1
2
3
4
5

local NoVowels = StringPlus.RemoveVowels("Hello, World!")
print(NoVowels)

local NoVowels = StringPlus.RemoveVowels("Hello, World!", "-")
print(NoVowels)

1
2

Hll, Wrld!
H-ll-, W-rld!

RemoveConsonants⚓︎

Purpose⚓︎

Removes all consonants from a string and replaces them with a specified replacement string if provided.

Syntax⚓︎

RemoveConsonants(Str: string, Replacement: string?): string

Parameters⚓︎

• Str: string
  The input string from which to remove the consonants.
• Replacement: string Optional
  The replacement string to use in place of the removed consonants.
  If not provided, the consonants are simply removed without being replaced.

Returns⚓︎

• string
  The input string with all consonants removed and replaced, if specified.

Examples⚓︎

1
2
3
4
5

local NoConsonants = StringPlus.RemoveConsonants("Hello, World!")
print(NoConsonants)

local NoConsonants = StringPlus.RemoveConsonants("Hello, World!", "-")
print(NoConsonants)

1
2

eo, o!
-e--o, -o---!

RemovePunctuation⚓︎

Purpose⚓︎

Removes all punctuation from a string and replaces them with a specified replacement string, if provided.

Syntax⚓︎

RemovePunctuation(Str: string, Replacement: string?): string

Parameters⚓︎

• Str: string
  The input string from which to remove the punctuation.
• Replacement: string Optional
  The replacement string to use in place of the removed punctuation.
  If not provided, the punctuation is simply removed without being replaced.

Returns⚓︎

• string
  The input string with all punctuation removed and replaced, if specified..

Examples⚓︎

1
2
3
4
5

local NoPunctuation = StringPlus.RemovePunctuation("Hello, World!")
print(NoPunctuation)

local NoPunctuation = StringPlus.RemovePunctuation("Hello, World!", "-")
print(NoPunctuation)

1
2

Hello World
Hello- World-

RemoveExtraSpaces⚓︎

Purpose⚓︎

Removes all leading, trailing, and extra spaces from a given string.

Syntax⚓︎

RemoveExtraSpaces(Str: string): string

Parameters⚓︎

• Str: string
  The string from which to remove extra spaces.

Returns⚓︎

• string
  A string with all leading, trailing, and extra spaces removed.

Examples⚓︎

1
2
3

local Str = "   This string   has extra   spaces   "
local NewStr = StringPlus.RemoveExtraSpaces(Str)
print(NewStr)

1

This string has extra spaces

MatchIgnoreCase⚓︎

Purpose⚓︎

Searches for a pattern within a string and returns the first occurrence of the pattern, ignoring the case of the characters in the string and pattern.

Syntax⚓︎

MatchIgnoreCase(Str: string, Pattern: string, Init: number?): string?

Parameters⚓︎

• Str: string
  The string to be searched.
• Pattern: string
  The pattern to be searched for.
• Init: number Optional
  The starting index for the search.

Returns⚓︎

• string
  A string containing the first occurrence of the pattern within the string, or nil if the pattern is not found.

Examples⚓︎

1
2

local Match = StringPlus.MatchIgnoreCase("Hello, World!", "WORLD")
print(Match)

1

World

Truncate⚓︎

Purpose⚓︎

Truncates the given string to the specified length and adds an optional omission suffix if specified. If the string is already shorter than the Length, the original Str is returned.

Syntax⚓︎

Truncate(Str: string, Length: number, OmissionSuffix: string?): string?

Parameters⚓︎

• Str: string
  The string to be truncated.
• Length: number
  The maximum length of the string or the minimum length to truncate it.
• OmissionSuffix: string Optional
  The string to be added to the end of the truncated string. Default is "…​".

Returns⚓︎

• string
  The truncated string.

Examples⚓︎

1
2
3
4
5
6
7
8

local Truncated = StringPlus.Truncate("Hello World", 5)
print(Truncated)

local Truncated = StringPlus.Truncate("Hello World", 5, "!!!")
print(Truncated)

local Truncated = StringPlus.Truncate("Hello", 5)
print(Truncated)

1
2
3

Hello...
Hello!!!
Hello

SwapCase⚓︎

Purpose⚓︎

Swaps the case of all the letters in the given string.

Syntax⚓︎

SwapCase(Str: string): string

Parameters⚓︎

• Str: string
  The string to be modified.

Returns⚓︎

• string
  A new string with the case of all the letters swapped.

Examples⚓︎

1
2
3
4
5

local Swapped = StringPlus.SwapCase("Hello World")
print(Swapped)

local Swapped = StringPlus.SwapCase("tHis Is A TeSt")
print(Swapped)

1
2

hELLO wORLD
ThIs iS a tEsT

Strip⚓︎

Purpose⚓︎

Removes leading and trailing characters from a string.

Syntax⚓︎

Strip(Str: string, Characters: string?): string

Parameters⚓︎

• Str: string
  The string to be stripped.
• Characters : string Optional
  A string of characters to be stripped from the start and end of the string.
  If not provided, default is to strip white-space characters².

Returns⚓︎

• string
  A new string with leading and trailing characters removed.

Examples⚓︎

1
2
3
4
5

local StrippedString = StringPlus.Strip("  hello  ", " ")
print(StrippedString)

local StrippedString = StringPlus.Strip("!+!+!he!llo!!", "!+-")
print(StrippedString)

1
2

hello
he!llo

RStrip⚓︎

Purpose⚓︎

Removes the specified characters from the end of the string or in other words, the right side of it.

Syntax⚓︎

RStrip(Str: string, Characters: string?): string

Parameters⚓︎

• Str: string
  The string to be stripped.
• Characters : string Optional
  A string containing the characters to be removed.
  If not specified, the function will remove white-space characters².

Returns⚓︎

• string
  A new string with trailing characters removed.

Examples⚓︎

1
2
3
4
5
6
7

local Str = "Hello World \n"
local StrippedStr = StringPlus.RStrip(Str, "\n")
print(StrippedStr)

local Str = "Hello World!!!"
local StrippedStr = StringPlus.RStrip(Str, "!")
print(StrippedStr)

1
2

Hello World
Hello World

LStrip⚓︎

Purpose⚓︎

Removes leading characters from a given string i.e. left side characters.

Syntax⚓︎

LStrip(Str: string, Characters: string?): string

Parameters⚓︎

• Str: string
  The input string to be modified.
• Characters : string Optional
  The characters to be removed from the beginning of the string. If no characters are specified, the function will remove leading white-space characters² by default.

Returns⚓︎

• string
  A new string with leading characters removed.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local Str = "   Hello World"
local StrippedStr = StringPlus.LStrip(Str)
print(StrippedStr)

local Str = "123456Hello World"
local StrippedStr = StringPlus.LStrip(Str, "%d")
print(StrippedStr)

local Str = "\t  Hello World"
local StrippedStr = StringPlus.LStrip(Str, " ")
print(StrippedStr)

1
2
3

Hello World
Hello World
\t  Hello World

Center⚓︎

Purpose⚓︎

Takes a string as input and centers it within a specified length, using a fill character to fill in the remaining spaces.
The fill character is optional and defaults to a space if not provided.

Syntax⚓︎

Center(Str: string, Length: number, FillChar: string?): string

Parameters⚓︎

• Str: string
  The string to be centered.
• Length: number
  The desired length of the resulting string.
• FillChar: string Optional
  The character to use to fill in the remaining spaces.
  Defaults to a space if not provided.

Returns⚓︎

• string
  The input string centered within the specified length, using the fill character to fill in the remaining spaces.

Examples⚓︎

1
2
3
4
5

local Centered = StringPlus.Center("Hello", 10)
print(Centered)

local Centered = StringPlus.Center("Hello", 9, "+")
print(Centered)

1
2

  Hello   
++Hello++

RJust⚓︎

Purpose⚓︎

Tight-justifies the given string by padding it with the specified filling character up to the given length.
If the length of the given string is already equal to or greater than the given length, the original string is returned without any performed padding.

Syntax⚓︎

RJust(Str: string, Length: number, FillChar: string?): string

Parameters⚓︎

• Str: string
  The string to be right-justified.
• Length: number
  The desired length of the returned string.
• FillChar: string Optional
  The character to be used for padding. Defaults to a space character.

Returns⚓︎

• string
  The modified string of the original one aligned to the right, padded with the specified fill character if specified or a space character by default.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local Str = "Hello"
local JustifiedString = StringPlus.RJust(Str, 10)
print(JustifiedString)

local Str = "Hello"
local JustifiedString = StringPlus.RJust(Str, 10, "*")
print(JustifiedString)

local Str = "Hello"
local JustifiedString = StringPlus.RJust(Str, 4)
print(JustifiedString)

1
2
3

Hello     
Hello*****
Hello

LJust⚓︎

Purpose⚓︎

Aligns the given string to the left by padding it with the given fill character until it reaches the desired length.
If the length of the string is already equal to or greater than the provided length, the original string is returned as is.

Syntax⚓︎

LJust(Str: string, Length: number, FillChar: string?): string

Parameters⚓︎

• Str: string
  The string to be left-aligned.
• Length: number
  The desired length of the left-aligned string.
• FillChar: string Optional
  The character to use for padding. Defaults to a space character.

Returns⚓︎

• string
  The left-aligned string with the desired length.

Examples⚓︎

1
2
3
4
5

local JustifiedString = StringPlus.LJust("Hello", 10)
print(JustifiedString)

local JustifiedString = StringPlus.LJust("Hello", 10, "*")
print(JustifiedString)

1
2

     Hello
*****Hello

ExpandTabs⚓︎

Purpose⚓︎

Expands all tab characters in the given string to the specified number of spaces, as defined by the optional TabSize parameter.
If TabSize is not provided, it defaults to 4 space characters.

Syntax⚓︎

ExpandTabs(Str: string, TabSize: number?): string

Parameters⚓︎

• Str: string
  The string in which to expand all tab characters.
• TabSize: number Optional
  The number of spaces to use to replace each tab character. If not provided, defaults to 4 spaces.

Returns⚓︎

• string
  A string with all tab characters expanded to the specified number of spaces.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local Str = "Hello\tWorld"
local Expanded = StringPlus.ExpandTabs(Str)
print(Expanded)

local Str = "Hello\t\tWorld"
local Expanded = StringPlus.ExpandTabs(Str)
warn(Expanded)

local Str = "Hello\t\tWorld"
local Expanded = StringPlus.ExpandTabs(Str, 0)
print(Expanded)

1
2
3

Hello   World
Hello       World
HelloWorld

Translate⚓︎

Purpose⚓︎

Replaces all occurrences of specified characters in the given string with new characters as defined in the mapping table.
The mapping table should contain a mapping of old characters (numbers representing the ASCII codes of the characters) to new characters which are also represented as numbers.

Syntax⚓︎

Translate(Str: string, MappingTable: {[number]: number}): string

Parameters⚓︎

• Str: string
  The string to perform the translation on.
• MappingTable: table
  A table that specifies the mapping of characters to be replaced.
  The keys of the table should be the characters to be replaced, and the values should be the characters that the keys should be replaced with.

Returns⚓︎

• string
  The modified string with all specified characters replaced with their corresponding values in the MappingTable.

Examples⚓︎

1
2
3
4
5
6
7
8
9

local MappingTable = {[65] = 97, [66] = 98} -- This table maps capital A (ASCII code 65) to lowercase a (ASCII code 97), and capital B (ASCII code 66) to lowercase b (ASCII code 98).
local OriginalStr = "AB"
local TranslatedStr = StringPlus.Translate(OriginalStr, MappingTable)
print(TranslatedStr)

local MappingTable = {[72] = 104, [87] = 119}
local OriginalStr = "Hello World!"
local TranslatedStr = StringPlus.Translate(OriginalStr, MappingTable)
print(TranslatedStr)

1
2

ab
hello world!

Count⚓︎

Purpose⚓︎

Counts the number of occurrences of the given pattern/substring in the given string.
The Start and End parameters can be used to specify a range within the Str string to search for the pattern.

Syntax⚓︎

Count(Str: string, Pattern: string, Start: number?, End: number?): number

Parameters⚓︎

• Str: string
  The input string to search for the Pattern.
• Pattern: string
  The pattern to search for within the string.
  This can be a lua pattern, word, or character.
• Start: number Optional
  The index within the string to start the search.
  Defaults to 1.
• End: number Optional
  The index within the string to end the search.
  Defaults to the length of the Str string.

Returns⚓︎

• number
  The number of occurrences of the Pattern in the Str string within the specified range.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local Count = StringPlus.Count("Hello, World!", "l")
print(Count)

local Count = StringPlus.Count("Hello, World!", "l", 6)
print(Count)

local Count = StringPlus.Count("Hello, World!", "l", 6, 8)
print(Count)

local Count = StringPlus.Count("the quick brown fox jumps over the lazy dog", "the")
print(Count)

1
2
3
4

3
1
0
2

SortWords⚓︎

Purpose⚓︎

Sorts the words in a string alphabetically in ascending or descending order.

Syntax⚓︎

SortWords(Str: string, Order: Enum.SortDirection?, ReturnArray: boolean?): (string | {string})

Parameters⚓︎

• Str: string
  The string to be sorted.
• Order: string Optional
  The sort direction, either ascending or descending. Default is ascending (Enum.SortDirection.Ascending).
• ReturnArray: boolean Optional
  If true, returns the sorted words as an array of strings.
  If false, returns a string with the sorted words separated by a space. Default is false.

Returns⚓︎

• string | table
  If ReturnArray is true, the function will return an array of the sorted words; Otherwise, the function would return a string with the sorted words separated by spaces.

Examples⚓︎

1
2
3
4
5
6
7
8

local SortedWords = StringPlus.SortWords("apple banana cherry", Enum.SortDirection.Descending, true)
print(SortedWords)

local SortedString = StringPlus.SortWords("apple banana cherry", Enum.SortDirection.Ascending)
print(SortedString)

local SortedString = StringPlus.SortWords("apple banana cherry")
print(SortedString)

1
2
3

{"cherry", "banana", "apple"}
apple banana cherry
apple banana cherry

SortByLength⚓︎

Purpose⚓︎

Sorts an array of strings by their length, in ascending or descending order.

Syntax⚓︎

SortByLength(StringArray: {string}, Order: Enum.SortDirection?): {string}

Parameters⚓︎

• StringArray: table
  The array of strings to be sorted.
• Order: string Optional
  The sort direction. Acceptable values are Enum.SortDirection.Ascending and Enum.SortDirection.Descending.
  Default is the ascending order.

Returns⚓︎

• table
  The sorted array of strings.

Examples⚓︎

1
2
3
4

local Array = {"apple", "banana", "cherry", "date", "elderberry", "fig"}

print(StringPlus.SortByLength(Array))
print(StringPlus.SortByLength(Array, Enum.SortDirection.Descending))

1
2

{"fig", "date", "apple", "cherry", "banana", "elderberry"}
{"elderberry", "banana", "cherry", "apple", "date", "fig"}

FilterByLength⚓︎

Purpose⚓︎

Filters a given array of strings, removing all strings that do not have a specified length.

Syntax⚓︎

FilterByLength(StringArray: {string}, Length: number): {string}

Parameters⚓︎

• StringArray: table
  The array of strings to be filtered.
• Length: number
  The desired length of the strings to be kept in the array.

Returns⚓︎

• table
  An array containing only the strings from the input array that have the specified length.

Examples⚓︎

1
2
3
4
5

local FilteredArray = StringPlus.FilterByLength({"Hello", "Hi", "Goodbye"}, 5)
print(FilteredArray)

local FilteredArray = StringPlus.FilterByLength({"Hello", "Goodbye", "Hi!", "Bye"}, 3)
print(FilteredArray)

1
2

{"Hello"}
{"Hi!", "Bye"}

Segments⚓︎

Purpose⚓︎

Returns an array of strings containing the segments of the input string each one with the specified length except for the last segment that could be less than the specified length number.

Syntax⚓︎

Segments(Str: string, Length: number): {string}

Parameters⚓︎

• Str: string
  The input string to split it into chunks.
• Length: number
  The desired length for each segment of the input string in the returned array.

Returns⚓︎

• table
  An array containing the segments of the given string.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

-- In the next prints the input string "Hello World!" is divided into segments of length 3 and 5
local Str = "Hello World!"
print(StringPlus.Segments(Str, 3))
print(StringPlus.Segments(Str, 5))

-- In the next few lines, we are dividing the Str variable into segements of length 4 and iterating over the returned array to print it's indexes and values using string interpolation
local Str = "This is a test string"
local StrSegments = StringPlus.Segments(Str, 4)
for Index, Segment in ipairs(StrSegments) do
    print(`{Index}: "{Segment}"`)
end

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
   [1] = "Hel",
   [2] = "lo ",
   [3] = "Wor",
   [4] = "ld!"
}
{
   [1] = "Hello",
   [2] = " Worl",
   [3] = "d!"
}
1: "This"
2: " is "
3: "a te"
4: "st s"
5: "trin"
6: "g"

LongestWord⚓︎

Purpose⚓︎

Returns the longest word in the input string, along with the number of characters in that word.

Syntax⚓︎

LongestWord(Str: string): (string, number)

Parameters⚓︎

• Str: string
  The input string to get the longest word from.

Returns⚓︎

• string
  The longest word found in the string.
• number
  The total number of characters in the found word.

Examples⚓︎

1
2
3
4
5

local LongestWord, Characters = StringPlus.LongestWord("The quick brown fox jumps over the lazy dog")
print(LongestWord, Characters

local LongestWord, Characters = StringPlus.LongestWord("Some text to check for the longest word...")
print(LongestWord, Characters)

1
2

jumps 5
longest 7

ReverseWords⚓︎

Purpose⚓︎

This function takes a string as input and returns a new string where all the words in the original string are reversed.
The order of the words in the returned string is the same as in the original string.

Syntax⚓︎

ReverseWords(Str: string): string

Parameters⚓︎

• Str: string
  The string to be processed.

Returns⚓︎

• string
  The string with reversed words.

Examples⚓︎

1
2
3
4
5
6
7
8

local Reversed = StringPlus.ReverseWords("Hello world")
print(Reversed)

local Reversed = StringPlus.ReverseWords("A string for testing!")
print(Reversed)

local Reversed = StringPlus.ReverseWords("Loren ipsun dolor")
print(Reversed)

1
2
3

olleH dlrow
A gnirts rof !gnitset
neroL nuspi rolod

CamelCase⚓︎

Purpose⚓︎

Converts a string or words separated by underscores into a string in camel case format.

Syntax⚓︎

CamelCase(Str: string): string

Parameters⚓︎

• Str: string
  The input string to be converted to camel case format.

Returns⚓︎

• string
  The input string in camel case format.

Examples⚓︎

1
2
3
4
5
6
7
8

local Str = "hello_world"
print(StringPlus.CamelCase(Str))

local Str = "HelloWorld"
print(StringPlus.CamelCase(Str))

local Str = "Hello_world"
print(StringPlus.CamelCase(Str))

1
2
3

helloWorld
helloWorld
helloWorld

SnakeCase⚓︎

Purpose⚓︎

This function converts a given string to snake case, a naming convention where all spaces and punctuation are replaced with underscores, and all letters are lowercase.
If the input string is all uppercase, it will be converted to lowercase.

Syntax⚓︎

SnakeCase(Str: string): string

Parameters⚓︎

• Str: string
  The input string to be converted to snake case.

Returns⚓︎

• string
  The input string in snake case.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

local SnakeCase = StringPlus.SnakeCase("ThisIsASentence")
print(SnakeCase)

local SnakeCase = StringPlus.SnakeCase("thisIsASentence")
print(SnakeCase)

local SnakeCase = StringPlus.SnakeCase("ThisIsASentence123")
print(SnakeCase)

local SnakeCase = StringPlus.SnakeCase("This_Is_A_Sentence")
print(SnakeCase)

local SnakeCase = StringPlus.SnakeCase("this_is_a_sentence")
print(SnakeCase)

1
2
3
4
5

this_is_a_sentence
this_is_a_sentence
this_is_a_sentence123
this_is_a_sentence
this_is_a_sentence

UniqueWords⚓︎

Purpose⚓︎

Returns an array or string of unique words in a given input string.

Syntax⚓︎

UniqueWords(Str: string, ReturnString: boolean?): (string | {string})

Parameters⚓︎

• Str: string
  The input string.
• ReturnString: boolean Optional
  A boolean value indicating whether to return the unique words as a single string value or as an array of strings.
  If this parameter is not provided, the default value is false.

Returns⚓︎

• string | table
  If ReturnString is true, the function returns a string of unique words separated by a single space character; otherwise, the function returns an array of the found unique words.

Examples⚓︎

1
2
3
4
5

local UniqueWords = StringPlus.UniqueWords("This is a string. This is also a text.")
print(UniqueWords)

local UniqueWords = StringPlus.UniqueWords("This is a string. This is also a text.", true)
print(UniqueWords)

1
2

{"string", "also", "text"}
string also text

Analyze⚓︎

Purpose⚓︎

Takes a string as an input and returns a dictionary containing various statistics about the string.

The statistics does include the number of all characters, alphabetical characters, words, unique words, common words, shortest and longest words, average word length, vowels, consonants, digits, punctuation marks, and lines in the string.

Syntax⚓︎

Analyze(Str: string): table

Parameters⚓︎

• Str: string
  A string to be analyzed.

Returns⚓︎

• table
  A dictionary containing the following key-value pairs:
  • AllCharacterCount: The number of all characters in the string
  • AlphaCharacterCount: The number of alphabetical characters in the string
  • WordCount: The number of words in the string
  • WordAppearCount: A dictionary containing the frequency of each word in the string where:
    • Each key represents the word string value
    • Each key value represents a number (integer) that specifies how many times the word has appeared
  • UniqueWordCount: The number of unique words in the string
  • CommonWordCount: The number of common words in the string
  • ShortestWord: A dictionary containing the shortest word in the string and its length where keys are:
    • Word: The shortest word string value
    • Length: The length of the shortest word represented as a number value
  • LongestWord: A dictionary containing the longest word in the string and its length where keys are:
    • Word: The longest word string value
    • Length: The length of the longest word represented as a number value
  • AvgWordLength: The average length of words in the string
  • VowelCount: The number of vowels in the string
  • ConsonantCount: The number of consonants in the string
  • DigitCount: The number of digits in the string
  • PunctuationCount: The number of punctuation marks in the string
  • LineCount: The number of lines in the string

Examples⚓︎

1
2
3
4
5
6
7
8
9

local Str = "Hello, world! This is a test string."
local Stats = StringPlus.Analyze(Str)

print(Stats.WordCount)
print(Stats.ShortestWord.Word)
print(Stats.LongestWord.Word)

local Str = "Luau comes with a set of linting passes, that help make sure that the code is correct and consistent. Unlike the type checker, that models the behavior of the code thoroughly and points toward type mismatches that are likely to result in runtime errors, the linter is more opinionated and produces warnings that can often be safely ignored, although it’s recommended to keep the code clean of the warnings."
print("Statics:", StringPlus.Analyze(Str))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

7
a
string
Statics: {
    ["AllCharacterCount"] = 408,
    ["AlphaCharacterCount"] = 331,
    ["AvgWordLength"] = 4.782608695652174,
    ["CommonWordCount"] = 9,
    ["ConsonantCount"] = 208,
    ["DigitCount"] = 0,
    ["LineCount"] = 1,
    ["LongestWord"] = {...},
    ["PunctuationCount"] = 6,
    ["ShortestWord"] = {...},
    ["UniqueWordCount"] = 40,
    ["VowelCount"] = 123,
    ["WordAppearCount"] = {...},
    ["WordCount"] = 69
}

Expand⚓︎

Purpose⚓︎

The StringPlus.Expand function takes in a string and a table of replacements (called Subset) and returns a new string with the specified replacements made.
The function uses the pattern "%${([%w_ %.%(#%)]+)" which is similar to javascript string interpolation syntax to identify which substrings in the input string should be replaced.

The Subset table should contain keys that match the substrings to be replaced and values that are the desired replacements. In addition to simple string replacements, the function also supports nested table keys and table numeric indices (TNI) in the Subset table.

Syntax⚓︎

Expand(Str: string, Subset: table): string

Parameters⚓︎

• Str: string
  The string to expand.
• Subset: table
  A table containing the values that will be used to expand the string.

Returns⚓︎

• string
  The expanded string.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

local Subset = {
    Name = "John",
    Mood = "good",
    [1] = "apple",
    [2] = "banana",
    [3] = "orange"
}

local Str = "Hello ${Name}, how are you? I hope you're having a ${Mood} day. Here's a list of items: ${(#1)}, ${(#2)}, ${(#3)}."
local ExpandedStr, Replacements = StringPlus.Expand(Str, Subset)
print(ExpandedStr)

local Subset = {
    ["Name"] = "John",
    ["Age"] = 25,
    ["Achievements"] = {
        "Graduated with honors",
        "Won a medal in a science fair",
        "Became a black belt in karate"
    },
    ["Hobbies"] = {
        "Swimming",
        "Running",
        "Reading"
    },
    ["Location"] = "New York"
}

local StringToExpand = "My name is ${Name} and I am ${Age} years old. I am from ${Location} and I enjoy ${Hobbies.1} and ${Hobbies.3}. Some of my achievements include: ${Achievements.1}, ${Achievements.2}, and ${Achievements.3}. I have also completed the marathon in 3 hours!"
local ExpandedString = StringPlus.Expand(StringToExpand, Subset)
print(ExpandedString)

1
2

Hello John, how are you? I hope you're having a good day. Here's a list of items: apple, banana, orange.
My name is John and I am 25 years old. I am from New York and I enjoy Swimming and Reading. Some of my achievements include: Graduated with honors, Won a medal in a science fair, and Became a black belt in karate. I have also completed the marathon in 3 hours!

Distort⚓︎

Purpose⚓︎

The Distort function takes a string, a percentage, and an optional set of replacement characters and returns the distorted string by replacing characters in the original string with characters from the array of replacement characters.

This function could be useful for simulating low signal transmission for games that has radio chats.

Syntax⚓︎

Distort(Str: string, Percentage: number, ReplacementChars: {string}?): string

Parameters⚓︎

• Str: string
  The string to be distorted.
• Percentage: boolean
  The percentage of characters to replace in the string. Must be between 0 and 100.
• ReplacementChars: table Optional
  An array of characters/strings to replace the characters in the original string with. The default value is {"#", "$", "@", "&"}.

Returns⚓︎

• string
  A modified version of the original string, where a specified percentage of characters are substituted with characters from a designated array of replacement characters.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local DistortedString = StringPlus.Distort("Hello", 85)
print(DistortedString)

local DistortedString = StringPlus.Distort("Hello Luau", 38, {"#", "*"})
print(DistortedString)

local DistortedString = StringPlus.Distort("E", 20)
print(DistortedString)

local DistortedString = StringPlus.Distort("Lorem ipsum dolor sit amet, consectetur adipisci elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua.", 12)
print(DistortedString)

1
2
3
4

&#l&&
He#l* ##au
E
Lorem@ipsum d@lor sit amet,@consect#$ur adipis#i e&i&, sed eiusmod tempor inc#du#t u&&labor# et dolore mag@a aliqua.

1
2
3
4

###l#
He*lo *u*#
#
Lore$ ipsum d@l#r sit ame#,&co&&e#tetur adipisci elit, sed eiusmod $empor incidu#t #t labore et $@lor& magna aliqua.

TitleCase⚓︎

Purpose⚓︎

Converts the input string to title case, following the English title case rules.
The first character of the first word and the first character of any word after a space are always capitalized.
Any character after a hyphen (-) is always lower-cased.

If the Strict parameter is set to true, the function will lower-case any word that is not considered a proper noun.
If the Strict parameter is set to false or not provided, the function will apply title case to all words in the input string.

Syntax⚓︎

TitleCase(Str: string, Strict: boolean?): string

Parameters⚓︎

• Str: string
  The input string to be converted to title case.
• Strict: boolean
  A boolean value indicating whether the function should strictly follow the English title case rules or not.
  If set to true, the function will lower-case any word that is not considered a proper noun.
  If set to false or not provided, the function will apply title case to all words in the input string.

Returns⚓︎

• string
  The input string in title case.

Examples⚓︎

1
2
3
4
5
6
7
8
9

local Str = "this is an example title"
local AppliedTitleCase = StringPlus.TitleCase(Str, true)
print(AppliedTitleCase)

local AppliedTitleCase = StringPlus.TitleCase(Str, false)
print(AppliedTitleCase)

local AppliedTitleCase = StringPlus.TitleCase("the quick BROWN fox")
print(AppliedTitleCase)

1
2
3

This Is an Example Title
This Is An Example Title
The Quick Brown Fox

Lines⚓︎

Purpose⚓︎

Used to split a given string into a list of lines, where each element in the returned array or each returned tuple element is a string representing a single line.

If the Strict parameter is set to true, the function will lower-case any word that is not considered a proper noun.
If the Strict parameter is set to false or not provided, the function will apply title case to all words in the input string.

Syntax⚓︎

Lines(Str: string, KeepEnds: boolean?, ReturnAsATuple: boolean?): (...string | {string}))

Parameters⚓︎

• Str: string
  The input string to return its lines.
• KeepEnds: boolean Optional: A boolean value indicating whether to keep the line endings³ in the returned strings.
  The default value is false.
• ReturnAsATuple: boolean Optional
  A boolean value indicating whether to return the lines as a tuple.
  The default value is false.

Returns⚓︎

• table | tuple
  An array of strings representing the lines in the input string, or a tuple of strings representing the lines if the ReturnAsATuple parameter is set to true. Each element in the array/tuple represents a single line in the input string, and includes the line ending characters if the KeepEnds parameter is set to true.
  If the input string does not contain more than one line, the function will return a array/tuple with a single element representing the input string.

Examples⚓︎

1
2
3
4
5

local Text = "This is a multi-line string\r\nThis is the second line\nThis is the third line\rThis is the fourth line"

print(StringPlus.Lines(Text))
print(StringPlus.Lines(Text, true))
print(StringPlus.Lines(Text, false, true))

1
2
3

{"This is a multi-line string", "This is the second line", "This is the third line", "This is the fourth line"}
{"This is a multi-line string\r\n", "This is the second line\n", "This is the third line\r", "This is the fourth line"}
This is a multi-line string, This is the second line, This is the third line, This is the fourth line

RFind⚓︎

Purpose⚓︎

Returns the starting and ending indices of the last occurrence of the Sub string within the input string, searching backwards from the optional End index to the optional Start index. If Sub is not found within the specified range, the function returns nil for both indices.

Syntax⚓︎

RFind(Str: string, Sub: string, Start: number?, End: number?): (number?, number?))

Parameters⚓︎

• Str: string
  The string in which the search will take place.
• Sub: string
  The substring to be searched for.
• Start: number Optional
  The starting position of the search.
  Defaults to the first character in the string from backwards.
• End: number Optional
  The ending position of the search.
  Defaults to the length of the string.

Returns⚓︎

• number
  The starting position of the found substring, or nil if not found.
• number
  The ending position of the found substring, or nil if not found.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

local Str = "The quick brown fox jumps over the lazy dog."
local Sub = "the"

-- Find the last occurrence of "the" within the string:
local Start, End = StringPlus.RFind(Str, Sub)
print(Start, End)

-- Find the last occurrence of "the" within the first half of the string (not found):
local Start, End = StringPlus.RFind(Str, Sub, 1, #Str / 2)
print(Start, End)

-- Find the last occurrence of "fox" within the string:
local Start, End = StringPlus.RFind(Str, "fox")
print(Start, End)

-- Find the last occurrence of "cat" within the string (not found):
local Start, End = StringPlus.RFind(Str, "cat")
print(Start, End)

1
2
3
4

32 34
nil nil
17 19
nil nil

Partition⚓︎

Purpose⚓︎

Takes in an input string, a separator string, and returns a tuple or an array (depending on the value of ReturnAsArray) representing the three partitioned parts of the input string.

Syntax⚓︎

Partition(Str: string, Separator: string, ReturnAsArray: boolean?): (...string | {string})

Parameters⚓︎

• Str: string
  The input string to be partitioned.
• Sub: string
  The separator string used to partition Str.
• ReturnAsArray: boolean Optional
  A boolean value that specifies whether the function should return the resulting partition as an array or as a tuple.
  If it is not provided or is nil, the function returns a tuple.

Returns⚓︎

• string
  The first element is the substring of Str before the first occurrence of Separator or nil if it doesn't exist.
• string
  The second element is the substring of Str between the first occurrence of Separator and the last occurrence of Separator or nil if it doesn't exist.
• string
  The third element is the substring of Str after the last occurrence of Separator or nil if it doesn't exist.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

local Str = "Hello, World!"
local p1, p2, p3 = StringPlus.Partition(Str, "|")
print(p1)
print(p2)
print(p3)
print("-----")

local Part = StringPlus.Partition(Str, "|", true)
print(Part)
print("-----")


local Str = "Hello, World! How are you doing today?"
local p1, p2, p3 = StringPlus.Partition(Str, ", ")
print(p1)
print(p2)
print(p3)
print("-----")

local Parts = StringPlus.Partition(Str, ", ", true)
print(Parts)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Hello, World!
nil
nil
-----
Hello, World!
-----
Hello
, 
World! How are you doing today?
-----
{"Hello", ", ", "World! How are you doing today?"}

RPartition⚓︎

Purpose⚓︎

Returns a tuple or an array containing three strings; The part of the string before the first occurrence of the separator, the separator string itself, and the part of the string after the separator.
If the separator is not found in the string, the entire string is returned.

Syntax⚓︎

RPartition(Str: string, Separator: string, ReturnAsArray: boolean?): (...string | {string})

Parameters⚓︎

• Str: string
  The original string that needs to be partitioned.
• Sub: string
  A string value that represents the boundary between the first and second substrings.
• ReturnAsArray: boolean Optional
  A boolean value that determines whether the function should return the three substrings as an array or as a tuple. The default value for this input is false which mean that the function will return a tuple containing three string values.

Returns⚓︎

• string
  The first substring of Str before the first occurrence of Separator or nil if it doesn't exist.
• string
  The second substring of Str if it exist.
• string
  The third substring of Str after the last occurrence of Separator or nil if it doesn't exist.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

local Str = "Hello, World!"

-- Separate the Str into three parts, using the space character as the separator
local left, separator, right = StringPlus.RPartition(Str, " ")
print(left)
print(separator)
print(right)
print("------")

-- Separate the Str into three parts, using the comma character as the separator, and get an array of parts
local parts =  StringPlus.RPartition(Str, ",", true)
print(parts[1])
print(parts[2])
print(parts[3])
print("------")

-- If the separator is not found, the original Str is returned as the left part and the right part is an empty Str
local left, separator, right =  StringPlus.RPartition(Str, "?")
print(left)
print(separator)
print(right)
print("------")

-- Separate the Str into three parts, using the word "bananas" as the separator.
local Str = "I could eat bananas all day, bananas are my favorite fruit."
local left, separator, right =  StringPlus.RPartition(Str, "bananas")
print(left)
print(separator)
print(right)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

Hello,

World!
------
Hello
,
 World!
------
Hello, World!
nil
nil
------
I could eat bananas all day, 
bananas
 are my favorite fruit.

BinaryEncode⚓︎

Purpose⚓︎

Takes in a string and returns its binary encoding, where each character is represented as an 8-bit binary string, separated by a space as a default.

Syntax⚓︎

BinaryEncode(Str: string, Delimiter: string?): string

Parameters⚓︎

• Str: string
  The string to be encoded.
• Delimiter: string Optional
  A string represents the separator to be used between every Byte of the output binary. Default value is a space.

Returns⚓︎

• string
  The binary encoded string, with each Byte being separated by a Delimiter.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local BinaryEncodedString = StringPlus.BinaryEncode("Hello, World!")
print(BinaryEncodedString)

local BinaryEncodedString = StringPlus.BinaryEncode("Test!", "-")
print(BinaryEncodedString)

local BinaryEncodedString = StringPlus.BinaryEncode("Hello, 世界!")
print(BinaryEncodedString)

local BinaryEncodedString = StringPlus.BinaryEncode("")
print(BinaryEncodedString)

1
2
3

01001000 01100101 01101100 01101100 01101111 00101100 00100000 01010111 01101111 01110010 01101100 01100100 00100001
01010100-01100101-01110011-01110100-00100001
01001000 01100101 01101100 01101100 01101111 00101100 00100000 11100111 10111010 11100111 11101111 11100111 01100001

BinaryDecode⚓︎

Purpose⚓︎

This function takes in a single parameter Encoded which is a string.
It converts this value to a string, removes any non-binary character from it, and processes each 8-bit binary sequence.
It converts each sequence to a number and then converts this number to its corresponding ASCII character. The resulting string is returned.

Syntax⚓︎

BinaryDecode(Encoded: string): string

Parameters⚓︎

• Encoded: string
  The binary string to be decoded.

Returns⚓︎

• string
  A string representing the decoded binary.

Examples⚓︎

1
2
3
4
5
6
7

local Encoded = "01001000 01100101 01101100 01101100 01101111"
local DecodedStr = StringPlus.BinaryDecode(Encoded)
print(DecodedStr)

local Encoded = "01001000-5-01100101-5-01101100-5-01101100-5-01101111-5-00100001-5-00100000-5-01010100-5-01101000-5-01101001-5-01110011-5-00100000-5-01110111-5-01100001-5-01110011-5-00100000-5-01100001-5-00100000-5-01100111-5-01110010-5-01100101-5-01100101-5-01110100-5-01101001-5-01101110-5-01100111"
local DecodedStr = StringPlus.BinaryDecode(Encoded)
print(DecodedStr)

1
2

Hello
Hello! This was a greeting

HexEncode⚓︎

Purpose⚓︎

This function takes a string as an input and returns a string of hexadecimal characters representing the input string.
If the input string is empty, the function simply returns nil.

Syntax⚓︎

HexEncode(Str: string): string

Parameters⚓︎

• Str: string
  A string value to be encoded in hexadecimal.

Returns⚓︎

• string
  A string of hexadecimal characters representing the input string.

Examples⚓︎

1
2
3

print(StringPlus.HexEncode("Hello, World!"))
print(StringPlus.HexEncode("abc123"))
print(StringPlus.HexEncode(""))

1
2
3

48656c6c6f2c20576f726c6421
616263313233
nil

HexDecode⚓︎

Purpose⚓︎

This function takes a single string argument HexStr which represents a string of hexadecimal digits. If HexStr does not contain only hexadecimal digits (i.e. it contains any characters other than 0-9, a-f, and A-F), the function returns nil. Otherwise, it returns a string containing the decoded version of HexStr.

The decoding is done by replacing each pair of hexadecimal digits with the corresponding ASCII character. For example, the string "41 42 43" (which represents the hexadecimal digits "ABC") would be decoded as the string "ABC".

Syntax⚓︎

HexDecode(HexStr: string): string?

Parameters⚓︎

• HexStr: string
  The input string containing hexadecimal characters/digits (0-9, a-f, A-F).

Returns⚓︎

• string
  The decoded string if the HexStr parameter is a valid string of hexadecimal characters/digits.

Examples⚓︎

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

local Decoded = StringPlus.HexDecode("48656c6c6f20576f726c64")
print(Decoded)

local UpperCaseHex = StringPlus.HexDecode("48656C6C6F20576F726C64")
print(UpperCaseHex)

local UpperCaseHex = StringPlus.HexDecode("48656c6c6f20526f626c6f7821")
print(UpperCaseHex)

local InvalidHex = StringPlus.HexDecode("48656c6c6f207$726c64")
print(InvalidHex)

1
2
3
4

Hello World
Hello World
Hello Roblox!
nil