Utils

Limits the absolute value of a number between two positive numbers, then sets it to its original sign.

@param value — The value to limit.

@param min — The minimum bound. If the absolute value of the specified value is less than this number, it is set to it.

@param max — The maximum bound. If the absolute value of the specified value is greater than this number, it is set to it.

@return result — The new limited number.

Returns the number further from zero.

@param a — The first number to compare.

@param b — The second number to compare.

@return result — The specified number that was further from zero than the other.

Returns the number closer to zero.

@param a — The first number to compare.

@param b — The second number to compare.

@return result — The specified number that was closer to zero than the other.

TODO: this function is a mess please comment it later

@param prefix — base directory of images in the mod

@param image — raw image path specified by tileset/map

@param path — path of tileset/map, image is relative to this

@return final_path — nil in case of error

Returns whether every value in a table is true, iterating numerically.

@param tbl — The table to iterate through.

@param func — If provided, each value of the table will instead be passed into the function, whose returned value will be considered instead of the table value itself.

@return result — Whether every value was true or not.

Returns the angle from one point to another, or from one object's position to another's.

@param x1 — The horizontal position of the first point.

@param y1 — The vertical position of the first point.

@param x2 — The horizontal position of the second point.

@param y2 — The vertical position of the second point.

@return angle — The angle from the first point to the second point.

Returns the distance between two angles, properly accounting for wrapping around.

@param a — The first angle to compare.

@param b — The second angle to compare.

@return diff — The difference between the two angles.

Returns whether any individual value in a table is true, iterating numerically.

@param tbl — The table to iterate through.

@param func — If provided, each value of the table will instead be passed into the function, whose returned value will be considered instead of the table value itself.

@return result — Whether any value was true or not.

Moves the specified value towards a target value by a specified amount, without exceeding the target.
If the target is less than the value, then the amount will be subtracted from the value instead to approach it.

@param val — The initial value.

@param target — The target value to approach.

@param amount — The amount the initial value should approach the target by.

@return result — The new value. If the value would have passed the target value, it will instead be set to the target.

Moves the specified angle towards a target angle by a specified amount, properly accounting for wrapping around.
Will always approach in the direction with the shorter distance.

@param val — The initial angle.

@param target — The target angle to approach.

@param amount — The amount the initial angle should approach the target by.

@return result — The new angle. If the angle would have passed the target angle, it will instead be set to the target.

Returns whether a value is between two numbers.

@param val — The value to compare.

@param a — The start value of the range.

@param b — The end value of the range.

@param include — Determines whether the function should consider being equal to a range value to be "between". (Defaults to false)

@return result — Whether the value was within the range.

Rounds the specified value up to the nearest integer.

@param value — The value to round.

@param to — If specified, the value will instead be rounded up to the nearest multiple of this number.

@return result — The rounded value.

Limits the specified value to be between 2 bounds, setting it to be the respective bound if it exceeds it.

@param val — The value to limit.

@param min — The minimum bound. If the value is less than this number, it is set to it.

@param max — The maximum bound. If the value is greater than this number, it is set to it.

@return result — The new limited number.

Maps a value between a specified range to its equivalent position in a new range.

@param val — The initial value in the initial range.

@param min_a — The start value of the initial range.

@param max_a — The end value of the initial range.

@param min_b — The start value of the new range.

@param max_b — The end value of the new range.

@param mode — If specified, the value's new position will be eased into the new range based on the percentage of its position in its initial range.

@return result — The value within the new range.

