Module cLib

Contains common methods for working with strings, numbers and tables.

##

Note that several classes in the cLib library invokes the LOG/TRACE statement - therefore, it is recommended that any cLib-powered tool includes this file

Functions

LOG (...) [Static] LOG statement - invokes cLib.log().
TRACE (...) [Static] Placeholder TRACE statement (include cDebug for the full-featured implementation)
log (...) [Static] Print important messages to the console (errors and warnings)
unpack_args (...) [Static] Turn varargs into a table
invoke_task (...) [Static] Call a class method or function and show/log results Note: currently with a maximum of 8 arguments can be passed (this is a convenience function after all...)
create_cvalue (t) [Static] Turn value descriptor into instance
match_table_key (t, key) Array/table methods
expand_table (t, k1, k2, k3, k4) [Static] Expand a multi-dimensional array with given keys
get_table_bounds (t) [Static] Find the highest/lowest numeric key (index) in a sparsely populated table
merge_tables (t1, t2) [Static] Merge two tables into one (recursive)
compact_table (t) [Static] Convert a sparsely populated table into a compact one
table_compare (t1, t2) [Static] Quick'n'dirty table compare (values in first level only)
scale_value (value, in_min, in_max, out_min, out_max) Number methods
string_to_percentage (str) [Static] Attempt to convert string to a number (strip percent sign)
average (...) [Static] Get average of supplied numbers
clamp_value (value, min_value, max_value) [Static] Clamp value - ensure value is within min/max
wrap_value (value, min_value, max_value) [Static] 'Wrap/rotate' value within specified range (with a range of 64-127, a value of 128 should output 65) TODO use % modulo to obtain offset
sign (x) [Static] Determine the sign of a number
inv_log_scale (ceiling, val) [Static] Inverse logarithmic scaling (exponential)
log_scale (ceiling, val) logarithmic scaling within a fixed space
is_whole_number (n) [Static] Check for whole number, using format()
note_to_hz (note) [Static] Convert between note/hertz
gcd (m, n) [Static] Greatest common divisor
lcm (m, n) [Static] Least common multiplier (2 args)
least_common (t) [Static] Find least common multiplier
round_value (num) [Static] Round value (from http://lua-users.org/wiki/SimpleRound)
float_compare (val1, val2, precision) [Static] Compare two numbers with variable precision
fraction (val) [Static] Return the fractional part of a number
get_hex_digits (val) [Static] Find number of hex digits needed to represent a number (e.g.
stringify_table (t, prefix, suffix) [Static] Take a table and convert into strings - useful e.g.
parse_str (str) [Static] Receives a string argument and turn it into a proper object or value
table_has_equal_values (t) Check if table values are all identical (useful e.g.
table_compare (t1, t2) Quick'n'dirty table compare, compares values (not keys)
table_count (t) Count table entries, including mixed types
serialize_object (obj) [Static] Try serializing a value or return "???" the result should be a valid, quotable string
serialize_table (t, max_depth, longstring) [Static] Serialize table into string, with some formatting options


Functions

LOG (...)
[Static] LOG statement - invokes cLib.log(). you can override this method with your own custom implementation

Parameters:

  • ... (vararg)
TRACE (...)
[Static] Placeholder TRACE statement (include cDebug for the full-featured implementation)

Parameters:

  • ... (vararg)
log (...)
[Static] Print important messages to the console (errors and warnings)

Parameters:

  • ... (vararg)
unpack_args (...)
[Static] Turn varargs into a table

Parameters:

  • ... (vararg)
invoke_task (...)
[Static] Call a class method or function and show/log results Note: currently with a maximum of 8 arguments can be passed (this is a convenience function after all...)

Parameters:

  • ... (vararg), [class+function or function] + argument(s)
create_cvalue (t)
[Static] Turn value descriptor into instance

Parameters:

  • t

Returns:

    cNumber or cValue
match_table_key (t, key)
Array/table methods [Static] Match item(s) in an associative array (provide key)

Parameters:

  • t (table)
  • key (string)

Returns:

    table
expand_table (t, k1, k2, k3, k4)
[Static] Expand a multi-dimensional array with given keys

Parameters:

  • t (table)
  • k1 (string)
  • k2 (string)
  • k3 (string)
  • k4 (string)

Returns:

    table
get_table_bounds (t)
[Static] Find the highest/lowest numeric key (index) in a sparsely populated table

Parameters:

  • t

Returns:

    lowest,highest
merge_tables (t1, t2)
[Static] Merge two tables into one (recursive)

Parameters:

  • t1 (table)
  • t2 (table)

Returns:

    table
compact_table (t)
[Static] Convert a sparsely populated table into a compact one

Parameters:

  • t (table)

Returns:

    table
table_compare (t1, t2)
[Static] Quick'n'dirty table compare (values in first level only)

Parameters:

  • t1 (table)
  • t2 (table)

Returns:

    boolean, true if identical
scale_value (value, in_min, in_max, out_min, out_max)
Number methods [Static] Scale value to a range within a range

Parameters:

  • value (number) the value we wish to scale
  • in_min (number)
  • in_max (number)
  • out_min (number)
  • out_max (number)

Returns:

    number
string_to_percentage (str)
[Static] Attempt to convert string to a number (strip percent sign)

Parameters:

  • str (string), e.g. "33.3%"

Returns:

    number or (TODO) nil if not able to convert
average (...)
[Static] Get average of supplied numbers

Parameters:

  • ...

Returns:

    number
clamp_value (value, min_value, max_value)
[Static] Clamp value - ensure value is within min/max

Parameters:

  • value (number)
  • min_value (number)
  • max_value (number)

Returns:

    number
wrap_value (value, min_value, max_value)
[Static] 'Wrap/rotate' value within specified range (with a range of 64-127, a value of 128 should output 65) TODO use % modulo to obtain offset

Parameters:

  • value
  • min_value
  • max_value
sign (x)
[Static] Determine the sign of a number

Parameters:

  • x

Returns:

    -1 if negative or 1 if positive
inv_log_scale (ceiling, val)
[Static] Inverse logarithmic scaling (exponential)

Parameters:

  • ceiling
  • val
log_scale (ceiling, val)
logarithmic scaling within a fixed space

Parameters:

  • ceiling (number) the upper boundary
  • val (number) the value to scale
is_whole_number (n)
[Static] Check for whole number, using format()

Parameters:

  • n
note_to_hz (note)
[Static] Convert between note/hertz

Parameters:

  • note
gcd (m, n)
[Static] Greatest common divisor

Parameters:

  • m
  • n
lcm (m, n)
[Static] Least common multiplier (2 args)

Parameters:

  • m
  • n
least_common (t)
[Static] Find least common multiplier

Parameters:

  • t (table), use values in table as argument
round_value (num)
[Static] Round value (from http://lua-users.org/wiki/SimpleRound)

Parameters:

  • num (number)
float_compare (val1, val2, precision)
[Static] Compare two numbers with variable precision

Parameters:

  • val1
  • val2
  • precision , '10000000' is suitable for parameter values

Returns:

    boolean
fraction (val)
[Static] Return the fractional part of a number

Parameters:

  • val

Returns:

    number
get_hex_digits (val)
[Static] Find number of hex digits needed to represent a number (e.g. 255 = 2)

Parameters:

  • val (int)

Returns:

    int
stringify_table (t, prefix, suffix)
[Static] Take a table and convert into strings - useful e.g. for viewbuilder popup (if table is associative, will use values)

Parameters:

  • t (table)
  • prefix (string) insert before each entry
  • suffix (string) insert after each entry

Returns:

    table
parse_str (str)
[Static] Receives a string argument and turn it into a proper object or value

Parameters:

  • str (string), e.g. "renoise.song().transport.keyboard_velocity"

Returns:

  1. value (can be nil)
  2. string, error message when failed
table_has_equal_values (t)
Check if table values are all identical (useful e.g. for detecting if a color is tinted)

Parameters:

  • t

Returns:

    boolean
table_compare (t1, t2)
Quick'n'dirty table compare, compares values (not keys)

Parameters:

  • t1
  • t2

Returns:

    boolean, true if identical
table_count (t)
Count table entries, including mixed types

Parameters:

  • t

Returns:

    int or nil
serialize_object (obj)
[Static] Try serializing a value or return "???" the result should be a valid, quotable string

Parameters:

  • obj , value or object

Returns:

    string
serialize_table (t, max_depth, longstring)
[Static] Serialize table into string, with some formatting options

Parameters:

  • t (table)
  • max_depth (int), determine how many levels to process - optional
  • longstring (boolean), use longstring format for multiline text

Returns:

    table
generated by LDoc 1.4.2