_ source

_(value)

Creates a lodash object which wraps value to enable implicit method chaining. Methods that operate on and return arrays, collections, and functions can be chained together. Methods that retrieve a single value or may return a primitive value will automatically end the chain sequence and return the unwrapped value. Otherwise, the value must be unwrapped with _#value.

Explicit chaining, which must be unwrapped with _#value in all cases, may be enabled using _.chain.

The execution of chained methods is lazy, that is, execution is deferred until _#value is implicitly or explicitly called.

Lazy evaluation allows several methods to support shortcut fusion. Shortcut fusion is an optimization strategy which merge iteratee calls; this can help to avoid the creation of intermediate data structures and greatly reduce the number of iteratee executions. Sections of a chain sequence may qualify for shortcut fusion if the section is applied to an array of at least two hundred elements and any iteratees or predicates accept only one argument. The heuristic for whether a section qualifies for shortcut fusion is subject to change.

Chaining is supported in custom builds as long as the _#value method is directly or indirectly included in the build.

In addition to lodash methods, wrappers have Array and String methods.

The wrapper Array methods are:
concat, join, pop, push, shift, sort, splice, and unshift

The wrapper String methods are:
replace and split

The wrapper methods that support shortcut fusion are:
compact, drop, dropRight, dropWhile, filter, find, findLast, head, initial, last, map, reject, reverse, slice, tail, take, takeRight, takeRightWhile, takeWhile, and toArray

The chainable wrapper methods are:
after, ary, assign, assignIn, assignInWith, assignWith, at, before, bind, bindAll, bindKey, chain, chunk, commit, compact, concat, conforms, conj, constant, countBy, create, curry, debounce, defaults, defaultsDeep, defer, delay, difference, differenceBy, differenceWith, disj, drop, dropRight, dropRightWhile, dropWhile, fill, filter, flatten, flattenDeep, flip, flow, flowRight, forEach, forEachRight, forIn, forInRight, forOwn, forOwnRight, functions, functionsIn, groupBy, initial, intersection, intersectionBy, intersectionWith, invert,invoke,iteratee,keyBy,keys,keysIn,map,mapKeys,mapValues,matches,matchesProperty,memoize,merge,mergeWith,method,methodOf,mixin,modArgs,modArgsSet', negate, nthArg, omit, omitBy, once, pairs, pairsIn, partial, partialRight, partition, pick, pickBy, plant, property, propertyOf, pull, pullAll, pullAllBy, pullAt, push, range, rearg, reject, remove, rest, reverse, sampleSize, set, setWith, shuffle, slice, sort, sortBy, sortByOrder, splice, spread, tail, take, takeRight, takeRightWhile, takeWhile, tap, throttle, thru, times, toArray, toPath, toPlainObject, transform, unary, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unset, unshift, unzip, unzipWith, values, valuesIn, without, wrap, xor, xorBy, xorWith, zip, zipObject, and zipWith

The wrapper methods that are not chainable by default are:
add, attempt, camelCase, capitalize, ceil, clamp, clone, cloneDeep, cloneDeepWith, cloneWith, deburr, endsWith, eq, escape, escapeRegExp, every, find, findIndex, findKey, findLast, findLastIndex, findLastKey, floor, get, gt, gte, has, hasIn, head, identity, includes, indexOf, inRange, isArguments, isArray, isArrayLike, isArrayLikeObject, isBoolean, isDate, isElement, isEmpty, isEqual, isEqualWith, isError, isFinite, isFunction, isInteger, isLength, isMatch, isMatchWith, isNaN, isNative, isNil, isNull, isNumber, isObject, isObjectLike, isPlainObject, isRegExp, isSafeInteger, isString, isUndefined, isTypedArray, join, kebabCase, last, lastIndexOf, lowerCase, lowerFirst, lt, lte, max, maxBy, min, minBy, noConflict, noop, now, pad, padLeft, padRight, parseInt, pop, random, reduce, reduceRight, repeat, result, round, runInContext, sample, shift, size, snakeCase, some, sortedIndex, sortedIndexBy, sortedLastIndex, sortedLastIndexBy, startCase, startsWith, sum, sumBy, template, toLower, toInteger, toLength, toNumber, toSafeInteger, toString,toUpper,trim,trimLeft,trimRight,truncate,unescape,uniqueId,upperCase,upperFirst,value, andwords`

Arguments

  1. value (*)

    The value to wrap in a lodash instance.

Returns (Object)

Returns the new lodash wrapper instance.

Example

function square(n) {
  return n * n;
}

var wrapped = _([1, 2, 3]);

// returns an unwrapped value
wrapped.reduce(_.add);
// => 6

// returns a wrapped value
var squares = wrapped.map(square);

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

_.isArray(squares.value());
// => true