SB-6.1-PRE

2021-02-02 13:50:53 +00:00
1 parent 690169a409
commit 358a25f522
@@ -0,0 +1,16 @@
+# coin
+
+```js
+// usage
+chance.coin()
+```
+
+Flip a coin!
+
+```js
+chance.coin();
+=> 'heads'
+
+chance.coin();
+=> 'tails'
+```
@@ -0,0 +1,29 @@
+# dice
+
+```js
+// usage
+chance.d4()
+chance.d6()
+chance.d8()
+chance.d10()
+chance.d12()
+chance.d20()
+chance.d30()
+chance.d100()
+```
+
+<p class="pullquote" data-pullquote='"Any dungeon master worth his weight in geldings goes nowhere without his 20 sided die."' markdown="1"></p>
+
+Return a value equal to the roll of a die.
+
+```js
+chance.d20();
+=> 13
+
+chance.d6();
+=> 4
+```
+
+These are just wrappers around natural() but are convenient for use by games.
+
+They return values between 1 and the number after the `d`, so `chance.d4()` returns 1, 2, 3, or 4, just like a 4 sided die would.
@@ -0,0 +1,16 @@
+# guid
+
+```js
+// usage
+chance.guid()
+chance.guid({version: 5})
+```
+
+Return a random guid, version 5 by default.
+
+```js
+chance.guid();
+=> 'f0d8368d-85e2-54fb-73c4-2d60374295e3'
+chance.guid({version: 4});
+=> 'c71f58e3-34af-43c0-b405-2764d6947d21'
+```
@@ -0,0 +1,35 @@
+# hash
+
+```js
+// usage
+chance.hash()
+chance.hash({length: 25})
+chance.hash({casing: 'upper'})
+```
+
+Return a random hex hash
+
+```js
+chance.hash()
+=> 'e5162f27da96ed8e1ae51def1ba643b91d2581d8'
+```
+
+By default, the hash is lowercase and 40 hex characters long (same as a git
+commit hash).
+
+Optionally specify a length
+
+```js
+chance.hash({length: 15})
+=> 'c28f57cb599ada4'
+```
+
+Optionally specify casing to get a hash with only uppercase letters
+rather than the default lowercase
+
+```js
+chance.hash({casing: 'upper'})
+=> '3F2EB3FB85D88984C1EC4F46A3DBE740B5E0E56E'
+```
+
+
@@ -0,0 +1,59 @@
+# hidden
+
+```js
+// usage
+chance.cc_types()
+chance.mersenne_twister()
+chance.mersenne_twister(12345)
+chance.months()
+chance.name_prefixes()
+chance.provinces()
+chance.states()
+chance.street_suffix()
+chance.street_suffixes()
+```
+
+These aren't really hidden per se, but just utility methods intended to be used
+internally but exposed externally in case they're useful to anyone.
+
+```js
+
+// Return the list of cc types
+chance.cc_types()
+=> [{name: "American Express", short_name: 'amex', prefix: '34', length: 15}, ...]
+
+// Return a new Mersenne Twister
+chance.mersenne_twister()
+=> [object Object] // An instance of a Mersenne Twister
+
+// Optionally provide a seed for that twister
+chance.mersenne_twister(12345)
+=> [object Object] // An instance of a twister with seed 12345
+
+// Return our list of name prefixes
+chance.months();
+=> [{name: 'January', short_name 'Jan', numeric: '01'}, ...]
+
+// Return our list of name prefixes
+chance.name_prefixes();
+=> [{name: 'Doctor', abbreviation: 'Dr.'}, {name: 'Miss', abbreviation: 'Miss'}, ...]
+
+// Return the list of provinces
+chance.provinces();
+=> [{name: 'Alberta', abbreviation: 'AB'}, {name: 'British Columbia', abbreviation: 'BC'}, ...]
+
+// Return the list of states
+chance.states();
+=> [{name: 'Alabama', abbreviation: 'AL'}, {name: 'Alaska', abbreviation: 'AK'}, ...]
+
+// Return a random street suffix
+chance.street_suffix();
+=> {name: 'Street', abbreviation: 'St'}
+
+// Return the list of street suffixes
+chance.street_suffixes();
+=> [{name: 'Avenue', abbreviation: 'Ave'}, {name: 'Boulevard', abbreviation: 'Blvd'}, ...]
+
+```
+
+
@@ -0,0 +1,35 @@
+# n
+
+```js
+// usage
+chance.n(chance.email, 5)
+chance.n(chance.email, 5, { domain: "socialradar.com" })
+```
+
+Provide any function that generates random stuff (usually another **Chance** function) and a number and `n()` will generate an array of items with a length matching the length you specified.
+
+For example, to generate 5 email addresses:
+
+```js
+chance.n(chance.email, 5);
+=> [ 'nese@me.gov',
+'tukvogi@novew.co.uk',
+'worzi@jotok.edu',
+'wicumafom@lalu.edu',
+'hifebwo@abecusa.com' ]
+```
+
+Any options that would be sent to the random function can be added following the number.
+
+For example, `chance.email()` has options which can be specified, so you can generate 5 emails with a known domain as follows:
+
+```js
+chance.n(chance.email, 5, { domain: "socialradar.com" })
+=> [ 'nuvvu@socialradar.com',
+'icolul@socialradar.com',
+'rig@socialradar.com',
+'ca@socialradar.com',
+'uc@socialradar.com' ]
+```
+
+Note, these items are not guaranteed to be unique. If that is the intent, see [`chance.unique()`](http://chancejs.com/#unique)
@@ -0,0 +1,35 @@
+# normal
+
+```js
+// usage
+chance.normal()
+chance.normal({mean: 100})
+chance.normal({mean: 100, dev: 15})
+```
+
+Return a normally-distributed random variate.
+
+```js
+chance.normal()
+=> 0.4244767651300604
+```
+
+By default this starts with a mean of `0` and a standard deviation of `1` which
+is the standard normal distribution.
+
+Optionally specify a mean and/or deviation.
+
+```js
+// Notice, since no deviation was specified, using the default of `1`
+chance.normal({mean: 100})
+=> 99.68352269988522
+
+// For example, to get a random IQ (which by definition has a mean of 100
+// and a standard deviation of 15)
+chance.normal({mean: 100, dev: 15})
+=> 85.11040121833615
+```
+
+Used in combination with the above generators, this can be an extremely powerful
+way to get more realistic results as often "pure random" results fail to
+approximate the real world.
@@ -0,0 +1,27 @@
+# radio
+
+```js
+// usage
+chance.radio()
+```
+
+<p class="pullquote" data-pullquote='Broadcast call signs start with a W if east of the Mississippi River and K if west.' markdown="1"></p>
+
+Generate a random radio call sign.
+
+```js
+chance.radio();
+=> 'KCXW'
+```
+
+Optionally specify a side of the Mississippi River to limit stations to that side.
+
+See [K and W](http://en.wikipedia.org/wiki/Call_signs_in_North_America#K_and_W) for more details
+
+```js
+chance.radio({side: 'east'});
+=> 'WKOQ'
+
+chance.radio({side: 'east'});
+=> 'WNOW'
+```
@@ -0,0 +1,25 @@
+# rpg
+
+```js
+// usage
+chance.rpg('#d#')
+chance.rpg('#d#', {sum: true})
+```
+
+Given an input looking like #d#, where the first # is the number of dice to
+roll and the second # is the max of each die, returns an array of dice values.
+
+```js
+chance.rpg('3d10');
+=> [1, 6, 9]
+
+chance.rpg('5d6');
+=> [3, 1, 2, 5, 2]
+```
+
+Optionally specify a sum be returned rather than an array of dice.
+
+```js
+chance.rpg('3d10', {sum: true});
+=> 14
+```
@@ -0,0 +1,25 @@
+# tv
+
+```js
+// usage
+chance.tv()
+chance.tv({side: 'west'})
+```
+
+Generate a TV station call sign. This is an alias for `radio()` since they both
+follow the same rules.
+
+```js
+chance.radio();
+=> 'WXTY'
+```
+
+Optionally specify a side of the Mississippi River to limit stations to that side.
+
+```js
+chance.radio({side: 'west'});
+=> 'KCYL'
+
+chance.radio({side: 'west'});
+=> 'KQDV'
+```
@@ -0,0 +1,47 @@
+# unique
+
+```js
+// usage
+chance.unique(chance.state, 5)
+chance.unique(chance.state, 5, { comparator: func })
+```
+
+Provide any function that generates random stuff (usually another **Chance** function) and a number and `unique()` will generate a random array of unique (not repeating) items with a length matching the one you specified.
+
+```js
+chance.unique(chance.state, 5);
+=> ["SC", "WA", "CO", "TX", "ND"]
+```
+
+This is helpful when there are a limited number of options and you want a bunch but want to ensure each is different.
+
+Optionally specify the comparator used to determine whether a generated item is in the list of already generated items. By default the comparator just checks to see if the newly generated item is in the array of already generated items. This works for most simple cases (such as `chance.state()`) but will not work if the generated item is an object (because the `Array.prototype.indexOf()` method will not work on an object since 2 objects will not be strictly equal, `===`, unless they are references to the same object).
+
+```js
+chance.unique(chance.currency, 2, {
+comparator: function(arr, val) {
+return arr.reduce(function(acc, item) {
+return acc || (item.code === val.code);
+}, false);
+}
+});
+=> [{ code: "KYF", name: "Cayman Islands Dollar" }, { code: "CDF", name: "Congo/Kinshasa Franc" }]
+```
+
+You can also specify any arbitrary options in this third argument and they'll be passed along to the method you specify as the first.
+
+For example, let's say you want to retrieve 10 unique integers between 0 and 100. This is easily achievable by specifying `chance.integer` as hte function, 10 as the number to retrieve, and a min/max in the options.
+
+```js
+chance.unique(chance.integer, 10, {min: 0, max: 100});
+=> [78, 49, 7, 87, 59, 89, 84, 62, 60, 63]
+```
+
+Note, there could be cases where it is impossible to generate the unique number. For example, if you choose `chance.state` as shown above as the random function and want say, 55 uniques, **Chance** will throw a RangeError because it is impossible to generate 55 uniques because there are only 51 states in the available pool (50 states plus the District of Columbia).
+
+```js
+chance.unique(chance.state, 55);
+=> RangeError: Chance: num is likely too large for sample set
+```
+
+
@@ -0,0 +1,55 @@
+# weighted
+
+```js
+// usage
+chance.weighted(['a', 'b'], [100, 1])
+chance.weighted(['a', 'b', 'c', 'd'], [1, 2, 3, 4])
+```
+
+Provide an array of items, and another array of items specifying the relative weights and **Chance** will select one of those items, obeying the specified weight.
+
+For example, the following code:
+
+```js
+chance.weighted(['a', 'b'], [100, 1]);
+=> 'a'
+```
+
+Will generate `'a'` 100 times more often than `'b'` but still choose one or the other randomly.
+
+The weights are all relative, so if you have more than just two it will ensure that all items are generated relative to all of the weights.
+
+For example, the following code:
+
+```js
+chance.weighted(['a', 'b', 'c', 'd'], [1, 2, 3, 4]);
+=> 'c'
+```
+
+Will generate a letter from the array but will pick `'b'` twice as often as it picks `'a'` and will pick `'c'` three times as often as it picks `'a'` and will pick `'d'` four times as often as it will pick `'a'` and will pick `'d'` two times as often as it will pick `'b'`.
+
+The weights can be whole numbers as shown above or fractions.
+
+```js
+chance.weighted(['a', 'b', 'c', 'd'], [0.1, 0.2, 0.3, 0.4]);
+=> 'd'
+```
+
+There is no requirement that the weights sum to anything in particular, they are all compared relative to each other so all of the following are equivalent:
+
+```js
+chance.weighted(['a', 'b', 'c', 'd'], [1, 2, 3, 4]);
+chance.weighted(['a', 'b', 'c', 'd'], [0.1, 0.2, 0.3, 0.4]);
+chance.weighted(['a', 'b', 'c', 'd'], [100, 200, 300, 400]);
+chance.weighted(['a', 'b', 'c', 'd'], [17, 34, 51, 68]);
+chance.weighted(['a', 'b', 'c', 'd'], [0.17, 0.34, 0.51, 0.68]);
+```
+
+Recall JavaScript has first class functions so you could do something like the following:
+
+```js
+chance.weighted([chance.fbid, chance.twitter, chance.ip], [10, 5, 1])();
+=> 10000345166213
+```
+
+That will pick one of the **Chance** methods with the relative weights specified and then immediately invoke it, so it will return a random fbid twice as often as it will return a twitter handle (because 10/5 is 2) and an fbid 10 times more often than it will return a random ip address (because 10/1 is 10). It will return a random twitter handle 5 times more often than it will return an ip address (because 5/1 is 5).