Function Name

name: base64Encode

Tags

tags: string

Description

• Returns the base64-encoded version of the provided string.

Syntax

base64Encode(value)

• value
  the string value to be encoded in Base64.

Usage Examples

Example 1 — Encoding a simple string

Lua expression

return base64Encode("hello")

JSON result

"aGVsbG8="

Example 2 — Handling nil values

Lua expression

return base64Encode(nil)

JSON result

null

Additional Notes

• If the input value is nil, the function returns nil.
• The function uses the base64.StdEncoding package from Go's standard library to encode the string.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: base64Decode

Tags

tags: string

Description

• Decodes a Base64-encoded string and returns the original string.

Syntax

base64Decode(value)

• value
  the Base64-encoded string to be decoded.

Usage Examples

Example 1 — Decoding a Base64-encoded string

Lua expression

return base64Decode("aGVsbG8=")

JSON result

"hello"

Example 2 — Handling nil values

Lua expression

return base64Decode(nil)

JSON result

null

Example 3 — Handling invalid Base64 strings

Lua expression

return base64Decode("invalid_base64")

Error result

"error: illegal base64 data at input byte X"

Additional Notes

• If the input value is nil, the function returns nil.
• If the input string is not valid Base64, the function raises an error.
• The function uses the base64.StdEncoding package from Go's standard library for decoding.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: decodeURLQuery

Tags

tags: url, query, decode

Description

• Parses a URL query string and returns a table containing the decoded key-value pairs.

Syntax

decodeURLQuery(url)

• url
  the URL containing the query string to be parsed.

Usage Examples

Example 1 — Decoding a URL query string

Lua expression

return decodeURLQuery("https://example.com/?key1=value1&key2=value2")

JSON result

{
"key1": "value1",
"key2": "value2"
}

Example 2 — Handling an invalid URL

Lua expression

return decodeURLQuery("invalid_url")

JSON result

{}

Example 3 — URL with no query parameters

Lua expression

return decodeURLQuery("https://example.com/")

JSON result

{}

Additional Notes

• If the input URL is invalid or contains no query parameters, the function returns an empty table.
• The function uses Go's net/url package for URL parsing and query decoding.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: flatten

Tags

tags: object, array, flatten

Description

• Flattens a nested object or array into a single-level structure with customizable options for prefix, separator, and depth.

Syntax

flatten(value [, prefix [, separator [, depth [, options]]]])

• value
  the object or array to be flattened.
• prefix [optional]
  a string to prepend to each key in the flattened structure (default: "").
• separator [optional]
  a string to place between concatenated keys (default: "").
• depth [optional]
  the maximum depth to flatten (default: 0, meaning no limit).
• options [optional]
  a table containing additional configuration, such as:
• array_start_index: the starting index for arrays in the flattened result.

Usage Examples

Example 1 — Flattening a simple nested object

Lua expression

return flatten({ key1 = { nestedKey1 = "value1" } })

JSON result

{
"key1.nestedKey1": "value1"
}

Example 2 — Using a custom separator and prefix

Lua expression

return flatten({ key1 = { nestedKey1 = "value1" } }, "root", "_")

JSON result

{
"root_key1_nestedKey1": "value1"
}

Example 3 — Limiting the depth of flattening

Lua expression

return flatten({ key1 = { nestedKey1 = { deeplyNestedKey = "value" } } }, "", ".", 1)

JSON result

{
"key1.nestedKey1": {
"deeplyNestedKey": "value"
}
}

Example 4 — Configuring array start index

Lua expression

return flatten({ array = { "value1", "value2" } }, "", ".", 0, { array_start_index = 1 })

JSON result

{
"array.1": "value1",
"array.2": "value2"
}

Additional Notes

• If options is not provided, default behaviors are applied.
• If depth is set to 0, the function flattens the entire structure regardless of depth.
• Array indices can be customized using the array_start_index option in options.
• The function uses JSON encoding and decoding internally to process Lua objects.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: join

Tags

