docs/source/Object.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Object'>/**
  19 </span> * @class Object
  20  *
  21  * Creates an object wrapper.
  22  *
  23  * The Object constructor creates an object wrapper for the given value. If the value is null or
  24  * undefined, it will create and return an empty object, otherwise, it will return an object of a type
  25  * that corresponds to the given value.
  26  *
  27  * When called in a non-constructor context, Object behaves identically.
  28  *
  29  * # Using Object given undefined and null types
  30  *
  31  * The following examples store an empty Object object in o:
  32  *     var o = new Object();
  33  *
  34  *     var o = new Object(undefined);
  35  *
  36  *     var o = new Object(null);
  37  *
  38  * # Using Object to create Boolean objects
  39  *
  40  * The following examples store Boolean objects in o:
  41  *
  42  *     // equivalent to o = new Boolean(true);
  43  *     var o = new Object(true);
  44  *
  45  *     // equivalent to o = new Boolean(false);
  46  *     var o = new Object(Boolean());
  47  *
  48  * &lt;div class=&quot;notice&quot;&gt;
  49  * Documentation for this class comes from &lt;a href=&quot;https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object&quot;&gt;MDN&lt;/a&gt;
  50  * and is available under &lt;a href=&quot;http://creativecommons.org/licenses/by-sa/2.0/&quot;&gt;Creative Commons: Attribution-Sharealike license&lt;/a&gt;.
  51  * &lt;/div&gt;
  52  */
  53
  54 <span id='Object-method-constructor'>/**
  55 </span> * @method constructor
  56  * Creates new Object.
  57  * @param {Object} [value] The value to wrap.
  58  */
  59
  60 //Properties
  61
  62 <span id='Object-property-prototype'>/**
  63 </span> * @property prototype
  64  * Allows the addition of properties to all objects of type Object.
  65  */
  66
  67 //Methods
  68
  69 <span id='Object-method-hasOwnProperty'>/**
  70 </span> * @method hasOwnProperty
  71  * Returns a boolean indicating whether an object contains the specified property as a direct property
  72  * of that object and not inherited through the prototype chain.
  73  *
  74  * Every object descended from `Object` inherits the `hasOwnProperty` method. This method can be used
  75  * to determine whether an object has the specified property as a direct property of that object;
  76  * unlike the `in` operator, this method does not check down the object's prototype chain.
  77  *
  78  * The following example determines whether the o object contains a property named prop:
  79  *
  80  *     o = new Object();
  81  *     o.prop = 'exists';
  82  *
  83  *     function changeO() {
  84  *         o.newprop = o.prop;
  85  *         delete o.prop;
  86  *     }
  87  *
  88  *     o.hasOwnProperty('prop');   //returns true
  89  *     changeO();
  90  *     o.hasOwnProperty('prop');   //returns false
  91  *
  92  * The following example differentiates between direct properties and properties inherited through the
  93  * prototype chain:
  94  *
  95  *     o = new Object();
  96  *     o.prop = 'exists';
  97  *     o.hasOwnProperty('prop');             // returns true
  98  *     o.hasOwnProperty('toString');         // returns false
  99  *     o.hasOwnProperty('hasOwnProperty');   // returns false
 100  *
 101  * The following example shows how to iterate over the properties of an object without executing on
 102  * inherit properties.
 103  *
 104  *     var buz = {
 105  *         fog: 'stack'
 106  *     };
 107  *
 108  *     for (var name in buz) {
 109  *         if (buz.hasOwnProperty(name)) {
 110  *             alert(&quot;this is fog (&quot; + name + &quot;) for sure. Value: &quot; + buz[name]);
 111  *         }
 112  *         else {
 113  *             alert(name); // toString or something else
 114  *         }
 115  *     }
 116  *
 117  * @param {String} prop The name of the property to test.
 118  * @return {Boolean} Returns true if object contains specified property; else
 119  * returns false.
 120  */
 121
 122 <span id='Object-method-isPrototypeOf'>/**
 123 </span> * @method isPrototypeOf
 124  * Returns a boolean indication whether the specified object is in the prototype chain of the object
 125  * this method is called upon.
 126  *
 127  * `isPrototypeOf` allows you to check whether or not an object exists within another object's
 128  * prototype chain.
 129  *
 130  * For example, consider the following prototype chain:
 131  *
 132  *     function Fee() {
 133  *         // . . .
 134  *     }
 135  *
 136  *     function Fi() {
 137  *         // . . .
 138  *     }
 139  *     Fi.prototype = new Fee();
 140  *
 141  *     function Fo() {
 142  *         // . . .
 143  *     }
 144  *     Fo.prototype = new Fi();
 145  *
 146  *     function Fum() {
 147  *         // . . .
 148  *     }
 149  *     Fum.prototype = new Fo();
 150  *
 151  * Later on down the road, if you instantiate `Fum` and need to check if `Fi`'s prototype exists
 152  * within the `Fum` prototype chain, you could do this:
 153  *
 154  *     var fum = new Fum();
 155  *     . . .
 156  *
 157  *     if (Fi.prototype.isPrototypeOf(fum)) {
 158  *     // do something safe
 159  *     }
 160  *
 161  * This, along with the `instanceof` operator particularly comes in handy if you have code that can
 162  * only function when dealing with objects descended from a specific prototype chain, e.g., to
 163  * guarantee that certain methods or properties will be present on that object.
 164  *
 165  * @param {Object} prototype an object to be tested against each link in the prototype chain of the
 166  * *object* argument
 167  * @param {Object} object the object whose prototype chain will be searched
 168  * @return {Boolean} Returns true if object is a prototype and false if not.
 169  */
 170
 171 <span id='Object-method-propertyIsEnumerable'>/**
 172 </span> * @method propertyIsEnumerable
 173  * Returns a boolean indicating if the internal ECMAScript DontEnum attribute is set.
 174  *
 175  * Every object has a `propertyIsEnumerable` method. This method can determine whether the specified
 176  * property in an object can be enumerated by a `for...in` loop, with the exception of properties
 177  * inherited through the prototype chain. If the object does not have the specified property, this
 178  * method returns false.
 179  *
 180  * The following example shows the use of `propertyIsEnumerable` on objects and arrays:
 181  *
 182  *     var o = {};
 183  *     var a = [];
 184  *     o.prop = 'is enumerable';
 185  *     a[0] = 'is enumerable';
 186  *
 187  *     o.propertyIsEnumerable('prop');   // returns true
 188  *     a.propertyIsEnumerable(0);        // returns true
 189  *
 190  * The following example demonstrates the enumerability of user-defined versus built-in properties:
 191  *
 192  *     var a = ['is enumerable'];
 193  *
 194  *     a.propertyIsEnumerable(0);          // returns true
 195  *     a.propertyIsEnumerable('length');   // returns false
 196  *
 197  *     Math.propertyIsEnumerable('random');   // returns false
 198  *     this.propertyIsEnumerable('Math');     // returns false
 199  *
 200  * Direct versus inherited properties
 201  *
 202  *     var a = [];
 203  *     a.propertyIsEnumerable('constructor');         // returns false
 204  *
 205  *     function firstConstructor()
 206  *     {
 207  *         this.property = 'is not enumerable';
 208  *     }
 209  *     firstConstructor.prototype.firstMethod = function () {};
 210  *
 211  *     function secondConstructor()
 212  *     {
 213  *         this.method = function method() { return 'is enumerable'; };
 214  *     }
 215  *
 216  *     secondConstructor.prototype = new firstConstructor;
 217  *     secondConstructor.prototype.constructor = secondConstructor;
 218  *
 219  *     var o = new secondConstructor();
 220  *     o.arbitraryProperty = 'is enumerable';
 221  *
 222  *     o.propertyIsEnumerable('arbitraryProperty');   // returns true
 223  *     o.propertyIsEnumerable('method');              // returns true
 224  *     o.propertyIsEnumerable('property');            // returns false
 225  *
 226  *     o.property = 'is enumerable';
 227  *
 228  *     o.propertyIsEnumerable('property');            // returns true
 229  *
 230  *     // These return false as they are on the prototype which
 231  *     // propertyIsEnumerable does not consider (even though the last two
 232  *     // are iteratable with for-in)
 233  *     o.propertyIsEnumerable('prototype'); // returns false (as of JS 1.8.1/FF3.6)
 234  *     o.propertyIsEnumerable('constructor'); // returns false
 235  *     o.propertyIsEnumerable('firstMethod'); // returns false
 236  *
 237  * @param {String} prop The name of the property to test.
 238  * @return {Boolean} If the object does not have the specified property, this
 239  * method returns false.
 240  */
 241
 242 <span id='Object-method-toLocaleString'>/**
 243 </span> * @method toLocaleString
 244  * Returns a string representing the object. This method is meant to be overridden by derived objects
 245  * for locale-specific purposes.
 246  *
 247  * `Object`'s `toLocaleString` returns the result of calling `toString`.
 248  *
 249  * This function is provided to give objects a generic `toLocaleString` method, even though not all
 250  * may use it. Currently, only `Array`, `Number`, and `Date` override `toLocaleString`.
 251  *
 252  * @return {String} Object represented as a string.
 253  */
 254
 255 <span id='Object-method-toString'>/**
 256 </span> * @method toString
 257  * Returns a string representation of the object.
 258  *
 259  * Every object has a `toString()` method that is automatically called when the object is to be
 260  * represented as a text value or when an object is referred to in a manner in which a string is
 261  * expected. By default, the `toString()` method is inherited by every object descended from `Object`.
 262  * If this method is not overridden in a custom object, `toString()` returns &quot;[object type]&quot;, where
 263  * `type` is the object type. The following code illustrates this:
 264  *
 265  *     var o = new Object();
 266  *     o.toString();           // returns [object Object]
 267  *
 268  * You can create a function to be called in place of the default `toString()` method. The
 269  * `toString()` method takes no arguments and should return a string. The `toString()` method you
 270  * create can be any value you want, but it will be most useful if it carries information about the
 271  * object.
 272  *
 273  * The following code defines the `Dog` object type and creates `theDog`, an object of type `Dog`:
 274  *
 275  *     function Dog(name,breed,color,sex) {
 276  *         this.name=name;
 277  *         this.breed=breed;
 278  *         this.color=color;
 279  *         this.sex=sex;
 280  *     }
 281  *
 282  *     theDog = new Dog(&quot;Gabby&quot;,&quot;Lab&quot;,&quot;chocolate&quot;,&quot;female&quot;);
 283  *
 284  * If you call the `toString()` method on this custom object, it returns the default value inherited
 285  * from `Object`:
 286  *
 287  *     theDog.toString(); //returns [object Object]
 288  *
 289  * The following code creates and assigns `dogToString()` to override the default `toString()` method.
 290  * This function generates a string containing the name, breed, color, and sex of the object, in the
 291  * form `&quot;property = value;&quot;`.
 292  *
 293  *     Dog.prototype.toString = function dogToString() {
 294  *         var ret = &quot;Dog &quot; + this.name + &quot; is a &quot; + this.sex + &quot; &quot; + this.color + &quot; &quot; + this.breed;
 295  *         return ret;
 296  *     }
 297  *
 298  * With the preceding code in place, any time theDog is used in a string context, JavaScript
 299  * automatically calls the `dogToString()` function, which returns the following string:
 300  *
 301  *     Dog Gabby is a female chocolate Lab
 302  *
 303  * `toString()` can be used with every object and allows you to get its class. To use the
 304  * `Object.prototype.toString()` with every object, you need to call `Function.prototype.call()` or
 305  * `Function.prototype.apply()` on it, passing the object you want to inspect as the first parameter
 306  * called `thisArg`.
 307  *
 308  *     var toString = Object.prototype.toString;
 309  *
 310  *     toString.call(new Date); // [object Date]
 311  *     toString.call(new String); // [object String]
 312  *     toString.call(Math); // [object Math]
 313  *
 314  * @return {String} Object represented as a string.
 315  */
 316
 317 <span id='Object-method-valueOf'>/**
 318 </span> * @method valueOf
 319  * Returns the primitive value of the specified object.
 320  *
 321  * JavaScript calls the `valueOf` method to convert an object to a primitive value. You rarely need to
 322  * invoke the `valueOf` method yourself; JavaScript automatically invokes it when encountering an
 323  * object where a primitive value is expected.
 324  *
 325  * By default, the `valueOf` method is inherited by every object descended from `Object`. Every built-
 326  * in core object overrides this method to return an appropriate value. If an object has no primitive
 327  * value, `valueOf` returns the object itself, which is displayed as:
 328  *
 329  *     [object Object]
 330  *
 331  * You can use `valueOf` within your own code to convert a built-in object into a primitive value.
 332  * When you create a custom object, you can override `Object.valueOf` to call a custom method instead
 333  * of the default `Object` method.
 334  *
 335  * You can create a function to be called in place of the default `valueOf` method. Your function must
 336  * take no arguments.
 337  *
 338  * Suppose you have an object type `myNumberType` and you want to create a `valueOf` method for it.
 339  * The following code assigns a user-defined function to the object's valueOf method:
 340  *
 341  *     myNumberType.prototype.valueOf = new Function(functionText)
 342  *
 343  * With the preceding code in place, any time an object of type `myNumberType` is used in a context
 344  * where it is to be represented as a primitive value, JavaScript automatically calls the function
 345  * defined in the preceding code.
 346  *
 347  * An object's `valueOf` method is usually invoked by JavaScript, but you can invoke it yourself as
 348  * follows:
 349  *
 350  *     myNumber.valueOf()
 351  *
 352  * Note: Objects in string contexts convert via the `toString` method, which is different from
 353  * `String` objects converting to string primitives using `valueOf`. All objects have a string
 354  * conversion, if only `&quot;[object type]&quot;`. But many objects do not convert to number, boolean, or
 355  * function.
 356  *
 357  * @return {Object} Returns value of the object or the object itself.
 358  */
 359
 360 //Properties
 361
 362 <span id='Object-property-constructor'>/**
 363 </span> * @property constructor
 364  * Specifies the function that creates an object's prototype.
 365  *
 366  * Returns a reference to the Object function that created the instance's prototype. Note that the
 367  * value of this property is a reference to the function itself, not a string containing the
 368  * function's name, but it isn't read only (except for primitive Boolean, Number or String values: 1,
 369  * true, &quot;read-only&quot;).
 370  *
 371  * All objects inherit a `constructor` property from their `prototype`:
 372  *
 373  *     o = new Object // or o = {} in JavaScript 1.2
 374  *     o.constructor == Object
 375  *     a = new Array // or a = [] in JavaScript 1.2
 376  *     a.constructor == Array
 377  *     n = new Number(3)
 378  *     n.constructor == Number
 379  *
 380  * Even though you cannot construct most HTML objects, you can do comparisons. For example,
 381  *
 382  *     document.constructor == Document
 383  *     document.form3.constructor == Form
 384  *
 385  * The following example creates a prototype, `Tree`, and an object of that type, theTree. The example then displays the `constructor` property for the object `theTree`.
 386  *
 387  *     function Tree(name) {
 388  *         this.name = name;
 389  *     }
 390  *     theTree = new Tree(&quot;Redwood&quot;);
 391  *     console.log(&quot;theTree.constructor is &quot; + theTree.constructor);
 392  *
 393  * This example displays the following output:
 394  *
 395  *     theTree.constructor is function Tree(name) {
 396  *         this.name = name;
 397  *     }
 398  *
 399  * The following example shows how to modify constructor value of generic objects. Only true, 1 and
 400  * &quot;test&quot; variable constructors will not be changed. This example explains that is not always so safe
 401  * to believe in constructor function.
 402  *
 403  *     function Type(){};
 404  *     var      types = [
 405  *          new Array,  [],
 406  *          new Boolean,        true,
 407  *          new Date,
 408  *          new Error,
 409  *          new Function,       function(){},
 410  *          Math,
 411  *          new Number, 1,
 412  *          new Object, {},
 413  *          new RegExp, /(?:)/,
 414  *          new String, &quot;test&quot;
 415  *     ];
 416  *     for(var i = 0; i &lt; types.length; i++){
 417  *         types[i].constructor = Type;
 418  *         types[i] = [types[i].constructor, types[i] instanceof Type, types[i].toString()];
 419  *     };
 420  *     alert(types.join(&quot;\n&quot;));
 421  */</pre>
 422 </body>
 423 </html>