X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..refs/heads/master:/docs/source/Format.html diff --git a/docs/source/Format.html b/docs/source/Format.html index 2e44a03d..2b95578f 100644 --- a/docs/source/Format.html +++ b/docs/source/Format.html @@ -1,7 +1,24 @@ -Sencha Documentation Project
/**
+
+
+
+  
+  The source code
+  
+  
+  
+  
+
+
+  
/**
  * @class Ext.util.Format
 
-This class is a centralized place for formatting functions inside the library. It includes
+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__
@@ -13,10 +30,10 @@ Options include:
 - currenyPrecision
 - currencySign
 - currencyAtEnd
-This class also uses the default date format defined here: {@link Ext.date#defaultFormat}.
+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 
+There are two helper functions that return a new function that can be used in conjunction with
 grid renderers:
 
     columns: [{
@@ -26,7 +43,7 @@ grid renderers:
         dataIndex: 'time',
         renderer: Ext.util.Format.numberRenderer('0.000')
     }]
-    
+
 Functions that only take a single argument can also be passed directly:
     columns: [{
         dataIndex: 'cost',
@@ -35,7 +52,7 @@ Functions that only take a single argument can also be passed directly:
         dataIndex: 'productCode',
         renderer: Ext.util.Format.uppercase
     }]
-    
+
 __Using with XTemplates__
 XTemplates can also directly use Ext.util.Format functions:
 
@@ -64,59 +81,54 @@ XTemplates can also directly use Ext.util.Format functions:
         I18NFormatCleanRe;
 
     Ext.apply(UtilFormat, {
-        /**
-         * @type String
-         * @property thousandSeparator
+        /**
+         * @property {String} thousandSeparator
          * <p>The character that the {@link #number} function uses as a thousand separator.</p>
-         * <p>This defaults to <code>,</code>, but may be overridden in a locale file.</p>
+         * <p>This may be overridden in a locale file.</p>
          */
         thousandSeparator: ',',
 
-        /**
-         * @type String
-         * @property decimalSeparator
+        /**
+         * @property {String} decimalSeparator
          * <p>The character that the {@link #number} function uses as a decimal point.</p>
-         * <p>This defaults to <code>.</code>, but may be overridden in a locale file.</p>
+         * <p>This may be overridden in a locale file.</p>
          */
         decimalSeparator: '.',
 
-        /**
-         * @type Number
-         * @property currencyPrecision
+        /**
+         * @property {Number} currencyPrecision
          * <p>The number of decimal places that the {@link #currency} function displays.</p>
-         * <p>This defaults to <code>2</code>, but may be overridden in a locale file.</p>
+         * <p>This may be overridden in a locale file.</p>
          */
         currencyPrecision: 2,
 
-        /**
-         * @type String
-         * @property currencySign
+        /**
+         * @property {String} currencySign
          * <p>The currency sign that the {@link #currency} function displays.</p>
-         * <p>This defaults to <code>$</code>, but may be overridden in a locale file.</p>
+         * <p>This may be overridden in a locale file.</p>
          */
         currencySign: '$',
 
-        /**
-         * @type Boolean
-         * @property currencyAtEnd
+        /**
+         * @property {Boolean} currencyAtEnd
          * <p>This may be set to <code>true</code> to make the {@link #currency} function
          * append the currency sign to the formatted value.</p>
-         * <p>This defaults to <code>false</code>, but may be overridden in a locale file.</p>
+         * <p>This may be overridden in a locale file.</p>
          */
         currencyAtEnd: false,
 
-        /**
+        /**
          * Checks a reference and converts it to empty string if it is undefined
-         * @param {Mixed} value Reference to check
-         * @return {Mixed} Empty string if converted, otherwise the original value
+         * @param {Object} value Reference to check
+         * @return {Object} Empty string if converted, otherwise the original value
          */
         undef : function(value) {
             return value !== undefined ? value : "";
         },
 
-        /**
+        /**
          * Checks a reference and converts it to the default value if it's empty
-         * @param {Mixed} value Reference to check
+         * @param {Object} value Reference to check
          * @param {String} defaultValue The value to insert of it's undefined (defaults to "")
          * @return {String}
          */
@@ -124,7 +136,7 @@ XTemplates can also directly use Ext.util.Format functions:
             return value !== undefined && value !== '' ? value : defaultValue;
         },
 