tags: string, array, join

Description

• Joins an array of strings into a single string, with an optional separator between elements.

Syntax

join(values [, separator])

• values
  the array of strings to join.
• separator [optional]
  the string to place between each joined value (default: "").

Usage Examples

Example 1 — Joining an array of strings with no separator

Lua expression

return join({ "a", "b", "c" })

JSON result

"abc"

Example 2 — Joining an array of strings with a custom separator

Lua expression

return join({ "a", "b", "c" }, ",")

JSON result

"a,b,c"

Example 3 — Handling an empty array

Lua expression

return join({})

JSON result

""

Example 4 — Handling nil values

Lua expression

return join(nil)

JSON result

null

Additional Notes

• If the input is nil, the function returns nil.
• If no separator is provided, the function defaults to an empty string "".
• The function raises an error if the input is not an array of strings.
• The function uses Go's strings.Join to concatenate the array elements.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: lower

Tags

tags: string, case, lower

Description

• Converts a string to lowercase.

Syntax

lower(value)

• value
  the string to be converted to lowercase.

Usage Examples

Example 1 — Converting a string to lowercase

Lua expression

return lower("HELLO")

JSON result

"hello"

Example 2 — Handling a mixed-case string

Lua expression

return lower("HeLLo WoRLD")

JSON result

"hello world"

Example 3 — Handling nil values

Lua expression

return lower(nil)

JSON result

null

Additional Notes

• If the input value is nil, the function returns nil.
• The function uses Go's strings.ToLower to convert the string to lowercase.
• Non-string inputs are automatically converted to strings before processing.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: millisecondsFor

Tags

tags: time, milliseconds

Description

• Returns the number of milliseconds since the Unix epoch for a given time.Time object.

Syntax

millisecondsFor(time)

• time
  the time.Time object to convert to milliseconds.

Usage Examples

Example 1 — Converting the current time to milliseconds

Lua expression

return millisecondsFor(os.date("*t"))

JSON result

1683145793345

Example 2 — Converting a specific time.Time object to milliseconds

Lua expression

return millisecondsFor({ year = 2024, month = 1, day = 1, hour = 0, min = 0, sec = 0 })

JSON result

1704115200000

Additional Notes

• The function calculates the milliseconds by dividing the Unix timestamp in nanoseconds by 1 million (1e6).
• It returns the number of milliseconds as an int64.
• This function assumes the input is a valid time.Time object.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: millisecondsSinceEpoch

Tags

tags: time, milliseconds, epoch

Description

• Returns the number of milliseconds since the Unix epoch for the current time.

Syntax

millisecondsSinceEpoch()

Usage Examples

Example 1 — Getting the current time in milliseconds since the Unix epoch

Lua expression

return millisecondsSinceEpoch()

JSON result

1703904000000

Additional Notes

• The function uses the system's current time and calculates the number of milliseconds since the Unix epoch.
• The result is returned as a lua.LNumber.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: millisecondsSinceEpochFromString

Tags

tags: time, string, milliseconds, epoch

Description

• Parses a string representing a date and time (in RFC3339 format) and returns the number of milliseconds since the Unix epoch.

Syntax

millisecondsSinceEpochFromString(datetime_string)

• datetime_string
  the string representing the date and time in RFC3339 format to convert to milliseconds.

Usage Examples

Example 1 — Parsing an RFC3339 string and converting to milliseconds

Lua expression

return millisecondsSinceEpochFromString("2024-12-30T00:00:00Z")

JSON result

1703904000000

Example 2 — Handling an invalid datetime string

Lua expression

return millisecondsSinceEpochFromString("invalid_date")

Error result

"error: parsing time \"invalid_date\" as \"2006-01-02T15:04:05Z07:00\": cannot parse \"invalid_date\" as \"2006-01-02T15:04:05Z07:00\""

Example 3 — Handling nil values

Lua expression

return millisecondsSinceEpochFromString(nil)

JSON result

null

Additional Notes

