String Shared

The String module extends Lua's native string capabilities by adding powerful utility functions for enhanced string manipulation. It seamlessly integrates with the standard string library by augmenting the string metatable, providing developers with a comprehensive toolkit for case conversion, string splitting, whitespace trimming, version number handling, and hexadecimal conversions.

string Methods

string:compareVersionWith()

Compare two version strings

Syntax

string:compareVersionWith(version)

Parameters

version : string

The string version to compare to

Return Value

Type : integer

-1 if the version is older, 0 if it's the same and 1 if it's more recent

Example

-- Basic version comparison examples
local currentVersion = "1.2.3"

-- Compare with older version
local olderVersion = "1.1.9"
print(currentVersion:compareVersionWith(olderVersion))
-- Expected output: 1 (current version is newer)

-- Compare with same version
local sameVersion = "1.2.3"
print(currentVersion:compareVersionWith(sameVersion))
-- Expected output: 0 (same version)

-- Compare with newer version
local newerVersion = "1.3.0"
print(currentVersion:compareVersionWith(newerVersion))
-- Expected output: -1 (current version is older)

---

string:convertVersion()

Convert a version string (like "1.2.3") to a numeric value

Syntax

string:convertVersion()

Return Value

Type : number

The converted numeric version

Example

local versionString = "1.2.3"
local numericVersion = versionString:convertVersion()
print(versionString .. " converted to number: " .. numericVersion)
-- Expected output: 1.2.3 converted to number: 3002001
-- (3*1 + 2*1000 + 1*1000000)

-- This can be useful for version comparison
local newVersion = "1.3.0"
if newVersion:convertVersion() > versionString:convertVersion() then
    print("New version is greater than current version")
end

---

string:firstToUpper()

Return the string with the first letter in uppercase

Syntax

string:firstToUpper()

Return Value

Type : string

Return the string with the first letter in uppercase

Example

local text = "hello world"
local capitalized = text:firstToUpper()
print(capitalized)
-- Expected output: Hello world

-- Useful for formatting names
local playerName = "john"
print("Welcome, " .. playerName:firstToUpper() .. "!")
-- Expected output: Welcome, John!

---

string:split()

Split a string into parts based on a delimiter

Syntax

string:split(delimiter, pieces)

Parameters

delimiter : string

The character(s) to split the string on

pieces : number Optional

The maximum number of pieces to split into

Return Value

Type : table

Array of string parts

Example

local csvData = "apple,banana,cherry,date"
local fruits = csvData:split(",")
for i, fruit in ipairs(fruits) do
    print(i .. ": " .. fruit)
end
-- Expected output:
-- 1: apple
-- 2: banana
-- 3: cherry
-- 4: date

-- Limit the number of splits
local limitedSplit = csvData:split(",", 2)
for i, item in ipairs(limitedSplit) do
    print(i .. ": " .. item)
end
-- Expected output:
-- 1: apple
-- 2: banana,cherry,date

---

string:toHex()

Convert a hexadecimal string to a number, handling signed values

Syntax

string:toHex()

Return Value

Type : number

The converted numeric value

Example

local hexColor = "0xFF5733"
local colorValue = hexColor:toHex()
print("Hex " .. hexColor .. " converted to number: " .. colorValue)
-- Expected output: Hex 0xFF5733 converted to number: 16733747

-- Handle negative values (signed hex)
local signedHex = "0x80000000"
local signedValue = signedHex:toHex()
print("Signed hex " .. signedHex .. " converted to number: " .. signedValue)
-- Expected output: Signed hex 0x80000000 converted to number: -2147483648

---

string:trim()

Remove whitespace from both ends of a string

Syntax

string:trim()

Return Value

Type : string

The trimmed string

Example

local paddedText = "   Hello, world!   "
local trimmed = paddedText:trim()
print("Original: '" .. paddedText .. "'")
print("Trimmed: '" .. trimmed .. "'")
-- Expected output:
-- Original: '   Hello, world!   '
-- Trimmed: 'Hello, world!'

-- Useful for cleaning user input
local userInput = "  search term   "
local cleanInput = userInput:trim()
print("Searching for: '" .. cleanInput .. "'")
-- Expected output: Searching for: 'search term'