Overview

About Boiler.js

Boiler is a utility library that makes every day tasks in JavaScript easier by providing over 115 methods that work with `arrays`, `collections`, `functions`, `numbers`, `objects`, and `strings`. It's the JavaScript equivalent of a Swiss Army Knife.

As with any library worth its own weight, Boiler has its own suite of Unit Tests available.

_([{hsl: [0, 50, 100] }, {hsl: [0, 120, 50]}]).pluck('hsl.1')
// => [50, 120]
_.sortBy([{foo: {bar: 2}}, {foo: {bar: 1}}, {foo: {bar: 3}}], 'foo.bar')
// => [{foo: {bar: 1}}, {foo: {bar: 2}}, {foo: {bar: 3}}]
_.resolve({animals: ['Dolphin', 'Lion', 'Turtle'] }, 'animals.0')
// => 'Dolphin'
_.chain([[1, 2, 3], [2, 3, 4]]).flatten().uniq().end()
// => [1, 2, 3, 4]

Fork on GitHub

If you're interested in contributing Fork us on GitHub to get started.

API

Arrays

at( arr, index )

Returns the element(s) at an index or array of indices.

If `^index^` is passed as an array the values within should represent the indices from which to get elements at.

Returns: Array

_.at(['Earth', 'Mars', 'Jupiter'], 1)
// => ['Mars']
_.at(['Red', 'Green', 'Magenta', 'Yellow'], [2])
// => ['Magenta']
_.at(['Red', 'Green', 'Magenta', 'Yellow'], [0, 2])
// => ['Red', 'Magenta']
_.at(['Red', ['Green', ['Magenta', ['Yellow']]]], 0)
// => ['Red']

Source

difference( arr, *arrs )

Returns the values from `^arr^` that are not in `*^arrs^`.

Accepts any number of arrays as arguments. The first array passed becomes the target array from which to compute differences.

Returns: Array

_.difference(['Red', 'Green', 'Blue'], ['Red', 'Green'])
// => ['Blue']

Source

first( arr, n )

Gets the first element of an array.

Passing `^n^` will return the first `^n^` number of elements starting from the beginning of the array.

Aliases: take

Returns: ...*, Array

_.first([1, 2, 3, 4])
// => 1
_.first(['Mercury', 'Venus', 'Earth', 'Mars'])
// => 'Mercury'
_.first(['Mercury', 'Venus', 'Earth', 'Mars'], 2)
// => ['Mercury', 'Venus']

Source

indexOf( arr, value, from, deep )

Returns the first index at which `^value^` occurs, deferring to JavaScript's native `indexOf` method when available.

Passing an index through `^from^` will get the first occurrence of `^value^` after `^from^`.

When `^deep^` is passed `true`, `^value^` will be searched for using a deep equality comparison, short circuiting the usage of the native `indexOf` method.

If `^value^` does not exist in the array `-1` is returned.

Aliases: firstIndexOf

Returns: ...*, -1

_.indexOf(['Honda', 'Ford', 'GM'], 'Ford')
// => 1
_.indexOf([1, 2, 3], 4);
// => -1
_.indexOf(['Honda', 'Ford', 'GM', 'Suburu', 'Honda'], 'Honda', 3)
// => 4
_.indexOf([1, 2, [3], 1, 2, [3]], [3], 3, true)
// => 5
_.indexOf(['Honda', 'Ford', ['GM']], ['GM'], true)
// => 2

Source

initial( arr, n )

Returns a copy of `^arr^` with all but the last element.

Passing `^n^` will return all but the last `^n^` number of element(s) from the end of `^arr^`.

Returns: Array

_.initial(['Tiger', 'Lion', 'Cheetah'])
// => ['Tiger', 'Lion']
_.initial([1, 2, 3, 4, 5, 6], 2)
// => [1, 2, 3, 4]

Source

intersection( arr, *arrs )

Gets the elements in `^arr^` that are also in `*^arrs^`.

Accepts any number of arrays as arguments. The first array passed becomes the target array from which to compare intersections.

Returns: Array

_.intersection([1, 2, 3, 4], [1, 2, 101, 102], [2, 1])
// => [1, 2]
_.intersection(['Red', 'Green'], ['Green', 'Magenta'])
// => ['Green']
_.intersection([7, 8, 9], [[9], 10, 11])
// => []

Source

last( arr, n )

Gets the last element in `^arr^`.

Passing `^n^` will return the last `^n^` number of elements from the end of `^arr^`.

Returns: Array

_.last([1, 2, 3, 4, 5])
// => 5
_.last(['Hercules', 'Posiedon', 'Apollo'], 2)
// => ['Posiedon', 'Apollo']

Source

lastIndexOf( arr, value, from, deep )

Returns the last index at which `^value^` occurs, deferring to JavaScript's native `lastIndexOf` method when available.

Passing an index through `^from^` will start the search for `^value^` at `^from^` searching backwards.

When `^deep^` is passed `true`, `^value^` will be searched for using a deep equality comparison, short circuiting the usage of the native `lastIndexOf` method.

If `^value^` does not exist in the array `-1` is returned.

Returns: ...*, -1

_.lastIndexOf(['Honda', 'Ford', 'GM'], 'Ford')
// => 1
_.lastIndexOf([1, 2, 3], 4);
// => -1
_.lastIndexOf(['Honda', 'Ford', 'GM', 'Suburu', 'Honda'], 'Honda', 3)
// => 0
_.lastIndexOf([1, 2, [3], 1, 2, [3]], [3], 3, true)
// => 2
_.lastIndexOf(['Honda', 'Ford', ['GM']], ['GM'], true)
// => 2

Source

object( ...*, *arrs )

Creates an object literal from passed values.

When a single array is passed, odd elements are used as keys and even as values.

When two arrays are passed the first is used to create the returned object's keys and the second its values.

When more than two arrays are passed, each array should contain one key and one value.

Passing an even number of arguments will result in all odd arguments being used as keys and all even arguments as values.

Aliases: toObject

Returns: Object

_.object([0, 'Blue'], [1, 'Red'], [2, 'Green'])
// => {0: 'Blue', 1: 'Red', 2: 'Green'}
_.object([0, 1, 2], ['Blue', 'Red', 'Green'])
// => {0: 'Blue', 1: 'Red', 2: 'Green'}
_.object(0, 'Blue', 1, 'Red', 2, 'Green')
// => {0: 'Blue', 1: 'Red', 2: 'Green'}
_.object('numbers', [1, 2, 3])
// => {numbers: [1, 2, 3]}

Source

remove( arr, value )

Removes all instances of `^value^` from the array `^arr^`.

Uses an optimized deep equality comparison to match values to be removed.

Differs from `_.without` in that `_.remove` is destructive.

Returns: Array

_.remove([1, 2, 2, 4], 2)
// => [1, 4]
_.remove([1, [2], [2], 4], [2])
// => [1, 4]

Source

rest( arr, index )

Gets elements from `^arr^` after the first element.

Passing `^index^` will get all elements from `^arr^` after index `^index^`.

Aliases: tail

Returns: Array

_.rest(['Magnolia', 'Rose', 'Lilly'])
// => ['Rose', 'Lilly']
_.rest([1, 2, 3, 4, 5, 6], 3)
// => [4, 5, 6]

Source

union( *arrs )

Returns an array containing all unique values within passed arrays in the order they are present.

Returns: Array

