Added fromArray to Cartesian2 and Cartesian4 for consistency

CHANGES.md

@@ -4,7 +4,15 @@ Change Log
 Beta Releases
 -------------
 
+### b15 - 2013-04-01
+
+* Breaking changes:
+   *
+* Added `BoundingSphere.fromCornerPoints`.
+* Added `fromArray` and `distance` functions to `Cartesian2`, `Cartesian3`, and `Cartesian4`.
+
 ### b14 - 2013-03-01
+
 * Breaking changes:
    * Major refactoring of both animation and widgets systems as we move to an MVVM-like architecture for user interfaces.
       * New `Animation` widget for controlling playback.

Source/Core/Cartesian2.js

@@ -34,6 +34,48 @@ define([
         this.y = defaultValue(y, 0.0);
     };
 
+    /**
+     * Creates a Cartesian2 from two consecutive elements in an array.
+     * @memberof Cartesian2
+     *
+     * @param {Array} values The array whose two consecutive elements correspond to the x and y components, respectively.
+     * @param {Number} [offset=0] The offset into the array of the first element, which corresponds to the x component.
+     * @param {Cartesian2} [result] The object onto which to store the result.
+     *
+     * @return {Cartesian2} The modified result parameter or a new Cartesian2 instance if one was not provided.
+     *
+     * @exception {DeveloperError} values is required.
+     * @exception {DeveloperError} offset + 2 is greater than the length of the array.
+     *
+     * @example
+     * // Create a Cartesian2 with (1.0, 2.0)
+     * var v = [1.0, 2.0];
+     * var p = Cartesian2.fromArray(v);
+     *
+     * // Create a Cartesian2 with (1.0, 2.0) using an offset into an array
+     * var v2 = [0.0, 0.0, 1.0, 2.0];
+     * var p2 = Cartesian2.fromArray(v2, 2);
+     */
+    Cartesian2.fromArray = function(values, offset, result) {
+        if (typeof values === 'undefined') {
+            throw new DeveloperError('values is required.');
+        }
+
+        if (offset + 2 > values.length) {
+            throw new DeveloperError('offset + 2 is greater than the length of the array.');
+        }
+
+        offset = defaultValue(offset, 0);
+
+        if (typeof result === 'undefined') {
+            result = new Cartesian2();
+        }
+
+        result.x = values[offset + 0];
+        result.y = values[offset + 1];
+        return result;
+    };
+
     /**
      * Duplicates a Cartesian2 instance.
      * @memberof Cartesian2

Source/Core/Cartesian3.js

@@ -72,7 +72,7 @@ define([
      * Creates a Cartesian3 from three consecutive elements in an array.
      * @memberof Cartesian3
      *
-     * @param {Array} values The Spherical to be converted to Cartesian3.
+     * @param {Array} values The array whose three consecutive elements correspond to the x, y, and z components, respectively.
      * @param {Number} [offset=0] The offset into the array of the first element, which corresponds to the x component.
      * @param {Cartesian3} [result] The object onto which to store the result.
      *

Source/Core/Cartesian4.js

@@ -48,6 +48,50 @@ define([
         this.w = defaultValue(w, 0.0);
     };
 
+    /**
+     * Creates a Cartesian4 from four consecutive elements in an array.
+     * @memberof Cartesian4
+     *
+     * @param {Array} values The array whose four consecutive elements correspond to the x, y, z, and w components, respectively.
+     * @param {Number} [offset=0] The offset into the array of the first element, which corresponds to the x component.
+     * @param {Cartesian4} [result] The object onto which to store the result.
+     *
+     * @return {Cartesian4} The modified result parameter or a new Cartesian4 instance if one was not provided.
+     *
+     * @exception {DeveloperError} values is required.
+     * @exception {DeveloperError} offset + 4 is greater than the length of the array.
+     *
+     * @example
+     * // Create a Cartesian4 with (1.0, 2.0, 3.0, 4.0)
+     * var v = [1.0, 2.0, 3.0, 4.0];
+     * var p = Cartesian4.fromArray(v);
+     *
+     * // Create a Cartesian4 with (1.0, 2.0, 3.0, 4.0) using an offset into an array
+     * var v2 = [0.0, 0.0, 1.0, 2.0, 3.0, 4.0];
+     * var p2 = Cartesian4.fromArray(v2, 2);
+     */
+    Cartesian4.fromArray = function(values, offset, result) {
+        if (typeof values === 'undefined') {
+            throw new DeveloperError('values is required.');
+        }
+
+        if (offset + 4 > values.length) {
+            throw new DeveloperError('offset + 4 is greater than the length of the array.');
+        }
+
+        offset = defaultValue(offset, 0);
+
+        if (typeof result === 'undefined') {
+            result = new Cartesian4();
+        }
+
+        result.x = values[offset + 0];
+        result.y = values[offset + 1];
+        result.z = values[offset + 2];
+        result.w = values[offset + 3];
+        return result;
+    };
+
     /**
      * Duplicates a Cartesian4 instance.
      * @memberof Cartesian4

Specs/Core/Cartesian2Spec.js

@@ -26,6 +26,35 @@ defineSuite([
         expect(cartesian.y).toEqual(2.0);
     });
 
+    it('fromArray creates a Cartesian2', function() {
+        var cartesian = Cartesian2.fromArray([1.0, 2.0]);
+        expect(cartesian).toEqual(new Cartesian2(1.0, 2.0));
+    });
+
+    it('fromArray with an offset creates a Cartesian2', function() {
+        var cartesian = Cartesian2.fromArray([0.0, 1.0, 2.0, 0.0], 1);
+        expect(cartesian).toEqual(new Cartesian2(1.0, 2.0));
+    });
+
+    it('fromArray creates a Cartesian2 with a result parameter', function() {
+        var cartesian = new Cartesian2();
+        var result = Cartesian2.fromArray([1.0, 2.0], 0, cartesian);
+        expect(result).toBe(cartesian);
+        expect(result).toEqual(new Cartesian2(1.0, 2.0));
+    });
+
+    it('fromArray throws without values', function() {
+        expect(function() {
+            Cartesian2.fromArray();
+        }).toThrow();
+    });
+
+    it('fromArray throws with an invalid offset', function() {
+        expect(function() {
+            Cartesian2.fromArray([0.0, 0.0], 1);
+        }).toThrow();
+    });
+
     it('clone without a result parameter', function() {
         var cartesian = new Cartesian2(1.0, 2.0);
         var result = cartesian.clone();

Specs/Core/Cartesian4Spec.js

@@ -24,6 +24,35 @@ defineSuite([
         expect(cartesian.w).toEqual(4.0);
     });
 
+    it('fromArray creates a Cartesian4', function() {
+        var cartesian = Cartesian4.fromArray([1.0, 2.0, 3.0, 4.0]);
+        expect(cartesian).toEqual(new Cartesian4(1.0, 2.0, 3.0, 4.0));
+    });
+
+    it('fromArray with an offset creates a Cartesian4', function() {
+        var cartesian = Cartesian4.fromArray([0.0, 1.0, 2.0, 3.0, 4.0, 0.0], 1);
+        expect(cartesian).toEqual(new Cartesian4(1.0, 2.0, 3.0, 4.0));
+    });
+
+    it('fromArray creates a Cartesian4 with a result parameter', function() {
+        var cartesian = new Cartesian4();
+        var result = Cartesian4.fromArray([1.0, 2.0, 3.0, 4.0], 0, cartesian);
+        expect(result).toBe(cartesian);
+        expect(result).toEqual(new Cartesian4(1.0, 2.0, 3.0, 4.0));
+    });
+
+    it('fromArray throws without values', function() {
+        expect(function() {
+            Cartesian4.fromArray();
+        }).toThrow();
+    });
+
+    it('fromArray throws with an invalid offset', function() {
+        expect(function() {
+            Cartesian4.fromArray([0.0, 0.0, 0.0, 0.0], 1);
+        }).toThrow();
+    });
+
     it('clone without a result parameter', function() {
         var cartesian = new Cartesian4(1.0, 2.0, 3.0, 4.0);
         var result = cartesian.clone();