JS Global Objects

/**

 * @class Array

 *

 * In JavaScript, the Array property of the global object is a constructor for

 * In JavaScript, the `Array` property of the global object is a constructor for

 * array instances.

 *

 * An array is a JavaScript object. Note that you shouldn't use it as an

 * associative array, use {@link Object} instead.

 *

 * # Creating an Array

 * 

 * The following example creates an array, msgArray, with a length of 0, then assigns values to 

 * msgArray[0] and msgArray[99], changing the length of the array to 100.

 *

 *     var msgArray = new Array();  

 *     msgArray[0] = "Hello";  

 *     msgArray[99] = "world";  

 *     

 *     if (msgArray.length == 100)  

 *     print("The length is 100.");  

 * 

 * # Creating a Two-dimensional Array

 * 

 * The following creates chess board as a two dimensional array of strings. The first move is made by 

 * copying the 'P' in 6,4 to 4,4. The position 4,4 is left blank.

 * 

 *     var board =   

 *     [ ['R','N','B','Q','K','B','N','R'],  

 *     ['P','P','P','P','P','P','P','P'],  

 *     [' ',' ',' ',' ',' ',' ',' ',' '],  

 *     [' ',' ',' ',' ',' ',' ',' ',' '],  

 *     [' ',' ',' ',' ',' ',' ',' ',' '],  

 *     [' ',' ',' ',' ',' ',' ',' ',' '],  

 *     ['p','p','p','p','p','p','p','p'],  

 *     ['r','n','b','q','k','b','n','r']];  

 *     print(board.join('\n') + '\n\n');  

 *     

 *     // Move King's Pawn forward 2  

 *     board[4][4] = board[6][4];  

 *     board[6][4] = ' ';  

 *     print(board.join('\n'));  

 *

 * Here is the output:

 *

 *     R,N,B,Q,K,B,N,R

 *     P,P,P,P,P,P,P,P

 *      , , , , , , , 

 *      , , , , , , , 

 *      , , , , , , , 

 *      , , , , , , , 

 *     p,p,p,p,p,p,p,p

 *     r,n,b,q,k,b,n,r

 * 

 *     R,N,B,Q,K,B,N,R

 *     P,P,P,P,P,P,P,P

 *      , , , , , , , 

 *      , , , , , , , 

 *      , , , ,p, , , 

 *      , , , , , , , 

 *     p,p,p,p, ,p,p,p

 *     r,n,b,q,k,b,n,r

 * 

 * # Accessing array elements

 *

 * Array elements are nothing less than object properties, so they are accessed as such.

/**

 * @property constructor

 * Specifies the function that creates an object's prototype.

 *

 * Returns a reference to the Array function that created the instance's prototype. Note that the value of 

 * this property is a reference to the function itself, not a string containing the function's name.

 */

/**

 * @property length

 * Reflects the number of elements in an array.

 *

 * The value of the `length` property is an integer with a positive sign and a value less than 2 to the 32 

 * power (232). 

 * 

 * You can set the `length` property to truncate an array at any time. When you extend an array by changing 

 * its `length` property, the number of actual elements does not increase; for example, if you set `length` 

 * to 3 when it is currently 2, the array still contains only 2 elements.

 * 

 * In the following example the array numbers is iterated through by looking at the `length` property to see 

 * how many elements it has. Each value is then doubled. 

 *

 *     var numbers = [1,2,3,4,5];

 *     for (var i = 0; i < numbers.length; i++) {

 *         numbers[i] *= 2;

 *     }

 *     // numbers is now [2,4,6,8,10];

 * 

 * The following example shortens the array `statesUS` to a length of 50 if the current `length` is greater 

 * than 50. 

 * 

 *     if (statesUS.length > 50) {

 *         statesUS.length=50

 *     }

 */

// Mutator methods. These methods modify the array:

 * The only native, array-like objects are strings, although they are not suitable in

 * applications of this method, as strings are immutable.

 *

 * ## Adding elements to an array

 * ### Adding elements to an array

 *

 * The following code creates the sports array containing two elements, then appends two elements

 * to it. After the code executes, sports contains 4 elements: "soccer", "baseball", "football"

