numbr
=====

A simple, fast javascript library for formatting numbers. Based heavily on Numeral.js

Formatting options

Soon. In the meantime, all format strings from http://numeraljs.com/ work as expected.

Examples

``javascript
var numbr = require('numbr');

numbr(1000.25).format('0,0.0');
// 1,000.3
`

`javascript
// Global language
var fr = require('numbr/languages/fr');
numbr.loadLang('fr', fr);
numbr.setGlobalLang('fr');
numbr(1000.234).format('$0,0.00');
// €1 000,23
`

`javascript
// Reuse a format
var fmt = numbr.compile('$ 0,0[.]00');
fmt.run(1001);
// $ 1,001
`

`javascript
// Per-instance language, all output '1er'
var num = numbr(1);
num.setLang('es');
num.format('0o');

numbr(1, 'es').format('0o');

var fmt = numbr.compile('0o');
fmt.run(1, null, 'es');
`

`javascript
// Custom round function
numbr(2280002).format('0.00a', Math.ceil);
// 2.29m
`

`javascript
// Add custom formatting options
var boolConsumer = new numbr.Consumer('&', {
// null means use the step below, 0 means 'normal weight' i.e. I don't care about the execution order of this step
consume: new numbr.Step(null, 0),
step: function(state, output, pos){
output[pos] = !!state.num? 'true' : 'false';
}
});

numbr.addConsumer(boolConsumer);

