/**
 * @class Ext.util.Format
 *  
 * This class is a centralized place for formatting functions. It includes
 * functions to format various different types of data, such as text, dates and numeric values.
 *  
 * ## Localization
 *
 * This class contains several options for localization. These can be set once the library has loaded,
 * all calls to the functions from that point will use the locale settings that were specified.
 *
 * Options include:
 *
 * - thousandSeparator
 * - decimalSeparator
 * - currencyPrecision
 * - currencySign
 * - currencyAtEnd
 *
 * This class also uses the default date format defined here: {@link Ext.Date#defaultFormat}.
 *
 * ## Using with renderers
 *
 * There are two helper functions that return a new function that can be used in conjunction with
 * grid renderers:
 *  
 *     columns: [{
 *         dataIndex: 'date',
 *         renderer: Ext.util.Format.dateRenderer('Y-m-d')
 *     }, {
 *         dataIndex: 'time',
 *         renderer: Ext.util.Format.numberRenderer('0.000')
 *     }]
 *  
 * Functions that only take a single argument can also be passed directly:
 *
 *     columns: [{
 *         dataIndex: 'cost',
 *         renderer: Ext.util.Format.usMoney
 *     }, {
 *         dataIndex: 'productCode',
 *         renderer: Ext.util.Format.uppercase
 *     }]
 *  
 * ## Using with XTemplates
 *
 * XTemplates can also directly use Ext.util.Format functions:
 *  
 *     new Ext.XTemplate([
 *         'Date: {startDate:date("Y-m-d")}',
 *         'Cost: {cost:usMoney}'
 *     ]);
 *
 * @singleton
 */
 
/**
 * @property {String} [defaultDateFormat='m/d/Y']
 * The global default date format.
 */
 
/**
 * @property {String} [thousandSeparator=","]
 * The character that the {@link #number} function uses as a thousand separator.
 *
 * This may be overridden in a locale file.
 * @locale
 */
 
/**
 * @property {String} [decimalSeparator="."]
 * The character that the {@link #number} function uses as a decimal point.
 *
 * This may be overridden in a locale file.
 * @locale
 */
 
/**
 * @property {Number} [currencyPrecision=2]
 * The number of decimal places that the {@link #currency} function displays.
 *
 * This may be overridden in a locale file.
 * @locale
 */
 
/**
 * @property {String} [currencySign="$"]
 * The currency sign that the {@link #currency} function displays.
 *
 * This may be overridden in a locale file.
 * @locale
 */
 
/**
 * @property {String} [currencySpacer='']
 * True to add a space between the currency and the value
 *
 * This may be overridden in a locale file.
 * @since 6.2.0
 * @locale
 */
 
/**
 * @property {String} [percentSign="%"]
 * The percent sign that the {@link #percent} function displays.
 *
 * This may be overridden in a locale file.
 * @locale
 */
 
/**
 * @property {Boolean} [currencyAtEnd=false]
 * This may be set to <code>true</code> to make the {@link #currency} function
 * append the currency sign to the formatted value.
 *
 * This may be overridden in a locale file.
 * @locale
 */
 
/**
 * @method nbsp
 * Returns a non-breaking space ("NBSP") for any "blank" value.
 * @param {Mixed} value 
 * @param {Boolean} [strict=true] Pass `false` to convert all falsey values to an
 * NBSP. By default, only '', `null` and `undefined` will be converted.
 * @return {Mixed}
 * @since 6.2.0
 */
 
/**
 * @method undef
 * Checks a reference and converts it to empty string if it is undefined.
 * @param {Object} value Reference to check
 * @return {Object} Empty string if converted, otherwise the original value
 */
 
/**
 * @method defaultValue
 * Checks a reference and converts it to the default value if it's empty.
 * @param {Object} value Reference to check
 * @param {String} [defaultValue=""] The value to insert of it's undefined.
 * @return {String}
 */
 
/**
 * Returns a substring from within an original string.
 * @param {String} value The original text
 * @param {Number} start The start index of the substring
 * @param {Number} length The length of the substring
 * @return {String} The substring
 * @method substr
 */
 
/**
 * @method
 * Converts a string to all lower case letters.
 * @param {String} value The text to convert
 * @return {String} The converted text
 */
 