• The function assumes the input string is in RFC3339 format (e.g., 2024-12-30T00:00:00Z).
• If an invalid date string is provided, the function raises an error.
• The function uses time.Parse to parse the date string and calculates the milliseconds since the Unix epoch.
• Custom formats are not supported currently, but you can extend the function to support them in the future.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: pathEscape

Tags

tags: string, URL, escape

Description

• Escapes a string to make it safe to use in a URL path by percent-encoding special characters.

Syntax

pathEscape(value)

• value
  the string to be percent-encoded for use in a URL path.

Usage Examples

Example 1 — Escaping a string for use in a URL path

Lua expression

return pathEscape("hello world")

JSON result

"hello%20world"

Example 2 — Escaping a string with special characters

Lua expression

return pathEscape("hello/world?query=1")

JSON result

"hello%2Fworld%3Fquery%3D1"

Example 3 — Handling nil values

Lua expression

return pathEscape(nil)

JSON result

null

Additional Notes

• If the input is nil, the function returns nil.
• The function uses Go's url.PathEscape to percent-encode the string, escaping characters that are not allowed in URL paths.
• This function only escapes characters necessary for URL paths and does not encode the entire URL.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: pathUnescape

Tags

tags: string, URL, unescape

Description

• Unescapes a percent-encoded string to its original form, reversing the effects of pathEscape.

Syntax

pathUnescape(value)

• value
  the percent-encoded string to be decoded.

Usage Examples

Example 1 — Unescaping a URL path-encoded string

Lua expression

return pathUnescape("hello%20world")

JSON result

"hello world"

Example 2 — Unescaping a string with encoded special characters

Lua expression

return pathUnescape("hello%2Fworld%3Fquery%3D1")

JSON result

"hello/world?query=1"

Example 3 — Handling an invalid percent-encoded string

Lua expression

return pathUnescape("hello%world")

Error result

"error: invalid percent-encoded string"

Example 4 — Handling nil values

Lua expression

return pathUnescape(nil)

JSON result

null

Additional Notes

• If the input is nil, the function returns nil.
• If the input contains invalid percent-encoded sequences, an error is raised.
• The function uses Go's url.PathUnescape to decode the percent-encoded string.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: queryEscape

Tags

tags: string, URL, escape

Description

• Escapes a string to make it safe for use in a URL query by percent-encoding special characters.

Syntax

queryEscape(value)

• value
  the string to be percent-encoded for use in a URL query.

Usage Examples

Example 1 — Escaping a string for use in a URL query

Lua expression

return queryEscape("hello world")

JSON result

"hello+world"

Example 2 — Escaping a string with special characters

Lua expression

return queryEscape("hello/world?query=1")

JSON result

"hello%2Fworld%3Fquery%3D1"

Example 3 — Handling nil values

Lua expression

return queryEscape(nil)

JSON result

null

Additional Notes

• If the input is nil, the function returns nil.
• The function uses Go's url.QueryEscape to percent-encode the string, escaping characters that are not allowed in URL query strings.
• This function escapes the characters necessary for query parameters, such as &, =, and others.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: queryUnescape

Tags

tags: string, URL, unescape

Description

• Unescapes a percent-encoded string in a URL query to its original form, reversing the effects of queryEscape.

Syntax

queryUnescape(value)

• value
  the percent-encoded string to be decoded.

Usage Examples

Example 1 — Unescaping a URL query-encoded string

Lua expression

return queryUnescape("hello+world")

JSON result

"hello world"

Example 2 — Unescaping a string with encoded special characters

Lua expression

return queryUnescape("hello%2Fworld%3Fquery%3D1")

JSON result

"hello/world?query=1"

Example 3 — Handling an invalid percent-encoded string

Lua expression

return queryUnescape("hello%world")

Error result

"error: invalid percent-encoded string"

Example 4 — Handling nil values

Lua expression

return queryUnescape(nil)

JSON result

null

Additional Notes