_.union(['Red', 'Green'], ['Blue', 'Red'])
// => ['Red', 'Green', 'Blue']
_.union([1, 2, 3], [2, 3, 4], [3, 4, 5])
// => [1, 2, 3, 4, 5]
_.union([1, 2, [3]], [2, 3, [4]], [3, [[4]], 5])
// => [1, 2, 3, 4, 5]

Source

uniq( arr, fn, scope )

Returns a copy of `^arr^` with all duplicate values removed using a deep equality comparison.

When `^fn^` is passed, each value in `^arr^` is passed through the callback `^fn^` before the uniqueness of values is computed.

When `^scope^` is passed the iterator `^fn^` is bound to the context of `^scope^` when called.

Aliases: unique

Returns: Array

_.uniq([1, 2, 3, 4, 5, 6, 1, 2, 3])
// => [1, 2, 3, 4, 5, 6]
_.uniq([[1, 2, 3], [4, 5, 6], [1, 2, 3], [4, 5, 6]])
// => [[1, 2, 3], [4, 5, 6]]
_.uniq([1, 2, 3, 3], function (n) { return n * 2; })
// => [2, 4, 6]
_.uniq([1, 1, 2, 2, [3, 3, 4, 4]])
// => [1, 2, [3, 3, 4, 4]]
_.uniq([1, 1, 2, 2, [3, 3, 4, 4]], true)
// => [1, 2, 3, 4]

Source

without( arr, values )

Returns a copy of `^arr^` with elements found in the `^values^` array removed.

Differs from `_.remove` in that `_.without` is non-destructive.

Aliases: exclude

Returns: Array

_.without(['Red', 'Green', 'Blue'], ['Red'])
// => ['Green', 'Blue']
_.without([{0: 'Red'}, {1: 'Green'}, {2: 'Blue'}], [{0:'Red'}])
// => [{1: 'Green'}, {2: 'Blue'}]
_.without([1, 2, 3, 4], [3, [4]], true)
// => [1, 2]

Source

zip( *arrs )

Merges the elements of `*^arrs^` into a single array.

Returns: Array

_.zip(['Red', 'Blue'], ['#F00', '#00F'])
// => [['Red', '#F00'], ['Blue', '#00F']]
_.zip([1, 1, 1, 1], [2, 2, 2, 2], [3, 3, 3, 3])
// => [[1, 2, 3], [1, 2, 3], [1, 2, 3], [1, 2, 3]]
_.zip(['Joe', 'Bob', 'Tod'], [28, 35, 40])
// => [['Joe', 28], ['Bob', 35], ['Tod', 40]]

Source

Collections

add( list, path, value )

Adds a value to a collection at `^path^` if target index at `^path^` does not exist.

Values can be added at dot delimited "namespace paths" such as `0.2.1` or `piano.company.22`.

Returns: Array, Object

_.add([1, 2], 2, 3)
// => [1, 2, 3]
_.add({0: 'Green', 1: {}}, '1.0', 'Red')
// => {0: 'Green', 1: 'Blue'}
_.add({piano: 'Yamaha', guitar: 'Fender'}, 'guitar', 'Gibson')
// => {piano: 'Yamaha', guitar: 'Fender'}
_.add({piano: 'Yamaha', guitar: []}, 'guitar.0', 'Gibson')
// => {piano: 'Yamaha', guitar: ['Gibson']}

Source

all( list, fn, scope, deep )

Returns `true` when all members of a collection pass a test established by a condition within `^fn^`.

When `^deep^` is passed as `true`, will perform a deep iteration over values in nested arrays and objects.

Aliases: every

Returns: Boolean

_.all([1, 2, 3], function (n) { return _.isNumber(n) ? true : false; })
// => true
_.all({0: 'Green', 1: 4}, function (n) { return _.isString(n) ? true : false; })
// => false
 _.all({0: 'Green', 1: 'Red', 2: ['Blue']}, function (n) { return _.isString(n) ? true : false; }, true)
// => true

Source

any( list, fn, scope, deep )

Returns `true` if any member of a collection passes a test established in the callback `^fn^`.

When `^deep^` is passed, performs a deep iteration over values in nested arrays and objects.

Aliases: some

Returns: Boolean

_.any(['Red', 22], function (n) {return _.isNumber(n) ? true : false;})
// => true
_.any({0: 44, 1: 'Blue'}, function (n) { return _.isString(n) ? true : false; })
// => true
_.any({0: 44, 1: [22, 'Blue', 66]}, function (n) { return _.isString(n) ? true : false; }, true)
// => true

Source

average( list, fn, deep )

Returns the average of all the numeric values in a collection.

When a callback `^fn^` is passed each value in `^list^` will be computed through `^fn^` before the average value is determined.

When `^deep^` is passed, will perform a deep iteration over values in nested arrays and objects.

Returns: Number

_.average([22, 44, 88])
// => 51.333333333333336
_.average({0: 99, 1: 999})
// => 549
_.average({0: 99, 1: 999, 2: [22, 222]}, true)
// => 335.5
_.average([1, 2, [3]], function(n) { return n * 2; }, true)
// => 4

Source

clear( list )

Returns `^list^` with its values/properties cleared.

Returns: Array, Object

_.clear({0: 'Red', 1: 'Green', 2: 'Blue'})
// => {}
_.clear(['Red', 'Green', 'Blue'])
// => []

Source

clone( list, fn, deep )

Creates a copy of a collection.

By default a shallow clone is returned (where arrays and objects are copied by reference).

A callback passed through `^fn^` will be invoked on each cloned value.

When `^deep^` is passed as `true` a deep copy of `^list^` is returned (where any nested arrays or objects are copied instead of referenced).

Returns: Array, Object

_.clone({0: 'Sky', 1: 'Sun'})
// => {0: 'Sky', 1: 'Sun'}
_.clone([1, 2, 3, [4]], true)
// => [1, 2, 3, [4]]
_.clone([1, 2, [3]], function(num) { return num * 2; })
// => [2, 4, [3]]
_.clone([1, 2, 3], function(num) { return num * 2; }, true)
// => [2, 4, [6]]

Source

compact( list, all )

