Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / JSON.html
index 5a1ecb1..4bff440 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.util.JSON"></div>/**
- * @class Ext.util.JSON
- * Modified version of Douglas Crockford"s json.js that doesn"t
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-JSON'>/**
+</span> * @class Ext.JSON
+ * Modified version of Douglas Crockford&quot;s json.js that doesn&quot;t
  * mess with the Object prototype
  * http://www.json.org/js.html
  * @singleton
  */
-Ext.util.JSON = new (function(){
-    var useHasOwn = !!{}.hasOwnProperty,
-        isNative = function() {
-            var useNative = null;
+Ext.JSON = new(function() {
+    var useHasOwn = !! {}.hasOwnProperty,
+    isNative = function() {
+        var useNative = null;
 
-            return function() {
-                if (useNative === null) {
-                    useNative = Ext.USE_NATIVE_JSON && window.JSON && JSON.toString() == '[object JSON]';
-                }
-        
-                return useNative;
-            };
-        }(),
-        pad = function(n) {
-            return n < 10 ? "0" + n : n;
-        },
-        doDecode = function(json){
-            return eval("(" + json + ')');    
-        },
-        doEncode = function(o){
-            if(!Ext.isDefined(o) || o === null){
-                return "null";
-            }else if(Ext.isArray(o)){
-                return encodeArray(o);
-            }else if(Ext.isDate(o)){
-                return Ext.util.JSON.encodeDate(o);
-            }else if(Ext.isString(o)){
-                return encodeString(o);
-            }else if(typeof o == "number"){
-                //don't use isNumber here, since finite checks happen inside isNumber
-                return isFinite(o) ? String(o) : "null";
-            }else if(Ext.isBoolean(o)){
-                return String(o);
-            }else {
-                var a = ["{"], b, i, v;
-                for (i in o) {
-                    // don't encode DOM objects
-                    if(!o.getElementsByTagName){
-                        if(!useHasOwn || o.hasOwnProperty(i)) {
-                            v = o[i];
-                            switch (typeof v) {
-                            case "undefined":
-                            case "function":
-                            case "unknown":
-                                break;
-                            default:
-                                if(b){
-                                    a.push(',');
-                                }
-                                a.push(doEncode(i), ":",
-                                        v === null ? "null" : doEncode(v));
-                                b = true;
-                            }
-                        }
-                    }
-                }
-                a.push("}");
-                return a.join("");
-            }    
-        },
-        m = {
-            "\b": '\\b',
-            "\t": '\\t',
-            "\n": '\\n',
-            "\f": '\\f',
-            "\r": '\\r',
-            '"' : '\\"',
-            "\\": '\\\\'
-        },
-        encodeString = function(s){
-            if (/["\\\x00-\x1f]/.test(s)) {
-                return '"' + s.replace(/([\x00-\x1f\\"])/g, function(a, b) {
-                    var c = m[b];
-                    if(c){
-                        return c;
-                    }
-                    c = b.charCodeAt();
-                    return "\\u00" +
-                        Math.floor(c / 16).toString(16) +
-                        (c % 16).toString(16);
-                }) + '"';
+        return function() {
+            if (useNative === null) {
+                useNative = Ext.USE_NATIVE_JSON &amp;&amp; window.JSON &amp;&amp; JSON.toString() == '[object JSON]';
             }
-            return '"' + s + '"';
-        },
-        encodeArray = function(o){
-            var a = ["["], b, i, l = o.length, v;
-                for (i = 0; i < l; i += 1) {
-                    v = o[i];
-                    switch (typeof v) {
-                        case "undefined":
-                        case "function":
-                        case "unknown":
-                            break;
-                        default:
-                            if (b) {
-                                a.push(',');
-                            }
-                            a.push(v === null ? "null" : Ext.util.JSON.encode(v));
-                            b = true;
-                    }
-                }
-                a.push("]");
-                return a.join("");
+
+            return useNative;
         };
+    }(),
+    pad = function(n) {
+        return n &lt; 10 ? &quot;0&quot; + n : n;
+    },
+    doDecode = function(json) {
+        return eval(&quot;(&quot; + json + ')');
+    },
+    doEncode = function(o) {
+        if (!Ext.isDefined(o) || o === null) {
+            return &quot;null&quot;;
+        } else if (Ext.isArray(o)) {
+            return encodeArray(o);
+        } else if (Ext.isDate(o)) {
+            return Ext.JSON.encodeDate(o);
+        } else if (Ext.isString(o)) {
+            return encodeString(o);
+        } else if (typeof o == &quot;number&quot;) {
+            //don't use isNumber here, since finite checks happen inside isNumber
+            return isFinite(o) ? String(o) : &quot;null&quot;;
+        } else if (Ext.isBoolean(o)) {
+            return String(o);
+        } else if (Ext.isObject(o)) {
+            return encodeObject(o);
+        } else if (typeof o === &quot;function&quot;) {
+            return &quot;null&quot;;
+        }
+        return 'undefined';
+    },
+    m = {
+        &quot;\b&quot;: '\\b',
+        &quot;\t&quot;: '\\t',
+        &quot;\n&quot;: '\\n',
+        &quot;\f&quot;: '\\f',
+        &quot;\r&quot;: '\\r',
+        '&quot;': '\\&quot;',
+        &quot;\\&quot;: '\\\\',
+        '\x0b': '\\u000b' //ie doesn't handle \v
+    },
+    charToReplace = /[\\\&quot;\x00-\x1f\x7f-\uffff]/g,
+    encodeString = function(s) {
+        return '&quot;' + s.replace(charToReplace, function(a) {
+            var c = m[a];
+            return typeof c === 'string' ? c : '\\u' + ('0000' + a.charCodeAt(0).toString(16)).slice(-4);
+        }) + '&quot;';
+    },
+    encodeArray = function(o) {
+        var a = [&quot;[&quot;, &quot;&quot;],
+        // Note empty string in case there are no serializable members.
+        len = o.length,
+        i;
+        for (i = 0; i &lt; len; i += 1) {
+            a.push(doEncode(o[i]), ',');
+        }
+        // Overwrite trailing comma (or empty string)
+        a[a.length - 1] = ']';
+        return a.join(&quot;&quot;);
+    },
+    encodeObject = function(o) {
+        var a = [&quot;{&quot;, &quot;&quot;],
+        // Note empty string in case there are no serializable members.
+        i;
+        for (i in o) {
+            if (!useHasOwn || o.hasOwnProperty(i)) {
+                a.push(doEncode(i), &quot;:&quot;, doEncode(o[i]), ',');
+            }
+        }
+        // Overwrite trailing comma (or empty string)
+        a[a.length - 1] = '}';
+        return a.join(&quot;&quot;);
+    };
 
-    <div id="method-Ext.util.JSON-encodeDate"></div>/**
-     * <p>Encodes a Date. This returns the actual string which is inserted into the JSON string as the literal expression.
-     * <b>The returned value includes enclosing double quotation marks.</b></p>
-     * <p>The default return format is "yyyy-mm-ddThh:mm:ss".</p>
-     * <p>To override this:</p><pre><code>
-Ext.util.JSON.encodeDate = function(d) {
-    return d.format('"Y-m-d"');
-};
-</code></pre>
+<span id='Ext-JSON-method-encodeDate'>    /**
+</span>     * &lt;p&gt;Encodes a Date. This returns the actual string which is inserted into the JSON string as the literal expression.
+     * &lt;b&gt;The returned value includes enclosing double quotation marks.&lt;/b&gt;&lt;/p&gt;
+     * &lt;p&gt;The default return format is &quot;yyyy-mm-ddThh:mm:ss&quot;.&lt;/p&gt;
+     * &lt;p&gt;To override this:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
+     Ext.JSON.encodeDate = function(d) {
+     return d.format('&quot;Y-m-d&quot;');
+     };
+     &lt;/code&gt;&lt;/pre&gt;
      * @param {Date} d The Date to encode
      * @return {String} The string literal to use in a JSON string.
      */
-    this.encodeDate = function(o){
-        return '"' + o.getFullYear() + "-" +
-                pad(o.getMonth() + 1) + "-" +
-                pad(o.getDate()) + "T" +
-                pad(o.getHours()) + ":" +
-                pad(o.getMinutes()) + ":" +
-                pad(o.getSeconds()) + '"';
+    this.encodeDate = function(o) {
+        return '&quot;' + o.getFullYear() + &quot;-&quot; 
+        + pad(o.getMonth() + 1) + &quot;-&quot;
+        + pad(o.getDate()) + &quot;T&quot;
+        + pad(o.getHours()) + &quot;:&quot;
+        + pad(o.getMinutes()) + &quot;:&quot;
+        + pad(o.getSeconds()) + '&quot;';
     };
 
-    <div id="method-Ext.util.JSON-encode"></div>/**
-     * Encodes an Object, Array or other value
+<span id='Ext-JSON-method-encode'>    /**
+</span>     * Encodes an Object, Array or other value
      * @param {Mixed} o The variable to encode
      * @return {String} The JSON string
      */
@@ -156,40 +143,53 @@ Ext.util.JSON.encodeDate = function(d) {
     }();
 
 
-    <div id="method-Ext.util.JSON-decode"></div>/**
-     * Decodes (parses) a JSON string to an object. If the JSON is invalid, this function throws a SyntaxError unless the safe option is set.
+<span id='Ext-JSON-method-decode'>    /**
+</span>     * Decodes (parses) a JSON string to an object. If the JSON is invalid, this function throws a SyntaxError unless the safe option is set.
      * @param {String} json The JSON string
+     * @param {Boolean} safe (optional) Whether to return null or throw an exception if the JSON is invalid.
      * @return {Object} The resulting object
      */
     this.decode = function() {
         var dc;
-        return function(json) {
+        return function(json, safe) {
             if (!dc) {
                 // setup decoding function on first access
                 dc = isNative() ? JSON.parse : doDecode;
             }
-            return dc(json);
+            try {
+                return dc(json);
+            } catch (e) {
+                if (safe === true) {
+                    return null;
+                }
+                Ext.Error.raise({
+                    sourceClass: &quot;Ext.JSON&quot;,
+                    sourceMethod: &quot;decode&quot;,
+                    msg: &quot;You're trying to decode an invalid JSON String: &quot; + json
+                });
+            }
         };
     }();
 
 })();
-<div id="method-Ext-encode"></div>/**
- * Shorthand for {@link Ext.util.JSON#encode}
+<span id='Ext-method-encode'>/**
+</span> * Shorthand for {@link Ext.JSON#encode}
  * @param {Mixed} o The variable to encode
  * @return {String} The JSON string
  * @member Ext
  * @method encode
  */
-Ext.encode = Ext.util.JSON.encode;
-<div id="method-Ext-decode"></div>/**
- * Shorthand for {@link Ext.util.JSON#decode}
+Ext.encode = Ext.JSON.encode;
+<span id='Ext-method-decode'>/**
+</span> * Shorthand for {@link Ext.JSON#decode}
  * @param {String} json The JSON string
  * @param {Boolean} safe (optional) Whether to return null or throw an exception if the JSON is invalid.
  * @return {Object} The resulting object
  * @member Ext
  * @method decode
  */
-Ext.decode = Ext.util.JSON.decode;
-</pre>    \r
-</body>\r
-</html>
\ No newline at end of file
+Ext.decode = Ext.JSON.decode;
+
+</pre>
+</body>
+</html>