-        /**
+        /**
          * Returns a substring from within an original string
          * @param {String} value The original text
          * @param {Number} start The start index of the substring
@@ -135,7 +147,7 @@ XTemplates can also directly use Ext.util.Format functions:
             return String(value).substr(start, length);
         },
 
-        /**
+        /**
          * Converts a string to all lower case letters
          * @param {String} value The text to convert
          * @return {String} The converted text
@@ -144,7 +156,7 @@ XTemplates can also directly use Ext.util.Format functions:
             return String(value).toLowerCase();
         },
 
-        /**
+        /**
          * Converts a string to all upper case letters
          * @param {String} value The text to convert
          * @return {String} The converted text
@@ -153,7 +165,7 @@ XTemplates can also directly use Ext.util.Format functions:
             return String(value).toUpperCase();
         },
 
-        /**
+        /**
          * Format a number as US currency
          * @param {Number/String} value The numeric value to format
          * @return {String} The formatted currency string
@@ -162,7 +174,7 @@ XTemplates can also directly use Ext.util.Format functions:
             return UtilFormat.currency(v, '$', 2);
         },
 
-        /**
+        /**
          * 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})
@@ -184,7 +196,7 @@ XTemplates can also directly use Ext.util.Format functions:
             for (; i < decimals; i++) {
                 format += '0';
             }
-            v = UtilFormat.number(v, format); 
+            v = UtilFormat.number(v, format);
             if ((end || UtilFormat.currencyAtEnd) === true) {
                 return Ext.String.format("{0}{1}{2}", negativeSign, v, currencySign || UtilFormat.currencySign);
             } else {
@@ -192,7 +204,7 @@ XTemplates can also directly use Ext.util.Format functions:
             }
         },
 
-        /**
+        /**
          * Formats the passed date using the specified format pattern.
          * @param {String/Date} value The value to format. If a string is passed, it is converted to a Date by the Javascript
          * Date object's <a href="http://www.w3schools.com/jsref/jsref_parse.asp">parse()</a> method.
@@ -209,7 +221,7 @@ XTemplates can also directly use Ext.util.Format functions:
             return Ext.Date.dateFormat(v, format || Ext.Date.defaultFormat);
         },
 
-        /**
+        /**
          * 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
@@ -220,25 +232,25 @@ XTemplates can also directly use Ext.util.Format functions:
             };
         },
 
-        /**
+        /**
          * Strips all HTML tags
-         * @param {Mixed} value The text from which to strip tags
+         * @param {Object} value The text from which to strip tags
          * @return {String} The stripped text
          */
         stripTags : function(v) {
             return !v ? v : String(v).replace(stripTagsRE, "");
         },
 
-        /**
+        /**
          * Strips all script tags
-         * @param {Mixed} value The text from which to strip script tags
+         * @param {Object} value The text from which to strip script tags
          * @return {String} The stripped text
          */
         stripScripts : function(v) {
             return !v ? v : String(v).replace(stripScriptsRe, "");
         },
 
-        /**
+        /**
          * 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
@@ -253,11 +265,12 @@ XTemplates can also directly use Ext.util.Format functions:
             }
         },
 
-        /**
+        /**
          * It does simple math for use in a template, for example:<pre><code>
          * var tpl = new Ext.Template('{value} * 10 = {value:math("* 10")}');
          * </code></pre>
          * @return {Function} A function that operates on the passed value.
+         * @method
          */
         math : function(){
             var fns = {};
@@ -270,7 +283,7 @@ XTemplates can also directly use Ext.util.Format functions:
             };
         }(),
 
-        /**
+        /**
          * 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.
@@ -285,14 +298,14 @@ XTemplates can also directly use Ext.util.Format functions:
             return result;
         },
 
-        /**
+        /**
          * <p>Formats the passed number according to the passed format string.</p>
          * <p>The number of digits after the decimal separator character specifies the number of
          * decimal places in the resulting string. The <u>local-specific</u> decimal character is used in the result.</p>
          * <p>The <i>presence</i> of a thousand separator character in the format string specifies that
          * the <u>locale-specific</u> thousand separator (if any) is inserted separating thousand groups.</p>
          * <p>By default, "," is expected as the thousand separator, and "." is expected as the decimal separator.</p>
-         * <p><b>New to Ext4</b></p>
+         * <p><b>New to Ext JS 4</b></p>
          * <p>Locale-specific characters are always used in the formatted output when inserting
          * thousand and decimal separators.</p>
          * <p>The format string must specify separator characters according to US/UK conventions ("," as the
@@ -314,8 +327,7 @@ XTemplates can also directly use Ext.util.Format functions:
          * @param {String} format The way you would like to format this text.
          * @return {String} The formatted number.
          */