• If the input is nil, the function returns nil.
• If the input contains invalid percent-encoded sequences, an error is raised.
• The function uses Go's url.QueryUnescape to decode the percent-encoded string.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: replace

Tags

tags: string, replace, text

Description

• Replaces all occurrences of a substring with another substring within a string.

Syntax

replace(value, old_substring, new_substring)

• value
  the string in which the replacement will occur.
• old_substring
  the substring to be replaced.
• new_substring
  the substring that will replace old_substring.

Usage Examples

Example 1 — Replacing all occurrences of a substring

Lua expression

return replace("hello world", "world", "Lua")

JSON result

"hello Lua"

Example 2 — Replacing a substring with an empty string

Lua expression

return replace("hello world", "world", "")

JSON result

"hello "

Example 3 — Handling nil values

Lua expression

return replace(nil, "world", "Lua")

JSON result

null

Additional Notes

• If value is nil, the function returns nil.
• The function uses Go's strings.ReplaceAll to perform the replacement of all occurrences of the old_substring with the new_substring.
• The function returns the modified string.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: resolveLocation

Tags

tags: time, location, resolve

Description

• Resolves a Lua table representing a time zone and returns a corresponding time.Location.
  If the table is not provided or invalid, it returns the provided fallback location.

Syntax

resolveLocation(value, fallback)

• value
  a Lua table containing the time zone information (name and offset).
• fallback
  the fallback time.Location to return if the value is not a valid Lua table.

Usage Examples

Example 1 — Resolving a time zone from a Lua table

Lua expression

return resolveLocation({name = "PST", offset = -28800}, time.UTC)

JSON result

"PST-08:00"

Example 2 — Using the fallback time zone when an invalid table is passed

Lua expression

return resolveLocation(nil, time.UTC)

JSON result

"UTC"

Additional Notes

• The Lua table should have a name (string) and offset (integer) to specify the time zone.
• The fallback time.Location is returned if the value is not a valid Lua table or cannot be resolved.
• The function uses Go's time.FixedZone to create the time.Location based on the provided name and offset.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: resolveInt

Tags

tags: number, resolve, fallback

Description

• Resolves an integer value from a Lua value. If the Lua value is a valid non-zero integer, it returns the integer.
  Otherwise, it returns the provided fallback value.

Syntax

resolveInt(value, fallback)

• value
  the Lua value to be resolved into an integer.
• fallback
  the fallback integer to return if the value is not a valid non-zero integer.

Usage Examples

Example 1 — Resolving a valid integer value

Lua expression

return resolveInt(42, 10)

JSON result

42

Example 2 — Using the fallback value when the Lua value is not an integer

Lua expression

return resolveInt(nil, 10)

JSON result

10

Example 3 — Using the fallback value when the Lua value is zero

Lua expression

return resolveInt(0, 10)

JSON result

10

Additional Notes

• If the Lua value is not a valid non-zero integer, the function returns the provided fallback value.
• The function uses Go's type assertion to check if the Lua value is a valid lua.LNumber and is non-zero.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: resolveString

Tags

tags: string, resolve, fallback

Description

• Resolves a string value from a Lua value. If the Lua value is a valid non-empty string, it returns the string.
  Otherwise, it returns the provided fallback string.

Syntax

resolveString(value, fallback)

• value
  the Lua value to be resolved into a string.
• fallback
  the fallback string to return if the value is not a valid non-empty string.

Usage Examples

Example 1 — Resolving a valid string value

Lua expression

return resolveString("hello", "fallback")

JSON result

"hello"

Example 2 — Using the fallback value when the Lua value is not a string

Lua expression

return resolveString(nil, "fallback")

JSON result

"fallback"

Example 3 — Using the fallback value when the Lua string is empty

Lua expression

return resolveString("", "fallback")

JSON result

"fallback"

Additional Notes

• If the Lua value is not a valid non-empty string, the function returns the provided fallback value.
• The function uses Go's type assertion to check if the Lua value is a valid lua.LString and is non-empty.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: secondsSinceEpoch

Tags

tags: time, epoch, current

