Lang methods

Lang methods test and convert JavaScript values: type checks (isArray, isPlainObject, isNil), equality (isEqual), and cloning or coercion (cloneDeep, toString, toNumber). Use these in place of hand-written typeof and Object.prototype.toString checks for consistent behavior across environments.

_.castArray(value)

Available since v4.4.0.

Casts value as an array if it's not one.

Returns Array — Returns the cast array.

_.castArray(1);
// => [1]

_.castArray({ 'a': 1 });
// => [{ 'a': 1 }]

_.castArray('abc');
// => ['abc']

_.castArray(null);
// => [null]

_.castArray(undefined);
// => [undefined]

_.castArray();
// => []

var array = [1, 2, 3];
console.log(_.castArray(array) === array);
// => true

_.clone(value)

Available since v0.1.0.

Creates a shallow clone of value.

Note: This method is loosely based on the structured clone algorithm and supports cloning arrays, array buffers, booleans, date objects, maps, numbers, Object objects, regexes, sets, strings, symbols, and typed arrays. The own enumerable properties of arguments objects are cloned as plain objects. An empty object is returned for uncloneable values such as error objects, functions, DOM nodes, and WeakMaps.

Returns any — Returns the cloned value.

var objects = [{ 'a': 1 }, { 'b': 2 }];

var shallow = _.clone(objects);
console.log(shallow[0] === objects[0]);
// => true

_.cloneDeep(value)

Available since v1.0.0.

This method is like _.clone except that it recursively clones value.

Returns any — Returns the deep cloned value.

var objects = [{ 'a': 1 }, { 'b': 2 }];

var deep = _.cloneDeep(objects);
console.log(deep[0] === objects[0]);
// => false

_.cloneDeepWith(value, [customizer])

Available since v4.0.0.

This method is like _.cloneWith except that it recursively clones value.

Returns any — Returns the deep cloned value.

function customizer(value) {
  if (_.isElement(value)) {
    return value.cloneNode(true);
  }
}

var el = _.cloneDeepWith(document.body, customizer);

console.log(el === document.body);
// => false
console.log(el.nodeName);
// => 'BODY'
console.log(el.childNodes.length);
// => 20

_.cloneWith(value, [customizer])

Available since v4.0.0.

This method is like _.clone except that it accepts customizer which is invoked to produce the cloned value. If customizer returns undefined, cloning is handled by the method instead. The customizer is invoked with up to four arguments; (value [, index|key, object, stack]).

Returns any — Returns the cloned value.

function customizer(value) {
  if (_.isElement(value)) {
    return value.cloneNode(false);
  }
}

var el = _.cloneWith(document.body, customizer);

console.log(el === document.body);
// => false
console.log(el.nodeName);
// => 'BODY'
console.log(el.childNodes.length);
// => 0

_.conformsTo(object, source)

Available since v4.14.0.

Checks if object conforms to source by invoking the predicate properties of source with the corresponding property values of object.

Note: This method is equivalent to _.conforms when source is partially applied.

Returns boolean — Returns true if object conforms, else false.

var object = { 'a': 1, 'b': 2 };

_.conformsTo(object, { 'b': function(n) { return n > 1; } });
// => true

_.conformsTo(object, { 'b': function(n) { return n > 2; } });
// => false

_.eq(value, other)

Available since v4.0.0.

Performs a SameValueZero comparison between two values to determine if they are equivalent.

Returns boolean — Returns true if the values are equivalent, else false.

var object = { 'a': 1 };
var other = { 'a': 1 };

_.eq(object, object);
// => true

_.eq(object, other);
// => false

_.eq('a', 'a');
// => true

_.eq('a', Object('a'));
// => false

_.eq(NaN, NaN);
// => true

_.gt(value, other)

Available since v3.9.0.

Checks if value is greater than other.

Returns boolean — Returns true if value is greater than other, else false.

_.gt(3, 1);
// => true

_.gt(3, 3);
// => false

_.gt(1, 3);
// => false

_.gte(value, other)

Available since v3.9.0.

Checks if value is greater than or equal to other.

Returns boolean — Returns true if value is greater than or equal to other, else false.

_.gte(3, 1);
// => true

_.gte(3, 3);
// => true

