Skip to content

Commit 9762e88

Browse files
kgrytekgryte
committed
docs: update signatures and add partial application docs
1 parent d7ca9e4 commit 9762e88

1 file changed

Lines changed: 127 additions & 36 deletions

File tree

  • lib/node_modules/@stdlib/random/array/tools/unary-factory

‎lib/node_modules/@stdlib/random/array/tools/unary-factory/README.md‎

Lines changed: 127 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ limitations under the License.
3030
var unaryFactory = require( '@stdlib/random/array/tools/unary-factory' );
3131
```
3232

33-
#### unaryFactory( prng, dtypes )
33+
#### unaryFactory( prng, dtypes, dtype )
3434

3535
Returns a factory function for generating pseudorandom values drawn from a unary PRNG.
3636

@@ -39,18 +39,19 @@ var exponential = require( '@stdlib/random/base/exponential' );
3939

4040
var dtypes = [ 'float64', 'float32', 'generic' ];
4141

42-
var factory = unaryFactory( exponential, dtypes );
42+
var factory = unaryFactory( exponential, dtypes, 'float64' );
4343
// returns <Function>
4444
```
4545

4646
The function has the following parameters:
4747

4848
- **prng**: unary pseudorandom number generator.
4949
- **dtypes**: list of supported output data types.
50+
- **dtype**: default output array data type.
5051

5152
* * *
5253

53-
#### factory( dtype\[, options] )
54+
#### factory( \[param1, ]\[options] )
5455

5556
Returns a function for generating pseudorandom values drawn from a unary PRNG.
5657

@@ -59,16 +60,16 @@ var exponential = require( '@stdlib/random/base/exponential' );
5960

6061
var dtypes = [ 'float64', 'float32', 'generic' ];
6162

62-
var factory = unaryFactory( exponential, dtypes );
63+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
6364
// returns <Function>
6465