Description

• Returns the current number of seconds since the Unix epoch (January 1, 1970).
  This is typically used to get the current timestamp in seconds.

Syntax

secondsSinceEpoch()

Usage Examples

Example 1 — Getting the current seconds since the Unix epoch

Lua expression

return secondsSinceEpoch()

JSON result

1703942400

Additional Notes

• This function calls the timeNow() function to get the current time and converts it to the number of seconds since the Unix epoch using Unix().
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: secondsSinceEpochFromString

Tags

tags: time, epoch, parse, string

Description

• Converts a string representing a date in RFC3339 format to the number of seconds since the Unix epoch (January 1, 1970).
  If the string is invalid, it raises an error.

Syntax

secondsSinceEpochFromString(value)

• value
  the date string in RFC3339 format to be converted to seconds since the Unix epoch.

Usage Examples

Example 1 — Converting a valid RFC3339 string to seconds since the Unix epoch

Lua expression

return secondsSinceEpochFromString("2024-12-30T12:00:00Z")

JSON result

1703942400

Example 2 — Handling invalid date string

Lua expression

return secondsSinceEpochFromString("invalid date")

Error result

"error: invalid date format"

Example 3 — Handling nil values

Lua expression

return secondsSinceEpochFromString(nil)

JSON result

null

Additional Notes

• If the input string is nil, the function returns nil.
• The function expects the input string to be in the RFC3339 format. If the format is incorrect, an error is raised.
• The function uses Go's time.Parse to parse the string and t.Unix() to get the number of seconds since the Unix epoch.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: split

Tags

tags: string, split, text

Description

• Splits a string into substrings based on a specified separator.
  If the separator is not provided, the function defaults to splitting by an empty string.
  It also supports an optional max parameter to limit the number of splits.

Syntax

split(value, separator, max)

• value
  the string to be split.
• separator [optional]
  the string that separates the substrings. If omitted, the default separator is an empty string.
• max [optional]
  the maximum number of splits to perform. If omitted, it splits all occurrences.

Usage Examples

Example 1 — Splitting a string by a separator

Lua expression

return split("one,two,three", ",")

JSON result

["one", "two", "three"]

Example 2 — Splitting a string by an empty string (default behavior)

Lua expression

return split("hello", "")

JSON result

["h", "e", "l", "l", "o"]

Example 3 — Limiting the number of splits

Lua expression

return split("one,two,three,four", ",", 2)

JSON result

["one", "two,three,four"]

Additional Notes

• The separator argument defaults to an empty string if not provided.
• The max argument controls the maximum number of splits. If max is 0, the function splits all occurrences.
• The result is returned as a Lua table containing the substrings.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: substring

Tags

tags: string, substring, text

Description

• Extracts a substring from the given string, starting from the specified start index and ending at the specified end index.
  If end is not provided, the substring will extend to the end of the string.
  If start is greater than end, the function returns an empty string.

Syntax

substring(value, start, end)

• value
  the string from which the substring will be extracted.
• start
  the index to start extracting the substring. This index is 0-based.
• end [optional]
  the index where the substring extraction ends. If omitted, the substring extends to the end of the string.

Usage Examples

Example 1 — Extracting a substring with a given start and end index

Lua expression

return substring("hello", 1, 3)

JSON result

"ell"

Example 2 — Extracting a substring with a specified start index, without an end index

Lua expression

return substring("hello", 2)

JSON result

"llo"

Example 3 — Using the start and end indices to extract a part of the string

Lua expression

return substring("world", 0, 4)

JSON result

"worl"

Additional Notes

• The start index is inclusive, and the end index is exclusive.
• If start is greater than end, the function returns an empty string.
• The end argument is optional; if omitted, the substring will go until the end of the string.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toBool

Tags

tags: boolean, type conversion, bool

Description

• Converts a value to a boolean. The function attempts to convert the value into a boolean using different rules depending on the type:
• If the value is already a boolean, it returns the same value.
• If the value is a number, it returns true for any non-zero number, and false for zero.
• If the value is a string, it returns true for non-empty strings, and false for an empty string.
• If the conversion fails, an error is raised.

