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