_.gte(1, 3);
// => false

_.isArguments(value)

Available since v0.1.0.

Checks if value is likely an arguments object.

Returns boolean — Returns true if value is an arguments object, else false.

_.isArguments(function() { return arguments; }());
// => true

_.isArguments([1, 2, 3]);
// => false

_.isArray(value)

Available since v0.1.0.

Checks if value is classified as an Array object.

Returns boolean — Returns true if value is an array, else false.

_.isArray([1, 2, 3]);
// => true

_.isArray(document.body.children);
// => false

_.isArray('abc');
// => false

_.isArray(_.noop);
// => false

_.isArrayBuffer(value)

Available since v4.3.0.

Checks if value is classified as an ArrayBuffer object.

Returns boolean — Returns true if value is an array buffer, else false.

_.isArrayBuffer(new ArrayBuffer(2));
// => true

_.isArrayBuffer(new Array(2));
// => false

_.isArrayLike(value)

Available since v4.0.0.

Checks if value is array-like. A value is considered array-like if it's not a function and has a value.length that's an integer greater than or equal to 0 and less than or equal to Number.MAX_SAFE_INTEGER.

Returns boolean — Returns true if value is array-like, else false.

_.isArrayLike([1, 2, 3]);
// => true

_.isArrayLike(document.body.children);
// => true

_.isArrayLike('abc');
// => true

_.isArrayLike(_.noop);
// => false

_.isArrayLikeObject(value)

Available since v4.0.0.

This method is like _.isArrayLike except that it also checks if value is an object.

Returns boolean — Returns true if value is an array-like object, else false.

_.isArrayLikeObject([1, 2, 3]);
// => true

_.isArrayLikeObject(document.body.children);
// => true

_.isArrayLikeObject('abc');
// => false

_.isArrayLikeObject(_.noop);
// => false

_.isBoolean(value)

Available since v0.1.0.

Checks if value is classified as a boolean primitive or object.

Returns boolean — Returns true if value is a boolean, else false.

_.isBoolean(false);
// => true

_.isBoolean(null);
// => false

_.isBuffer(value)

Available since v4.3.0.

Checks if value is a buffer.

Returns boolean — Returns true if value is a buffer, else false.

_.isBuffer(new Buffer(2));
// => true

_.isBuffer(new Uint8Array(2));
// => false

_.isDate(value)

Available since v0.1.0.

Checks if value is classified as a Date object.

Returns boolean — Returns true if value is a date object, else false.

_.isDate(new Date);
// => true

_.isDate('Mon April 23 2012');
// => false

_.isElement(value)

Available since v0.1.0.

Checks if value is likely a DOM element.

Returns boolean — Returns true if value is a DOM element, else false.

_.isElement(document.body);
// => true

_.isElement('<body>');
// => false

_.isEmpty(value)

Available since v0.1.0.

Checks if value is an empty object, collection, map, or set.

Objects are considered empty if they have no own enumerable string keyed properties.

Array-like values such as arguments objects, arrays, buffers, strings, or jQuery-like collections are considered empty if they have a length of 0. Similarly, maps and sets are considered empty if they have a size of 0.

Returns boolean — Returns true if value is empty, else false.

_.isEmpty(null);
// => true

_.isEmpty(true);
// => true

_.isEmpty(1);
// => true

_.isEmpty([1, 2, 3]);
// => false

_.isEmpty({ 'a': 1 });
// => false

_.isEqual(value, other)

Available since v0.1.0.

Performs a deep comparison between two values to determine if they are equivalent.

Note: This method supports comparing arrays, array buffers, booleans, date objects, error objects, maps, numbers, Object objects, regexes, sets, strings, symbols, and typed arrays. Object objects are compared by their own, not inherited, enumerable properties. Functions and DOM nodes are compared by strict equality, i.e. ===.

Returns boolean — Returns true if the values are equivalent, else false.

var object = { 'a': 1 };
var other = { 'a': 1 };

_.isEqual(object, other);
// => true

object === other;
// => false

_.isEqualWith(value, other, [customizer])

Available since v4.0.0.