Returns a copy of `^list^` with all "falsy" values (`false`, `null`, `0`, `''`, `undefined`, and `NaN`) removed`.

When `^all^` is passed as `true` any empty arrays or empty objects will be removed as well.

Returns: Array

_.compact([0, null, undefined, '', NaN, false, {}, [], 'Red'])
// => [{}, [], 'Red']
_.compact({0: [], 1: 'Green', 2: {}, 3: 'Blue'})
// => ['Green', 'Blue']
_.compact([[], 'Green', {}, 'Blue'], true)
// => ['Green', 'Blue']

Source

contains( list, value, deep )

Returns true if `^value^` is within the collection `^list^`.

When `^deep^` is passed `true` values within nested arrays and objects are iterated through.

Aliases: inArray

Returns: Boolean

_.contains([1, 2, 3, 4], 3)
// => true
_.contains({0: 'Red', 1: 'Blue'}, 'Green')
// => false
_.contains({color: 'Red', rgb: ['#F00']}, ['#F00'])
// => true
_.contains({0: 1, 1: [2]}, 2)
// => false
_.contains({0: 1, 1: [2]}, 2, true)
// => true

Source

count( list, fn, scope )

Returns the count of how many values in a collection pass a test.

The test is established by a condition within `^fn^`. The scope of `^fn^` can be bound to the value passed through `^scope^`.

Returns: Number

_.count([1, 'silver', 3, 'gold'], function (v) { return _.isNumber(v); })
// => 2
_.count([1, 'silver', 3, [4, 'gold', 5]], function (v) { return _.isNumber(v); }, true)
// => 4
_.count({0: 'red', 1: 'blue', 2: ['green']}, function(v) { return _.isString(v); })
// => 2
_.count({0: 'red', 1: 'blue', 2: ['green']}, function(v) { return _.isString(v); }, true)
// => 3

Source

countBy( list, fn, scope )

Sorts a collection into groups.

The object returned uses the value as the property that references the number of values in that group.

Returns: Object

_.countBy([1.3, 1.5, 2.2, 2.9], function (n) { return Math.floor(n); })
// => {1: 1, 2: 1}
_.countBy({0: 'Red', 1: 'Red', 2: 'Blue'}, function (c) { return c; })
// => {Red: 2, Blue: 1}

Source

deep( list, fn, depth )

Performs a deep iteration on the target collection calling `^fn^` on every value (including values in nested collections) within `^list^` and returns an array of values that have passed a condition established by the iterator.

When more than three arguments need be passed a configuration object is expected. This configuration object accepts the following properties:

  • `list` The collection to iterate through
  • `fn` The iterator function
  • `depth` The nested depth of which to iterate to
  • `args` An array of arguments to pass to the iterator
  • `noArrays` A boolean flag indicating not to iterate over nested arrays' values
  • `noObjects` A boolean flag indicating not to iterate over nested object-literals' values
  • `retType` A boolean flag telling the method to return `^list^` instead of an array of values that have passed the condition established by `fn`

When `^depth^` is passed an integer, `_.deep` will iterate over nested arrays and object-literals below the specified depth otherwise all nested levels are iterated through. Passing the string `'*'` through `^depth^` has the same effect as not passing `^depth^` in the first place and all nested levels are iterated through.

The iterator callback accepts the following arguments:

  • `depth` A string or integer representing the depth at a given iteration
  • `index` The property name or index of the value at an iteration
  • `value` The value at a current iteration
  • `reference` A reference to `^list^` per iteration
  • `...*` Additional arguments that have been passed to iterator through `^args^`

Returns: Array, Object

_.deep({obj: {0: 'object', 1: {}}, fn: function (d, i, v, r) { r[i] = _.type(v); }, retType: true})
// => {0: 'string', 1: 'object'}
_.deep([0, [1, [2, [3]]]], function (d, i, v) { return _.isNumber(v) ? v : false; })
// => [1, 2, 3]
_.deep({0: {1: {2: {3: [0, 1, 2, 3, [4, 5, 6]]}}}}, function (d, i, v) { return v; }, 1)
// => [{1: {2: {}}}]

Source

each( list, fn, scope )

Iterates through a collection applying the callback `^fn^` to every value in `^list^`.

If `^fn^` returns `false` the loop will break and the callback returns.

Defers to JavaScript's native `forEach` method on arrays when available.

Aliases: forEach

Returns: undefined

_.each([1, 2, 3], function (v, i) { return v === 2 ? false : true; })
// => [1, 2, 3]
_.each([{0: 'red'}, function (v, i) { return v === 2 ? false : true; })
// => [1, 2, 3]

Source

empty( list, deep )

Sets all values in a collection to undefined.

When `^deep^` is passed as `true` nested arrays' and objects' values are set to `undefined` as well.

Returns: Array, Object

_.empty([1, 2])
// => [undefined, undefined]
_.empty({0: 1, 1: 2})
// => {0: undefined, 1: undefined}
_.empty([1, [2]], true)
// => [undefined, [undefined]]
_.empty([1, {0: 2}], true)
// => [undefined, {0: undefined}]
_.empty({0: 1, 1: [2]}, true)
// => {0: undefined, 1: [undefined]}
_.empty({0: 1, 1: {0: 2}}, true)
// => {0: undefined, 1: {0: undefined}}

Source

filter( list, fn, scope )

Searches through the values in a collection returning those that pass a test established by a condition within `^fn^`.

Returns: Array

_.filter([1, 'Blue', 3], function (v) { return _.isString(v) ? true : false; })
// => ['Blue']
_.filter({0: 2, 1: 'Red'}, function (v) { return _.isNumber(v) ? true : false; })
// => [2]

Source

find( list, fn, scope, deep )

Searches through all values in the collection `^list^` returning the first that passes a test established by a condition within `^fn^`.

When `^deep^` is passed as `true` values will be searched for within any nested arrays and objects within `^list^`.

Aliases: findValue

Returns: String, Number

_.find([1, 'Red', 'Blue'], function (v) { return _.isString(v) ? true : false; })
// => 'Red'
_.find({0: 1, 1: 2, 2: 'Red'}, function (v) { return _.isNumber(v) ? true : false; })
// => 1
_.find([1, {0: 2}], function(n) { return n === 2; })
// => undefined
_.find([1, {0: 2}], function(n) { return n === 2; }, true)
// => 2

Source

findKey( obj, fn, scope, deep )

Returns the first value whose property/index has passed a test established by a condition within `^fn^`.

When `^deep^` is passed as `true` properties/indices will be searched for within any nested arrays and objects within `^list^`.

Returns: Number, String

Aliases: findIndex

_.findKey([1, 2, 3, 4], function (v) { return v === 2 ? true : false; })
// => 3
_.findKey({0: 99, 1: 100, 2: 'str'}, function (v) { return v == 2 ? true : false; })
// => "str"
_.findKey([1, [2, 3, 4]], function(k) { return k == 2; })
// => undefined
_.findKey([1, [2, 3, 4]], function(k) { return k == 2; }, true)
// => 4

Source

flatten( obj, depth )

Flattens a nested collection of any depth.

Passing `^n^` will flatten a collection to the specified depth.

Returns: Array

_.flatten([1, [2]])
// => [1, 2]
_.flatten({0: 1, 1: {1: 2}})
// => [1, 2]
_.flatten({0: 1, 1: [2]})
// => [1, 2]
_.flatten([1, [2, {0: 3}]])
// => [1, 2, 3]
_.flatten({0: 1, 1: 2, 2: [3, [4]]}, 1)
// => [1, 2, [3, [4]]]
_.flatten([1, 2, {0: 3, 1: [4]}], 1)
// => [1, 2, {0: 3, 1: [4]}]
_.flatten([1, [2, [3]]], 2)
// => [1, 2, [3]]

Source

getByType( list, type, deep )

Performs a search through the values in a collection and returns an array of values from `^list^ of a given type.

When `^type^` is passed as `'*'` all member values in `^list^` are returned. Supported types are `arguments`, `array`, `bool`, `date`, `element`, `function`, `infinite`, `nan`, `null`, `number`, `object`, `regexp`, `string`, and `undefined`.

When `^deep^` is passed as `true` a recursive search is performed through nested arrays and objects.

Returns: Array

_.getByType({0: 99, 1: 98, 2: 97}, 'number')
// => [99, 98, 97]
_.getByType({0: 99, 1: 98, 2: {0: 'blue'}}, 'string', true)
// => ['blue']
_.getByType({0: 'red', 1: 'green', 2: {0: 96}}, '*', true)
// => ['red', 'green', {0: 96}, 96]
_.getByType([[[1]], [[2]], [[3]]], 'array', true)
// => [[[1]], [1], [[2]], [2], [[3]], [3]]

Source

groupBy( list, map, scope )

Groups a collections values after running each value through `^map^`.

When `^map^` is a string values are grouped by property name.

Returns: Object