/**

 * @method shift

 * Removes the first element from an array and returns that element.

 *

 * The `shift` method removes the element at the zeroeth index and shifts the values at consecutive 

 * indexes down, then returns the removed value.

 *

 * `shift` is intentionally generic; this method can be called or applied to objects resembling 

 * arrays. Objects which do not contain a `length` property reflecting the last in a series of 

 * consecutive, zero-based numerical properties may not behave in any meaningful manner.

 *

 * The following code displays the `myFish` array before and after removing its first element. It also 

 * displays the removed element:

 *

 *     // assumes a println function is defined

 *     var myFish = ["angel", "clown", "mandarin", "surgeon"];

 *     println("myFish before: " + myFish);

 *     var shifted = myFish.shift();

 *     println("myFish after: " + myFish);

 *     println("Removed this element: " + shifted);

 *

 * This example displays the following:

 *

 *     myFish before: angel,clown,mandarin,surgeon

 *     myFish after: clown,mandarin,surgeon

 *     Removed this element: angel

 *

 * @return {Mixed} The first element of the array prior to shifting.

 */

/**

 * @method sort

 * Sorts the elements of an array.

 * 

 * If `compareFunction` is not supplied, elements are sorted by converting them to strings and 

 * comparing strings in lexicographic ("dictionary" or "telephone book," not numerical) order. For 

 * example, "80" comes before "9" in lexicographic order, but in a numeric sort 9 comes before 80.

 *

 * If `compareFunction` is supplied, the array elements are sorted according to the return value of 

 * the compare function. If a and b are two elements being compared, then:

 * If `compareFunction(a, b)` is less than 0, sort `a` to a lower index than `b`.

 * If `compareFunction(a, b)` returns 0, leave `a` and `b` unchanged with respect to each other, but 

 * sorted with respect to all different elements. Note: the ECMAscript standard does not guarantee 

 * this behaviour, and thus not all browsers respect this.

 * If `compareFunction(a, b)` is greater than 0, sort `b` to a lower index than `a`.

 * `compareFunction(a, b)` must always returns the same value when given a specific pair of elements a 

 * and b as its two arguments. If inconsistent results are returned then the sort order is undefined

 * 

 * So, the compare function has the following form:

 * 

 *     function compare(a, b)  

 *     {  

 *         if (a is less than b by some ordering criterion)  

 *             return -1;  

 *         if (a is greater than b by the ordering criterion)  

 *            return 1;  

 *         // a must be equal to b  

 *         return 0;  

 *     }  

 *

 * To compare numbers instead of strings, the compare function can simply subtract `b` from `a`:

 *

 *     function compareNumbers(a, b)  

 *     {  

 *     return a - b;  

 *     }  

 *

 * The sort() method can be conveniently used with closures: 

 *

 *     var numbers = [4, 2, 5, 1, 3];  

 *     numbers.sort(function(a, b) {  

 *         return a - b;  

 *     });  

 *     print(numbers);   

 *

 * @param {Mixed} compareFunction Specifies a function that defines the sort order. If omitted, the 

 * array is sorted lexicographically (in dictionary order) according to the string conversion of each 

 * element.

 * @return {Array} A reference to the array

 */

/**

 * @method splice

 * Adds and/or removes elements from an array.

 *

 * If you specify a different number of elements to insert than the number you're removing, the array 

 * will have a different length at the end of the call.

 *

 *     // assumes a print function is defined  

 *     var myFish = ["angel", "clown", "mandarin", "surgeon"];  

 *     print("myFish: " + myFish);  

 * 

 *     var removed = myFish.splice(2, 0, "drum");  

 *     print("After adding 1: " + myFish);  

 *     print("removed is: " + removed);  

 *     

 *     removed = myFish.splice(3, 1);  

 *     print("After removing 1: " + myFish);  

 *     print("removed is: " + removed);  

 *     

 *     removed = myFish.splice(2, 1, "trumpet");  

 *     print("After replacing 1: " + myFish);  

 *     print("removed is: " + removed);  

 *     

 *     removed = myFish.splice(0, 2, "parrot", "anemone", "blue");  

 *     print("After replacing 2: " + myFish);  

 *     print("removed is: " + removed);  

 *

 * This script displays:

 *

 *     myFish: angel,clown,mandarin,surgeon

 *     After adding 1: angel,clown,drum,mandarin,surgeon

 *     removed is: 

 *     After removing 1: angel,clown,drum,surgeon

 *     removed is: mandarin

 *     After replacing 1: angel,clown,trumpet,surgeon

 *     removed is: drum

 *     After replacing 2: parrot,anemone,blue,trumpet,surgeon

 *     removed is: angel,clown

 *

 * @param {Number} index Index at which to start changing the array. If negative, will begin that 

 * many elements from the end.

 * @param {Number} howMany An integer indicating the number of old array elements to remove. If 

 * `howMany` is 0, no elements are removed. In this case, you should specify at least one new element. 

 * If no `howMany` parameter is specified all elements after index are removed.

 * @param {Mixed} element1, ..., elementN The elements to add to the array. If you don't specify any 

 * elements, `splice` simply removes elements from the array.

 * @return {Array} An array containing the removed elements. If only one element is removed, an array 

 * of one element is returned..

 */