This method is like _.isEqual except that it accepts customizer which is invoked to compare values. If customizer returns undefined, comparisons are handled by the method instead. The customizer is invoked with up to six arguments: (objValue, othValue [, index|key, object, other, stack]).

Returns boolean — Returns true if the values are equivalent, else false.

function isGreeting(value) {
  return /^h(?:i|ello)$/.test(value);
}

function customizer(objValue, othValue) {
  if (isGreeting(objValue) && isGreeting(othValue)) {
    return true;
  }
}

var array = ['hello', 'goodbye'];
var other = ['hi', 'goodbye'];

_.isEqualWith(array, other, customizer);
// => true

_.isError(value)

Available since v3.0.0.

Checks if value is an Error, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, or URIError object.

Returns boolean — Returns true if value is an error object, else false.

_.isError(new Error);
// => true

_.isError(Error);
// => false

_.isFinite(value)

Available since v0.1.0.

Checks if value is a finite primitive number.

Note: This method is based on Number.isFinite.

Returns boolean — Returns true if value is a finite number, else false.

_.isFinite(3);
// => true

_.isFinite(Number.MIN_VALUE);
// => true

_.isFinite(Infinity);
// => false

_.isFinite('3');
// => false

_.isFunction(value)

Available since v0.1.0.

Checks if value is classified as a Function object.

Returns boolean — Returns true if value is a function, else false.

_.isFunction(_);
// => true

_.isFunction(/abc/);
// => false

_.isInteger(value)

Available since v4.0.0.

Checks if value is an integer.

Note: This method is based on Number.isInteger.

Returns boolean — Returns true if value is an integer, else false.

_.isInteger(3);
// => true

_.isInteger(Number.MIN_VALUE);
// => false

_.isInteger(Infinity);
// => false

_.isInteger('3');
// => false

_.isLength(value)

Available since v4.0.0.

Checks if value is a valid array-like length.

Note: This method is loosely based on ToLength.

Returns boolean — Returns true if value is a valid length, else false.

_.isLength(3);
// => true

_.isLength(Number.MIN_VALUE);
// => false

_.isLength(Infinity);
// => false

_.isLength('3');
// => false

_.isMap(value)

Available since v4.3.0.

Checks if value is classified as a Map object.

Returns boolean — Returns true if value is a map, else false.

_.isMap(new Map);
// => true

_.isMap(new WeakMap);
// => false

_.isMatch(object, source)

Available since v3.0.0.

Performs a partial deep comparison between object and source to determine if object contains equivalent property values.

Note: This method is equivalent to _.matches when source is partially applied.

Partial comparisons will match empty array and empty object source values against any array or object value, respectively. See _.isEqual for a list of supported value comparisons.

Returns boolean — Returns true if object is a match, else false.

var object = { 'a': 1, 'b': 2 };

_.isMatch(object, { 'b': 2 });
// => true

_.isMatch(object, { 'b': 1 });
// => false

_.isMatchWith(object, source, [customizer])

Available since v4.0.0.

This method is like _.isMatch except that it accepts customizer which is invoked to compare values. If customizer returns undefined, comparisons are handled by the method instead. The customizer is invoked with five arguments: (objValue, srcValue, index|key, object, source).

Returns boolean — Returns true if object is a match, else false.

function isGreeting(value) {
  return /^h(?:i|ello)$/.test(value);
}

function customizer(objValue, srcValue) {
  if (isGreeting(objValue) && isGreeting(srcValue)) {
    return true;
  }
}

var object = { 'greeting': 'hello' };
var source = { 'greeting': 'hi' };

_.isMatchWith(object, source, customizer);
// => true

_.isNaN(value)

Available since v0.1.0.

Checks if value is NaN.

Note: This method is based on Number.isNaN and is not the same as global isNaN which returns true for undefined and other non-number values.

Returns boolean — Returns true if value is NaN, else false.

_.isNaN(NaN);
// => true

_.isNaN(new Number(NaN));
// => true

isNaN(undefined);
// => true

_.isNaN(undefined);
// => false

_.isNative(value)

Available since v3.0.0.

Checks if value is a pristine native function.

