Utils¶

The st.utils library contains miscellaneous Lua helper functions.

Note that the require paths for the functions are just the module. i.e. require "st.utils.lazy_require" to pull in the lazy require util function. The documentation is presented differently due to limitations of the documentation generation tools.

st.utils.backoff_builder.backoff_builder(max, inc, rand)¶

Build an exponential backoff time value generator (function)

Parameters:

max (number) – the maximum wait interval (not including rand factor)
inc (number) – the rate at which to exponentially back off
rand (number) – a randomization range of (-rand, rand) to be added to each interval

st.utils.bitify.bitify(byte_string)¶

Turn a byte string into an array of bits with the most significant bit of each byte listed first

Parameters:: byte_string (str) – the byte string to convert to bits

st.utils.bit_list_to_byte_str.bit_list_to_byte_str(bit_list)¶

Convert a bit list to a byte string

Parameters:: bit_list (list[number]) – An array of bits (1 or 0) must be a length multiple of bytes

st.utils.bit_list_to_int.bit_list_to_int(bit_list)¶

Turn an array of bits into a number

Parameters:: bit_list (list[number]) – An array of bits (1 or 0)

st.utils.bytes_to_hex_string.bytes_to_hex_string(str)¶

convert binary string as ascii hex

Parameters:: str (str)

st.utils.camel_case.camel_case(str)¶

Convert the passed string to camelCase.

Parameters:: str (str) – string to convert

st.utils.clamp_value.clamp_value(val, min, max)¶

Force a value to fall between a min and max

Parameters:

val (number) – the value to be clamped
min (number) – the minimum value to be returned
max (number) – the maximum value to be returned

st.utils.c_to_f.c_to_f(celsius)¶

Convert celsius to fahrenheit.

Parameters:: celsius (number) – temperature in celsius

st.utils.deep_copy.deep_copy(val)¶

Copy a table and all it’s values recursively

Parameters:: val (table) – the table to copy

st.utils.deserialize_int.deserialize_int(buf, width, signed, little_endian)¶

Deserialize an integer from the passed string.

Parameters:

buf (str) – bytestring from which to deserialize an integer
width (number) – integer width in bytes
signed (boolean) – true if signed, false if unsigned
little_endian (boolean) – true if little endian, false if big endian

st.utils.ensure_property.ensure_property(t, k, v, raw)¶

Ensure that a key is populated in a table, if not populated the provided value

will be assigned to t[k]

Parameters:

t (table) – The table to populate
k (any) – The key to ensure is present
v (any) – The default value to assign to t[k]
raw (boolean) – If the property should be set using rawset

st.utils.fkeys.fkeys(t)¶

Table iterator for traversal by forward-sorted keys.

Parameters:: t (table) – over which to iterate

st.utils.f_to_c.f_to_c(fahrenheit)¶

Convert fahrenheit to celsius.

Parameters:: fahrenheit (number) – temperature in fahrenheit

st.utils.fvalues.fvalues(t)¶

Table iterator for traversal by forward-sorted values.

Parameters:: t (table) – over which to iterate

st.utils.generate_uuid_v4.generate_uuid_v4()¶: Generate a version 4 uuid as a string

st.utils.get_print_safe_string.get_print_safe_string(str)¶

Print binary string as ascii hex

Parameters:: str (str) – string data to print safely

st.utils.hsl_to_rgb.hsl_to_rgb(hue, saturation, lightness)¶

Convert from Hue/Saturation/Lightness to Red/Green/Blue

Parameters:

hue (number) – hue in the range [0,100]%
saturation (number) – saturation in the range [0,100]%
lightness (number or nil) – lightness in the range [0,100]%, default 50

st.utils.hsv_to_rgb.hsv_to_rgb(hue, saturation)¶

Converts Hue/Saturation to Red/Green/Blue

Parameters:

hue (number) – hue in range [0,1]
saturation (number) – saturation in range[0,1]

st.utils.lazy_handler.lazy_handler(require_str, require_prefix)¶

Lazily require and execute a function

Parameters:

require_str (str) – require string to require
require_prefix (str or nil) – prefix to prepend to the require_str

class st.utils.lazy_require¶

This module allows one to lazily load a named module. It’s a drop in replacement for require.

For example, to load some module, “st.my_module”, replace local my_module = require "st.my_module" with local my_module = lazy_require "st.my_module".

Then, the module will only be loaded in when it is either indexed (like my_module.hello), called (like my_module("howdy")), or participates in field assignment (like my_module["hi"] = 123).

After the module is either indexed or called, there will no longer be any string references to the module, so it will be GC’d if the package.loaded table is in "v" mode, which is the case for us at the time of writing.

On the other hand, after field assignment, the module will be cached so that it cannot be GC’d immediately after.

To always cache after the first index or call, append { caching = true } to the construction of the lazy_require. For example, local my_module = lazy_require("st.my_module", { caching = true })

Returned lazy_require also have a member function load which can be used to manually load the module. You can call it like my_module:load(). It is hidden from EmmyLua annotations due to limitations of the language server.

Creation of a new lazy_require with the same name as an existing instance will return the existing table. Consequently, lazy_require can be used as keys in tables. However, this also means that creating a lazy_require with caching enabled will elevate all instances of that lazy_require to use caching.

class st.utils.lazy_loader.lazy_loader¶

This class wraps a module so that it can be lazily loaded at the time of indexing

prefix: str¶: the path prefix for loaded modules

caching: boolean¶: determines whether returned lazy_require will use caching.