65-
var random = factory( dtypes[ 0 ] );
66+
var random = factory();
6667
// returns <Function>
6768
```
6869

6970
The function has the following parameters:
7071

71-
- **dtype**: default output array data type.
72+
- **oaram1**: PRNG parameter. If provided a PRNG parameter, the function returns a partially applied function for creating arrays, which can be useful when wanting to pass around a parameterized function for array creation.
7273
- **options**: function options.
7374

7475
The function supports the following options:
@@ -77,9 +78,12 @@ The function supports the following options:
7778
- **seed**: pseudorandom value generator seed.
7879
- **state**: pseudorandom value generator state.
7980
- **copy**: boolean indicating whether to copy a provided pseudorandom value generator state.
81+
- **dtype**: default output array data type. Setting this option overrides the default output array data type provided to the parent function.
8082

8183
* * *
8284

85+
### Full Arity
86+
8387
#### random( len, param1\[, options] )
8488

8589
Returns an array of pseudorandom values drawn from a unary PRNG.
@@ -89,10 +93,10 @@ var exponential = require( '@stdlib/random/base/exponential' );
8993

9094
var dtypes = [ 'float64', 'float32', 'generic' ];
9195

92-
var factory = unaryFactory( exponential, dtypes );
96+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
9397
// returns <Function>
9498

95-
var random = factory( dtypes[ 0 ] );
99+
var random = factory();
96100
// returns <Function>
97101

98102
var v = random( 10, 2.0 );
@@ -114,10 +118,10 @@ var exponential = require( '@stdlib/random/base/exponential' );
114118

115119
var dtypes = [ 'float64', 'float32', 'generic' ];
116120

117-
var factory = unaryFactory( exponential, dtypes );
121+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
118122
// returns <Function>
119123

120-
var random = factory( dtypes[ 0 ] );
124+
var random = factory();
121125
// returns <Function>
122126

123127
var v = random( 10, 2.0, {
@@ -136,10 +140,10 @@ var zeros = require( '@stdlib/array/zeros' );
136140

137141
var dtypes = [ 'float64', 'float32', 'generic' ];
138142

139-
var factory = unaryFactory( exponential, dtypes );
143+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
140144
// returns <Function>
141145

142-
var random = factory( dtypes[ 0 ] );
146+
var random = factory();
143147
// returns <Function>
144148

145149
var out = zeros( 10, 'float64' );
@@ -157,6 +161,93 @@ The method has the following parameters:
157161
- **param1**: PRNG parameter.
158162
- **out**: output array.
159163

164+
### Partial Application
165+
166+
#### random( len\[, options] )
167+
168+
Returns an array of pseudorandom values drawn from a unary PRNG.
169+
170+
```javascript
171+
var exponential = require( '@stdlib/random/base/exponential' );
172+
173+
var dtypes = [ 'float64', 'float32', 'generic' ];
174+
175+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
176+
// returns <Function>
177+
178+
var random = factory( 2.0 );
179+
// returns <Function>
180+
181+
var v = random( 10 );
182+
// returns <Float64Array>
183+
184+
v = random( 10 );
185+
// returns <Float64Array>
186+
```
187+
188+
The function has the following parameters:
189+
190+
- **len**: output array length.
191+
- **options**: function options.
192+
193+
The function accepts the following options:
194+
195+
- **dtype**: output array data type. Setting this option overrides the default output array data type.
196+
197+
```javascript
198+
var exponential = require( '@stdlib/random/base/exponential' );
199+
200+
var dtypes = [ 'float64', 'float32', 'generic' ];
201+
202+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
203+
// returns <Function>
204+
205+
var random = factory( 2.0 );
206+
// returns <Function>
207+
208+
var v = random( 10, {
209+
'dtype': 'float32'
210+
});
211+
// returns <Float32Array>
212+
213+
v = random( 10, {
214+
'dtype': 'generic'
215+
});
216+
// returns [...]
217+
```
218+
219+
#### random.assign( out )
220+
221+
Fills an array with pseudorandom values drawn from a unary PRNG.
222+
223+
```javascript
224+
var exponential = require( '@stdlib/random/base/exponential' );
225+
var zeros = require( '@stdlib/array/zeros' );
226+
227+
var dtypes = [ 'float64', 'float32', 'generic' ];
228+
229+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
230+
// returns <Function>
231+
232+
var random = factory( 2.0 );
233+
// returns <Function>
234+
235+
var out = zeros( 10, 'float64' );
236+
// returns <Float64Array>
237+
238+
var v = random.assign( out );
239+
// returns <Float64Array>
240+
241+
var bool = ( out === v );
242+
// returns true
243+
```
244+
245+
The method has the following parameters:
246+
247+
- **out**: output array.
248+
249+
* * *
250+
160251
#### random.PRNG
161252

162253
The underlying pseudorandom number generator.
@@ -167,10 +258,10 @@ var zeros = require( '@stdlib/array/zeros' );
167258

168259
var dtypes = [ 'float64', 'float32', 'generic' ];
169260

170-
var factory = unaryFactory( exponential, dtypes );
261+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
171262
// returns <Function>
172263

173-
var random = factory( dtypes[ 0 ] );
264+
var random = factory();
174265
// returns <Function>
175266

176267
var prng = random.PRNG;
@@ -187,10 +278,10 @@ var zeros = require( '@stdlib/array/zeros' );
187278

188279
var dtypes = [ 'float64', 'float32', 'generic' ];
189280

190-
var factory = unaryFactory( exponential, dtypes );
281+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
191282
// returns <Function>
192283

193-
var random = factory( dtypes[ 0 ] );
284+
var random = factory();
194285
// returns <Function>
195286

196287
var seed = random.seed;
@@ -206,10 +297,10 @@ var zeros = require( '@stdlib/array/zeros' );
206297

207298
var dtypes = [ 'float64', 'float32', 'generic' ];
208299

209-
var factory = unaryFactory( exponential, dtypes );
300+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
210301
// returns <Function>
211302

212-
var random = factory( dtypes[ 0 ], {
303+
var random = factory({
213304
'prng': minstd
214305
});
215306
// returns <Function>
@@ -228,10 +319,10 @@ var zeros = require( '@stdlib/array/zeros' );
228319

229320
var dtypes = [ 'float64', 'float32', 'generic' ];
230321

231-
var factory = unaryFactory( exponential, dtypes );
322+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
232323
// returns <Function>
233324

234-
var random = factory( dtypes[ 0 ] );
325+
var random = factory();
235326
// returns <Function>
236327

237328
var len = random.seedLength;
@@ -247,10 +338,10 @@ var zeros = require( '@stdlib/array/zeros' );
247338

248339
var dtypes = [ 'float64', 'float32', 'generic' ];
249340

250-
var factory = unaryFactory( exponential, dtypes );
341+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
251342
// returns <Function>
252343

253-
var random = factory( dtypes[ 0 ], {
344+
var random = factory({
254345
'prng': minstd
255346
});
256347
// returns <Function>
@@ -269,10 +360,10 @@ var zeros = require( '@stdlib/array/zeros' );
269360

270361
var dtypes = [ 'float64', 'float32', 'generic' ];
271362

272-
var factory = unaryFactory( exponential, dtypes );
363+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
273364
// returns <Function>
274365

275-
var random = factory( dtypes[ 0 ] );
366+
var random = factory();
276367
// returns <Function>
277368

278369
var state = random.state;
@@ -288,10 +379,10 @@ var zeros = require( '@stdlib/array/zeros' );
288379

289380
var dtypes = [ 'float64', 'float32', 'generic' ];
290381

291-
var factory = unaryFactory( exponential, dtypes );
382+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
292383
// returns <Function>
293384

294-
var random = factory( dtypes[ 0 ], {
385+
var random = factory({
295386
'prng': minstd
296387
});
297388
// returns <Function>
@@ -310,10 +401,10 @@ var zeros = require( '@stdlib/array/zeros' );
310401

311402
var dtypes = [ 'float64', 'float32', 'generic' ];
312403

313-
var factory = unaryFactory( exponential, dtypes );
404+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
314405
// returns <Function>
315406

316-
var random = factory( dtypes[ 0 ] );
407+
var random = factory();
317408
// returns <Function>
318409

319410
var len = random.stateLength;
@@ -329,10 +420,10 @@ var zeros = require( '@stdlib/array/zeros' );
329420

330421
var dtypes = [ 'float64', 'float32', 'generic' ];
331422

332-
var factory = unaryFactory( exponential, dtypes );
423+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
333424
// returns <Function>
334425

335-
var random = factory( dtypes[ 0 ], {
426+
var random = factory({
336427
'prng': minstd
337428
});
338429
// returns <Function>
@@ -351,10 +442,10 @@ var zeros = require( '@stdlib/array/zeros' );
351442

352443
var dtypes = [ 'float64', 'float32', 'generic' ];
353444

354-
var factory = unaryFactory( exponential, dtypes );
445+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
355446
// returns <Function>
356447

357-
var random = factory( dtypes[ 0 ] );
448+
var random = factory();
358449
// returns <Function>
359450

360451
var sz = random.byteLength;
@@ -370,10 +461,10 @@ var zeros = require( '@stdlib/array/zeros' );
370461

371462
var dtypes = [ 'float64', 'float32', 'generic' ];
372463

373-
var factory = unaryFactory( exponential, dtypes );
464+
var factory = unaryFactory( exponential, dtypes, dtypes[ 0 ] );
374465
// returns <Function>
375466

376-
var random = factory( dtypes[ 0 ], {
467+
var random = factory({
377468
'prng': minstd
378469
});
379470
// returns <Function>
@@ -408,10 +499,10 @@ var unaryFactory = require( '@stdlib/random/array/tools/unary-factory' );
408499
var dt = dtypes( 'real_floating_point' );
409500
dt.push( 'generic' );
410501

411-
var factory = unaryFactory( exponential, dt );
502+
var factory = unaryFactory( exponential, dt, 'float64' );
412503
// returns <Function>
413504

414-
var random = factory( 'float64' );
505+
var random = factory();
415506
// returns <Function>
416507

417508
var x = random( 10, 2.0 );

0 commit comments

Comments
 (0)