1 /**
  2  * Abstract; see an implementing class.
  3  *
  4  * @class Represents an abstract text formatter and parser. A <i>format</i> is a
  5  * function that converts an object of a given type, such as a <tt>Date</tt>, to
  6  * a human-readable string representation. The format may also have a
  7  * {@link #parse} method for converting a string representation back to the
  8  * given object type.
  9  *
 10  * <p>Because formats are themselves functions, they can be used directly as
 11  * mark properties. For example, if the data associated with a label are dates,
 12  * a date format can be used as label text:
 13  *
 14  * <pre>    .text(pv.Format.date("%m/%d/%y"))</pre>
 15  *
 16  * And as with scales, if the format is used in multiple places, it can be
 17  * convenient to declare it as a global variable and then reference it from the
 18  * appropriate property functions. For example, if the data has a <tt>date</tt>
 19  * attribute, and <tt>format</tt> references a given date format:
 20  *
 21  * <pre>    .text(function(d) format(d.date))</pre>
 22  *
 23  * Similarly, to parse a string into a date:
 24  *
 25  * <pre>var date = format.parse("4/30/2010");</pre>
 26  *
 27  * Not all format implementations support parsing. See the implementing class
 28  * for details.
 29  *
 30  * @see pv.Format.date
 31  * @see pv.Format.number
 32  * @see pv.Format.time
 33  */
 34 pv.Format = {};
 35 
 36 /**
 37  * Formats the specified object, returning the string representation.
 38  *
 39  * @function
 40  * @name pv.Format.prototype.format
 41  * @param {object} x the object to format.
 42  * @returns {string} the formatted string.
 43  */
 44 
 45 /**
 46  * Parses the specified string, returning the object representation.
 47  *
 48  * @function
 49  * @name pv.Format.prototype.parse
 50  * @param {string} x the string to parse.
 51  * @returns {object} the parsed object.
 52  */
 53 
 54 /**
 55  * @private Given a string that may be used as part of a regular expression,
 56  * this methods returns an appropriately quoted version of the specified string,
 57  * with any special characters escaped.
 58  *
 59  * @param {string} s a string to quote.
 60  * @returns {string} the quoted string.
 61  */
 62 pv.Format.re = function(s) {
 63   return s.replace(/[\\\^\$\*\+\?\[\]\(\)\.\{\}]/g, "\\$&");
 64 };
 65 
 66 /**
 67  * @private Optionally pads the specified string <i>s</i> so that it is at least
 68  * <i>n</i> characters long, using the padding character <i>c</i>.
 69  *
 70  * @param {string} c the padding character.
 71  * @param {number} n the minimum string length.
 72  * @param {string} s the string to pad.
 73  * @returns {string} the padded string.
 74  */
 75 pv.Format.pad = function(c, n, s) {
 76   var m = n - String(s).length;
 77   return (m < 1) ? s : new Array(m + 1).join(c) + s;
 78 };
 79