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

var numbr = require('numbr');
 
numbr(1000.25).format('0,0.0');
// 1,000.3

// 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

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

// 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');

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

// 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])
  • numbr.format([fmt], [roundFn])
  • 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])
• 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.cacheEnabled(enabled)
  • numbr.setDefaultConsumer(consumer)
  • numbr.addConsumer(consumer)

class: Numbr

Members

• class: Numbr
  • new Numbr(value, [lang])
  • numbr.format([fmt], [roundFn])
  • 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.<number> - 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(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.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