_.groupBy(['Cat', 'Dog', 'Iguana'], function (s){ return s.length; })
// => {3: ['Dog'], 6: ['Iguana']}
_.groupBy([{elm: 'K', type: 'metal'}, {elm: 'Ca', type: 'metal'}, {elm: 'Ne', type: 'gas'}], 'type')
// => {metal: [{elm: 'K', type: 'metal'}, {elm: 'Ca', type: 'metal'}], gas: [{elm: 'Ne', type: 'gas'}]}

Source

groupsOf( list, n, pad )

Parses a collection into groups of `^n^` values.

If `^pad^` is passed the collection is padded with `^pad^`.

Returns: Array

_.groupsOf([1.3, 1.5, 2.1, 2.4, 3.9, 3.8, 4.2], 2)
// => [[1.3, 1.5], [2.1, 2.4], [3.9, 3.8], [4.2]]
_.groupsOf([1.3, 1.5, 2.1, 2.4, 3.9, 3.8, 4.2], 2, 9.9)
// => [[1.3, 1.5], [2.1, 2.4], [3.9, 3.8], [4.2, 9.9]]
_.groupsOf({0: 1.3, 1: 1.5, 2: 2.1, 3: 2.4, 4: 3.9, 5: 3.8, 6: 4.2}, 3, 'pad')
// => [[1.3, 1.5, 2.1], [2.4, 3.9, 3.8], [4.2, 'pad', 'pad']]

Source

has( list, key, deep )

Returns `true` if a property/index in a collection exists, deferring to JavaScript's native `has` method when available and `^deep^` has not been passed.

Aliases: keyExists

Returns: Boolean

_.has([0, 1, 2, 3, 4], 3)
// => true
_.has({name: 'Ted', age: 33}, 'name')
// => true
_.has({color: 'red', hex: '#F00'}, 'rgb')
// => false
_.has({color: 'red', hex: '#F00', other: {rgb: '255,0,0'}}, 'rgb')
// => false
_.has({color: 'red', hex: '#F00', other: {rgb: '255,0,0'}}, 'rgb', true)
// => true

Source

invert( list )

Flips a collection's name/value or index/element pairs.

Returns: Array, Object

_.invert({0: 'Green', 1: 'Blue', 2: 'Red', 3:'Yellow'})
// => {Green: 0, Blue: 1, Red: 2, Yellow: 3}
_.invert([1, 2, 3, 4, 5])
// => {1: 0, 2: 1, 3: 2, 4: 3, 5: 4}

Source

invoke( list, fn, args )

Calls `^fn^` on each value in the target collection.

All values in the `^args^` array are passed to `^fn^` when invoked.

Returns: Array, Object

_.invoke({0: 'Tulip', 1: 'Daisy'}, function (v, a) { return v + a; }, [' is a flower.'])
// => ['Tulip is a flower.', 'Daisy is a flower.']

Source

isEmpty( list )

Returns `true` if the collection `^list^` has no values.

Returns: Boolean

_.isEmpty([])
// => true
_.isEmpty({})
// => true
_.isEmpty(['Red', 'Green', 'Blue'])
// => false
_.isEmpty(false)
// => false

Source

isUnique( list, index )

Returns `true` when a targeted value at `^index^` in a collection is unique.

Returns: Boolean

_.isUnique([1, 2, 1, 2, 3], 4)
// => true
_.isUnique({0: 'green', 1: 'green', 2: 'blue'}, 0)
// => false
_.isUnique({arr1: [1, 2, 3], arr2: [1, 2, 3]}, 'arr2')
// => false

Source

keys( list, deep )

Returns an array containing a collection's properties/indices, deferring to JavaScript's native `keys` method when available and `^deep^` has not been passed.

When `^deep^` is passed as `true` the keys of all nested objectss and arrays are returned as well.

Returns: Array

_.keys(['Red', 'Green', 'Blue'])
// => ['0', '1', '2']
_.keys({name: 'Ted', age: 33, eyecolor: 'Blue'})
// => ['name', 'age', 'eyecolor']
_.keys({name: 'Ted', age: 33, extra: {eyecolor: 'Blue'}}, true)
// => ['name', 'age', 'extra', 'extra.eyecolor']
_.keys({name: 'Ted', age: 33, extra: ['Male']}, true)
// => ['name', 'age', 'extra', 'extra.0']

Source

least( list, map )

Returns the value in a collection with the least occurrences.

The `^map^` argument should be a function mapping the value to be tested or a string representing the property name to test.

Returns: ...*

_.least([1, 1, 2, 2, 3])
// => 1
_.least({0: 'Zero', 1: 'Zero', 2: 'One', 3: 'Two', 4: 'Two'})
// => 'One'
_.least([{color: 'Red'}, {color: 'Red'}, {color: 'Green'}])
// => {color: 'Green'}
_.least([{p: 'al', age: 22}, {p: 'al', age: 47}, {p: 'greg', age: 22}], function (t) { return t.age; })
// => {p: 'greg', age: 22}

Source

len( list, deep )

Gets the number of values in a collection.

Performs a deep count of nested values in `^list^` when `^deep^` is `true`.

Returns: Number

_.len([1, 2, 3, 4])
// => 4
_.len({0: 'Zero', 1: 'Zero', 2: 'One', 3: 'Two', 4: 'Two'})
// => 5
_.len([1, [2, [3, [4]]]], true)
// => 4
_.len([1, 2, {colors: ['Red', 'Blue'], numbers: [1, 2]}], true)
// => 6

Source

map( list, fn, scope, deep )

Returns a new array of values transformed by the iterator `^fn^`.

When `^deep^` is passed, will perform a deep iteration over values in nested arrays and objects.

Aliases: collect

Returns: Array

_.map(['Red', 'Green', 'Blue'], function (v) { return v + ' is a primary.'; })
// => ['Red is a primary.', 'Green is a primary.', 'Blue is a primary.']
_.map({one: 'Red', two: 'Green', more: {three: 'Blue'}}, function (v) { return v + ' is a primary.'; }, true)
// => ['Red is a primary.', 'Green is a primary.', 'Blue is a primary.']
_.map([1, 2, 3, [4]], function (v){ return v * this.multiplier; }, {multiplier: 3}, true);
// => [3, 6, 9, 12]

Source

max( list, fn, deep )

Returns the maximum value in a collection.

When a callback `^fn^` is passed each value in `^list^` will be computed through `^fn^` before the maximum value is determined.

When `^deep^` is passed, will perform a deep iteration over values in nested arrays and objects.

Returns: Number

_.max([1, 2, 3])
// => 3
_.max({A: 99, B: 1000, C: 499})
// => 1000
_.max({A: 99, B: [22, 1000], C: 499}, true)
// => 1000
_.max([1, 2, 3], function(n) { return n * 2; })
// => 6

Source

min( list, fn, deep )

Returns the minimum value in a collection.

When a callback `^fn^` is passed each value in `^list^` will be computed through `^fn^` before the minimum value is determined.

When `^deep^` is passed, will perform a deep iteration over values in nested arrays and objects.

Returns: Number

_.min([1, 2, 3])
// => 1
_.min({A: 99, B: 1000, C: 499})
// => 99
_.min([33, 66, 22, [11]], true)
// => 11
_.min([1, 2, 3], function(n) { return n * 2; })
// => 2

Source

most( list, fn )

Returns the value in a collection with the most occurrences.

The callback passed through `^fn^` should map the value to be tested or be a string representing the property name to test.

Returns: ...*