-        number:
-            function(v, formatString) {
+        number: function(v, formatString) {
             if (!formatString) {
                 return v;
             }
@@ -395,10 +407,19 @@ XTemplates can also directly use Ext.util.Format functions:
                 }
             }
 
+            if (neg) {
+                /*
+                 * Edge case. If we have a very small negative number it will get rounded to 0,
+                 * however the initial check at the top will still report as negative. Replace
+                 * everything but 1-9 and check if the string is empty to determine a 0 value.
+                 */
+                neg = fnum.replace(/[^1-9]/g, '') !== '';
+            }
+
             return (neg ? '-' : '') + formatString.replace(/[\d,?\.?]+/, fnum);
         },
 
-        /**
+        /**
          * 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
@@ -409,7 +430,7 @@ XTemplates can also directly use Ext.util.Format functions:
             };
         },
 
-        /**
+        /**
          * Selectively do a plural form of a word based on a numeric value. For example, in a template,
          * {commentCount:plural("Comment")}  would result in "1 Comment" if commentCount was 1 or would be "x Comments"
          * if the value is 0 or greater than 1.
@@ -421,7 +442,7 @@ XTemplates can also directly use Ext.util.Format functions:
             return v +' ' + (v == 1 ? s : (p ? p : s+'s'));
         },
 
-        /**
+        /**
          * Converts newline characters to the HTML tag &lt;br/>
          * @param {String} The string value to format.
          * @return {String} The string with embedded &lt;br/> tags in place of newlines.
@@ -430,48 +451,59 @@ XTemplates can also directly use Ext.util.Format functions:
             return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, '<br/>');
         },
 
-        /**
-         * Capitalize the given string. See {@link Ext.String#capitalize}.
+        /**
+         * Alias for {@link Ext.String#capitalize}.
+         * @method
+         * @alias Ext.String#capitalize
          */
         capitalize: Ext.String.capitalize,
 
-        /**
-         * Truncate a string and add an ellipsis ('...') to the end if it exceeds the specified length.
-         * See {@link Ext.String#ellipsis}.
+        /**
+         * Alias for {@link Ext.String#ellipsis}.
+         * @method
+         * @alias Ext.String#ellipsis
          */
         ellipsis: Ext.String.ellipsis,
 
-        /**
-         * Formats to a string. See {@link Ext.String#format}
+        /**
+         * Alias for {@link Ext.String#format}.
+         * @method
+         * @alias Ext.String#format
          */
         format: Ext.String.format,
 
-        /**
-         * Convert certain characters (&, <, >, and ') from their HTML character equivalents.
-         * See {@link Ext.string#htmlDecode}.
+        /**
+         * Alias for {@link Ext.String#htmlDecode}.
+         * @method
+         * @alias Ext.String#htmlDecode
          */
         htmlDecode: Ext.String.htmlDecode,
 
-        /**
-         * Convert certain characters (&, <, >, and ') to their HTML character equivalents for literal display in web pages.
-         * See {@link Ext.String#htmlEncode}.
+        /**
+         * Alias for {@link Ext.String#htmlEncode}.
+         * @method
+         * @alias Ext.String#htmlEncode
          */
         htmlEncode: Ext.String.htmlEncode,
 
-        /**
-         * Adds left padding to a string. See {@link Ext.String#leftPad}
+        /**
+         * Alias for {@link Ext.String#leftPad}.
+         * @method
+         * @alias Ext.String#leftPad
          */
         leftPad: Ext.String.leftPad,
 
-        /**
-         * Trims any whitespace from either side of a string. See {@link Ext.String#trim}.
+        /**
+         * Alias for {@link Ext.String#trim}.
+         * @method
+         * @alias Ext.String#trim
          */
         trim : Ext.String.trim,
 
-        /**
+        /**
          * 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} v The encoded margins
+         * @param {Number/String} v The encoded margins
          * @return {Object} An object with margin sizes for top, right, bottom and left
          */
         parseBox : function(box) {
@@ -500,7 +532,7 @@ XTemplates can also directly use Ext.util.Format functions:
             };
         },
 
-        /**
+        /**
          * Escapes the passed string for use in a regular expression
          * @param {String} str
          * @return {String}
@@ -510,4 +542,6 @@ XTemplates can also directly use Ext.util.Format functions:
         }
     });
 })();
-
\ No newline at end of file +
+ +