Syntax

toBool(value)

• value
  the value to be converted to a boolean. It can be a boolean, number, or string.

Usage Examples

Example 1 — Converting a number to a boolean

Lua expression

return toBool(1)

JSON result

true

Example 2 — Converting an empty string to a boolean

Lua expression

return toBool("")

JSON result

false

Example 3 — Converting a non-zero number to a boolean

Lua expression

return toBool(42)

JSON result

true

Example 4 — Converting a boolean to a boolean

Lua expression

return toBool(true)

JSON result

true

Additional Notes

• The function raises an error if it cannot convert the value to a boolean.
• If the value is a number, any non-zero number is considered true, and 0 is considered false.
• If the value is a string, any non-empty string is considered true, and an empty string is considered false.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toDateTime

Tags

tags: datetime, format, conversion, time

Description

• Converts a string representing a date/time to a formatted string based on the provided input and output formats.
  It supports optional parameters for the input/output time formats and time zones. If no format is provided, it defaults to the RFC3339 format.
  The function parses the input string into a time.Time object and then formats it according to the specified output format and location.

Syntax

toDateTime(value, options)

• value
  the string representing the date and time to be parsed.
• options [optional]
  a table containing optional parameters for customizing the input/output formats and locations:
• inputFormat [optional] (default: time.RFC3339)
  the format of the input date/time string.
• inputLocation [optional] (default: time.UTC)
  the location (timezone) to interpret the input date/time string.
• outputFormat [optional] (default: time.RFC3339)
  the format of the resulting formatted date/time string.
• outputLocation [optional] (default: time.UTC)
  the location (timezone) for the output formatted date/time string.

Usage Examples

Example 1 — Converting a date string to the default format (RFC3339)

Lua expression

return toDateTime("2024-12-30T12:00:00Z")

JSON result

"2024-12-30T12:00:00Z"

Example 2 — Converting a date string with a custom input format

Lua expression

return toDateTime("30/12/2024 12:00", {inputFormat = "%d/%m/%Y %H:%M", outputFormat = "%Y-%m-%d %H:%M:%S"})

JSON result

"2024-12-30 12:00:00"

Example 3 — Converting a date string to a different timezone

Lua expression

return toDateTime("2024-12-30T12:00:00Z", {outputLocation = "America/New_York"})

JSON result

"2024-12-30T07:00:00-05:00"

Example 4 — Using custom formats for input and output

Lua expression

return toDateTime("2024-12-30 12:00", {inputFormat = "%Y-%m-%d %H:%M", outputFormat = "%d-%m-%Y"})

JSON result

"30-12-2024"

Additional Notes

• If no format or location is provided, the function defaults to using the RFC3339 format and UTC timezone.
• The function raises an error if the input string cannot be parsed with the given input format or location.
• The input format should match the format of the provided date/time string exactly.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toFloat

Tags

tags: float, type conversion, number

Description

• Converts a value to a float64. The function attempts to convert the value into a floating-point number. It can handle different input types, including number, boolean, and string. If the conversion fails, an error is raised.

Syntax

toFloat(value)

• value
  the value to be converted to a floating-point number. It can be a number, boolean, or string.

Usage Examples

Example 1 — Converting a number to a float

Lua expression

return toFloat(42)

JSON result

42.0

Example 2 — Converting a boolean to a float

Lua expression

return toFloat(true)

JSON result

1.0

Example 3 — Converting a string to a float

Lua expression

return toFloat("3.14")

JSON result

3.14

Example 4 — Handling invalid conversion

Lua expression

return toFloat("not a number")

JSON result

{ "error": "invalid conversion" }

Additional Notes

• The function raises an error if it cannot convert the value to a float64.
• If the value is a boolean, true is converted to 1.0, and false is converted to 0.0.
• If the value is a string, it must represent a valid floating-point number.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toISOCountry

