diff --git a/doc/index.html b/doc/index.html index 05ed79b..d57da27 100644 --- a/doc/index.html +++ b/doc/index.html @@ -41,6 +41,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • @@ -112,6 +113,11 @@ The DirectMapManipulator is similiar to the MapManipulator, except that it does not use the VoxelManip object, but the Minetest get_node/set_node functions. + + + random + Random is a static utility that provides fast and easy access to + random numbers. log diff --git a/doc/modules/arrayutil.html b/doc/modules/arrayutil.html index 2b79148..e542f2c 100644 --- a/doc/modules/arrayutil.html +++ b/doc/modules/arrayutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/blockedcache.html b/doc/modules/blockedcache.html index 6d4774c..2955d16 100644 --- a/doc/modules/blockedcache.html +++ b/doc/modules/blockedcache.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/blockutil.html b/doc/modules/blockutil.html index 5cadb44..a25721d 100644 --- a/doc/modules/blockutil.html +++ b/doc/modules/blockutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/color.html b/doc/modules/color.html index eaa9f9f..8f44b8a 100644 --- a/doc/modules/color.html +++ b/doc/modules/color.html @@ -49,6 +49,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/constants.html b/doc/modules/constants.html index 210918b..d3ecf1a 100644 --- a/doc/modules/constants.html +++ b/doc/modules/constants.html @@ -49,6 +49,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/directmapmanipulator.html b/doc/modules/directmapmanipulator.html index 9182c00..63ea5a2 100644 --- a/doc/modules/directmapmanipulator.html +++ b/doc/modules/directmapmanipulator.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/facedirutil.html b/doc/modules/facedirutil.html index 1943605..5fe4b9f 100644 --- a/doc/modules/facedirutil.html +++ b/doc/modules/facedirutil.html @@ -50,6 +50,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/fisheryates.html b/doc/modules/fisheryates.html index 7f1b83f..62dc7a1 100644 --- a/doc/modules/fisheryates.html +++ b/doc/modules/fisheryates.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/interpolate.html b/doc/modules/interpolate.html index 44d8259..49efbec 100644 --- a/doc/modules/interpolate.html +++ b/doc/modules/interpolate.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/inventoryutil.html b/doc/modules/inventoryutil.html index 9c7e8c8..349e788 100644 --- a/doc/modules/inventoryutil.html +++ b/doc/modules/inventoryutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/list.html b/doc/modules/list.html index a96667f..436bcd0 100644 --- a/doc/modules/list.html +++ b/doc/modules/list.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/log.html b/doc/modules/log.html index 0bdc8cd..60dbd3a 100644 --- a/doc/modules/log.html +++ b/doc/modules/log.html @@ -49,6 +49,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/mapmanipulator.html b/doc/modules/mapmanipulator.html index a98f934..478d226 100644 --- a/doc/modules/mapmanipulator.html +++ b/doc/modules/mapmanipulator.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/mathutil.html b/doc/modules/mathutil.html index f6bec01..0b077d1 100644 --- a/doc/modules/mathutil.html +++ b/doc/modules/mathutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/nodeutil.html b/doc/modules/nodeutil.html index 119432e..b428098 100644 --- a/doc/modules/nodeutil.html +++ b/doc/modules/nodeutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/noisemanager.html b/doc/modules/noisemanager.html index b6b636e..4e1cd8f 100644 --- a/doc/modules/noisemanager.html +++ b/doc/modules/noisemanager.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/pathutil.html b/doc/modules/pathutil.html index 33eca80..56f7127 100644 --- a/doc/modules/pathutil.html +++ b/doc/modules/pathutil.html @@ -49,6 +49,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/posutil.html b/doc/modules/posutil.html index ba4224b..debd0a9 100644 --- a/doc/modules/posutil.html +++ b/doc/modules/posutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/random.html b/doc/modules/random.html new file mode 100644 index 0000000..067bf18 --- /dev/null +++ b/doc/modules/random.html @@ -0,0 +1,282 @@ + + + + + utils + + + + +
    + +
    + +
    +
    +
    + + +
    + + + + + + +
    + +

    Module random

    +

    Random is a static utility that provides fast and easy access to + random numbers.

    +

    + + +

    Functions

    + + + + + + + + + + + + + + + + + +
    init ()Initializes random.
    next_bool (chance)Returns true or false based on the given chance.
    next_float (lower_bound, upper_bound, decimal_places)Returns a float between the given bounds.
    next_int (lower_bound, upper_bound)Returns an int between the given bounds.
    +

    Fields

    + + + + + + + + + + + + + +
    maxThe internal maximum value.
    minThe internal minimum value.
    random_providerThe provider for random numbers.
    + +
    +
    + + +

    Functions

    +
    +
    + + init () +
    +
    + Initializes random. Should not be called from the client. + + + + + + + +
    +
    + + next_bool (chance) +
    +
    + Returns true or false based on the given chance. + + +

    Parameters:

    +
      +
    • chance + Optional. The "one in chance" chance to get true, defaults + to 2 (ans in "one in two"). +
      • +
    + +

    Returns:

    +
      + + true or false based in the given chance. +
    + + + + +
    +
    + + next_float (lower_bound, upper_bound, decimal_places) +
    +
    + Returns a float between the given bounds. + + +

    Parameters:

    +
      +
    • lower_bound + Optional. The lower bound (inclusive), defaults to 0. +
      • +
    • upper_bound + Optional. The upper bound (exclusive), defaults to 1. +
      • +
    • decimal_places + Optional. To how many decimal places the resulting + float should be rounded. +
      • +
    + +

    Returns:

    +
      + + a float between the given bounds. +
    + + + + +
    +
    + + next_int (lower_bound, upper_bound) +
    +
    + Returns an int between the given bounds. + + +

    Parameters:

    +
      +
    • lower_bound + Optional. The lower bound (inclusive), defaults to + random.min. +
      • +
    • upper_bound + Optional. The upper bound (exclusive), defaults to + random.max. +
      • +
    + +

    Returns:

    +
      + + a integer between the given bounds. +
    + + + + +
    +
    +

    Fields

    +
    +
    + + max +
    +
    + The internal maximum value. + + + + + + + +
    +
    + + min +
    +
    + The internal minimum value. + + + + + + + +
    +
    + + random_provider +
    +
    + The provider for random numbers. + + + + + + + +
    +
    + + +
    +
    +
    +generated by LDoc 1.4.2 +
    +
    + + diff --git a/doc/modules/rotationutil.html b/doc/modules/rotationutil.html index 2233e78..121a992 100644 --- a/doc/modules/rotationutil.html +++ b/doc/modules/rotationutil.html @@ -49,6 +49,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/scheduler.html b/doc/modules/scheduler.html index b708cf9..cf2ff14 100644 --- a/doc/modules/scheduler.html +++ b/doc/modules/scheduler.html @@ -49,6 +49,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/settings.html b/doc/modules/settings.html index 4d97a09..4a7570f 100644 --- a/doc/modules/settings.html +++ b/doc/modules/settings.html @@ -49,6 +49,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/stopwatch.html b/doc/modules/stopwatch.html index 4d228e7..737751f 100644 --- a/doc/modules/stopwatch.html +++ b/doc/modules/stopwatch.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/stringutil.html b/doc/modules/stringutil.html index ef855fa..bb2228e 100644 --- a/doc/modules/stringutil.html +++ b/doc/modules/stringutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/tableutil.html b/doc/modules/tableutil.html index c5709cd..dc8f795 100644 --- a/doc/modules/tableutil.html +++ b/doc/modules/tableutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/tango.html b/doc/modules/tango.html index c43d0d2..f10deb1 100644 --- a/doc/modules/tango.html +++ b/doc/modules/tango.html @@ -44,6 +44,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/test.html b/doc/modules/test.html index 5f04d7a..861208f 100644 --- a/doc/modules/test.html +++ b/doc/modules/test.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/textureutil.html b/doc/modules/textureutil.html index 2256806..2af9410 100644 --- a/doc/modules/textureutil.html +++ b/doc/modules/textureutil.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/transform.html b/doc/modules/transform.html index 89df282..83a1cce 100644 --- a/doc/modules/transform.html +++ b/doc/modules/transform.html @@ -48,6 +48,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/doc/modules/wallmountedutil.html b/doc/modules/wallmountedutil.html index 6fb0e10..2841ceb 100644 --- a/doc/modules/wallmountedutil.html +++ b/doc/modules/wallmountedutil.html @@ -50,6 +50,7 @@
  • wallmountedutil
  • tango
  • directmapmanipulator
    • +
  • random
  • log
  • rotationutil
  • textureutil
    • diff --git a/mods/utils/init.lua b/mods/utils/init.lua index 091d08f..54deea8 100644 --- a/mods/utils/init.lua +++ b/mods/utils/init.lua @@ -49,6 +49,7 @@ dofile(base_path .. "/mathutil.lua") dofile(base_path .. "/nodeutil.lua") dofile(base_path .. "/pathutil.lua") dofile(base_path .. "/posutil.lua") +dofile(base_path .. "/random.lua") dofile(base_path .. "/rotationutil.lua") dofile(base_path .. "/scheduler.lua") dofile(base_path .. "/settings.lua") diff --git a/mods/utils/random.lua b/mods/utils/random.lua new file mode 100644 index 0000000..347d756 --- /dev/null +++ b/mods/utils/random.lua @@ -0,0 +1,113 @@ +--[[ +Copyright (c) 2015, Robert 'Bobby' Zenz +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +--]] + + +--- Random is a static utility that provides fast and easy access to +-- random numbers. +random = { + --- The internal maximum value. + max = 2147483647, + + --- The internal minimum value. + min = 0, + + --- The provider for random numbers. + random_provider = nil +} + + +--- Initializes random. Should not be called from the client. +function random.init() + if PcgRandom ~= nil then + random_provider = PcgRandom(os.time()) + else + math.randomseed(os.time()) + + random_provider = { + next = function(self, lower_bound, upper_bound) + return math.abs(math.random(lower_bound, upper_bound - 1)) + end + } + end +end + +--- Returns true or false based on the given chance. +-- +-- @param chance Optional. The "one in chance" chance to get true, defaults +-- to 2 (ans in "one in two"). +-- @return true or false based in the given chance. +function random.next_bool(chance) + chance = chance or 2 + + if chance <= 0 then + return false + elseif chance == 1 then + return true + end + + return random.next_int(0, chance) == chance - 1 +end + +--- Returns a float between the given bounds. +-- +-- @param lower_bound Optional. The lower bound (inclusive), defaults to 0. +-- @param upper_bound Optional. The upper bound (exclusive), defaults to 1. +-- @param decimal_places Optional. To how many decimal places the resulting +-- float should be rounded. +-- @return a float between the given bounds. +function random.next_float(lower_bound, upper_bound, decimal_places) + lower_bound = lower_bound or 0 + upper_bound = upper_bound or 1.0 + + local value = random_provider:next(random.min, random.max + 1) + value = (value - random.min) / (random.max - random.min) + value = value * (upper_bound - lower_bound) + lower_bound + + if decimal_places then + value = mathutil.round(value, decimal_places) + end + + return value +end + +--- Returns an int between the given bounds. +-- +-- @param lower_bound Optional. The lower bound (inclusive), defaults to +-- random.min. +-- @param upper_bound Optional. The upper bound (exclusive), defaults to +-- random.max. +-- @return a integer between the given bounds. +function random.next_int(lower_bound, upper_bound) + lower_bound = lower_bound or random.min + upper_bound = upper_bound or random.max + + return random_provider:next(lower_bound, upper_bound) +end + + +-- Initialize the random object. +random.init() + diff --git a/test/random.lua b/test/random.lua new file mode 100644 index 0000000..73c551f --- /dev/null +++ b/test/random.lua @@ -0,0 +1,70 @@ + +-- Load the test file. +dofile("./mods/utils/test.lua") + +-- Load the file for testing. +dofile("./mods/utils/random.lua") +dofile("./mods/utils/mathutil.lua") +dofile("./mods/utils/tableutil.lua") + + +-- The following tests are neither perfect nor well formed, +-- but they make sure the code is run and is kinda working. + + +test.start("random") + + +test.run("next_boolean", function() + for counter = 0, 1000, 1 do + test.equals(true, random.next_bool(1), "next_bool(1) returned false.") + end + + local trues = 0 + for counter = 0, 1000, 1 do + if random.next_bool() then + trues = trues + 1 + end + end + + test.equals(false, trues > 750, "next_bool() returned more than 3/4 (" .. trues .. ") as true.") + test.equals(false, trues < 250, "next_bool() returned less than 1/4 (" .. trues .. ") as true.") + + trues = 0 + for counter = 0, 1000, 1 do + if random.next_bool(5) then + trues = trues + 1 + end + end + + test.equals(false, trues > 250, "next_bool() returned more than 250 (" .. trues .. ") as true.") + test.equals(false, trues < 50, "next_bool() returned less than 50 (" .. trues .. ") as true.") +end) + +test.run("next_float", function() + for counter = 0, 1000, 1 do + local value = random.next_float(0, 15) + test.equals(true, mathutil.in_range(value, 0, 14.9999999999999), value .. " is not in range 0-14.999...") + end + for counter = 0, 1000, 1 do + local value = random.next_float(0.25, 0.5) + test.equals(true, mathutil.in_range(value, 0.25, 0.49999999999), value .. " is not in range 0.25-0.4999...") + end + + for counter = 0, 1000, 1 do + local value = random.next_float(0, 1.0, 2) + test.equals(value, mathutil.round(value, 2), value .. " has more than 2 decimal places.") + end +end) + +test.run("next_int", function() + for counter = 0, 1000, 1 do + local value = random.next_int(0, 15) + test.equals(true, mathutil.in_range(value, 0, 14), value .. " is not in range 0-14.") + end + for counter = 0, 1000, 1 do + local value = random.next_int(15, 30) + test.equals(true, mathutil.in_range(value, 15, 29), value .. " is not in range 15-29.") + end +end) +