/**

 * @method unshift

 * Adds one or more elements to the front of an array and returns the new length of the array.

 *

 * The `unshift` method inserts the given values to the beginning of an array-like object.

 *

 * `unshift` is intentionally generic; this method can be called or applied to objects resembling 

 * arrays. Objects which do not contain a `length` property reflecting the last in a series of 

 * consecutive, zero-based numerical properties may not behave in any meaningful manner.

 *

 * The following code displays the myFish array before and after adding elements to it.

 *

 *     // assumes a println function exists

 *     myFish = ["angel", "clown"];

 *     println("myFish before: " + myFish);

 *     unshifted = myFish.unshift("drum", "lion");

 *     println("myFish after: " + myFish);

 *     println("New length: " + unshifted);

 * 

 * This example displays the following:

 *

 *     myFish before: ["angel", "clown"]

 *     myFish after: ["drum", "lion", "angel", "clown"]

 *     New length: 4

 *

 * @param {Mixed} element1, ..., elementN The elements to add to the front of the array.

 * @return {Number} The array's new length.

 */

// Accessor methods. These methods do not modify the array and return some representation of the array.

/**

 * @method concat

 * Returns a new array comprised of this array joined with other array(s) and/or value(s).

 *

 * `concat` creates a new array consisting of the elements in the `this` object on which it is called, 

 * followed in order by, for each argument, the elements of that argument (if the argument is an 

 * array) or the argument itself (if the argument is not an array).

 *

 * `concat` does not alter `this` or any of the arrays provided as arguments but instead returns a 

 * "one level deep" copy that contains copies of the same elements combined from the original arrays. 

 * Elements of the original arrays are copied into the new array as follows:

 * Object references (and not the actual object): `concat` copies object references into the new 

 * array. Both the original and new array refer to the same object. That is, if a referenced object is 

 * modified, the changes are visible to both the new and original arrays.

 * Strings and numbers (not {@link String} and {@link Number} objects): `concat` copies the values of 

 * strings and numbers into the new array.

 *

 * Any operation on the new array will have no effect on the original arrays, and vice versa.

 * 

 * ### Concatenating two arrays

 * 

 * The following code concatenates two arrays:

 *

 *     var alpha = ["a", "b", "c"];  

 *     var numeric = [1, 2, 3];  

 *     

 *     // creates array ["a", "b", "c", 1, 2, 3]; alpha and numeric are unchanged  

 *     var alphaNumeric = alpha.concat(numeric);  

 *

 * ### Concatenating three arrays

 *

 * The following code concatenates three arrays:

 *

 *     var num1 = [1, 2, 3];  

 *     var num2 = [4, 5, 6];  

 *     var num3 = [7, 8, 9];  

 *     

 *     // creates array [1, 2, 3, 4, 5, 6, 7, 8, 9]; num1, num2, num3 are unchanged  

 *     var nums = num1.concat(num2, num3);  

 *

 * ### Concatenating values to an array

 *

 * The following code concatenates three values to an array:

 * 

 *     var alpha = ['a', 'b', 'c'];  

 *     

 *     // creates array ["a", "b", "c", 1, 2, 3], leaving alpha unchanged  

 *     var alphaNumeric = alpha.concat(1, [2, 3]);  

 *

 * @param {Mixed} ValueN Arrays and/or values to concatenate to the resulting array.

 * @return {Array} New array.

 */