/**
 * @method uppercase
 * Converts a string to all upper case letters.
 * @param {String} value The text to convert
 * @return {String} The converted text
 */
 
/**
 * @method usMoney
 * Format a number as US currency.
 * @param {Number/String} value The numeric value to format
 * @return {String} The formatted currency string
 */
 
/**
 * @method currency
 * Format a number as a currency.
 * @param {Number/String} value The numeric value to format
 * @param {String} [sign] The currency sign to use (defaults to {@link #currencySign})
 * @param {Number} [decimals] The number of decimals to use for the currency
 * (defaults to {@link #currencyPrecision})
 * @param {Boolean} [end] True if the currency sign should be at the end of the string
 * (defaults to {@link #currencyAtEnd})
 * @param {String} [currencySpacer] True to add a space between the currency and value
 * @return {String} The formatted currency string
 */
 
/**
 * @method date
 * Formats the passed date using the specified format pattern.
 * Note that this uses the native Javascript Date.parse() method and is therefore subject to its idiosyncrasies.
 * Most formats assume the local timezone unless specified. One notable exception is 'YYYY-MM-DD' (note the dashes)
 * which is typically interpreted in UTC and can cause date shifting.
 *
 * @param {String/Date} value The value to format. Strings must conform to the format
 * expected by the JavaScript Date object's
 * [parse() method](http://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date/parse).
 * @param {String} [format] Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
 * @return {String} The formatted date string.
 */
 
/**
 * @method dateRenderer
 * Returns a date rendering function that can be reused to apply a date format multiple times efficiently.
 * @param {String} format Any valid date format string. Defaults to {@link Ext.Date#defaultFormat}.
 * @return {Function} The date formatting function
 */
 
/**
 * @method hex
 * Returns the given number as a base 16 string at least `digits` in length. If
 * the number is fewer digits, 0's are prepended as necessary. If `digits` is
 * negative, the absolute value is the *exact* number of digits to return. In this
 * case, if then number has more digits, only the least significant digits are
 * returned.
 *
 *      expect(Ext.util.Format.hex(0x12e4, 2)).toBe('12e4');
 *      expect(Ext.util.Format.hex(0x12e4, -2)).toBe('e4');
 *      expect(Ext.util.Format.hex(0x0e, 2)).toBe('0e');
 *
 * @param {Number} value The number to format in hex.
 * @param {Number} digits 
 * @return {string}
 */
 
/**
 * @method or
 * Returns this result:
 *
 *      value || orValue
 *
 * The usefulness of this formatter method is in templates. For example:
 *
 *      {foo:or("bar")}
 *
 * @param {Boolean} value The "if" value.
 * @param {Mixed} orValue 
 */
 
/**
 * @method pick
 * If `value` is a number, returns the argument from that index. For example
 *
 *      var s = Ext.util.Format.pick(2, 'zero', 'one', 'two');
 *      // s === 'two'
 *
 * Otherwise, `value` is treated in a truthy/falsey manner like so:
 *
 *      var s = Ext.util.Format.pick(null, 'first', 'second');
 *      // s === 'first'
 *
 *      s = Ext.util.Format.pick({}, 'first', 'second');
 *      // s === 'second'
 *
 * The usefulness of this formatter method is in templates. For example:
 *
 *      {foo:pick("F","T")}
 *
 *      {bar:pick("first","second","third")}
 *
 * @param {Boolean} value The "if" value.
 * @param {Mixed} firstValue 
 * @param {Mixed} secondValue 
 */
 
/**
 * @method lessThanElse
 * Compares `value` against `threshold` and returns:
 *
 * - if `value` < `threshold` then it returns `below`
 * - if `value` > `threshold` then it returns `above`
 * - if `value` = `threshold` then it returns `equal` or `above` when `equal` is missing
 *
 * The usefulness of this formatter method is in templates. For example:
 *
 *      {foo:lessThanElse(0, 'negative', 'positive')}
 *
 *      {bar:lessThanElse(200, 'lessThan200', 'greaterThan200', 'equalTo200')}
 *
 * @param {Number} value Value that will be checked
 * @param {Number} threshold Value to compare against
 * @param {Mixed} below Value to return when `value` < `threshold`
 * @param {Mixed} above Value to return when `value` > `threshold`. If `value` = `threshold` and
 * `equal` is missing then `above` is returned.
 * @param {Mixed} equal Value to return when `value` = `threshold`
 * @return {Mixed}
 */
 
