brando

Brando

Brando is a module to handle pseudo-random sequences/permutations of integers using Buffers.

Install

$ npm install brando [-g]

require:

var Brando  = require( 'brando' );

Run Tests

to run all test files, install devDependecies:

 $ cd brando/
 # install or update devDependecies  
 $ npm install --dev
 # run tests 
 $ npm test

to execute a single test file simply do:

 $ node test/file-name.js

Run Benchmarks

run miscellaneous benchmarks for Brando

 $ cd brando/
 $ npm run bench

---

Methods

Arguments within [ ] are optional.

Brando.sham

Print some informational numbers about a particular sequence or permutation, without creating anything.

Brando#sham : function ( Number items, Number range [, Number repeat ] ) : undefined

Brando.emt

A simple factory method, it returns an EventEmitter that parses random data and emits results with the number of selected items and within the selected range (unsigned integers). Internally, it creates an empty Buffer of the length necessary to hold all requested values, thent is possible to fill it with values generated through Math.Random (biased result) or through a random source of data.

NOTE: If repetition is off, it returns a Sequence, otherwise, when items value is equal to range, it returns a FullPerm, otherwise a PartPerm.

/*
 * For default, repeat = +Infinity, or unlimited repetitions.
 *
 * - if repeat === 1
 *   - if items >= range, it returns a FullPerm.
 *   - if items < range, a PartPerm.
 *
 * - otherwise, it returns a Sequence (unlimited repetitions).
 *
 * Every instance of the Sequence EventEmitter, has 3 methods:
 * 
 * - for filling the Buffer with Math.random:
 *
 *   Sequence#fill : function () : Sequence
 *
 * - for executing multiple times a Fisher-Yates shuffle (using Math.random)
 *
 *   Sequence#shuffle : function ( [ Number times ] ) : Sequence
 *
 * - before reusing Sequence, resetting internal status and/or set a new result buffer:
 *
 *   Sequence#clear : function ( [ Boolean trash [, Boolean refill ] ] ) : Sequence
 *
 * - for parsing input data from a random source:
 *
 *   Sequence#parse : function ( Buffer data ) : undefined
 *
 * - using #parse, Sequence emits:
 *   - 'feed' when needs more data: function ( Number miss_bytes, Number curr_usage_ratio )
 *   - 'fart' when result is ready: function ( Buffer result, Number curr_usage_ratio )
 */
Brando#emt : function ( Number items, Number range [, Number repeat ] ) : Sequence

NOTE:

• max allowed value for items and range is 2^(32)-1, or 4 bytes values.
• max output size for sequences is 16GB. Virtually, there is no size limit for sequences with repetitions, but the max length for FP and PP is limited to:
  • ( 2^32 values ) * ( 4 bytes/value ), or 16GB.

See also emitter examples.

---

Transform Streams

Use a Transform stream to consume random data from an input source, it outputs results within the selected range of values, limiting the number to items.

Brando.stream

A simple factory method, it returns a SeqTransStream (stream.Transform), or a sub-type between FPTransStream and PPTransStream.

/*
 * For default, repeat = +Infinity, or unlimited repetitions.
 *
 * - if repeat === 1, it returns a stream that filters a full or a partial permutation.
 *   - if items >= range, it returns a FPTransStream.
 *   - if items < range, a PPTransStream.
 *
 * - otherwise, it returns a SeqTransStream (unlimited repetitions).
 *   - if items === 0, the stream consume all data that it receives, until stream ends.
 *
 * - for default, stream_opt is:
 * {
 *  highWaterMark : 16 * 1024
 *  , encoding : null
 *  , objectMode : false
 }
 */
Brando#stream : function ( Number items, Number range [, Number repeat [, Object stream_opt ] ] ) : SeqTransStream

NOTE:

• How many bytes will be consumed to produce 1 byte of result, depends on many factors, items, range, repetition, but moreover on the quality of random data, parsed from the input source to pipe in.

See also stream examples.

MIT License

Copyright (c) 2015 < Guglielmo Ferri : [e-mail] >

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.