Note: This method can't reliably detect native functions in the presence of the core-js package because core-js circumvents this kind of detection. Despite multiple requests, the core-js maintainer has made it clear: any attempt to fix the detection will be obstructed. As a result, we're left with little choice but to throw an error. Unfortunately, this also affects packages, like babel-polyfill, which rely on core-js.

Returns boolean — Returns true if value is a native function, else false.

_.isNative(Array.prototype.push);
// => true

_.isNative(_);
// => false

_.isNil(value)

Available since v4.0.0.

Checks if value is null or undefined.

Returns boolean — Returns true if value is nullish, else false.

_.isNil(null);
// => true

_.isNil(void 0);
// => true

_.isNil(NaN);
// => false

_.isNull(value)

Available since v0.1.0.

Checks if value is null.

Returns boolean — Returns true if value is null, else false.

_.isNull(null);
// => true

_.isNull(void 0);
// => false

_.isNumber(value)

Available since v0.1.0.

Checks if value is classified as a Number primitive or object.

Note: To exclude Infinity, -Infinity, and NaN, which are classified as numbers, use the _.isFinite method.

Returns boolean — Returns true if value is a number, else false.

_.isNumber(3);
// => true

_.isNumber(Number.MIN_VALUE);
// => true

_.isNumber(Infinity);
// => true

_.isNumber('3');
// => false

_.isObject(value)

Available since v0.1.0.

Checks if value is the language type of Object. (e.g. arrays, functions, objects, regexes, new Number(0), and new String(''))

Returns boolean — Returns true if value is an object, else false.

_.isObject({});
// => true

_.isObject([1, 2, 3]);
// => true

_.isObject(_.noop);
// => true

_.isObject(null);
// => false

_.isObjectLike(value)

Available since v4.0.0.

Checks if value is object-like. A value is object-like if it's not null and has a typeof result of "object".

Returns boolean — Returns true if value is object-like, else false.

_.isObjectLike({});
// => true

_.isObjectLike([1, 2, 3]);
// => true

_.isObjectLike(_.noop);
// => false

_.isObjectLike(null);
// => false

_.isPlainObject(value)

Available since v0.8.0.

Checks if value is a plain object, that is, an object created by the Object constructor or one with a [[Prototype]] of null.

Returns boolean — Returns true if value is a plain object, else false.

function Foo() {
  this.a = 1;
}

_.isPlainObject(new Foo);
// => false

_.isPlainObject([1, 2, 3]);
// => false

_.isPlainObject({ 'x': 0, 'y': 0 });
// => true

_.isPlainObject(Object.create(null));
// => true

_.isRegExp(value)

Available since v0.1.0.

Checks if value is classified as a RegExp object.

Returns boolean — Returns true if value is a regexp, else false.

_.isRegExp(/abc/);
// => true

_.isRegExp('/abc/');
// => false

_.isSafeInteger(value)

Available since v4.0.0.

Checks if value is a safe integer. An integer is safe if it's an IEEE-754 double precision number which isn't the result of a rounded unsafe integer.

Note: This method is based on Number.isSafeInteger.

Returns boolean — Returns true if value is a safe integer, else false.

_.isSafeInteger(3);
// => true

_.isSafeInteger(Number.MIN_VALUE);
// => false

_.isSafeInteger(Infinity);
// => false

_.isSafeInteger('3');
// => false

_.isSet(value)

Available since v4.3.0.

Checks if value is classified as a Set object.

Returns boolean — Returns true if value is a set, else false.

_.isSet(new Set);
// => true

_.isSet(new WeakSet);
// => false

_.isString(value)

Available since v0.1.0.

Checks if value is classified as a String primitive or object.

Returns boolean — Returns true if value is a string, else false.

_.isString('abc');
// => true

_.isString(1);
// => false

_.isSymbol(value)

Available since v4.0.0.

Checks if value is classified as a Symbol primitive or object.

Returns boolean — Returns true if value is a symbol, else false.

_.isSymbol(Symbol.iterator);
// => true

_.isSymbol('abc');
// => false

_.isTypedArray(value)

Available since v3.0.0.

Checks if value is classified as a typed array.

Returns boolean — Returns true if value is a typed array, else false.

_.isTypedArray(new Uint8Array);
// => true

_.isTypedArray([]);
// => false

_.isUndefined(value)

Available since v0.1.0.