mode:
    | "linear"
    | "in-quad"
    | "in-cubic"
    | "in-quart"
    | "in-quint"
    | "in-sine"
    | "in-expo"
    | "in-circ"
    | "in-back"
    | "in-bounce"
    | "in-elastic"
    | "out-quad"
    | "out-cubic"
    | "out-quart"
    | "out-quint"
    | "out-sine"
    | "out-expo"
    | "out-circ"
    | "out-back"
    | "out-bounce"
    | "out-elastic"
    | "in-out-quad"
    | "in-out-cubic"
    | "in-out-quart"
    | "in-out-quint"
    | "in-out-sine"
    | "in-out-expo"
    | "in-out-circ"
    | "in-out-back"
    | "in-out-bounce"
    | "in-out-elastic"
    | "inQuad"
    | "outQuad"
    | "inOutQuad"
    | "outInQuad"
    | "inCubic"
    | "outCubic"
    | "inOutCubic"
    | "outInCubic"
    | "inQuart"
    | "outQuart"
    | "inOutQuart"
    | "outInQuart"
    | "inQuint"
    | "outQuint"
    | "inOutQuint"
    | "outInQuint"
    | "inSine"
    | "outSine"
    | "inOutSine"
    | "outInSine"
    | "inExpo"
    | "outExpo"
    | "inOutExpo"
    | "outInExpo"
    | "inCirc"
    | "outCirc"
    | "inOutCirc"
    | "outInCirc"
    | "inElastic"
    | "outElastic"
    | "inOutElastic"
    | "outInElastic"
    | "inBack"
    | "outBack"
    | "inOutBack"
    | "outInBack"
    | "inBounce"
    | "outBounce"
    | "inOutBounce"
    | "outInBounce"

Limits the specified value to be between 2 bounds, wrapping around if it exceeds it.

@param val — The value to wrap.

@param min — The minimum bound. If not specified, defaults to 1 for array wrapping.

@param max — The maximum bound.

@return result — The new wrapped number.

Empties a table of all defined values.

@param tbl — The table to clear.

Creates a Collider based on a Tiled object shape.

@param parent — The object that the new Collider should be parented to.

@param data — The Tiled shape data.

@param x — An optional value defining the horizontal position of the collider.

@param y — An optional value defining the vertical position of the collider.

@param properties — A table defining additional properties for the collider.

@return collider — The new Collider instance.

Returns whether a string contains a given substring.
Note: This function uses find, so special characters must be escaped with a %.

@param str — The string to check.

@param filter — The substring that the string may contain.

@return result — Whether the string contained the specified substring.

Whether the table contains the specified value.

@param tbl — The table to check the value from.

@param val — The value to check.

@return result — Whether the table contains the specified value.

Makes a new copy of a table, giving it all of the same values.

@param tbl — The table to copy.

@param deep — Whether tables inside the specified table should be copied as well.

@param seen — (Used internally) A table of values used to keep track of which objects have been cloned.

@return new — The new table.

Copies the values of one table into a different one.

@param new_tbl — The table receiving the copied values.

@param tbl — The table to copy values from.

@param deep — Whether tables inside the specified table should be copied as well.

@param seen — (Used internally) A table of values used to keep track of which objects have been cloned.

Returns the distance between two points.

@param x1 — The horizontal position of the first point.

@param y1 — The vertical position of the first point.

@param x2 — The horizontal position of the second point.

@param y2 — The vertical position of the second point.

@return dist — The linear distance from the first point to the second point.

Returns a string converting a table value into readable text. Useful for debugging table values.

@param o — The value to convert to a string.

@return result — The newly generated string.

Returns a value eased between two numbers, determined by a percentage from 0 to 1.

@param a — The start value of the range.

@param b — The end value of the range.

@param t — The percentage (from 0 to 1) that determines the point on the specified range.

