Expose _.toLength.

lodash.js

@@ -1475,9 +1475,9 @@
      * `random`, `reduce`, `reduceRight`, `repeat`, `result`, `round`, `runInContext`,
      * `sample`, `shift`, `size`, `snakeCase`, `some`, `sortedIndex`, `sortedIndexBy`,
      * `sortedLastIndex`, `sortedLastIndexBy`, `startCase`, `startsWith`, `sum`,
-     * `sumBy`, `template`, `toLower`, `toInteger`, `toSafeInteger`, `toString`,
+     * `sumBy`, `template`, `toLower`, `toInteger`, `toLength`, `toSafeInteger`,
-     * `toUpper`, `trim`, `trimLeft`, `trimRight`, `truncate`, `unescape`, `uniqueId`,
+     * `toString`, `toUpper`, `trim`, `trimLeft`, `trimRight`, `truncate`, `unescape`,
-     * `upperCase`, `upperFirst`, `value`, and `words`
+     * `uniqueId`, `upperCase`, `upperFirst`, `value`, and `words`
      *
      * @name _
      * @constructor
@@ -9832,6 +9832,22 @@
       return value === value ? (remainder ? value - remainder : value) : 0;
     }
 
+    /**
+     * The abstract operation toLength converts its argument to an integer
+     * suitable for use as the length of an array-like object.
+     *
+     * **Note:** This function is loosely based on [`ToLength`](http://ecma-international.org/ecma-262/6.0/#sec-tolength).
+     *
+     * @static
+     * @memberOf _
+     * @category Lang
+     * @param {*} value The object to be converted to a length.
+     * @return {number} Integer in range 0 to 2^32-1.
+     */
+    function toLength(value) {
+      return clamp(toInteger(value), 0, MAX_ARRAY_LENGTH);
+    }
+
     /**
      * Converts `value` to a plain object flattening inherited enumerable
      * properties of `value` to own properties of the plain object.
@@ -13487,6 +13503,7 @@
     lodash.sumBy = sumBy;
     lodash.template = template;
     lodash.toInteger = toInteger;
+    lodash.toLength = toLength;
     lodash.toLower = toLower;
     lodash.toSafeInteger = toSafeInteger;
     lodash.toString = toString;

test/test.js

@@ -19338,6 +19338,29 @@
 
   /*--------------------------------------------------------------------------*/
 
+  QUnit.module('lodash.toLength');
+
+  (function() {
+    QUnit.test('should return number literal integers in range unchanged', function(assert) {
+      assert.expect(3);
+
+      assert.strictEqual(_.toLength(0), 0);
+      assert.strictEqual(_.toLength(3), 3);
+      assert.strictEqual(_.toLength(MAX_ARRAY_LENGTH), MAX_ARRAY_LENGTH);
+    });
+
+    QUnit.test('should return number as integer clamped to range', function(assert) {
+      assert.expect(4);
+
+      assert.strictEqual(_.toLength(-1), 0);
+      assert.strictEqual(_.toLength('1'), 1);
+      assert.strictEqual(_.toLength(1.1), 1);
+      assert.strictEqual(_.toLength(MAX_INTEGER), MAX_ARRAY_LENGTH);
+    });
+  }());
+
+  /*--------------------------------------------------------------------------*/
+
   QUnit.module('lodash.toPath');
 
   (function() {
@@ -22023,7 +22046,7 @@
     var acceptFalsey = lodashStable.difference(allMethods, rejectFalsey);
 
     QUnit.test('should accept falsey arguments', function(assert) {
-      assert.expect(273);
+      assert.expect(274);
 
       var emptyArrays = lodashStable.map(falsey, lodashStable.constant([]));