Checks if value is undefined.

Returns boolean — Returns true if value is undefined, else false.

_.isUndefined(void 0);
// => true

_.isUndefined(null);
// => false

_.isWeakMap(value)

Available since v4.3.0.

Checks if value is classified as a WeakMap object.

Returns boolean — Returns true if value is a weak map, else false.

_.isWeakMap(new WeakMap);
// => true

_.isWeakMap(new Map);
// => false

_.isWeakSet(value)

Available since v4.3.0.

Checks if value is classified as a WeakSet object.

Returns boolean — Returns true if value is a weak set, else false.

_.isWeakSet(new WeakSet);
// => true

_.isWeakSet(new Set);
// => false

_.lt(value, other)

Available since v3.9.0.

Checks if value is less than other.

Returns boolean — Returns true if value is less than other, else false.

_.lt(1, 3);
// => true

_.lt(3, 3);
// => false

_.lt(3, 1);
// => false

_.lte(value, other)

Available since v3.9.0.

Checks if value is less than or equal to other.

Returns boolean — Returns true if value is less than or equal to other, else false.

_.lte(1, 3);
// => true

_.lte(3, 3);
// => true

_.lte(3, 1);
// => false

_.toArray(value)

Available since v0.1.0.

Converts value to an array.

Returns Array — Returns the converted array.

_.toArray({ 'a': 1, 'b': 2 });
// => [1, 2]

_.toArray('abc');
// => ['a', 'b', 'c']

_.toArray(1);
// => []

_.toArray(null);
// => []

_.toFinite(value)

Available since v4.12.0.

Converts value to a finite number.

Returns number — Returns the converted number.

_.toFinite(3.2);
// => 3.2

_.toFinite(Number.MIN_VALUE);
// => 5e-324

_.toFinite(Infinity);
// => 1.7976931348623157e+308

_.toFinite('3.2');
// => 3.2

_.toInteger(value)

Available since v4.0.0.

Converts value to an integer.

Note: This method is loosely based on ToInteger.

Returns number — Returns the converted integer.

_.toInteger(3.2);
// => 3

_.toInteger(Number.MIN_VALUE);
// => 0

_.toInteger(Infinity);
// => 1.7976931348623157e+308

_.toInteger('3.2');
// => 3

_.toLength(value)

Available since v4.0.0.

Converts value to an integer suitable for use as the length of an array-like object.

Note: This method is based on ToLength.

Returns number — Returns the converted integer.

_.toLength(3.2);
// => 3

_.toLength(Number.MIN_VALUE);
// => 0

_.toLength(Infinity);
// => 4294967295

_.toLength('3.2');
// => 3

_.toNumber(value)

Available since v4.0.0.

Converts value to a number.

Returns number — Returns the number.

_.toNumber(3.2);
// => 3.2

_.toNumber(Number.MIN_VALUE);
// => 5e-324

_.toNumber(Infinity);
// => Infinity

_.toNumber('3.2');
// => 3.2

_.toPlainObject(value)

Available since v3.0.0.

Converts value to a plain object flattening inherited enumerable string keyed properties of value to own properties of the plain object.

Returns Object — Returns the converted plain object.

function Foo() {
  this.b = 2;
}

Foo.prototype.c = 3;

_.assign({ 'a': 1 }, new Foo);
// => { 'a': 1, 'b': 2 }

_.assign({ 'a': 1 }, _.toPlainObject(new Foo));
// => { 'a': 1, 'b': 2, 'c': 3 }

_.toSafeInteger(value)

Available since v4.0.0.

Converts value to a safe integer. A safe integer can be compared and represented correctly.

Returns number — Returns the converted integer.

_.toSafeInteger(3.2);
// => 3

_.toSafeInteger(Number.MIN_VALUE);
// => 0

_.toSafeInteger(Infinity);
// => 9007199254740991

_.toSafeInteger('3.2');
// => 3

_.toString(value)

Available since v4.0.0.

Converts value to a string. An empty string is returned for null and undefined values. The sign of -0 is preserved.

Returns string — Returns the converted string.

_.toString(null);
// => ''

_.toString(-0);
// => '-0'

_.toString([1, 2, 3]);
// => '1,2,3'