MochiKit Back to docs index

Name

MochiKit.Format - string formatting goes here

Synopsis

assert( truncToFixed(0.12345, 4) == "0.1234" );
assert( roundToFixed(0.12345, 4) == "0.1235" );
assert( twoDigitAverage(1, 0) == "0" );
assert( twoDigitFloat(1.2345) == "1.23" );
assert( twoDigitFloat(1) == "1" );
assert( percentFormat(1.234567) == "123.46%" );
assert( numberFormatter("###,###%")(125) == "12,500%" );
assert( numberFormatter("##.000")(1.25) == "1.250" );

Description

Formatting strings and stringifying numbers is boring, so a couple useful functions in that domain live here.

Dependencies

None.

Overview

Formatting Numbers

MochiKit provides an extensible number formatting facility, modeled loosely after the Number Format Pattern Syntax [1] from Java. numberFormatter(pattern[, placeholder=""[, locale="default"]) returns a function that converts Number to string using the given information. pattern is a string consisting of the following symbols:

Symbol Meaning
- If given, used as the position of the minus sign for negative numbers. If not given, the position to the left of the first number placeholder is used.
# The placeholder for a number that does not imply zero padding.
0 The placeholder for a number that implies zero padding. If it is used to the right of a decimal separator, it implies trailing zeros, otherwise leading zeros.
, The placeholder for a "thousands separator". May be used at most once, and it must be to the left of a decimal separator. Will be replaced by locale.separator in the result (the default is also ,).
. The decimal separator. The quantity of # or 0 after the decimal separator will determine the precision of the result. If no decimal separator is present, the fractional precision is 0 -- meaning that it will be rounded to the nearest integer.
% If present, the number will be multiplied by 100 and the % will be replaced by locale.percent.

API Reference

Functions

formatLocale(locale="default"):

Return a locale object for the given locale. locale may be either a string, which is looked up in the MochiKit.Format.LOCALE object, or a locale object. If no locale is given, LOCALE.default is used (equivalent to LOCALE.en_US).

Availability:
Available in MochiKit 1.3.1+

lstrip(str, chars="\s"):

Returns a string based on str with leading whitespace stripped.

If chars is given, then that expression will be used instead of whitespace. chars should be a string suitable for use in a RegExp [character set].

Availability:
Available in MochiKit 1.3.1+

numberFormatter(pattern, placeholder="", locale="default"):

Return a function formatNumber(aNumber) that formats numbers as a string according to the given pattern, placeholder and locale.

pattern is a string that describes how the numbers should be formatted, for more information see Formatting Numbers.

locale is a string of a known locale (en_US, de_DE, fr_FR, default) or an object with the following fields:

separator The "thousands" separator for this locale (en_US is ",")
decimal The decimal separator for this locale (en_US is ".")
percent The percent symbol for this locale (en_US is "%")
Availability:
Available in MochiKit 1.3.1+

percentFormat(aNumber):

Return a string representation of aNumber * 100, rounded to a maximum precision of 2 fractional digits. Roughly equivalent to: sprintf("%.2f%%", aNumber * 100)

In new code, you probably want to use: numberFormatter("#.##%")(aNumber) instead.

Availability:
Available in MochiKit 1.3.1+

roundToFixed(aNumber, precision):

Return a string representation of aNumber, rounded to precision digits with trailing zeros. This is similar to Number.toFixed(aNumber, precision), but this has implementation consistent rounding behavior (some versions of Safari round 0.5 down!) and also includes preceding 0 for numbers less than 1 (Safari, again).

For example, roundToFixed(0.1357, 2) returns 0.14 on every supported platform, where some return .13 for (0.1357).toFixed(2).

Availability:
Available in MochiKit 1.3.1+

rstrip(str, chars="\s"):

Returns a string based on str with trailing whitespace stripped.

If chars is given, then that expression will be used instead of whitespace. chars should be a string suitable for use in a RegExp [character set].

Availability:
Available in MochiKit 1.3.1+

strip(str, chars="\s"):

Returns a string based on str with leading and trailing whitespace stripped (equivalent to lstrip(rstrip(str, chars), chars)).

If chars is given, then that expression will be used instead of whitespace. chars should be a string suitable for use in a RegExp [character set].

Availability:
Available in MochiKit 1.3.1+

truncToFixed(aNumber, precision):

Return a string representation of aNumber, truncated to precision digits with trailing zeros. This is similar to aNumber.toFixed(precision), but this truncates rather than rounds and has implementation consistent behavior for numbers less than 1. Specifically, truncToFixed(aNumber, precision) will always have a preceding 0 for numbers less than 1.

For example, truncToFixed(0.1357, 2) returns 0.13.

Availability:
Available in MochiKit 1.3.1+

twoDigitAverage(numerator, denominator):

Calculate an average from a numerator and a denominator and return it as a string rounded to a maximum precision of two fractional digits (e.g. "1.23").

If the denominator is 0, "0" will be returned instead of NaN.

Availability:
Available in MochiKit 1.3.1+

twoDigitFloat(aNumber):

Return a string representation of aNumber, rounded to a maximum precision of 2 fractional digits. This is a variation of roundToFixed(aNumber, 2) that removes trailing zeros from the fractional part.

For example, twoDigitFloat(0.1357) returns 0.14 and twoDigitFloat(12.00) returns 12.

In new code, you probably want to use: numberFormatter("#.##")(aNumber) instead.

Availability:
Available in MochiKit 1.3.1+

See Also

[1]Java Number Format Pattern Syntax: http://java.sun.com/docs/books/tutorial/i18n/format/numberpattern.html

Authors