/tine20/library/ExtJS/src/util/Format.js

/*!
 * Ext JS Library 3.1.1
 * Copyright(c) 2006-2010 Ext JS, LLC
 * licensing@extjs.com
 * http://www.extjs.com/license
 */
/**

 * @class Ext.util.Format

 * Reusable data formatting functions

 * @singleton

 */

Ext.util.Format = function(){

    var trimRe = /^\s+|\s+$/g,

        stripTagsRE = /<\/?[^>]+>/gi,

        stripScriptsRe = /(?:<script.*?>)((\n|\r|.)*?)(?:<\/script>)/ig,

        nl2brRe = /\r?\n/g;

        

    return {

        /**

         * Truncate a string and add an ellipsis ('...') to the end if it exceeds the specified length

         * @param {String} value The string to truncate

         * @param {Number} length The maximum length to allow before truncating

         * @param {Boolean} word True to try to find a common work break

         * @return {String} The converted text

         */

        ellipsis : function(value, len, word){

            if(value && value.length > len){

                if(word){

                    var vs = value.substr(0, len - 2),

                        index = Math.max(vs.lastIndexOf(' '), vs.lastIndexOf('.'), vs.lastIndexOf('!'), vs.lastIndexOf('?'));

                    if(index == -1 || index < (len - 15)){

                        return value.substr(0, len - 3) + "...";

                    }else{

                        return vs.substr(0, index) + "...";

                    }

                } else{

                    return value.substr(0, len - 3) + "...";

                }

            }

            return value;

        },



        /**

         * 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

         */

        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 {String} defaultValue The value to insert of it's undefined (defaults to "")

         * @return {String}

         */

        defaultValue : function(value, defaultValue){

            return value !== undefined && value !== '' ? value : defaultValue;

        },



        /**

         * Convert certain characters (&, <, >, and ') to their HTML character equivalents for literal display in web pages.

         * @param {String} value The string to encode

         * @return {String} The encoded text

         */

        htmlEncode : function(value){

            return !value ? value : String(value).replace(/&/g, "&amp;").replace(/>/g, "&gt;").replace(/</g, "&lt;").replace(/"/g, "&quot;");

        },



        /**

         * Convert certain characters (&, <, >, and ') from their HTML character equivalents.

         * @param {String} value The string to decode

         * @return {String} The decoded text

         */

        htmlDecode : function(value){

            return !value ? value : String(value).replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&quot;/g, '"').replace(/&amp;/g, "&");

        },



        /**

         * Trims any whitespace from either side of a string

         * @param {String} value The text to trim

         * @return {String} The trimmed text

         */

        trim : function(value){

            return String(value).replace(trimRe, "");

        },



        /**

         * 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

         */

        substr : function(value, start, length){

            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

         */

        lowercase : function(value){

            return String(value).toLowerCase();

        },



        /**

         * Converts a string to all upper case letters

         * @param {String} value The text to convert

         * @return {String} The converted text

         */

        uppercase : function(value){

            return String(value).toUpperCase();

        },



        /**

         * Converts the first character only of a string to upper case

         * @param {String} value The text to convert

         * @return {String} The converted text

         */

        capitalize : function(value){

            return !value ? value : value.charAt(0).toUpperCase() + value.substr(1).toLowerCase();

        },



        // private

        call : function(value, fn){

            if(arguments.length > 2){

                var args = Array.prototype.slice.call(arguments, 2);

                args.unshift(value);

                return eval(fn).apply(window, args);

            }else{

                return eval(fn).call(window, value);

            }

        },



        /**

         * Format a number as US currency

         * @param {Number/String} value The numeric value to format

         * @return {String} The formatted currency string

         */

        usMoney : function(v){

            v = (Math.round((v-0)*100))/100;

            v = (v == Math.floor(v)) ? v + ".00" : ((v*10 == Math.floor(v*10)) ? v + "0" : v);

            v = String(v);

            var ps = v.split('.'),

                whole = ps[0],

                sub = ps[1] ? '.'+ ps[1] : '.00',

                r = /(\d+)(\d{3})/;

            while (r.test(whole)) {

                whole = whole.replace(r, '$1' + ',' + '$2');

            }

            v = whole + sub;

            if(v.charAt(0) == '-'){

                return '-$' + v.substr(1);

            }

            return "$" +  v;

        },



        /**

         * Parse a value into a formatted date using the specified format pattern.

         * @param {String/Date} value The value to format (Strings must conform to the format expected by the javascript Date object's <a href="http://www.w3schools.com/jsref/jsref_parse.asp">parse()</a> method)

         * @param {String} format (optional) Any valid date format string (defaults to 'm/d/Y')

         * @return {String} The formatted date string

         */

        date : function(v, format){

            if(!v){

                return "";

            }

            if(!Ext.isDate(v)){

                v = new Date(Date.parse(v));

            }

            return v.dateFormat(format || "m/d/Y");

        },



        /**

         * 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

         * @return {Function} The date formatting function

         */

        dateRenderer : function(format){

            return function(v){

                return Ext.util.Format.date(v, format);

            };

        },

        

        /**

         * Strips all HTML tags

         * @param {Mixed} 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

         * @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

         */

        fileSize : function(size){

            if(size < 1024) {

                return size + " bytes";

            } else if(size < 1048576) {

                return (Math.round(((size*10) / 1024))/10) + " KB";

            } else {

                return (Math.round(((size*10) / 1048576))/10) + " MB";

            }

        },



        /**

         * 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.

         */

        math : function(){

            var fns = {};

            return function(v, a){

                if(!fns[a]){

                    fns[a] = new Function('v', 'return v ' + a + ';');

                }

                return fns[a](v);

            }

        }(),



        /**

         * 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.

         * @return {Number} The rounded value.

         */

        round : function(value, precision) {

            var result = Number(value);

            if (typeof precision == 'number') {

                precision = Math.pow(10, precision);

                result = Math.round(value * precision) / precision;

            }

            return result;

        },



        /**

         * Formats the number according to the format string.

         * <div style="margin-left:40px">examples (123456.789):

         * <div style="margin-left:10px">

         * 0 - (123456) show only digits, no precision<br>

         * 0.00 - (123456.78) show only digits, 2 precision<br>

         * 0.0000 - (123456.7890) show only digits, 4 precision<br>

         * 0,000 - (123,456) show comma and digits, no precision<br>

         * 0,000.00 - (123,456.78) show comma and digits, 2 precision<br>

         * 0,0.00 - (123,456.78) shortcut method, show comma and digits, 2 precision<br>

         * To reverse the grouping (,) and decimal (.) for international numbers, add /i to the end.

         * For example: 0.000,00/i

         * </div></div>

         * @param {Number} v The number to format.

         * @param {String} format The way you would like to format this text.

         * @return {String} The formatted number.

         */

        number: function(v, format) {

            if(!format){

		        return v;

		    }

		    v = Ext.num(v, NaN);

            if (isNaN(v)){

                return '';

            }

		    var comma = ',',

		        dec = '.',

		        i18n = false,

		        neg = v < 0;

		

		    v = Math.abs(v);

		    if(format.substr(format.length - 2) == '/i'){

		        format = format.substr(0, format.length - 2);

		        i18n = true;

		        comma = '.';

		        dec = ',';

		    }

		

		    var hasComma = format.indexOf(comma) != -1, 

		        psplit = (i18n ? format.replace(/[^\d\,]/g, '') : format.replace(/[^\d\.]/g, '')).split(dec);

		

		    if(1 < psplit.length){

		        v = v.toFixed(psplit[1].length);

		    }else if(2 < psplit.length){

		        throw ('NumberFormatException: invalid format, formats should have no more than 1 period: ' + format);

		    }else{

		        v = v.toFixed(0);

		    }

		

		    var fnum = v.toString();

		    if(hasComma){

		        psplit = fnum.split('.');

		

		        var cnum = psplit[0], parr = [], j = cnum.length, m = Math.floor(j / 3), n = cnum.length % 3 || 3;

		

		        for(var i = 0; i < j; i += n){

		            if(i != 0){

		                n = 3;

		            }

		            parr[parr.length] = cnum.substr(i, n);

		            m -= 1;

		        }

		        fnum = parr.join(comma);

		        if(psplit[1]){

		            fnum += dec + psplit[1];

		        }

		    }

		

		    return (neg ? '-' : '') + format.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

         */

        numberRenderer : function(format){

            return function(v){

                return Ext.util.Format.number(v, format);

            };

        },



        /**

         * 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.

         * @param {Number} value The value to compare against

         * @param {String} singular The singular form of the word

         * @param {String} plural (optional) The plural form of the word (defaults to the singular with an "s")

         */

        plural : function(v, s, p){

            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.

         */

        nl2br : function(v){

            return Ext.isEmpty(v) ? '' : v.replace(nl2brRe, '<br/>');

        }

    }

}();