@param mode — The ease type to use between the two values. (Refer to https://easings.net/)

mode:
    | "linear"
    | "in-quad"
    | "in-cubic"
    | "in-quart"
    | "in-quint"
    | "in-sine"
    | "in-expo"
    | "in-circ"
    | "in-back"
    | "in-bounce"
    | "in-elastic"
    | "out-quad"
    | "out-cubic"
    | "out-quart"
    | "out-quint"
    | "out-sine"
    | "out-expo"
    | "out-circ"
    | "out-back"
    | "out-bounce"
    | "out-elastic"
    | "in-out-quad"
    | "in-out-cubic"
    | "in-out-quart"
    | "in-out-quint"
    | "in-out-sine"
    | "in-out-expo"
    | "in-out-circ"
    | "in-out-back"
    | "in-out-bounce"
    | "in-out-elastic"
    | "inQuad"
    | "outQuad"
    | "inOutQuad"
    | "outInQuad"
    | "inCubic"
    | "outCubic"
    | "inOutCubic"
    | "outInCubic"
    | "inQuart"
    | "outQuart"
    | "inOutQuart"
    | "outInQuart"
    | "inQuint"
    | "outQuint"
    | "inOutQuint"
    | "outInQuint"
    | "inSine"
    | "outSine"
    | "inOutSine"
    | "outInSine"
    | "inExpo"
    | "outExpo"
    | "inOutExpo"
    | "outInExpo"
    | "inCirc"
    | "outCirc"
    | "inOutCirc"
    | "outInCirc"
    | "inElastic"
    | "outElastic"
    | "inOutElastic"
    | "outInElastic"
    | "inBack"
    | "outBack"
    | "inOutBack"
    | "outInBack"
    | "inBounce"
    | "outBounce"
    | "inOutBounce"
    | "outInBounce"

Returns whether a string ends with the specified substring, or a table ends with the specified series of values.
The function will also return a second value, created by copying the inital value and removing the suffix.

@param value — The value to check the end of.

@param suffix — The prefix that should be checked.

@return success — Whether the value ended with the specified suffix.

@return rest — A new value created by removing the suffix substring or values from the initial value. If the result was unsuccessful, this value will simply be the initial unedited value.

Returns whether two tables have an equivalent set of values.

@param a — The first table to compare.

@param b — The second table to compare.

@param deep — Whether table values within these tables should also be compared using Utils.equal().

@return success — Whether the sets of values for the two tables were equivalent.

Returns a facing direction nearest to the specified angle.

@param angle — The angle to convert.

@return direction — The facing direction the specified angle is closest to.

direction:
    | "right"
    | "down"
    | "left"
    | "up"

Returns a new table containing only values that a function returns true for.

@param tbl — An array of values.

@param filter — A function that should return true for all values in the table to keep, and false for values to discard.

@return result — A new array containing only approved values.

Removes values from a table if a function does not return true for them.

@param tbl — An array of values.

@param filter — A function that should return true for all values in the table to keep, and false for values to discard.

Merges a list of tables containing values into a single table containing each table's contents.

@param tbl — The array of tables to merge.

@param deep — If true, tables contained inside listed tables will also be merged.

@return result — The new table containing all values.

Flips the values of a 2-dimensional array, such that its columns become its rows, and vice versa.
As an example, the following table:

{
    {1, 2},
    {3, 4},
}

would result in this when passed into the function:

{
    {1, 3},
    {2, 4},
}

@param tbl — The table array to flip the values of.

@return result — The new flipped array.

Rounds the specified value down to the nearest integer.

@param value — The value to round.

@param to — If specified, the value will instead be rounded down to the nearest multiple of this number.

@return result — The rounded value.

This function substitutes values from a table into a string using placeholders in the form of {key} or {}, where the latter indexes the table by number.

@param str — The string to substitute values into.

@param tbl — The table containing the values to substitute.

@return result — The formatted string.

Returns the value found for a string index, ignoring case-sensitivity.

@param t — The table to get the value from.

@param key — The index to check within the table.

@return value — The value found at the specified index, or nil if no similar index was found.

Returns the name of a given class, using the name of the global variable for the class.
If it cannot find a global variable associated with the class, it will instead return the name of the class it extends, along with the class's ID.

@param class — The class instance to check.

@param parent_check — Whether the function should only return the extended class, and not attach the class's ID, if the class does not have a global name.

@return name — The name of the class, or nil if it cannot find one.

Concatenates exclusively string values within a table.

@param text — The table of values to combine.

@return result — The concatenated string.

See: https //stackoverflow.com/a/12191225

Returns two numbers defining a vector based on the specified direction.

@param facing — The facing direction to get the vector of.

@return x — The horizontal factor of the specified direction.

@return y — The vertical factor of the specified direction.

facing:
    | "right"
    | "down"
    | "left"
    | "up"

Returns a table of file names within the specified directory, checking subfolders as well.

@param dir — The file path to check, relative to the LÖVE Kristal directory.

@param ext — If specified, only files with the specified extension will be returned, and the extension will be stripped. (eg. "png" will only return .png files)

@return result — The table of file names.

Returns the position of a specified value found within an array.

@param t — The array to get the position from.

@param value — The value to find the position of.

@return position — The position found for the specified value.

Returns the non-numerical key of a specified value found within a table.

@param t — The table to get the key from.

@param value — The value to find the key of.

@return key — The key found for the specified value.

Returns a list of every key in a table.

@param t — The table to get the keys from.

@return result — An array of each key in the table.

Returns the point at which two lines intersect.

@param l1p1x — The horizontal position of the first point for the first line.

@param l1p1y — The vertical position of the first point for the first line.

@param l1p2x — The horizontal position of the second point for the first line.

@param l1p2y — The vertical position of the second point for the first line.

@param l2p1x — The horizontal position of the first point for the second line.

@param l2p1y — The vertical position of the first point for the second line.

@param l2p2x — The horizontal position of the second point for the second line.

@param l2p2y — The vertical position of the second point for the second line.

@param seg1 — If true, the first line will be treated as a line segment instead of an infinite line.

@param seg2 — If true, the second line will be treated as a line segment instead of an infinite line.

@return x — If the lines intersected, this will be the horizontal position of the intersection; otherwise, this value will be false.

@return y — If the lines intersected, this will be the vertical position of the intersection; otherwise, this will be a string describing why the lines did not intersect.

y:
    | "The lines are parallel."
    | "The lines don't intersect."

Returns a point at a certain distance along a path.

@param path — An array of tables with X and Y values each, defining the coordinates of each point on the path.

@param t — The distance along the path that the point should be at.

@return x — The horizontal position of the point found on the path.

@return y — The vertical position of the point found on the path.

Returns the bounds of a rectangle containing every point of a polygon.

@param points — An array of tables with two number values each, defining the points of a polygon.

@return x — The horizontal position of the bounds.

@return y — The vertical position of the bounds.

@return width — The width of the bounds.

@return height — The height of the bounds.

Returns a table of line segments based on a set of polygon points.

@param points — An array of tables with two number values each, defining the points of a polygon.

@return edges — An array of tables containing four values each, defining line segments describing the edges of a polygon.

Returns a new polygon with points offset outwards by a certain distance.

@param points — An array of tables with two number values each, defining the points of a polygon.

@param dist — The distance to offset the points by. If this value is negative, the points will be offset inwards.

@return A — new polygon array.

Creates a table grouping values of a table into a series of tables.

@param tbl — The table to group values from.

@param count — The amount of values that should belong in each group. If the table does not divide evenly, the final group of the returned table will be incomplete.

@return result — The table containing the grouped values.

Converts a hex color string to an RGBA color table.

@param hex — The string to convert to RGB. The string must be formatted with a # at the start, eg. "#ff00ff".

@param value — An optional number specifying the alpha the returned table should have.

@return rgba — The converted RGBA table.

Source: https://github.com/s-walrus/hex2color

Replaces a function within a class with a new function.
Also allows calling the original function, allowing you to add code to the beginning or end of existing functions.
Utils.hook() should always be called in Mod:init(). An example of how to hook a function is as follows:

-- this code will hook 'Object:setPosition(x, y)', and will be run whenever that function is called
-- all class functions receive the object instance as the first argument. in this function, i name that argument 'obj', and it refers to whichever object is calling 'setPosition()'
Utils.hook(Object, "setPosition", function(orig, obj, x, y)
    -- calls the original code (setting its position as normal)
    orig(obj, x, y)
    
    -- sets 'new_x' and 'new_y' variables for the object instance
    obj.new_x = x
    obj.new_y = y
end)

@param target — The class variable containing the function you want to hook.

@param name — The name of the function to hook.

@param hook — The function containing the new code to replace the old code with. Receives the original function as an argument, followed by the arguments the original function receives.

@param exact_func — (Used internally) Whether the function should be replaced exactly, or whether it should be replaced with a function that calls the hook function. Should not be specified by users.

@param include — The class to extend from. If passed as a string, will be looked up from the current registry (e.g. scripts/data/actors if creating an actor) or the global namespace.

@return class — The new class, extended from include if provided.

@return super — Allows calling methods from the base class. self must be passed as the first argument to each method.

Converts HSL values to RGB values. Both HSL and RGB should be values between 0 and 1.

@param h — The hue value of the HSL color.

@param s — The saturation value of the HSL color.

@param l — The lightness value of the HSL color.

@return r — The red value of the converted color.

@return g — The green value of the converted color.

@return b — The blue value of the converted color.

Source: https://github.com/Wavalab/rgb-hsl-rgb

Converts HSV values to RGB values. Both HSV and RGB should be values between 0 and 1.

@param h — The hue value of the HSV color.

@param s — The saturation value of the HSV color.

@param v — The 'value' value of the HSV color.

@return r — The red value of the converted color.

@return g — The green value of the converted color.

@return b — The blue value of the converted color.

Source: https://love2d.org/wiki/HSV_color

Returns whether a table contains exclusively numerical indexes.

@param tbl — The table to check.

@return result — Whether the table contains only numerical indexes or not.

Returns whether the specified angle is considered to be in the specified direction.

@param facing — The facing direction to compare.

@param angle — The angle to compare.

@return result — Whether the angle is closest to the specified facing direction.

facing:
    | "right"
    | "down"
    | "left"
    | "up"

Checks if the value is NaN (Not a Number)

Determines whether a polygon's points are clockwise or counterclockwise.

@param points — An array of tables with two number values each, defining the points of a polygon.

@return result — Whether the polygon is clockwise or not.

Iterates through the fields of a class (e.g. pairs) excluding special class variables and functions

Returns a non-numerical index based on its position in a pairs() iterator.

@param t — The table to get the index from.

@param number — The numerical position the index will be at.

@return index — The index found at the specified position.

Returns the length of a UTF-8 string, erroring if it's invalid.

Returns a value between two numbers, determined by a percentage from 0 to 1.
If given a table, it will lerp between each value in the table.

@param a — The start value of the range.

@param b — The end value of the range.

@param t — The percentage (from 0 to 1) that determines the point on the specified range.

@param oob — If true, then the percentage can be values beyond the range of 0 to 1.

@return result — The new value from the range.

Lerps between two coordinates.

@param x1 — The horizontal position of the first point.

@param y1 — The vertical position of the first point.

@param x2 — The horizontal position of the second point.

@param y2 — The vertical position of the second point.

@param t — The percentage (from 0 to 1) that determines the new point on the specified range between the specified points.

@param oob — If true, then the percentage can be values beyond the range of 0 to 1.

@return new_x — The horizontal position of the new point.

@return new_y — The vertical position of the new point.

Merges the values of one table into another one.

@param tbl — The table to merge values into.

@param other — The table to copy values from.

@param deep — Whether shared table values between the two tables should also be merged.

@return tbl — The initial table, now containing new values.

Merges two colors based on a percentage between 0 and 1.

@param start_color — The first table of RGBA values to merge.

@param end_color — The second table of RGBA values to merge.

@param amount — A percentage (from 0 to 1) that determines how much of the second color to merge into the first.

@return result_color — A new table of RGBA values.

Merges a list of tables into a new table.

@param ... — The list of tables to merge values from.

@return result — A new table containing the values of the series of tables provided.

Returns a number based on the position of a specified key in a pairs() iterator.

@param t — The table to get the position from.

@param name — The key to find the position of.

@return position — The numerical position of the specified index.

Equivalent of the next function, but returns the keys in the alphabetic order. We use a temporary ordered key table that is stored in the table being iterated. See: http //lua-users.org/wiki/SortedIteration

Equivalent of the pairs() function on tables. Allows to iterate in order

@param t — The table to iterate See: http //lua-users.org/wiki/SortedIteration

Returns a function that calls a new function, giving it an older function as an argument.
Essentially, it's a version of Utils.hook() that works with local functions.

@param old_func — The function to be passed into the new function.

@param new_func — The new function that will be called by the result function.

@return result_func — A function that will call the new function, providing the original function as an argument, followed by any other arguments that this function receives.

Returns a string with a specified length, filling it with empty spaces by default. Used to make strings consistent lengths for UI.
If the specified string has a length greater than the desired length, it will not be adjusted.

@param str — The string to extend.

@param len — The amount of characters the returned string should be.

@param beginning — If true, the beginning of the string will be filled instead of the end.

@param with — If specified, the string will be filled with this specified string, instead of with spaces.

@return result — The new padded result.

Converts a Tiled color property to an RGBA color table.

@param property — The property string to convert.

@return rgba — The converted RGBA table.

Returns a series of values used to determine the behavior of a flag property for a Tiled event.

@param flag — The name of the flag property.

@param inverted — The name of the property used to determine if the flag should be inverted.

@param value — The name of the property used to determine what the flag's value should be compared to.

@param default_value — If a property for the value name is not found, the value will be this instead.

@param properties — The properties table of a Tiled event's data.

@return flag — The name of the flag to check.

@return inverted — Whether the result of the check should be inverted.

@return value — The value that the flag should be compared to.

Returns a table with values based on Tiled properties.
The function will check for a series of numbered properties starting with the specified id string, eg. "id1", followed by "id2", etc.

@param id — The name the series of properties should all start with.

@param properties — The properties table of a Tiled event's data.

@return result — The list of property values found.

Returns an array of tables with values based on Tiled properties.
The function will check for a series of layered numbered properties started with the specified id string, eg. "id1_1", followed by "id1_2", "id2_1", "id2_2", etc.

The returned table will contain a list of tables correlating to each individual list.
For example, the first table in the returned array will contain the values for "id1_1" and "id1_2", the second table will contain "id2_1" and "id2_2", etc.

@param id — The name the series of properties should all start with.

@param properties — The properties table of a Tiled event's data.

@return result — The list of property values found.

Returns the actual GID and flip flags of a tile.

@param id — The GID of the tile.

@return gid — The GID of the tile without the flags.

@return flip_x — Whether the tile should be flipped horizontally.

@return flip_y — Whether the tile should be flipped vertically.

@return flip_diag — Whether the tile should be flipped diagonally.

Returns a random value from an array.

@param tbl — An array of values.

@param sort — If specified, the table will be sorted via Utils.filter(tbl, sort) before selecting a value.

@param remove — If true, the selected value will be removed from the given table.

@return result — The randomly selected value.

Returns multiple random values from an array, not selecting any value more than once.

@param tbl — An array of values.

@param amount — The amount of values to select from the table.

@param sort — If specified, the table will be sorted via Utils.filter(tbl, sort) before selecting a value.

@return result — A table containing the randomly selected values.

Returns a randomly generated decimal value.
If no arguments are provided, the value is between 0 and 1.
If a is provided, the value is between 0 and a.
If a and b are provided, the value is between a and b.
If c is provided, the value is between a and b, rounded to the nearest multiple of c.

@param a — The first argument.

@param b — The second argument.

@param c — The third argument.

@return rng — The new random value.

Returns a table of 2 numbers, defining a vector in a random cardinal direction. (eg. {0, -1})

@return vector — The vector table.

Returns the coordinates a random point along the border of the specified rectangle.

@param x — The horizontal position of the topleft of the rectangle.

@param y — The vertical position of the topleft of the rectangle.

@param w — The width of the rectangle.

@param h — The height of the rectangle.

@return x — The horizontal position of a random point on the rectangle border.

@return y — The vertical position of a random point on the rectangle border.

Returns either -1 or 1.

@return sign — The new random sign.

Remove duplicate elements from a table.

@param tbl — The table to remove duplicates from.

@param deep — Whether tables inside the tbl will also have their duplicates removed.

@return result — The new table that has its duplicates removed.

Removes the specified value from the table.

@param tbl — The table to remove the value from.

@param val — The value to be removed from the table.

@return val — The now removed value.

Returns a table containing the values of an array in reverse order.

@param tbl — An array of values.

@param group — If defined, the values will be grouped into sets of the specified size, and those sets will be reversed.

@return result — The new table containing the values of the specified array.

Converts a table of RGB values to a hex color string.

@param rgb — The RGB table to convert. Values should be between 0 and 1.

@return hex — The converted hex string. Formatted with a # at the start, eg. "#ff00ff".

Converts RGB values to HSL values. Both RGB and HSL should be values between 0 and 1.

@param r — The red value of the RGB color.

@param g — The green value of the RGB color.

@param b — The blue value of the RGB color.

@return h — The hue value of the converted color.

@return s — The saturation value of the converted color.

@return l — The lightness value of the converted color.

Source: https://github.com/Wavalab/rgb-hsl-rgb

Rotates the values of a 2-dimensional array.
As an example, the following table:

{
    {1, 2},
    {3, 4},
}

would result in this when passed into the function, rotating it clockwise:

{
    {3, 1},
    {4, 2},
}

@param tbl — The table array to rotate the values of.

@param ccw — Whether the rotation should be counterclockwise.

@return result — The new rotated array.

Returns whether two numbers are roughly equal (less than 0.01 away from each other).

@param a — The first value to compare.

@param b — The second value to compare.

@return result — Whether the two values are roughly equal.

Rounds the specified value to the nearest integer.

@param value — The value to round.

@param to — If specified, the value will instead be rounded to the nearest multiple of this number.

@return result — The rounded value.

Rounds the specified value to the nearest integer away from zero.

@param value — The value to round.

@return result — The rounded value.

Rounds the specified value to the nearest integer towards zero.

@param value — The value to round.

@return result — The rounded value.

Returns a table containing the values of another table, randomly rearranged.

@param tbl — An array of values.

@return result — The new randomly shuffled array.

Returns the polarity of the specified value: -1 if it's negative, 1 if it's positive, and 0 otherwise.

@param num — The value to check.

@return sign — The sign of the value.

Splits a string into a new table of strings using a substring as a separator.
Less optimized than Utils.splitFast(), but allows separating with multiple characters, and is more likely to work for any string.

@param str — The string to separate.

@param sep — The substring used to split the main string.

@param remove_empty — Whether strings containing no characters shouldn't be included in the result table.

@return result — The table containing the new split strings.

Splits a string into a new table of strings using a single character as a separator.
More optimized than Utils.split(), at the cost of lacking features.
Note: This function uses gmatch, so special characters must be escaped with a %.

@param str — The string to separate.

@param sep — The character used to split the main string.

@return result — The table containing the new split strings.

Finds and returns the scale required to print str with the font font, such that it's width does not exceed max_width.
If a min_scale is specified, strings that would have to be squished smaller than it will instead have their remaining part truncated.
Returns the input string (truncated if necessary), and the scale to print it at.

@param str — The string to squish and truncate.

@param font — The font being used to print the string.

@param max_width — The maximum width the string should be able to take up.

@param def_scale — The default scale used to print the string. Defaults to 1.

@param min_scale — The minimum scale that the string can be squished to before being truncated.

@param trunc_affix — The affix added to the string during truncation. If false, does not add an affix. Defaults to ....

@return result — The truncated result. Returns the original string if it was not truncated.

@return scale — The scale the result string should be printed at to fit within the specified width.

trunc_affix:
    | false