new(options)¶

Parameters:: options (table) – { prefix: string, caching: boolean? }
Return type:: lazy_loader

st.utils.log_func_wrapper.log_func_wrapper(func, func_name, log_level)¶

Wrap a function that will log all calls to the function along with the arguments.

Parameters:

func (function) – the function to be wrapped
func_name (str) – the name of the function to include in the logs
log_level (str) – the level you want the function logging to print at, defaults to LOG_LEVEL_DEBUG

st.utils.merge.merge(target_table, template)¶

Recursively merge all fields of template not already present in target_table.

Parameters:

target_table (table) – table into which to merge template
template (table) – table to merge into target_table

st.utils.mole_per_cubic_meter_to_ppm.mole_per_cubic_meter_to_ppm(value)¶

Convert a gas concentration given in moles per cubic meter [mol/m3] to value in part per million [ppm]

Parameters:: value (number) – Concentration of gas [mol/m3]

st.utils.pairs_by_key.pairs_by_key(t, f)¶

Table iterator for traversal by ordered keys.

Parameters:

t (table) – over which to iterate
f (function) – optional key comparison function

st.utils.pairs_by_value.pairs_by_value(t, f)¶

Table iterator for traversal by ordered values.

Parameters:

t (table) – over which to iterate
f (value) – required value comparison function

st.utils.pascal_case.pascal_case(str)¶

Convert the passed string to PascalCase.

Parameters:: str (str) – string to convert

st.utils.rgb_to_hsl.rgb_to_hsl(red, green, blue)¶

Convert from red, green, blue to hue, saturation, lightness.

Parameters:

red (number) – red component in the range [0,255]
green (number) – green component in the range [0,255]
blue (number) – blue component in the range [0,255]

st.utils.rgb_to_xy.rgb_to_xy(red, green, blue)¶

Convert from Red/Green/Blue to x/y/Y

Parameters:

red (number) – red in range [0,1]
green (number) – green in range [0,1]
blue (number) – blue in range [0,1]

st.utils.rkeys.rkeys(t)¶

Table iterator for traversal by reverse-sorted keys.

Parameters:: t (table) – over which to iterate

st.utils.round.round(val)¶

Round a number to the nearest integer (.5 rounds up)

Parameters:: val (number) – the value to be rounded

st.utils.rsort.rsort(tbl)¶

Reverse-sort the passed table.

Parameters:: tbl (table) – (in/out) table to be reverse sorted

st.utils.rvalues.rvalues(t)¶

Table iterator for traversal by reverse-sorted values.

Parameters:: t (table) – over which to iterate

st.utils.safe_hsv_to_xy.safe_hsv_to_xy(hue, saturation)¶

Safe convert from Hue/Saturation to x/y/Y

Parameters:

hue (number or nil) – red in range [0,100]%; default 0
saturation (number or nil) – green in range [0,100]%; default 0

st.utils.safe_xy_to_hsv.safe_xy_to_hsv(x, y, Y)¶

Convert from x/y/Y to Hue/Saturation

Parameters:

x (number or nil) – red in range [0x0000, 0xFFFF], default 0
y (number or nil) – green in range [0x0000, 0xFFFF], default 0
Y (number or nil) – blue in range [0x0000, 0xFFFF], default 1

st.utils.screaming_snake_case.screaming_snake_case(str)¶

Convert the passed string to SCREAMING_SNAKE_CASE.

Parameters:: str (str) – string to convert

st.utils.serialize_int.serialize_int(value, width, signed, little_endian)¶

Serialize an integer into a bytestring.

Parameters:

value (number) – value to write
width (number) – integer width in bytes
signed (boolean) – true if signed, false if unsigned
little_endian (boolean) – true if little endian, false if big endian

st.utils.signed_to_unsigned.signed_to_unsigned(value, size)¶

Convert a value from a 2s complement signed integer to an unsigned integer

Parameters:

value (number) – the signed value
size (number) – the size of the value (in bytes)

st.utils.snake_case.snake_case(str)¶

Convert the passed string to snake_case.

Parameters:: str (str) – string to convert

st.utils.stringify_table.stringify_table(val, name, multi_line)¶

Convert value to string

Parameters:

val (table) – Value to stringify
name (str) – Print a name along with value [Optional]
multi_line (boolean) – use newlines to provide a more easily human readable string [Optional]

st.utils.table_size.table_size(t)¶

Return number of elements stored in a table

Parameters:: t (table) – The table which length needs to be calculated

st.utils.unsigned_to_signed.unsigned_to_signed(value, size)¶

Convert an unsigned integer into a 2s complement signed integer

Parameters:

value (number) – the unsigned integer value
size (number) – the size of the value (in bytes)

st.utils.update.update(target_table, template, set_nil)¶

Recursively update all fields of target_table that are common and present in template.

Parameters:

target_table (table) – table in which to update common fields from template
template (table) – table from which to update common fields in target_table
set_nil (boolean) – ? if true, template keys not present in target table will be added

st.utils.verify_type.verify_type(value, v_type, arg_name)¶

Throw an error if the provided value isn’t of the provided type

Parameters:

value (any) – The value to check the type of
v_type (str) – the expected value of type(value)
arg_name (str or nil) – If present, used in generated error message

st.utils.xy_to_rgb.xy_to_rgb(x, y, Y)¶

Convert from x/y/Y to Red/Green/Blue

Parameters:

x (number) – x axis non-negative value
y (number) – y axis non-negative value
Y (number) – Y tristimulus value