docs revamp

docs/library/random.md

@@ -0,0 +1,71 @@
+# random
+
+Random number generation.
+
+```javascript
+var random = use('random')
+```
+
+## Functions
+
+### random.random()
+
+Returns a number between 0 (inclusive) and 1 (exclusive).
+
+```javascript
+random.random()  // e.g., 0.7234...
+```
+
+### random.random_fit()
+
+Returns a random 56-bit integer in the range -36028797018963968 to 36028797018963967.
+
+```javascript
+random.random_fit()  // e.g., 12345678901234
+```
+
+### random.random_whole(max)
+
+Returns a whole number from 0 (inclusive) to max (exclusive).
+
+```javascript
+random.random_whole(10)   // 0-9
+random.random_whole(100)  // 0-99
+random.random_whole(6) + 1  // dice roll: 1-6
+```
+
+## Examples
+
+```javascript
+var random = use('random')
+
+// Random boolean
+var coin_flip = random.random() < 0.5
+
+// Random element from array
+function pick(arr) {
+  return arr[random.random_whole(length(arr))]
+}
+
+var colors = ["red", "green", "blue"]
+var color = pick(colors)
+
+// Shuffle array
+function shuffle(arr) {
+  var result = array(arr)  // copy
+  for (var i = length(result) - 1; i > 0; i--) {
+    var j = random.random_whole(i + 1)
+    var temp = result[i]
+    result[i] = result[j]
+    result[j] = temp
+  }
+  return result
+}
+
+// Random in range
+function random_range(min, max) {
+  return min + random.random() * (max - min)
+}
+
+var x = random_range(-10, 10)  // -10 to 10
+```