/**
 * @method sign
 * Checks if `value` is a positive or negative number and returns the proper param.
 *
 * The usefulness of this formatter method is in templates. For example:
 *
 *      {foo:sign("clsNegative","clsPositive")}
 *
 * @param {Number} value 
 * @param {Mixed} negative 
 * @param {Mixed} positive 
 * @param {Mixed} zero 
 * @return {Mixed}
 */
 
/**
 * @method stripTags
 * Strips all HTML tags.
 * @param {Object} value The text from which to strip tags
 * @return {String} The stripped text
 */
 
/**
 * @method stripScripts
 * Strips all script tags.
 * @param {Object} value The text from which to strip script tags
 * @return {String} The stripped text
 */
 
/**
 * @method fileSize
 * Simple format for a file size (xxx bytes, xxx KB, xxx MB).
 * @param {Number/String} size The numeric value to format
 * @return {String} The formatted file size
 */
 
/**
 * It does simple math for use in a template, for example:
 *
 *     var tpl = new Ext.Template('{value} * 10 = {value:math("* 10")}');
 *
 * @return {Function} A function that operates on the passed value.
 * @method math
 */
 
/**
 * @method round
 * Rounds the passed number to the required decimal precision.
 * @param {Number/String} value The numeric value to round.
 * @param {Number} [precision] The number of decimal places to which to round the
 * first parameter's value. If `undefined` the `value` is passed to `Math.round`
 * otherwise the value is returned unmodified.
 * @return {Number} The rounded value.
 */
 
/**
 * @method number
 * Formats the passed number according to the passed format string.
 *
 * The number of digits after the decimal separator character specifies the number of
 * decimal places in the resulting string. The *local-specific* decimal character is
 * used in the result.
 *
 * The *presence* of a thousand separator character in the format string specifies that
 * the *locale-specific* thousand separator (if any) is inserted separating thousand groups.
 *
 * By default, "," is expected as the thousand separator, and "." is expected as the decimal separator.
 *
 * Locale-specific characters are always used in the formatted output when inserting
 * thousand and decimal separators. These can be set using the {@link #thousandSeparator} and
 * {@link #decimalSeparator} options.
 *
 * The format string must specify separator characters according to US/UK conventions ("," as the
 * thousand separator, and "." as the decimal separator)
 *
 * To allow specification of format strings according to local conventions for separator characters, add
 * the string `/i` to the end of the format string. This format depends on the {@link #thousandSeparator} and
 * {@link #decimalSeparator} options. For example, if using European style separators, then the format string
 * can be specified as `'0.000,00'`. This would be equivalent to using `'0,000.00'` when using US style formatting.
 *
 * Examples (123456.789):
 *
 * - `0` - (123457) show only digits, no precision
 * - `0.00` - (123456.79) show only digits, 2 precision
 * - `0.0000` - (123456.7890) show only digits, 4 precision
 * - `0,000` - (123,457) show comma and digits, no precision
 * - `0,000.00` - (123,456.79) show comma and digits, 2 precision
 * - `0,0.00` - (123,456.79) shortcut method, show comma and digits, 2 precision
 * - `0.####` - (123,456.789) Allow maximum 4 decimal places, but do not right pad with zeroes
 * - `0.00##` - (123456.789) Show at least 2 decimal places, maximum 4, but do not right pad with zeroes
 *
 * @param {Number} v The number to format.
 * @param {String} formatString The way you would like to format this text.
 * @return {String} The formatted number.
 */
 
/**
 * @method numberRenderer
 * Returns a number rendering function that can be reused to apply a number format multiple
 * times efficiently.
 *
 * @param {String} format Any valid number format string for {@link #number}
 * @return {Function} The number formatting function
 */
 
/**
 * @method percent
 * Formats the passed number as a percentage according to the passed format string.
 * The number should be between 0 and 1 to represent 0% to 100%.
 *
 * @param {Number} value The percentage to format.
 * @param {String} [formatString="0"] See {@link #number} for details.
 * @return {String} The formatted percentage.
 */
 
/**
 * @method attributes
 * Formats an object of name value properties as HTML element attribute values suitable for using when creating textual markup.
 * @param {Object} attributes An object containing the HTML attributes as properties eg: `{height:40, vAlign:'top'}`
 */
 
