Add angular.Array.limitTo and docs for angular.Array

src/apis.js

@@ -19,6 +19,25 @@ var angularCollection = {
 var angularObject = {
   'extend': extend
 };
+
+/**
+ * @workInProgress
+ * @ngdoc overview
+ * @name angular.Array
+ *
+ * @description
+ * Utility functions for manipulation with JavaScript Array objects.
+ *
+ * These functions are exposed in two ways:
+ *
+ * - **in angular expressions**: the functions are bound to the Array objects and augment the Array
+ *   type as array methods. The names of these methods are prefixed with `$` character to minimize
+ *   naming collisions. To call a method, invoke `myArrayObject.$foo(params)`.
+ *
+ * - **in JavaScript code**: the functions don't augment the Array type and must be invoked as
+ *   functions of `angular.Array` as `angular.Array.foo(myArrayObject, params)`.
+ *
+ */
 var angularArray = {
   'indexOf': indexOf,
   'sum':function(array, expression) {
@@ -173,7 +192,44 @@ var angularArray = {
         return t1 < t2 ? -1 : 1;
       }
     }
+  },
 
+
+  /**
+   * @workInProgress
+   * @ngdoc function
+   * @name angular.Array.limitTo
+   * @function
+   *
+   * @description
+   * Creates a new array containing only the first, or last `limit` number of elements of the
+   * source `array`.
+   *
+   * @param {Array} array Source array to be limited.
+   * @param {string|Number} limit The length of the returned array. If the number is positive, the
+   *     first `limit` items from the source array will be copied, if the number is negative, the
+   *     last `limit` items will be copied.
+   * @returns {Array} New array of length `limit`.
+   *
+   */
+  limitTo: function(array, limit) {
+    limit = parseInt(limit, 10);
+    var out = [],
+        i, n;
+
+    if (limit > 0) {
+      i = 0;
+      n = limit;
+    } else {
+      i = array.length + limit;
+      n = array.length;
+    }
+
+    for (; i<n; i++) {
+      out.push(array[i]);
+    }
+
+    return out;
   }
 };
 

test/ApiSpecs.js

@@ -115,6 +115,36 @@ describe('api', function(){
   });
 
 
+  describe('limit', function() {
+    var items;
+
+    beforeEach(function() {
+      items = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
+    });
+
+
+    it('should return the first X items when X is positive', function() {
+      expect(angular.Array.limitTo(items, 3)).toEqual(['a', 'b', 'c']);
+      expect(angular.Array.limitTo(items, '3')).toEqual(['a', 'b', 'c']);
+    });
+
+
+    it('should return the last X items when X is negative', function() {
+      expect(angular.Array.limitTo(items, -3)).toEqual(['f', 'g', 'h']);
+      expect(angular.Array.limitTo(items, '-3')).toEqual(['f', 'g', 'h']);
+    });
+
+
+    it('should return an empty array when X cannot be parsed', function() {
+      expect(angular.Array.limitTo(items, 'bogus')).toEqual([]);
+      expect(angular.Array.limitTo(items, 'null')).toEqual([]);
+      expect(angular.Array.limitTo(items, 'undefined')).toEqual([]);
+      expect(angular.Array.limitTo(items, null)).toEqual([]);
+      expect(angular.Array.limitTo(items, undefined)).toEqual([]);
+    })
+  });
+
+
   it('Add', function(){
     var add = angular.Array.add;
     assertJsonEquals([{}, "a"], add(add([]),"a"));