_.most([1, 1, 2, 2, 3])
// => 1
_.most({0: 'Zero', 1: 'Zero', 2: 'One', 3: 'Two'})
// => 'Zero'
_.most([{color: 'Red'}, {color: 'Red'}, {color: 'Green'}], 'color')
// => {color: 'Red'}
_.most([{p: 'al', age: 22}, {p: 'al', age: 47}, {p: 'greg', age: 22}], function (t) { return t.p; })
// => {p: 'al', age: 22}

Source

none( list, fn, scope, deep )

Returns true if none of the values in a collection passes a condition established within `^fn^`.

When `^deep^` is passed, will perform a deep iteration over values in nested arrays and objects.

Returns: Boolean

_.none(['Red', 'Green', 'Blue'], function (v)  { return _.isNull(v) ? true : false; })
// => true
_.none([0, 1, null], function (v) { return _.isNull(v) ? true : false; })
// => false
_.none([0, 1, [null]], function (v) { return _.isNull(v) ? true : false; }, true)
// => false

Source

omit( list, keys )

Returns all values in `^list^` with properties/indices that are not matched in `^keys^`.

Aliases: blacklist

Returns: Array, Object

_.omit(['Red', 'Green', 'Blue'], 0)
// => ['Green', 'Blue']
_.omit(['Red', 'Green', 'Blue'], [0, 1])
// => ['Blue']
_.omit({red: '#F00', green: '#0F0', blue: '#00F'}, 'green')
// => ['#F00', '#00F']
_.omit({red: '#F00', green: '#0F0', blue: '#00F'}, ['red', 'green'])
// => ['#00F']

Source

only( list, indices )

Returns only the values whose properties/indices are matched in the `^indices^` array.

Aliases: whitelist

Returns: Array, Object

_.only(['red', 'green', 'blue'], [0, 1])
// => ['red', 'green']
_.only({red: '#F00', green: '#0F0', blue: '#00F'}, ['green'])
// => ['#0F0']

Source

paths( list, keys, enum )

Returns an object-literal containing unique "namespace paths" as properties that reference corresponding values in the target `^list^`.

Alternatively passing `^keys^` with a value of `true` will return an object-literal with "namespace path" property names that reference their paths as values.

When `^enum^` receives a value of `true` the paths of any non-enumerable properties in `^list^` will be returned as well.

The `paths` method returns array paths in the same manner where a dot delimited string of `0.2.1` could be thought to represent a value in a nested array such as `arr[0][2][1]`.

Returns: Object

_.paths({color: {rgb: '#0F0'}})
// => {color: {rgb: '#0F0'}, 'color.rgb': '#0F0'}
_.paths({color: {red: {val: '#F00'}}})
// => {color: 'color', red: 'color.red', val: 'color.red.val'}
_.paths(['red'], false, true)
// => {0: 'red', length: 1}

Source

reduce( list, fn, scope )

Returns the reduced value from `^list^`'s values.

The iterator `^fn^` determines the initial value of the reduction.

Aliases: foldl

Returns: Number

_.reduce([22, 44, 88], function (base, value, index) { return base - value; })
// => -110

Source

reduceRight( list, fn, scope )

Returns the right associative reduced value from `^list^`'s values.

The iterator `^fn^` determines the initial value of the reduction.

Aliases: foldr

Returns: Number

_.reduceRight([88, 44, 22], function (base, value, index) { return base - value; })
// => 22

Source

reject( list, fn, scope )

Searches through all values in the collection `^list^` returning all but the values that pass a test in `^fn^`.

This method is the opposite of `filter`. The test is established by a condition within `^fn^`.

Returns: Array

_.reject([1, 2, 3, 'String'], function (v) { return _.isNumber(v) ? true : false; })
// => ['String']
_.reject({0: 1, 1: 2, 2: 'String'}, function (v) { return _.isNumber(v) ? true : false; })
// => ['String']

Source

replace( list, fn, scope, deep )

Returns a collection that has had the iterator `^fn^` passed over each value.

The returned result from `^fn^` is placed at the corresponding name/index in `^list^`.

When `^deep^` is passed as `true` any nested arrays' and object-literals' values are iterated over.

Returns: Array, Object

_.replace({red: '#F00', blue: '#00F'}, function (v) { return v + '000'; })
// => {red: '#F00000', blue: '#00F000'}
_.replace([1, 2], function(v) { return v * this.x; }, {x: 2})
// => [2, 4]
_.replace([1, [2]], function(v) { return v * 2; }, true)
// => [2, [4]]
_.replace({0: 1, 1: [2]}, function(v) { return v * 2; }, true)
// => {0: 2, 1: [4]}

Source

sample( list, n, deep )

Gets a random sample of values from a collection.

When `^n^` is passed returns `^n^` number of random samples.

When `^deep^` is passed as `true` values within nested arrays and objects are flattened.

Returns: Array

_.sample([2, 3, 5, 4, 1])
// => [2]
_.sample([1, 2, 4, 3, 5], 3)
// => [2, 1, 1]
_.sample([1, 2, 4, [3, 5]], 3, true)
// => [5, 1, 3]

Source

set( list, path, value )

Adds a value to a collection at `^path^` even if target index at `^path^` already exists.

Values can be added at dot delimited "namespace paths" such as `0.2.1` or `piano.company.22`.

Returns: Array, Object

_.set([1, 2, 'String', 4, 5, 6], 2, 3)
// => [1, 2, 3, 4, 5, 6]
_.set({red: '#F00', green: '#0F0', yellow: '#000'}, 'yellow', '#0FF')
// => {red: '#F00', green: '#0F0', yellow: '#0FF'}
_.set({red: '#F00', green: '#0F0', others: {}}, 'others.yellow', '#0FF')
// => {red: '#F00', green: '#0F0', others: {yellow: '#0FF'}}

Source

setUndef( list, value, deep )

Sets all undefined values in a collection to `^value^`.

When `^deep^` is passed as `true` any nested arrays or object-literals in `^list^` are iterated through as well.

Returns: Array, Object

_.setUndef([1, undefined, 3], 2)
// => [1, 2, 3]
_.setUndef({blue: '#00F', yellow: '#0FF', cyan: undefined}, '#0FF')
// => {blue: '#00F', yellow: '#0FF', cyan: '#0FF'}
_.setUndef([1, undefined, [9, undefined]], 2, true)
// => [1, 2, 3]

Source

shuffle( list )

Gets a randomized copy of values in a collection.

Implements Fischer-Yates shuffle algorithm.

Returns: Array, Object

_.shuffle([5, 4, 2, 3, 1])
// => [5, 4, 2, 3, 1]
_.shuffle({0: 'Red', 1: 'Green', 2: 'Blue', 3: 'Yellow'})
// => ['Green', 'Red', 'Yellow', 'Blue']

Source

size( list, deep )

Gets the number of values in a collection that are not "falsy" (`null`, `undefined`, `0`, `''`, `false` or `NaN`).

When `^deep^` is passed as `true` non-falsy values in nested arrays and objects are counted.

Returns: Number

_.size([1, null, 2, 3, ''])
// => 3
_.size([1, [false, [2, [undefined, [3]]]]], true)
// => 3

Source

sortBy( list, fn, scope )

Returns an array of elements that have been sorted in ascending order by the computed results of running the values in `^list^` through the callback `^fn^`.

When a property name is passed through `^fn^` a callback is created that returns the value at the given property in each element. Deeply nested properties can be targeted via dot notation.

Returns: Array

