Neologistic Paraphasic Mumbling
    Have ideas to improve npm?Join in the discussion! »

    fin-rounds

    0.1.0 • Public • Published

    module fin-rounds

    The module contains classes that implement wide range of rounding algorithms and provide infrastructure for polymorphic managing rounding processes.

    The implemented methods are the following:

    • javascript, native - Javascript native call of Math.round
    • ceil - Javascript native call of Math.ceil
    • floor - Javascript native call of Math.floor
    • math - Mathematical rounding - rounds .5 to nearest larger by module integer
    • bank, bankers - Banker's rounding - rounds .5 to nearest even integer
    • random, stochastic - Stochastic rounding - uses Math.random() to define rounding direction (see wiki)
    • series, alternative - The rounding algorithm that alternates direction of rounding (see wiki).
    • void- The dummy algorithm that returns the original value without rounding

    Install

    npm install fin-rounds

    Development & Testing

    git clone https://github.com/DScheglov/fin-rounds.git
    cd fin-rounds
    npm install
    npm test

    Usage

    var Round = require('fin-rounds').Round;
     
    // Creating rounding function with banker's algorithm and
    // 2-digits after coma precision
    var round = new Round('bank', 2);
     
    console.log(round(2.535));
    console.log(round(3.525));

    Output:

    2.54
    3.52

    Description

    The module exports 3 classes:

    • Round - provides infrastructure for different rounding algorithm
    • Precision - provides accuracy logic
    • RoundError - provides identification of exception raised in the module

    class Round

    Implements Function interface and wraps different methods of numbers rounding. Also this class holds the collection of registered rounding algorithms and provides polymorphic interface to use them.

    • constructor - creates a function that provides rounding
    Fields:
    • static allowedMethods: Array of String - the names of registered rounding methods
    • static methods: Object - contains registered rounding methods
    • static Error: reference - the reference to the RoundError class
    • static name: String - the name of the rounding method
    • index: Number - the number of calls of alternative rounding method. If you will use it in you own code, you should to update this counter by yourself
    • precision: Precision - the instance of Precision class that bound to the constructed function

    The fields of Round instance (name, index, precision) could be accessed inside function that implements rounding algorithm by this reference. For example:

    function some_rounding_algo(amount) {
      if (amount < 0) {
        throw new RoundError(
          `The "${amount}" is illegal parameter for this algorithm`,
          this.name
        );
      }
      ...
    }

    or some like this:

    function rounding_meth(amount) {
      this.index ++;
      if (this.index % 2) {
        throw new RoundError('This strange methods works only for even calls', this.name);
      }
      ...
    }
    Methods:
    • static register - registers a rounding method

    constructor Round(method[, precision])

    Creates a function that provides rounding according to method and with precision

    • method: String, Rounding method. One of the listed above methods
    • precision: Number, The number digits after/before come that will be considered due the rounding

    Returns: Round

    Example:
    var Round = require('fin-rounds').Round;
    var round1 = Round('math', 6); // Mathematical rounding with 6-digits after come accuracy
    // The code bellow will have the same effect:
    var round2 = new Round('math', 6);
     
    console.log(round1(1.58436587324657));
    console.log(round2(1.58436587324657));

    Output:

    1.584366
    1.584366
    Example:
    var Round = require('fin-rounds').Round;
    var round = Round('series', 1); // Alternative rounding with 1-digit after come accuracy
     
    console.log(round(1.35));
    console.log(round(2.65));
    console.log(round(1.35));
    console.log(round(1.35));

    Output:

    1.3
    2.7
    1.3
    1.4

    static Round.register([method, ]fn)

    Creates a function that provides rounding according to the method and with the precision

    • method: String, the name of rounding method. Optional. If ommited the fn.name will be used as name of rounding method
    • fn: Function, the function that implements rounding algorithm

    Returns: Round

    fn(amount) - rounding algorithm implementation
    • amount: Number, the amount shout be rounded.

    If the fn should provide rounding to whole integer. The Round.register decorates the algorithm function with applying accuracy ratio and further normalization of rounded value. If you code needs the parameters of precision it could access them by this.precision inside you function.

    Example:
    var Round = require('fin-rounds').Round;
     
    Round.register('odd', round_odd);
     
    var round = new Round('odd');
     
    console.log(round(1.5));
    console.log(round(2.5));
     
    // Rounding 0.5 to the nearest odd integer
    function round_odd(amount) {
      var floor = parseInt(amount, 10);
      var rest = Math.abs(amount - floor) * 2;
      var delta;
      if (rest > 1) delta = 1;
      else if (rest === 1 && floor % 2 === 0) delta = 1;
      else delta = 0;
      if (delta && amount < 0) delta = -delta;
      return (floor + delta);
    }

    Output:

    1
    3

    class Precision

    Provides accuracy logic and grants specified number of digits before or after coma in rounded value. If precision < 0 the rounding will be processed to |precision| digits before coma, otherwise -- after.

    In major number of cases you do not need to use this Class directly.

    • constructor - creates an instance of Precision class
    Fields:
    • exponent: Number - the number of digits before/after coma
    • ratio: Number - the number is used to scale rounding numbers
    • reverse: Boolean - the marker of reverse rounding (rounding to digits before coma)
    Methods:
    • applyRatio - multiply or divide the amount on precision ratio
    • normalize - the reverse method to applyRatio
    • static decorate - decorates the algorithm function with call of applyRatio before method call and normalize after the method processed

    constructor Precision([precision])

    • precision: Number, Number of digits after/before coma that should be granted after rounding. Optional. If omitted the precision ratio will be equal to 1.

    returns: Precision, created Precision instance

    Precision#applyRatio(amount)

    Multiplies or divides the amount on precision ratio

    • amount: Number, the amount should be prepared for further whole integer rounding

    returns: Number, the amount that is ready for whole-integer rounding

    Precision#normalize(amount)

    • amount Number, the result of whole-integer rounding

    returns: Number, the scale-restored value

    static Precision.decorate(method)

    Decorates the algorithm function with call of Precision#applyRatio before method call and Precision#normalize after the method processed

    • method Function, algorithm function that should be decorated

    returns: Function, decorated function

    class RoundError extends Error

    Exception class to identify errors in the fin-rounds module

    • constructor -- creates an exception object
    Fields:
    • message: String - the error message
    • method: String - the name of method generated the exception
    • name: String - the name of exception is always RoundError.

    constructor RoundError(msg, method)

    • msg: String, the error message
    • method: String, the method generated the error

    Install

    npm i fin-rounds

    DownloadsWeekly Downloads

    0

    Version

    0.1.0

    License

    MIT

    Last publish

    Collaborators

    • avatar