/**
 * @method plural
 * Selectively return the plural form of a word based on a numeric value.
 *
 * For example, the following template would result in "1 Comment".  If the
 * value of `count` was 0 or greater than 1, the result would be "x Comments".
 *
 *     var tpl = new Ext.XTemplate('{count:plural("Comment")}');
 *
 *     tpl.apply({
 *         count: 1
 *     }); // returns "1 Comment"
 *
 * Examples using the static `plural` method call:
 *
 *     Ext.util.Format.plural(2, 'Comment');
 *     // returns "2 Comments"
 *
 *     Ext.util.Format.plural(4, 'person', 'people');
 *     // returns "4 people"
 *
 * @param {Number} value The value to compare against
 * @param {String} singular The singular form of the word
 * @param {String} [plural] The plural form of the word (defaults to the
 * singular form with an "s" appended)
 * @return {String} output The pluralized output of the passed singular form
 */
 
/**
 * @method nl2br
 * Converts newline characters to the HTML tag `<br/>`
 *
 * @param {String} v The string value to format.
 * @return {String} The string with embedded `<br/>` tags in place of newlines.
 */
 
/**
 * Alias for {@link Ext.String#capitalize}.
 * @method capitalize
 * @inheritdoc Ext.String#capitalize
 */
 
/**
 * Alias for {@link Ext.String#uncapitalize}.
 * @method uncapitalize
 * @inheritdoc Ext.String#uncapitalize
 */
 
/**
 * Alias for {@link Ext.String#ellipsis}.
 * @method ellipsis
 * @inheritdoc Ext.String#ellipsis
 */
 
/**
 * Alias for {@link Ext.String#escape}.
 * @method escape
 * @inheritdoc Ext.String#escape
 */
 
/**
 * Alias for {@link Ext.String#escapeRegex}.
 * @method escapeRegex
 * @inheritdoc Ext.String#escapeRegex
 */
 
/**
 * Alias for {@link Ext.String#htmlDecode}.
 * @method htmlDecode
 * @inheritdoc Ext.String#htmlDecode
 */
 
/**
 * Alias for {@link Ext.String#htmlEncode}.
 * @method htmlEncode
 * @inheritdoc Ext.String#htmlEncode
 */
 
/**
 * Alias for {@link Ext.String#leftPad}.
 * @method leftPad
 * @inheritdoc Ext.String#leftPad
 */
 
/**
 * Alias for {@link Ext.String#toggle}.
 * @method toggle
 * @inheritdoc Ext.String#toggle
 */
 
/**
 * Alias for {@link Ext.String#trim}.
 * @method trim
 * @inheritdoc Ext.String#trim
 */
 
/**
 * @method parseBox
 * Parses a number or string representing margin sizes into an object.
 * Supports CSS-style margin declarations (e.g. 10, "10", "10 10", "10 10 10" and
 * "10 10 10 10" are all valid options and would return the same result).
 *
 * @param {Number/String} box The encoded margins
 * @return {Object} An object with margin sizes for top, right, bottom and left
 */
 
/**
 * @method resource
 * Resolves the specified resource `url` with an optional `prefix`. This resolution
 * is based on {@link Ext#resolveResource}. The prefix is intended to be used for
 * a package or resource pool identifier.
 *
 * @param {String} url The resource url to resolve
 * @param {String} [prefix] A prefix/identifier to include in the resolution.
 * @return {String}
 */
 
/**
 * @method uri
 * Formats the given value using `encodeURI`.
 * @param {String} value The value to encode.
 * @returns {string}
 * @since 6.2.0
 */
 
/**
 * @method uriCmp
 * Formats the given value using `encodeURIComponent`.
 * @param {String} value The value to encode.
 * @returns {string}
 * @since 6.2.0
 */
 
/**
 * @method word
 * Returns the word at the given `index`. Spaces and punctuation are considered
 * as word separators by default. For example:
 *
 *      console.log(Ext.util.Format.word('Hello, my name is Bob.', 2);
 *      // == 'name'
 *
 * @param {String} value The sentence to break into words.
 * @param {Number} index The 0-based word index.
 * @param {String/RegExp} [sep="[\W\s]+"] The pattern by which to separate words.
 * @return {String} The requested word or empty string.
 */