_.sortBy([1, 2, 3, 4, 5, 6], function (num){ return Math.cos(num); })
// => [3, 4, 2, 5, 1, 6]
_.sortBy([1, 2, 3, 4, 5, 6], function (num){ return Math.cos(num * 2); }, {x: 2})
// => [5, 2, 1, 4, 6, 3]
_.sortBy(['Jupiter', 'Earth', 'Venus', 'Mars'], function(p) { return p.length; })
// => ['Mars', 'Earth', 'Venus', 'Jupiter']
_.sortBy(['Jupiter', 'Earth', 'Venus', 'Mars'], 'length')
// => ['Mars', 'Earth', 'Venus', 'Jupiter']
_.sortBy([{foo: {bar: 2}}, {foo: {bar: 1}}, {foo: {bar: 3}}], 'foo.bar')
// => [{foo: {bar: 1}}, {foo: {bar: 2}}, {foo: {bar: 3}}]

Source

sum( list, deep )

Returns the sum total of all the numeric values in the collection `^list^`.

When the callback is passed, `^fn^` is invoked on each numeric value before the value is used in computing the sum total.

When `^deep^` is passed as `true`, numeric values in nested arrays and objects are additionally used to compute the sum total.

Returns: Number

_.sum([1, 2, 3, 4])
// => 10
_.sum({0: 99, 1: 999, 2: 9999})
// => 11097
_.sum({0: 99, 1: 999, 2: 9999, 3: [22, 222, 2222]}, true)
// => 13563
_.sum([1, 2, 3, 4], function (num) { return num * 2; })
// => 20

Source

tap( list, fn, scope )

Method is useful for interjecting arbitrary code upon intermediary results within a chained sequence.

Returns: ...*

_.tap({0: 'Red'}, function (obj){ return _.toArray(obj); })
// => ['Red']
_.chain([1, 2, 3]).tap(function(arr) { return _.toObject('arr1', arr); }).len(true).end();
// => 3

Source

values( list, deep )

Returns an array containing the values in a collection.

When `^deep^` is passed as `true` the values of all nested objects and arrays are returned as well.

Returns: Array

_.values(['Red', 'Green', 'Blue'])
// => ['Red', 'Green', 'Blue']
_.values({name: 'Ted', age: 33})
// => ['Ted', 33]
_.values({0: 1, 1: {0: 1, 1: 2}}, true)
// => [0, {0: 1, 1: 2}, 1, 2]

Source

where( list, matches )

Returns an array containing the name/value pairs in `^list^` that contain matching the name/value pairs in `^matches^`.

Returns: Array

_.where([{id: 0, age: 22}, {id: 1, age: 29}, {id: 2, age: 29}], {age: 29})
// => [{id: 1, age: 29}, {id: 2, age: 29}]
_.where([{id: 0, age: 22}, {id: 1, age: 29}, {id: 2, age: 29}], {id: 1, age: 29})
// => [{id: 1, age: 29}]

Source

whereFirst( list, matches )

Returns the first matched object containing the name/value pairs in `^matches^`.

Returns: Object

_.whereFirst([{id: 0, age: 29}, {id: 1, age: 29}, {id: 2, age: 29}], {age: 29})
// => {id: 0, age: 29}

Source

Functions

after( fn, n, start )

Returns a function that will execute on every `^n^`th call.

Returns: Function

var fn = function(val) { alert(val); };
fn = _.after(fn, 3);
// => fn(99); fn(99); fn(99); => 99

Source

bind( fn, scope, args )

Returns a function that is bound to the context of `^scope^` when called.

Currying of an unlimited number of arguments is achieved by passing `^args^` as an array of arguments to be passed to `^fn^`. When `^fn^` is passed additional arguments when the function is called they are added to the end of the curried arguments passed through `^args^`.

Returns: Function

var ecosystem = function() { alert(this.type + '!'); };
var rainforest = {type: 'Tropical'};
ecosystem = _.bind(ecosystem, rainforest);
// => ecosystem() => 'Tropical!'

Source

bindAll( obj, methods )

Binds one or more methods to the objects specified in `^methods^`.

Bound `^methods^` are executed in the context of the target object `^obj^`. When `^methods^` is not passed all of the target object's function properties are bound.

Returns: Function

var htmlButton = {
    title   : 'Boiler.js',
    onClick : function() { alert('Mouse Click: ' + this.title); },
    onHover : function() { console.log('Mouse Hovering: ' + this.title); }
};
_.bindAll(htmlButton);
jQuery('#button').bind('click', htmlButton.onClick);
jQuery('#button').bind('mouseover', htmlButton.onHover);
// => When the button is clicked, this.title will have the value 'Boiler.js'

Source

compose( *fns )

Returns a function that is the composition of all passed functions.

The returned value from a function is given as the first argument of the next function in *`^fns^`. Mathematically, function composition is the application of one function to the results of another.

Returns: Function

var scorch = function(meat) { return meat + ' is scorched'; };
var broil = function(meat){ return meat + ' and broiled!'; };
var meat = _.compose(broil, scorch);
// => meat('Chicken') => 'Chicken is scorched and broiled!'

Source

debounce( fn, n, edge )

Returns a function that will NOT be invoked until it hasn't been called for `^n^` milaseconds.

When `^edge^` is passed with `true`, `^fn^` is triggered on the leading vs. the trailing edge of the interval. A debounced function allows us to "temper" the number of times it runs. For instance in the case of a window resize event, instead of an event listener firing on every iteration we can ensure that it fires once every `^n^` milliseconds. This behavior can be extremely beneficial for handlers that might otherwise bog down a users browser.

Returns: Function

var windowWidth = function() { return window.width; }
var widthChange = _.debounce(windowWidth, 500);
jQuery(window).resize(widthChange);
// => When window is resizing `windowWidth` is fired every 500 ms.

Source

defer( fn )

Returns a function that when called will not run immediately; instead, it runs after the current call stack is cleared.

This method is similar to using the `setTimeout` function with no delay and can be useful when performing computationally expensive operations that may block the browser UI thread from rendering.

Returns: Function

var message = function( msg ){ alert(msg); };
var deferredMsg = _.defer(message);
message('One');
deferredMsg('Two');
message('Three');
// => 'Three' alerts before 'Two'

Source

delay( fn, ms )

Returns a function that executes after `^ms^` number of milliseconds when invoked.

Returns: Function

var delayed = _.delay(function(msg) { alert('3 seconds ' + msg); }, 3000);
delayed('after page load!');
// => '3 seconds afteer page load!' alerts after three seconds.

Source

fill( fn, args )

Returns a function that has been partially "applied" by currying its arguments.

The execution context (the dynamic `this` value) goes unchanged.

Aliases: partial

Returns: Function

var filledFn = _.fill(setTimeout, undefined, 1000);
filledFn(function() {
    // Will be executed 1000 ms later
});
// => Curries values to be used by setTimeout.

Source

memoize( fn, hash )

Returns a memoized version of `^fn^` by caching the function's returned result.

Memoization can drastically speed up sluggish computations that might otherwise bring a given system to a halt.

When passed the optional hashing function `^hash^` it will be used to determine the hash key where the cached result is stored based on the arguments passed to `^fn^`. By default the first argument of `^fn^` is used as the hash key.

Returns: Function

var fibonacci = _.memoize(function(n) {
    return n < 2 ? n : fibonacci(n - 1) + fibonacci(n - 2);
});
// => When called stores previously computed values onto itself

Source

once( fn )

Returns a function that can only be called one time.

Returns: Function

var init = _.once(myApplication);
init();
init();
// => The second call to init() does nothing.

Source

throttle( fn, ms )

Returns a throttled version of `^fn^` that can only be invoked every `^ms^` number of milliseconds.

This method is useful when a function is being called repeatedly and limiting the rate of its invocation is a factor.

