# Name

MochiKit.Format - string formatting goes here

# Function Index

formatLocale(locale="default")
lstrip(str, chars="\s")
numberFormatter(pattern, placeholder="", locale="default")
percentFormat(someFloat)
roundToFixed(aNumber, precision)
rstrip(str, chars="\s")
strip(str, chars="\s")
truncToFixed(aNumber, precision)
twoDigitAverage(numerator, denominator)
twoDigitFloat(someFloat)

# 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(someFloat):

> Roughly equivalent to: `sprintf("%.2f%%", someFloat * 100)`

> In new code, you probably want to use: numberFormatter("#.##%")(someFloat) 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 with two digits of precision (e.g. "1.23").

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

> Availability:
>   Available in MochiKit 1.3.1+

twoDigitFloat(someFloat):

> Roughly equivalent to: `sprintf("%.2f", someFloat)`

> In new code, you probably want to use numberFormatter("#.##")(someFloat) 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

- Bob Ippolito <bob@redivi.com>

# Copyright

Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is dual-licensed free software; you can redistribute it and/or modify it under the terms of the MIT License or the Academic Free License v2.1.