Tags

tags: country, ISO, lookup

Description

• Converts a country name (in string format) to its corresponding ISO country code. The function looks up the country name in a predefined map and returns the ISO code. If the country is not found, the input value is returned as is.

Syntax

toISOCountry(countryName)

• countryName
  the name of the country to be converted. The function expects the name to be in string format.

Usage Examples

Example 1 — Converting a country name to its ISO code

Lua expression

return toISOCountry("United States")

JSON result

"US"

Example 2 — Handling a non-existent country

Lua expression

return toISOCountry("Atlantis")

JSON result

"Atlantis"

Example 3 — Converting a lowercase country name

Lua expression

return toISOCountry("canada")

JSON result

"CA"

Additional Notes

• The function performs a case-insensitive lookup by converting the input country name to lowercase before searching the ISO map.
• If the country name is not found in the map, the function returns the input value unchanged.
• The CountryToISO map must be predefined and contain the country names as keys and ISO codes as values.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toMD5Hash

Tags

tags: hash, MD5, string

Description

• Converts a string to its MD5 hash. The function takes a string input and returns the MD5 hash of that string. If the input is not a valid string, an error is raised.

Syntax

toMD5Hash(value)

• value
  the string to be converted to its MD5 hash.

Usage Examples

Example 1 — Converting a string to an MD5 hash

Lua expression

return toMD5Hash("hello world")

JSON result

"5eb63bbbe01eeed093cb22bb8f5acdc3"

Example 2 — Handling invalid input type

Lua expression

return toMD5Hash(12345)

JSON result

{ "error": "expected string, got number" }

Example 3 — Handling an empty string

Lua expression

return toMD5Hash("")

JSON result

"d41d8cd98f00b204e9800998ecf8427e"

Additional Notes

• The function expects a string input. If the input is not a string, a type error will be raised.
• The MD5 hash is returned as a hexadecimal string.
• MD5 is a widely used cryptographic hash function that produces a 128-bit hash value, typically represented as a 32-character hexadecimal number.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toRoundedInt

Tags

tags: round, integer, float

Description

• Converts a float value to its nearest integer. The function takes a floating-point number and returns the integer closest to it, rounding up or down as necessary.

Syntax

toRoundedInt(value)

• value
  the floating-point number to be rounded to an integer.

Usage Examples

Example 1 — Converting a float to a rounded integer

Lua expression

return toRoundedInt(3.6)

JSON result

4

Example 2 — Converting a float to a rounded integer (rounding down)

Lua expression

return toRoundedInt(3.2)

JSON result

3

Example 3 — Handling invalid input type

Lua expression

return toRoundedInt("not a number")

JSON result

{ "error": "invalid float" }

Additional Notes

• The function uses the standard rounding rules: numbers greater than or equal to .5 are rounded up, while numbers less than .5 are rounded down.
• If the input value cannot be converted to a float, an error will be raised.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toSHA256Hash

Tags

tags: hash, SHA256, string

Description

• Converts a string to its SHA-256 hash. The function takes a string input and returns the SHA-256 hash of that string. If the input is not a valid string, an error is raised.

Syntax

toSHA256Hash(value)

• value
  the string to be converted to its SHA-256 hash.

Usage Examples

Example 1 — Converting a string to a SHA-256 hash

Lua expression

return toSHA256Hash("hello world")

JSON result

"a591a6d40bf420404a011733cfb7b190d62c65bf0bcda8d8abbd7f6b3bfb2d4a"

Example 2 — Handling invalid input type

Lua expression

return toSHA256Hash(12345)

JSON result

{ "error": "expected string, got number" }

Example 3 — Handling an empty string

Lua expression

return toSHA256Hash("")

JSON result

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Additional Notes

• The function expects a string input. If the input is not a string, a type error will be raised.
• SHA-256 is a cryptographic hash function that produces a 256-bit (32-byte) hash value, typically represented as a 64-character hexadecimal string.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toString

Tags

tags: string, conversion, type cast