Returns: Function

var throttled = _.throttle(getWindowSize, 200);
$(window).resize(throttled);
// => On window resize throttle will execute only every 200 ms

Source

times( fn, n )

Returns a function that will sequentially execute `^n^` times.

Returns: Function

var rain = function() { return 'drop'; };
rain = _.times(rain, 3);
rain();
// => 'drop' => 'drop' => 'drop'

Source

wrap( fn, wrapper )

Returns a function that has been wrapped in the `^wrapper^` function.

The function that is wrapped is passed as the first argument to `^wrapper^`. This provides a mechanism for running code before and/or after `^fn^` runs.

Returns: Function

var season = function(name) { return name + ' which is before '; };
season = _.wrap(season, function(fn) {
    return "First winter then " + fn('Spring') + 'Summer!';
});
season();
// => 'First winter then Spring which is before Summer!'

Source

Numbers

range( start, stop, step )

Returns an array containing numbers in a range.

Returns: Array

_.range(0, 100, 10)
// => [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]

Source

uniqueId( prefix )

Returns a globally unique ID.

Unique ID will be prefixed with `^prefix^` when passed.

Returns: String, Number

_.uniqueId()
// => '1421'
_.uniqueId('pre-')
// => 'pre-00884'

Source

Objects

array( *objs )

Creates an array from an object.

When multiple object arguments are passed creates an array from the values in `*^objs^`.

Aliases: toArray

Returns: Array

_.array({0: 'Green', 1: 'Blue'})
// => ['Green', 'Blue']
_.array({0: 'Red'}, {0: 'Green'}, {0: 'Blue'})
// => ['Red', 'Green', 'Blue']

Source

defaults( obj, defaults )

Sets `null` and `undefined` values in `^obj^` with default replacement values.

Replacement values are passed in the `^defaults^` object and will not override values that have already been set.

Returns: Object

_.defaults({color: 'Red', rgb: '#F00', hsl: '0, 100, 50'}, {hsl: '0, 100, 50', rgb: '#F00'})
// => {color: 'Red', rgb: '#F00', hsl: '0, 100, 50'}

Source

extend( *objs, deep )

Merges two or more objects together into the first.

Properties with the same name will be overridden by merged objects.

When `^deep^` is passed as `true` nested objects in the target object will additionally be extended.

Aliases: merge

Returns: Object

_.extend({0: 'zero', 1: 'one', 2: 'two'}, {1: 'one'}, {2: 'two'})
// => {0: 'zero', 1: 'one', 2: 'two'}
_.extend({0: 'zero', 1: 'one', 2: 'two', A: {1: 'one', 2: 'two'}}, {1: 'one'}, true, {2: 'two'})
// => {0: 'zero', 1: 'one', 2: 'two', A: {1: 'one', 2: 'two'}}

Source

get( obj, key )

Gets the value located at the `^key^` target property within `^obj^`.

Performs a deep search through all nested objects to find `^key^` and returns the first match.

Returns: ...*

_.get({0: {a: 8, b: {b_1: 'Green'}}}, 'b_1')
// => 'Green'

Source

howDeep( obj, key )

Returns an integer representing the value targeted at `^key^`'s nest level (or depth) within `^obj^`.

When duplicate keys exist the depth of the one deepest is returned.

Returns: Number

_.howDeep({0: {1: {2: 'Green'}}}, 2)
// => 3
_.howDeep({color: {red: {vals: {hex: '#F00'}}}}, 'hex')
// => 4
_.howDeep([['red'], [{color: 'blue'}]], 'color')
// => 3
_.howDeep([[[['green']]]], 0)
// => 4

Source

isArguments( obj )

Returns `true` if `^obj^` is of type `[argument]`.

Returns: Boolean

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

Source

isArray( obj )

Returns `true` if `^obj^` is of type `[array]`.

Returns: Boolean

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

Source

isBool( obj )

Returns `true` if `^obj^` is of type `[bool]`.

Returns: Boolean

_.isBool(false)
// => true

Source

isDate( obj )

Returns `true` if `^obj^` is of type `[date]`.

Returns: Boolean

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

Source

isElement( obj )

Returns `true` if `^obj^` is of type `[element]`.

Returns: Boolean

_.isElement(document.createElement('a'))
// => true

Source

isEqual( obj1, obj2 )

Performs a deep comparison between two objects, testing for equality between all properties and values.

Returns: Boolean

_.isEqual(null, null)
// => true
_.isEqual(0, 0)
// => true
_.isEqual(undefined, undefined)
// => true
_.isEqual(NaN, NaN)
// => true
_.isEqual('', '')
// => true
_.isEqual(function (){}, function (){})
// => true
_.isEqual([1, 2, 3, 4], [1, 2, 3, 4])
// => true
_.isEqual([1, 2, 3, 4, [1,  2]], [1, 2, 3, 4, [1,  2]])
// => true
_.isEqual({0: {a: 3, b: {b_1: 'Green'}}}, {0: {a: 3, b: {b_1: 'Green'}}})
// => true

Source

isFalsy( obj )

Returns `true` if `^obj^`'s value is `false`, `null`, `0`, `""`, `undefined`, `NaN`.

Returns: Boolean

_.isFalsy('')
// => true
_.isFalsy(0)
// => true
_.isFalsy(NaN)
// => true
_.isFalsy(false)
// => true
_.isFalsy(null)
// => true
_.isFalsy([])
// => false
_.isFalsy({})
// => false

Source

isFunction( obj )

Returns `true` if `^obj^` is of type `[function]`.

Returns: Boolean

_.isFunction(function () {})
// => true

Source

isInfinite( obj )

Returns `true` if `^obj^` is of type `[infinite]`.

Returns: Boolean

_.isInfinite(Infinity)
// => true
_.isInfinite(-Infinity)
// => true

Source

isNaN( obj )

Returns `true` if `^obj^` is of type `[nan]`.

Returns: Boolean

_.isNaN(NaN)
// => true

Source

isNull( obj )

Returns `true` if `^obj^` is of type `[null]`.

Returns: Boolean

_.isNull(null)
// => true

Source

isNumber( obj )

Returns `true` if `^obj^` is of type `[number]`.

Returns: Boolean

_.isNumber(99)
// => true
_.isNumber(-99)
// => true
_.isNumber(99.98798)
// => true
_.isNumber(Infinity)
// => true
_.isNumber(NaN)
// => true
_.isNumber('99')
// => false

Source

isObject( obj )

Returns `true` if `^obj^` is of type `[object]`.

Will return `true` for all object types in JavaScript.

Returns: Boolean

_.isObject({color: {red: '#F00'}})
// => true
_.isObject(function () {})
// => false
_.isObject(Math)
// => true

Source

isPlainObject( obj )

Returns `true` if `^obj^` is of type `[object]`.

Returns: Boolean

_.isPlainObject({color: {red: '#F00'}})
// => true
_.isPlainObject(function () {})
// => false
_.isPlainObject(Math)
// => false

Source

isRegExp( obj )

Returns `true` if `^obj^` is of type `[regexp]`.

Returns: Boolean