/**

 * @method join

 * Joins all elements of an array into a string.

 *

 * The string conversions of all array elements are joined into one string.

 *

 * The following example creates an array, `a`, with three elements, then joins the array three times: 

 * using the default separator, then a comma and a space, and then a plus.

 *

 *     var a = new Array("Wind","Rain","Fire");

 *     var myVar1 = a.join();      // assigns "Wind,Rain,Fire" to myVar1

 *     var myVar2 = a.join(", ");  // assigns "Wind, Rain, Fire" to myVar2

 *     var myVar3 = a.join(" + "); // assigns "Wind + Rain + Fire" to myVar3

 *

 * @param {String} Separator Specifies a string to separate each element of the array. The separator 

 * is converted to a string if necessary. If omitted, the array elements are separated with a comma.

 * @return {String} A string of the array elements.

 */

/**

 * @method slice

 * Extracts a section of an array and returns a new array.

 *

 * `slice` does not alter the original array, but returns a new "one level deep" copy that contains 

 * copies of the elements sliced from the original array. Elements of the original array are copied 

 * into the new array as follows:

 * *   For object references (and not the actual object), `slice` copies object references into the 

 * new array. Both the original and new array refer to the same object. If a referenced object 

 * changes, the changes are visible to both the new and original arrays.

 * *   For strings and numbers (not {@link String} and {@link Number} objects), `slice` copies strings 

 * and numbers into the new array. Changes to the string or number in one array does not affect the 

 * other array.

 * 

 * If a new element is added to either array, the other array is not affected.

 *

 * ### Using slice

 *

 * In the following example, `slice` creates a new array, `newCar`, from `myCar`. Both include a 

 * reference to the object `myHonda`. When the color of `myHonda` is changed to purple, both arrays 

 * reflect the change.

 *

 *     // Using slice, create newCar from myCar.

 *     var myHonda = { color: "red", wheels: 4, engine: { cylinders: 4, size: 2.2 } };

 *     var myCar = [myHonda, 2, "cherry condition", "purchased 1997"];

 *     var newCar = myCar.slice(0, 2);

 *     

 *     // Print the values of myCar, newCar, and the color of myHonda

 *     //  referenced from both arrays.

 *     print("myCar = " + myCar.toSource());

 *     print("newCar = " + newCar.toSource());

 *     print("myCar[0].color = " + myCar[0].color);

 *     print("newCar[0].color = " + newCar[0].color);

 *     

 *     // Change the color of myHonda.

 *     myHonda.color = "purple";

 *     print("The new color of my Honda is " + myHonda.color);

 *     

 *     // Print the color of myHonda referenced from both arrays.

 *     print("myCar[0].color = " + myCar[0].color);

 *     print("newCar[0].color = " + newCar[0].color);

 *

 * This script writes:

 *

 *     myCar = [{color:"red", wheels:4, engine:{cylinders:4, size:2.2}}, 2, "cherry condition", 

 *     "purchased 1997"]

 *     newCar = [{color:"red", wheels:4, engine:{cylinders:4, size:2.2}}, 2]

 *     myCar[0].color = red 

 *     newCar[0].color = red

 *     The new color of my Honda is purple

 *     myCar[0].color = purple

 *     newCar[0].color = purple

 *

 * @param {Number} begin Zero-based index at which to begin extraction.

 * As a negative index, `start` indicates an offset from the end of the sequence. `slice(-2)` extracts 

 * the second-to-last element and the last element in the sequence

 * @param {Number} end Zero-based index at which to end extraction. `slice` extracts up to but not 

 * including `end`.

 * `slice(1,4)` extracts the second element through the fourth element (elements indexed 1, 2, and 3).

 * As a negative index, end indicates an offset from the end of the sequence. `slice(2,-1)` extracts 

 * the third element through the second-to-last element in the sequence.

 * If `end` is omitted, `slice` extracts to the end of the sequence.

 * @return {Array} Array from the new start position up to (but not including) the specified end position.

 */

/**

 * @method toString

 * Returns a string representing the array and its elements. Overrides the Object.prototype.toString method.

 * Returns a string representing the array and its elements. Overrides the `Object.prototype.toString` 

 * method.

 *

 * The {@link Array} object overrides the `toString` method of {@link Object}. For Array objects, the 

 * `toString` method joins the array and returns one string containing each array element separated by 

 * commas. For example, the following code creates an array and uses `toString` to convert the array 

 * to a string.

 *

 *     var monthNames = new Array("Jan","Feb","Mar","Apr");

 *     myVar = monthNames.toString(); // assigns "Jan,Feb,Mar,Apr" to myVar

 * 

 * JavaScript calls the `toString` method automatically when an array is to be represented as a text 

 * value or when an array is referred to in a string concatenation.

 *

 * @return {String} The array as a string.

 */

 No newline at end of file