numbr(1).format('0 is &');
// 1 is true
numbr(0).format('0 is &');
// 0 is false
`

Why duplicate Numeral.js?

Because I needed faster formatting times and extensibility for a project I am working on.

License

MIT

#Index

Classes

* class: Numbr
* [new Numbr(value, [lang])](#new_Numbr)
* [numbr.format([fmt], [roundFn])](#Numbr#format)
* numbr.setLang(lang)
* numbr.valueOf()
* numbr.value()
* numbr.set(num)
* numbr.clone()
* class: CompiledFormat
* new CompiledFormat(steps, opts, sortedPos)
* compiledFormat.run(num, roundFn, lang)
* class: Step
* [new Step(step, weight, [opts], [consumed])](#new_Step)
* class: Consumer
* new Consumer(tokens, def)

Namespaces

* numbr
* numbr.echoConsumer
* numbr.noopConsumer
* numbr.compile(fmt)
* numbr.zeroFormat(fmt)
* numbr.defaultFormat(fmt)
* numbr.loadLang(langCode, langDef)
* numbr.getGlobalLang()
* numbr.setGlobalLang(langCode)
* [numbr.language([langCode], [langDef])](#numbr.language)
* numbr.cacheEnabled(enabled)
* numbr.setDefaultConsumer(consumer)
* numbr.addConsumer(consumer)


#class: Numbr
Members

* class: Numbr
* [new Numbr(value, [lang])](#new_Numbr)
* [numbr.format([fmt], [roundFn])](#Numbr#format)
* numbr.setLang(lang)
* numbr.valueOf()
* numbr.value()
* numbr.set(num)
* numbr.clone()


##new Numbr(value, [lang])
A wrapper for numeral-like formatting.
Stores the given value for further formatting.

Params

- value number
- \[lang\] string


##numbr.format([fmt], [roundFn])
Formats the wrapped value according to fmt.
By default, the format is compiled into a series of transformations and then cached globally, if you'd like to
disable the caching feature, use cacheEnabled.

Params

- \[fmt=defaultFormat\] string
- \[roundFn=Math.round\] function

Returns: string - the formatted number

##numbr.setLang(lang)
Sets the language for this Numbr.
The provided language must be already loaded via loadLang.

Params

- lang - the language code


##numbr.valueOf()
Returns: number

##numbr.value()
Access to the wrapped value

Returns: number

##numbr.set(num)
Sets the wrapped value

Params

- num number


##numbr.clone()
Returns a new Numbr object with the same value and language as this Numbr.

Returns: Numbr

#class: CompiledFormat
Members

* class: CompiledFormat
* new CompiledFormat(steps, opts, sortedPos)
* compiledFormat.run(num, roundFn, lang)


##new CompiledFormat(steps, opts, sortedPos)
A wrapper object for compiled formats.
Objects of this class should not be created directly. Use compile instead.

Params

- steps Array.<Step> - An array of step functions to be called during run
- opts object - A options object that will be passed to every step function as part of the run state
- sortedPos Array. - An array of output position indexes of each step in steps


##compiledFormat.run(num, roundFn, lang)
Runs all the transformation step functions using the given number and rounding function.

Params

- num - The number to format
- roundFn function - A rounding function
- lang string - The language code

Returns: string - the formatted number

#class: Step
Members

* class: Step
* [new Step(step, weight, [opts], [consumed])](#new_Step)


##new Step(step, weight, [opts], [consumed])
Params

- step function
- weight number
- \[opts\] object
- \[consumed\] number


#class: Consumer
Members

* class: Consumer
* new Consumer(tokens, def)


##new Consumer(tokens, def)
Params

- tokens string - A list of characters which will trigger this consumer
- def object - The consumer definition


#numbr
Function wrapper for creating new Numbr instances, it also has useful static methods to
control the global module behaviour.

All classes can be accessed via numbr.ClassName, e.g. numbr.Numbr, numbr.CompiledFormat, etc.

Params

- value number
- \[lang\] string

Returns: Numbr
Members

* numbr
* numbr.echoConsumer
* numbr.noopConsumer
* numbr.compile(fmt)
* numbr.zeroFormat(fmt)
* numbr.defaultFormat(fmt)
* numbr.loadLang(langCode, langDef)
* numbr.getGlobalLang()
* numbr.setGlobalLang(langCode)
* [numbr.language([langCode], [langDef])](#numbr.language)
* numbr.cacheEnabled(enabled)
* numbr.setDefaultConsumer(consumer)
* numbr.addConsumer(consumer)


##numbr.echoConsumer
A simple consumer that echoes back as many characters as possible in one step.
This is the default consumer.

Type: Consumer

##numbr.noopConsumer
A simple consumer that consumes the single character is given and does nothing else.
You can set this consumer as the default by using setDefaultConsumer

Type: Consumer

##numbr.compile(fmt)
Compiles the given string into a CompiledFormat object ready to be used.

Params

- fmt string

Returns: CompiledFormat

##numbr.zeroFormat(fmt)
Sets the global zero format.
If defined, the zero format is used as the outout of format whenever the wrapped value === 0.

Params

- fmt


##numbr.defaultFormat(fmt)
Sets the default format.
The default format is used if format is called without arguments. By default, the format is '0.0'.

Params

- fmt string


##numbr.loadLang(langCode, langDef)
Stores the given language definition with the code langCode.

Params

- langCode string
- langDef object


##numbr.getGlobalLang()
Access the global language code.

Returns: string

##numbr.setGlobalLang(langCode)
Sets the global language.

Params

- langCode


##numbr.language([langCode], [langDef])
Gets the global language, sets the global language or loads a language.
If called with no arguments, returns the global language.
If called with just the language code, it sets the global language.
If called with both arguments, the language is just loaded.

Params

- \[langCode\] string - The language code
- \[langDef\] object - A valid language definition


##numbr.cacheEnabled(enabled)
Enables or disables the format cache.
By default every format is compiled into a series of transformation functions that are cached and reused every
time format is called.

Disabling the cache may cause a significant performance hit and it is not recommended. Most applications will
probably use just a handful of formats, so the memory overhead is non-existent.

Params

- enabled boolean` - Whether to enable or disable the cache


##numbr.setDefaultConsumer(consumer)
Sets the default consumer.
The default consumer is used when no other consumer is able to consume a slice of the input format string.
By default, this is echoConsumer.

Params

- consumer Consumer


##numbr.addConsumer(consumer)
Adds a consumer to the list of global consumers.
Consumers are used to translate the string format input into actual transforming steps.

Params

- consumer Consumer