Implemented a variety of generalized rounding functions.

Author: adam-rumpf

README.md

@@ -27,15 +27,19 @@ The following is a brief description of the included functions, divided into rou
 A variety of scripts dealing with sequences, functions, and sets, which may have some uses for managing data structures. For example, the various pairing and inverse pairing functions can be used to store pairs of numbers as single numbers in data structures (like stacks and queues) and then recovered.
 
 * [`_base_to_decimal`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_base_to_decimal/_base_to_decimal.gml): Converts a number from an array of base-_b_ digits to decimal. The inverse of `_decimal_to_base`.
+* [`_ceil`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_ceil/_ceil.gml): Generalized ceiling function which accepts a step size argument.
 * [`_decimal_to_base`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_decimal_to_base/_decimal_to_base.gml): Converts a number from decimal to an array of base-_b_ digits. The inverse of `_base_to_decimal`.
 * [`_factorial`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_factorial/_factorial.gml): Calculates the factorial (_n!_) of a nonnegative integer.
+* [`_floor`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_floor/_floor.gml): Generalized floor function which accepts a step size argument.
+* [`_frac`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_frac/_frac.gml): Generalized fractional part function which accepts a step size argument.
 * [`_integer_pair_to_natural`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_integer_pair_to_natural/_integer_pair_to_natural.gml): Maps an ordered pair of integers to a unique natural number (by composing `_nautral_pair_to_natural` on `_integer_to_natural`). This is the inverse of `_natural_to_integer_pair`.
 * [`_integer_to_natural`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_integer_to_natural/_integer_to_natural.gml): Maps an integer to a unique natural number using the zig-zagging bijection from _(0, 1, -1, 2, -2, ...)_ to _(0, 1, 2, 3, 4, ...)_. This is the inverse of `_natural_to_integer`.
 * [`_k_tuples`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_k_tuples/_k_tuples.gml): Generates an array of all possible base-_b_ _k_-tuples, in ascending (or descending) order.
 * [`_natural_to_integer`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_natural_to_integer/_natural_to_integer.gml): Maps a natural number to a unique integer using the zig-zagging bijection from _(0, 1, 2, 3, 4, ...)_ to _(0, 1, -1, 2, -2, ...)_. This is the inverse of `_integer_to_natural`.
 * [`_natural_to_integer_pair`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_natural_to_integer_pair/_natural_to_integer_pair.gml): Maps a natural number to a unique ordered pair of integers (by composing `_nautral_to_integer` on `_natural_to_natural_pair`). This is the inverse of `_integer_pair_to_natural`.
 * [`_natural_to_natural_pair`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_natural_to_natural_pair/_natural_to_natural_pair.gml): Maps a natural number to a unique ordered pair of natural numbers using the [inverse Cantor pairing function](https://en.wikipedia.org/wiki/Pairing_function#Inverting_the_Cantor_pairing_function). This is the inverse of `_pair_to_natural`.
 * [`_natural_pair_to_natural`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_natural_pair_to_natural/_natural_pair_to_natural.gml): Maps an ordered pair of natural numbers to a unique natural number using the [Cantor pairing function](https://en.wikipedia.org/wiki/Pairing_function#Cantor_pairing_function). This is the inverse of `_natural_to_pair`.
+* [`_round`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_round/_round.gml): Generalized rounding function which accepts a step size argument.
 
 ## Array Functions
 
@@ -84,8 +88,9 @@ Common linear algebra algorithms for dealing with matrices and vectors. In all f
 
 Functions which involve randomization.
 
-* [`_random_weighted_index`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_random_weighted_index/_random_weighted_index.gml): Chooses a random array index with probabilities defined by a given weight array.
+* [`_random_round`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_random_round/_random_round.gml): Rounds a number either up or down to an integer value with a probability based on its fractional part.
 * [`_random_sample`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_random_sample/_random_sample.gml): Draws a set of random samples from an array, either with or without replacement.
+* [`_random_weighted_index`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_random_weighted_index/_random_weighted_index.gml): Chooses a random array index with probabilities defined by a given weight array.
 
 ## Cellular Automata Functions
 

scripts/_ceil/_ceil.gml

@@ -0,0 +1,18 @@
+/// @func _ceil(x[, step])
+/// @desc Rounds a number up to a multiple of a given step size. This generalizes the built-in ceil() function, which uses a step size of 1.
+/// @param {real} x - Number to round.
+/// @param {real} [step=1.0] - Step size to round to.
+/// @return {real} Least multiple of step which is greater than or equal to x.
+
+function _ceil(xx)
+{
+	// Get step size argument
+	var step = (argument_count > 1 ? argument[1] : 1.0);
+	
+	// Verify that step size is positive
+	if (step <= 0)
+		return undefined;
+	
+	// Subtract generalized fractional part from x and add one step
+	return xx - (xx mod step) + step;
+}

scripts/_floor/_floor.gml

@@ -0,0 +1,18 @@
+/// @func _floor(x[, step])
+/// @desc Rounds a number down to a multiple of a given step size. This generalizes the built-in floor() function, which uses a step size of 1.
+/// @param {real} x - Number to round.
+/// @param {real} [step=1.0] - Step size to round to.
+/// @return {real} Greatest multiple of step which is less than or equal to x.
+
+function _floor(xx)
+{
+	// Get step size argument
+	var step = (argument_count > 1 ? argument[1] : 1.0);
+	
+	// Verify that step size is positive
+	if (step <= 0)
+		return undefined;
+	
+	// Subtract generalized fractional part from x
+	return xx - (xx mod step);
+}

scripts/_frac/_frac.gml

@@ -0,0 +1,18 @@
+/// @func _frac(x[, step])
+/// @desc Finds the fractional part of a number above a multiple of a given step size. This generalizes the built-in frac() function, which uses a step size of 1.
+/// @param {real} x - Number to find the fractional part of.
+/// @param {real} [step=1.0] - Step size.
+/// @return {real} Amount by which x exceeds the greatest multiple of step that does not exceed x. Equivalent to x - _floor(x, step).
+
+function _frac(xx)
+{
+	// Get step size argument
+	var step = (argument_count > 1 ? argument[1] : 1.0);
+	
+	// Verify that step size is positive
+	if (step <= 0)
+		return undefined;
+	
+	// Find the generalized fractional part
+	return (xx mod step);
+}

scripts/_random_round/_random_round.gml

@@ -0,0 +1,24 @@
+/// @func _random_round(x[, step])
+/// @desc Randomly rounds a real up or down with a probability equal to the fractional part.
+/// @param {real} x - Number to be rounded.
+/// @param {real} [step=1.0] - Step size to round to.
+/// @return {int} Either ceil(x) or floor(x), with the probability of the ceiling being the fractional part of x.
+
+function _random_round(xx)
+{
+	// Get step size argument
+	var step = (argument_count > 1 ? argument[1] : 1.0);
+	
+	// Verify that step size is positive
+	if (step <= 0)
+		return undefined;
+	
+	// Get generalized fractional part of x
+	var fraction = (xx mod step);
+	
+	// Decide random return value based on fractional part
+	if (random_range(0.0, 1.0) < fraction)
+		return xx - (xx mod step) + step; // round up with probability equal to fractional part
+	else
+		return xx - (xx mod step); // otherwise round down
+}

scripts/_round/_round.gml

@@ -0,0 +1,40 @@
+/// @func _round(x[, step[, down]])
+/// @desc Rounds a number to the nearest multiple of a given step size. This generalizes the built-in round() function, which uses a step size of 1.
+/// @param {real} x - Number to round.
+/// @param {real} [step=1.0] - Step size to round to.
+/// @param {bool} [down=true] - Whether to round down in case of a tie. If false, rounds up instead.
+/// @return {real} Nearest multiple of step to x.
+
+function _round(xx)
+{
+	// Get step size and direction arguments
+	var step = (argument_count > 1 ? argument[1] : 1.0);
+	var down = (argument_count > 2 ? argument[2] : true);
+	
+	// Verify that step size is positive
+	if (step <= 0)
+		return undefined;
+	
+	// Get normalized distance between consecutive multiples of the step
+	var dist = (xx mod step)/step;
+	
+	// Use distance to decide rounding direction
+	if (dist < 0.5)
+	{
+		// Round down if less than half
+		return xx - (xx mod step);
+	}
+	else if (dist > 0.5)
+	{
+		// Round up if more than half
+		return xx - (xx mod step) + step;
+	}
+	else
+	{
+		// Break ties based on direction argument
+		if (down == true)
+			return xx - (xx mod step);
+		else
+			return xx - (xx mod step) + step;
+	}
+}