Description

• Converts a Lua value to its string representation. This function accepts various types of Lua values and converts them to their respective string representations. If the input value is nil, it returns nil as output.

Syntax

toString(value)

• value
  the Lua value to be converted to a string.

Usage Examples

Example 1 — Converting a number to a string

Lua expression

return toString(12345)

JSON result

"12345"

Example 2 — Converting a boolean to a string

Lua expression

return toString(true)

JSON result

"true"

Example 3 — Handling nil value

Lua expression

return toString(nil)

JSON result

null

Additional Notes

• The function returns the string representation of various Lua types such as numbers, booleans, and tables (if applicable).
• When the input is nil, the function returns nil as well.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toTruncatedFloat

Tags

tags: float, precision, rounding

Description

• Converts a floating-point number to a truncated version, removing digits after the specified precision. If no precision is provided, it defaults to truncating to 0 decimal places. The function effectively removes any digits after the specified precision, without rounding the value.

Syntax

toTruncatedFloat(value, [precision])

• value
  the floating-point number to be truncated.
• precision [optional]
  the number of decimal places to retain. Defaults to 0 if omitted.

Usage Examples

Example 1 — Truncating a float to a specific precision

Lua expression

return toTruncatedFloat(3.14159, 2)

JSON result

3.14

Example 2 — Truncating a float with default precision (0 decimal places)

Lua expression

return toTruncatedFloat(3.14159)

JSON result

3

Example 3 — Handling nil value

Lua expression

return toTruncatedFloat(nil)

JSON result

null

Additional Notes

• The precision parameter is optional and defaults to 0 if not provided.
• Note: The function truncates the number by removing extra digits without rounding.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: toTruncatedInt

Tags

tags: int, truncation, rounding

Description

• Converts a floating-point number to an integer by truncating it, removing any decimal places. The function does not round the value; it simply removes any digits after the decimal point.

Syntax

toTruncatedInt(value)

• value
  the floating-point number to be truncated to an integer.

Usage Examples

Example 1 — Truncating a float to an integer

Lua expression

return toTruncatedInt(3.14159)

JSON result

3

Example 2 — Handling negative float truncation

Lua expression

return toTruncatedInt(-3.14159)

JSON result

-3

Example 3 — Handling nil value

Lua expression

return toTruncatedInt(nil)

JSON result

null

Additional Notes

• The function truncates the floating-point number by removing the digits after the decimal point without rounding.
• Note: The input must be a number; other types will cause an error.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: trim

Tags

tags: string, trimming, whitespace

Description

• Removes leading and trailing whitespace from a string. This includes spaces, tabs, and newlines.

Syntax

trim(value)

• value
  the string to be trimmed of whitespace characters at the beginning and end.

Usage Examples

Example 1 — Trimming leading and trailing spaces

Lua expression

return trim("  Hello, World!  ")

JSON result

"Hello, World!"

Example 2 — Trimming tabs and newlines

Lua expression

return trim("\t\nHello, Lua!\n\t")

JSON result

"Hello, Lua!"

Example 3 — Handling nil value

Lua expression

return trim(nil)

JSON result

null

Additional Notes

• The function trims whitespace from both ends of the string but does not remove spaces within the string.
• Note: The input must be a string; other types will return nil without modification.
• Update Notes
• 12/30/24
• Initial documentation created.

Function Name

name: upper

Tags

tags: string, uppercase

Description

• Converts all characters of a string to uppercase.

Syntax

upper(value)

• value
  the string to be converted to uppercase.

Usage Examples

Example 1 — Converting a string to uppercase

Lua expression

return upper("hello, world!")

JSON result

"HELLO, WORLD!"

Example 2 — Handling nil value

Lua expression

return upper(nil)

JSON result

null

Additional Notes

• The function converts only the alphabetic characters to uppercase; non-alphabetic characters remain unaffected.
• Note: The input must be a string; other types will return nil without modification.
• Update Notes
• 12/30/24
• Initial documentation created.