review.tizen.org Git - platform/framework/web/crosswalk-tizen.git/blob

   1 # random #
   2
   3 Pseudo-random generators.
   4
   5 mout uses `Math.random` by default on all the pseudo-random generators, if
   6 you need a seeded random or a better algorithm see the [`random()`](#random)
   7 documentation for instructions.
   8
   9
  10
  11 ## choice(...items):*
  12
  13 Returns a random element from the supplied arguments or from an array if single
  14 argument is an array.
  15
  16 ### Example:
  17
  18 ```js
  19 choice(1, 2, 3, 4, 5); // 3
  20
  21 var arr = ['lorem', 'ipsum', 'dolor'];
  22 choice(arr); // 'dolor'
  23 ```
  24
  25
  26
  27 ## guid():String
  28
  29 Generates a pseudo-random [Globally Unique Identifier](http://en.wikipedia.org/wiki/Globally_unique_identifier) (v4).
  30
  31 Since the total number of GUIDs is 2<sup>122</sup> the chance of generating the
  32 same value twice is negligible.
  33
  34 **Important:** this method uses `Math.random` by default so the UUID isn't
  35 *safe* (sequence of outputs can be predicted in some cases), check the
  36 [`random()`](#random) documentation for more info on how to replace the default
  37 PRNG if you need extra safety or need *seeded* results.
  38
  39 See: [`randHex()`](#randHex), [`random()`](#random)
  40
  41 ### Example:
  42
  43 ```js
  44 guid();      // 830e9f50-ac7f-4369-a14f-ed0e62b2fa0b
  45 guid();      // 5de3d09b-e79c-4727-932b-48c49228d508
  46 ```
  47
  48
  49
  50 ## rand([min], [max]):Number
  51
  52 Gets a random number inside range or snap to min/max values.
  53
  54 ### Arguments:
  55
  56  1. `[min]` (Number)         : Minimum value. Defaults to `number/MIN_INT`.
  57  2. `[max]` (Number)         : Maximum value. Defaults to `number/MAX_INT`.
  58
  59
  60 ### Example:
  61
  62 ```js
  63 rand();      // 448740433.55274725
  64 rand();      // -31797596.097682
  65 rand(0, 10); // 7.369723
  66 rand(0, 10); // 5.987042
  67 ```
  68
  69 See: [`random()`](#random)
  70
  71
  72
  73 ## randBit():Number
  74
  75 Returns a random "bit" (0 or 1). Useful for addition/subtraction.
  76
  77 It's slightly faster than `choice(0, 1)` since implementation is simpler (not
  78 that it will make a huge difference in most cases).
  79
  80 See: [`choice()`](#choice)
  81
  82 ### Example:
  83
  84 ```js
  85 randBit(); // 1
  86 randBit(); // 0
  87
  88 //same effect as
  89 choice(0, 1);
  90 ```
  91
  92
  93 ## randBool():Boolean
  94
  95 Returns a random Boolean (`true` or `false`).
  96
  97 Since this is very common it makes sense to abstract it into a discrete method.
  98
  99 ### Example:
 100
 101 ```js
 102 randBool(); // true
 103 randBool(); // false
 104 ```
 105
 106
 107
 108 ## randHex([size]):String
 109
 110 Returns a random hexadecimal string.
 111
 112 The default `size` is `6`.
 113
 114 ### Example:
 115
 116 ```js
 117 randHex();   // "dd8575"
 118 randHex();   // "e6baeb"
 119 randHex(2);  // "a2"
 120 randHex(30); // "effd7e2ad9a4a3067e30525fab983a"
 121 ```
 122
 123
 124
 125 ## randInt([min], [max]):Number
 126
 127 Gets a random integer inside range or snap to min/max values.
 128
 129 ### Arguments:
 130
 131  1. `[min]` (Number)         : Minimum value. Defaults to `number/MIN_INT`.
 132  2. `[max]` (Number)         : Maximum value. Defaults to `number/MAX_INT`.
 133
 134
 135 ### Example:
 136
 137 ```js
 138 randInt();      // 448740433
 139 randInt();      // -31797596
 140 randInt(0, 10); // 7
 141 randInt(0, 10); // 5
 142 ```
 143
 144
 145
 146 ## randSign():Number
 147
 148 Returns a random "sign" (-1 or 1). Useful for multiplications.
 149
 150 It's slightly faster than `choice(-1, 1)` since implementation is simpler (not
 151 that it will make a huge difference in most cases).
 152
 153 See: [`choice()`](#choice)
 154
 155 ### Example:
 156
 157 ```js
 158 randSign(); // -1
 159 randSign(); // 1
 160
 161 //same effect as
 162 choice(-1, 1);
 163 ```
 164
 165
 166
 167 ## random():Number
 168
 169 Returns a random number between `0` and `1`. Same as `Math.random()`.
 170
 171 ```js
 172 random(); // 0.35435103671625257
 173 random(); // 0.8768321881070733
 174 ```
 175
 176 **Important:** No methods inside mout should call `Math.random()`
 177 directly, they all use `random/random` as a proxy, that way we can
 178 inject/replace the pseudo-random number generator if needed (ie. in case we
 179 need a seeded random or a better algorithm than the native one).
 180
 181 ### Replacing the PRNG
 182
 183 In some cases we might need better/different algorithms than the one provided
 184 by `Math.random` (ie. safer, seeded).
 185
 186 Because of licensing issues, file size limitations and different needs we
 187 decided to **not** implement a custom PRNG and instead provide a easy way to
 188 override the default behavior. - [issue #99](https://github.com/millermedeiros/amd-utils/issues/99)
 189
 190 If you are using mout with a loader that supports the [AMD map
 191 config](https://github.com/amdjs/amdjs-api/wiki/Common-Config), such as
 192 [RequireJS](http://requirejs.org/), you can use it to replace the PRNG
 193 (recommended approach):
 194
 195 ```js
 196 requirejs.config({
 197     map : {
 198         // all modules will load "my_custom_prng" instead of
 199         // "mout/random/random"
 200         '*' : {
 201             'mout/random/random' : 'my_custom_prng'
 202         }
 203     }
 204 });
 205 ```
 206
 207 You also have the option to override `random.get` in case you are using
 208 mout on node.js or with a loader which doesn't support the map config:
 209
 210 ```js
 211 // replace the PRNG
 212 var n = 0;
 213 random.get = function(){
 214     return ++n % 2? 0 : 1; // not so random :P
 215 };
 216 random(); // 0
 217 random(); // 1
 218 random(); // 0
 219 random(); // 1
 220 ```
 221
 222 See this [detailed explanation about PRNG in
 223 JavaScript](http://baagoe.org/en/w/index.php/Better_random_numbers_for_javascript)
 224 to understand the issues with the native `Math.random` and also for a list of
 225 algorithms that could be used instead.
 226
 227
 228
 229 ## randString([length, dictionary]):String
 230
 231 Returns a random string.
 232
 233 By default returns string containing alphanumeric characters (lowercase and uppercase) with a length of 8.
 234
 235 ### Arguments:
 236
 237  1. `[length]`      (number)       : Length of the string to return. Defaults to 8.
 238  2. `[dictionary]`  (string)       : A string containing all characters used as a dictionary for the random string construction. Defaults to alphanumeric characters (lowercase and uppercase).
 239
 240 ### Example:
 241
 242 ```js
 243 randString();             // returns a string with length 8.
 244 randString(12);           // returns a string of length 12.
 245 randString(-1);           // returns a string of length 8.
 246 randString(null, 'pew!'); // returns a random string of length 8 composed of 'p', 'e', 'w' and '!'.
 247 randString(10, '0');      // always returns '0's of length 10.
 248 randString(rand(8, 10));  // returns a random string with length between 8 and 10.
 249 ```
 250
 251
 252
 253 -------------------------------------------------------------------------------
 254
 255 For more usage examples check specs inside `/tests` folder. Unit tests are the
 256 best documentation you can get...