_.isRegExp(/[a-z]/)
// => true
_.isRegExp(/[\']([0-9])[\']/g)
// => true
_.isRegExp(new RegExp('\\w+'))
// => true

Source

isString( obj )

Returns `true` if `^obj^` is of type `[string]`.

Returns: Boolean

_.isString('Apples are not oranges.')
// => true
_.isString(['Apples', 'Oranges'])
// => false

Source

isUndefined( obj )

Returns `true` if `^obj^` is of type `[undefined]`.

Returns: Boolean

_.isUndefined(undefined)
// => true
_.isUndefined({})
// => false

Source

module( ns )

Builds an object from a namespace string such as `'MyModule.DOM.Utility'`.

Aliases: build

Returns: Object

_.module('Earth.places.ocean')
// => {Earth: {places: {ocean: {}}}}

Source

nest( obj, prefix )

Returns an object whose children have been encapsulated within their own object.

When `^prefix^` is passed a prefix string will be prepended to the newly nested objects' property names.

Returns: Object

_.nest({red: {red: '#F00'}, blue: {blue: '#00F'}, green: {green: '#0F0'}})
// => {red: {red: '#F00'}, blue: {blue: '#00F'}, green: {green: '#0F0'}}
_.nest({red: {'color-red': '#F00'}, blue: {'color-blue': '#00F'}, green: {'color-green': '#0F0'}}, 'color-')
// => {red: {'color-red': '#F00'}, blue: {'color-blue': '#00F'}, green: {'color-green': '#0F0'}}

Source

pairs( obj )

Gets the name value pairs from `^obj^`.

An object's name/value pairs are returned as an array of arrays.

Returns: Array

_.pairs({red: '#F00', green: '#0F0', blue: '#00F'})
// => [['red', '#F00'], ['green', '#0F0'], ['blue', '#00F']]

Source

parent( obj, key )

Gets the parent object of a nested object at the property `^key^`.

When no parent object exists the target object is returned.

Returns: Object

_.parent({color: {red: {val: {rgb: '#F00'}}}}, 'val')
// => {val: {rgb: '#F00'}}

Source

pluck( obj, key )

Returns an array containing extracted property values.

This method is a shortcut for a common usage of the `map` method where values that exists at a property are returned.

Deep targeting of values is supported by passing a dot delimited "namespace path" through `^key^`.

Aliases: fetch

Returns: Array

_.pluck([{color: 'red', hex: '#F00'}, {color: 'blue', hex: '#00F'}, {color: 'green', hex: '#0F0'}], 'color')
// => ['red', 'blue', 'green']
var colors = [{color: {vals: {hex: 'FF0'}}}, {color: {vals: {hex: '0F0'}}}, {color: {vals: {hex: '00F'}}}];
_.pluck(colors, 'color.vals.hex')
// => ['FF0', '0F0', '00F']

Source

resolve( obj, key, paths, own )

Returns the value at a target `^key^` (property name) OR the full path to a partial property name within `^obj^`.

When `^paths^` is passed as `true` the full namespace path of a partial path given through `^key^` is returned.

When `^own^` is passed as `true` non-enumerable properties become accessible.

Returns: String

_.resolve({colors: {red: {vals: {rgb: '#F00', hsl: '0, 100, 50'}}}}, 'colors.red.vals.rgb')
// => '#F00'
_.resolve({colors: {red: {vals: {rgb: '#F00', hsl: '0, 100, 50'}}}}, 'rgb', true)
// => 'colors.red.vals.rgb'
_.resolve({colors: {red: {vals: {rgb: '#F00', hsl: [0, 100, 50]}}}}, 'colors.red.vals.hsl.1')
// => 100
_.resolve([['red', 'blue'], ['green'], 'orange'], '0.length', false, true)
// => 2

Source

toQueryString( obj, prefix )

Creates a query string converted from an object literal.

Will attempt to convert deeply nested objects and arrays. When `^prefix^` is provided the prefix string is prepended to each property name.

Returns: String

_.toQueryString({firstname: 'John', middlename: 'Edgar', lastname: 'Hoover'})
// => "firstname%3DJohn%26middlename%3DEdgar%26lastname%3DHoover"
_.toQueryString({colors: ['Red', 'Blue']}, 'pre-')
// => "pre-colors%5B%5D%3DRed%26pre-colors%5B%5D%3DBlue"

Source

type( obj )

Returns a string representative of `^obj^`'s type.

Method is capable of testing for objects of type: `[Element]`, `[Array]`, `[Object]`, `[Arguments]`, `[Function]`, `[String]`, `[Number]`, `[Infinity]`, `[Boolean]`, `[Date]`, `[RegExp]`, `[NaN]`, `[Null]`, or `[undefined]`.

Returns: String

_.type((function(){return arguments;})())
// => 'arguments'
_.type([])
// => 'array'
_.type(false)
// => 'bool'
_.type(new Date())
// => 'date'
_.type(document.createElement('a'))
// => 'element'
_.type(-Infinity)
// => 'infinity'
_.type(function() {})
// => 'function'
_.type(NaN)
// => 'nan'
_.type(null)
// => 'null'
_.type(99)
// => 'number'
_.type(Math)
// => 'object'
_.type({})
// => 'object'
_.type(/(.)/g)
// => 'regexp'
_.type('blue')
// => 'string'
_.type(undefined)
// => 'undefined'

Source

Strings

fromQueryString( str, deep )

Creates an object from a query string encoded by `toQueryString`.

When `^deep^` is passed with `true`, will attempt to reassemble all arrays encoded by the `toQueryString` method.

Returns: Object

_.fromQueryString('firstname%3DJohn%26middlename%3DEdgar%26lastname%3DHoover')
// => {firstname: 'John', middlename: 'Edgar', lastname: 'Hoover'}
_.fromQueryString('pre-colors%5B%5D%3DRed%26pre-colors%5B%5D%3DBlue', true)
// => {'pre-colors': ['Red', 'Blue']}

Source

htmlEncode( str )

Encodes common HTML characters into their entity representations.

Characters encoded include `"`, `&`, `'`, `/`, `<`, and `>`.

Returns: String

_.htmlEncode('<html></html>')
// => '&lt;html&gt;&lt;&#x2F;html&gt;'

Source

htmlDecode( str )

Decodes common HTML entity representations into their HTML characters.

Entities decoded include `quot`, `amp`, `apos`, `#x2F`, `lt`, and `gt`.

Returns: String

'&lt;html&gt;&lt;/html&gt;'
// => <html></html>

Source

Utility

chain( obj )

Starts a chained method sequence by returning a modified version of the library object.

The `chain` method can be thought of as a wrapper to the Boiler.js library method: `_()`. Arguments passed through `chain` will be passed to the first method called in a chained sequence. All sequences are terminated by calling the `end`.

Returns: Object

_.chain([1, 2, null, [3, "", 4]]).compact().end()
// => [1, 2, 3, 4]

Source

end( )

Returns the computed value from a sequence of chained method calls.

The `end` method is always called at the end of a method chain to return the computed value.

Aliases: result

Returns: ...*

_.chain([1, 2, null, [3, "", 4]]).compact().end();
// => [1, 2, 3, 4]

Source

identity( value )

Returns the value passed through `^value^`.

Mathematically this is represented as `f(v) = v`. This method differs from the `value` method in that arguments that are functions will not be invoked.

Returns: ...*

_.identity(555.3)
// => 555.3
_.identity(function (){ return true; })
// => function (){ return true; }

Source

noConflict( )

Relinquishes control of the library global to its previous owner and returns a reference to the Boiler.js object.

Returns: Object

var boiler = _.noConflict();
// => Previous libraries regain access to their conflicted reference

Source

value( value )

Returns the value passed through `^value^`.

When `^value^` is a function will invoke it and return its return value.

Returns: ...*

_.value(99)
// => 99
_.value(function () { return [1, 2, 3]; })
// => [1, 2, 3]

Source

[ click to expand ]
Top