Adds one or more values to an Array, Set, or other collection.
Requires Node.js 8.3.0 or above.
npm i vadd
The module exports an add()
function that has one other function attached to it as a method: add.all()
.
- Bindable:
collection
(Array, Set, or WeakSet): The collection to which to add a value. valueToAdd
(any): The value to add to the end of the collection.- Optional: Object argument:
arrays
/sets
/weakSets
(arrays of classes/strings): Arrays of classes and/or string names of classes that should be treated as equivalent toArray
/Set
/WeakSet
(respectively).index
(integer): The index at which to splice the new values. Only applies ifcollection
is an Array. To insert values at the end, either omit the argument or set it to-0
(negative zero).loose
(boolean): Whether or not to compare values loosely (as defined bylooselyEquals
) for the purpose of testing uniqueness ifunique
istrue
. Defaults tofalse
.looselyEquals
(function): A callback that accepts two values and returnstrue
if they are to be considered equivalent orfalse
otherwise. This argument is only used ifloose
istrue
. If omitted, the default behavior will, among other things, consider arrays/objects to be equal if they have the same entries.unique
(boolean): Whether or not to refrain from adding values that already exist in the collection. Defaults tofalse
. You can define what uniqueness means by using theloose
andlooselyEquals
arguments.
The number of items added (either 0
or 1
).
const add = require('vadd')
const arr = [1]
add(arr, 2) // [1, 2]
add(arr, 0, {index: 0}) // [0, 1, 2]
Use this function if you want to add multiple values to a collection at once. The signature is the same as the main function except that the second parameter is called valuesToAdd
and takes an iterable (such as an array). The return value is the total number of items added.
const add = require('vadd')
const set = new Set()
add.all(set, [1, 2, 3])
set.has(1) // true
set.has(2) // true
set.has(3) // true
The “k” family of modules works on keyed/indexed collections.
The “v” family of modules works on any collection of values.