Section 14.8. String Conversions and Value Formatting

14.8. String Conversions and Value Formatting

A common need in any software is to convert values between machine-maintained formats and human-understandable ones. MochiKit provides some of the most commonly required functions for working with dates and formatting numeric values as strings.

14.8.1. Working with Dates and Times

JavaScript has a handy Date object for keeping track of dates and times. Unfortunately, however, when you make an Ajax request to a server, that server isn't going to understand that Date object (even if you could find a way to directly send it!). And you're not going to get a JavaScript date back from the server. MochiKit.DateTime provides a set of functions for converting dates between JavaScript and the rest of the world.

To get a JavaScript Date object, use one of the following functions:

• americanDate(str) MM/DD/YYYY

• isoDate(str) ISO 8601 date (YYYY-MM-DD)

• isoTimestamp(str) ISO 8601 timestamp (YYYY-MM-DD hh:mm:ss or YYYY-MM-DDThh:mm:ssZ)

To convert a JavaScript Date object for use externally, use one of the following functions:

• toISOTime(date) Returns hh:mm:ss

• toISOTimestamp(date, realISO=false) Returns YYYY-MM-DD hh:mm:ss or, if realISO is true, YYYY-MM-DDThh:mm:ssZ

• toISODate(date) YYYY-MM-DD

• toPaddedAmericanDate(date) MM/DD/YYYY (for example, 04/05/2005)

• toAmericanDate(date) M/D/YYYY (for example, 4/5/2005)

14.8.2. Formatting Numbers

MochiKit.Format provides useful string formatting functions, including a powerful number formatter. No one likes to see a number such as 483483232 on a web page, although people in different countries might argue about what the proper way to display that number is. In the United States, we'd like that number to be formatted as 483,483,232. Here's how we do that with MochiKit:

  >>> f = numberFormatter("#,###")   ("#,###")   >>> f(483483232)   "483,483,232"

numberFormatter(pattern, placeholder="", locale="default") returns a function that will format a number according to the pattern. If you provide a placeholder and the value presented for formatting isn't a number, you'll get that placeholder back. The locale can be a known locale (en_US, de_DE, fr_FR, etc.) or an object with separator (the "thousands" separator), decimal (the decimal separator), and percent (the symbol for a percent).

The pattern, of course, is the most interesting part of the numberFormatter call. For displaying numbers, MochiKit uses the following special characters:

- positions the minus sign for negative numbers.

# a position for a number that is not zero padded.

0 a position for a number that will be zero padded.

, the "thousands" separator. Only the first one applies.

. the decimal separator.

% a percent sign.

Note that you'll actually get the locale-specific characters rather than ",", "." and "%" in the final, formatted string. Here are some more examples to show off usage of the formatter:

    >>> numberFormatter("USD $#,###.00")(15)    "USD $15.00"    >>> numberFormatter("#,### %")(0.75)    "1 %"    >>> numberFormatter("#,### %")(75)    "75 %"    >>> numberFormatter("#,###%")(75)    "7,500%"    >>> numberFormatter("0,000")(75)    "0,075"    >>> numberFormatter("##,##")(7534)    "75,34"

You can see from the middle examples that the position of the % sign makes a difference in whether MochiKit treats the number as a percentage.

14.8.3. Other String Formatting Functions

MochiKit includes the following additional simple functions for formatting values.

• lstrip(str, chars="\s") Strips off the whitespace on the left of the string, or strips off any characters that match the chars regular expression

• rstrip(str, chars="\s") Strips whitespace off of the right of the string

• strip(str, chars="\s") Strips whitespace off of the right and left

• roundToFixed(num, precision) Returns a string with num rounded to precision digits with trailing zeros (and works consistently across browsers)

• TRuncToFixed(num, precision) Returns a string with num TRuncated to precision digits

• twoDigitAverage(numerator, denominator) Returns numerator/denominator rounded to two digits, with the special feature that a 0 in the denominator will return 0.