/**

 * @class Boolean

 *

 * The `Boolean` object is an object wrapper for a boolean value.

 * 

 * The value passed as the first parameter is converted to a boolean value, if necessary. If value is 

 * omitted or is 0, -0, null, false, `NaN`, undefined, or the empty string (""), the object has an

 * initial value of false. All other values, including any object or the string `"false"`, create an 

 * object with an initial value of true.

 * 

 * Do not confuse the primitive Boolean values true and false with the true and false values of the 

 * Boolean object.

 * 

 * Any object whose value is not `undefined` or `null`, including a Boolean object whose value is false, 

 * evaluates to true when passed to a conditional statement. For example, the condition in the following 

 * if statement evaluates to true:

 * 

 *     x = new Boolean(false);

 *     if (x) {

 *         // . . . this code is executed

 *     }

 * 

 * This behavior does not apply to Boolean primitives. For example, the condition in the following if 

 * statement evaluates to `false`:

 *     x = false;

 *     if (x) {

 *         // . . . this code is not executed

 *     }

 *

 * Do not use a `Boolean` object to convert a non-boolean value to a boolean value. Instead, use Boolean 

 * as a function to perform this task:

 *

 *     x = Boolean(expression);     // preferred

 *     x = new Boolean(expression); // don't use

 *

 * If you specify any object, including a Boolean object whose value is false, as the initial value of a 

 * Boolean object, the new Boolean object has a value of true.

 *

 *     myFalse = new Boolean(false);   // initial value of false

 *     g = new Boolean(myFalse);       // initial value of true

 *     myString = new String("Hello"); // string object

 *     s = new Boolean(myString);      // initial value of true

 *

 * Do not use a Boolean object in place of a Boolean primitive.

 *

 * # Creating Boolean objects with an initial value of false

 * 

 *     bNoParam = new Boolean();

 *     bZero = new Boolean(0);

 *     bNull = new Boolean(null);

 *     bEmptyString = new Boolean("");

 *     bfalse = new Boolean(false);

 *

 * # Creating Boolean objects with an initial value of true

 *

 *     btrue = new Boolean(true);

 *     btrueString = new Boolean("true");

 *     bfalseString = new Boolean("false");

 *     bSuLin = new Boolean("Su Lin");

 *

 */

//Properties

/**

 * @property prototype

 * Defines a property that is shared by all Boolean objects.

 */

/**

 * @property constructor

 * Returns the function that created an instance's prototype. This is the `Boolean` function by default.

 */

//Methods

/**

 * @method toString

 * Returns a string of either "true" or "false" depending upon the value of the object. 

 * Overrides the `Object.prototype.toString` method.

 *

 * The Boolean object overrides the `toString` method of the `Object` object; it does not inherit 

 * `Object.toString`. For Boolean objects, the `toString` method returns a string representation of 

 * the object.

 * 

 * JavaScript calls the `toString` method automatically when a Boolean is to be represented as a text 

 * value or when a Boolean is referred to in a string concatenation.

 * 

 * For Boolean objects and values, the built-in `toString` method returns the string `"true"` or 

 * `"false"` depending on the value of the boolean object. In the following code, `flag.toString` 

 * returns `"true"`.

 *

 *     var flag = new Boolean(true)

 *     var myVar = flag.toString() 

 *

 * @return {String} The boolean value represented as a string.

 */

/**

 * @method valueOf

 * Returns the primitive value of the `Boolean` object. Overrides the `Object.prototype.valueOf` method.

 *

 * The `valueOf` method of Boolean returns the primitive value of a Boolean object or literal Boolean 

 * as a Boolean data type.

 * 

 * This method is usually called internally by JavaScript and not explicitly in code.

 * 

 *     x = new Boolean();

 *     myVar = x.valueOf()      //assigns false to myVar

 *

 * @return {Boolean} The primitive value.

 */

 No newline at end of file