@quenty/randomutils 2.1.0 → 2.1.1-canary.238.2c4d310.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.1.1-canary.238.2c4d310.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/randomutils@2.1.0...@quenty/randomutils@2.1.1-canary.238.2c4d310.0) (2021-12-29)
+
+**Note:** Version bump only for package @quenty/randomutils
+
+
+
+
+
 # [2.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/randomutils@2.0.0...@quenty/randomutils@2.1.0) (2021-10-02)
 
 

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014 Quenty
+Copyright (c) 2014-2021 Quenty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
 ## RandomUtils
 <div align="center">
-  <a href="http://quenty.github.io/api/">
+  <a href="http://quenty.github.io/NevermoreEngine/">
     <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/randomutils",
-  "version": "2.1.0",
+  "version": "2.1.1-canary.238.2c4d310.0",
   "description": "Quenty's RandomUtils, utility functions for Roblox",
   "keywords": [
     "Roblox",
@@ -28,5 +28,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2cae4b40a33765f444e6f0b1f3d6e181489dfa57"
+  "gitHead": "2c4d310b84afd0570d89667dc5d4aa69a0ef304a"
 }

package/src/Shared/RandomUtils.lua

@@ -1,9 +1,31 @@
----
--- @module RandomUtils
--- @author Quenty
+--[=[
+	Utility functions involving random variables. This is quite useful
+	for a variety of game mechanics.
+
+	:::tip
+	Each method generally takes a random object in as the last argument,
+	which can be used to seed the randomness. This is especially useful for
+	reproducting state in testing.
+	:::
+
+	@class RandomUtils
+]=]
 
 local RandomUtils = {}
 
+--[=[
+	Picks an option from a list. Returns nil if the list is empty.
+
+	```lua
+	local options = Players:GetPlayers()
+	local choosen = RandomUtils.choice(options)
+	print(choosen)
+	```
+
+	@param list { T }
+	@param random Random? -- Optional
+	@return T?
+]=]
 function RandomUtils.choice(list, random)
 	if #list == 0 then
 		return nil
@@ -18,34 +40,58 @@ function RandomUtils.choice(list, random)
 	end
 end
 
---- Creates a copy of the table, but shuffled using fisher-yates shuffle
--- @tparam table orig A new table to copy
--- @tparam[opt=nil] A random to use when shuffling
-function RandomUtils.shuffledCopy(orig, random)
-	local tbl = {}
-	for i=1, #orig do
-		tbl[i] = orig[i]
+--[=[
+	Creates a copy of the table, but shuffled using fisher-yates shuffle
+
+	@param list { T } -- A new table to copy
+	@param random Random? -- Optional random to use when shuffling
+	@return { T }
+]=]
+function RandomUtils.shuffledCopy(list, random)
+	local copy = {}
+	for i=1, #list do
+		copy[i] = list[i]
 	end
 
-	RandomUtils.shuffle(tbl, random)
+	RandomUtils.shuffle(copy, random)
 
-	return tbl
+	return copy
 end
 
-function RandomUtils.shuffle(tbl, random)
+--[=[
+	Shuffles the list in place
+
+	@param list {T}
+	@param random Random? -- Optional random to use when shuffling
+]=]
+function RandomUtils.shuffle(list, random)
 	if random then
-		for i = #tbl, 2, -1 do
+		for i = #list, 2, -1 do
 			local j = random:NextInteger(1, i)
-			tbl[i], tbl[j] = tbl[j], tbl[i]
+			list[i], list[j] = list[j], list[i]
 		end
 	else
-		for i = #tbl, 2, -1 do
+		for i = #list, 2, -1 do
 			local j = math.random(i)
-			tbl[i], tbl[j] = tbl[j], tbl[i]
+			list[i], list[j] = list[j], list[i]
 		end
 	end
 end
 
+--[=[
+	Like [/api/RandomUtils#Choice](RandomUtils.Choice) but weighted options in a
+	performance friendly way. Takes O(n) time.
+
+	:::warning
+	A weight of 0 may still be picked, and negative weights may result in
+	undefined behavior.
+	:::
+
+	@param list { T } -- List of options
+	@param weights { number } -- Array the same length with weights.
+	@param random Random? -- Optional random
+	@return T? -- May return nil if the list is empty
+]=]
 function RandomUtils.weightedChoice(list, weights, random)
 	if #list == 0 then
 		return nil
@@ -81,6 +127,12 @@ function RandomUtils.weightedChoice(list, weights, random)
 	end
 end
 
+--[=[
+	Computes the gaussian random function which is the independent probability curve.
+
+	@param random Random? -- Optional random to use
+	@return number
+]=]
 function RandomUtils.gaussianRandom(random)
 	local a, t
 	if random then
@@ -94,6 +146,10 @@ function RandomUtils.gaussianRandom(random)
 	return math.sqrt(-2*math.log(1 - t))*math.cos(a)
 end
 
+--[=[
+	@param random? Random? -- Optional random to use
+	@return Vector3
+]=]
 function RandomUtils.randomUnitVector3(random)
 	return Vector3.new(
 		RandomUtils.gaussianRandom(random),