Utility methods

Part of: tag_Utilities

Each Sqimitive instance inherits a bunch of functions from your utility library in addition to standard ones (tag_Utilities) – those used to sort, filter, transform, count, locate, cook, boil, slice up and serve nest’ed children as regular objects and arrays. For example:

sqim.filter(child => child.get('enabled'))
// Instead of:
_.filter(sqim.slice(), child => child.get('enabled'))

These functions are generally portable but with subtle differences in availability and behaviour between NoDash no@, Underscore un: and LoDash – check the no:COMPATIBILITY table for details.

If doing several transformations one after another consider _() which allows chaining.

from unordered

Attention: JavaScript objects are unordered, as explained in the description of Ordered.

• each(), filter(), etc. can iterate in any order
• find(), first(), etc. can return an arbitrary child
• indexOf(), etc. may change result on each call
• reduceRight() may not fold from the end

For this reason some methods are only available when mixing-in Sqimitive\Ordered which guarantees iteration order.

The iterator argument may be followed by call context (cx) which defaults to the sqimitive if omitted.

Methods working with children keys (nested())

iterator = function (Sqimitive child, string parentKey)

Methods available for Sqimitive\Base subclasses:

• no:keys() – returns an array of all children keys (of _parentKey-s if _owning)
• no:omit(keys | key[, key, ...] | iterator[, cx]) – the opposite of pick(), children with mismatching keys
• no:pick(keys | key[, key, ...] | iterator[, cx]) – returns object of children with matching keys:

  sqim.pick(['k1', 'k2'])   //=> {k1: child1, k2: child2}
  sqim.pick('k1', 'k2')
  sqim.pick(child => child.get('enabled'))

  The iterator form is similar to filter() but returns {key: child, ...}, not [child, ...].

  Warning: keys are always strings (see Base.nestEx()). sqim.pick(1) always returns [] – use sqim.pick('1').

Methods working on children positions (slice())

iterator = function (Sqimitive child, int index)

from unordered

Attention: JavaScript objects are unordered, as explained in the description of Ordered.

If Sqimitive\Ordered is not used, index is an arbitrary number sequential in this particular call to the utility method; sqim.filter((c, i) => sqim.slice(i, 1)) may produce undefined behaviour. For Ordered, index is stable and can be given to at() or slice().

Attention: forEach() and other methods here work with child indexes, not keys! Obtain keys by _parentKey if the collection is _owning, or by findKey(), or do _.each(col.nested(), (sqim, key) => ...). For Ordered, can also use at(index).key.

Methods available for Sqimitive\Base subclasses:

• no:chunk(length) – returns an array of arrays of length members each (except last): [child1, child2], [child3, child4], [child5]
• no:includes(sqim) – returns true if there’s a nested sqim instance (similar to nested())
• no:countBy(iterator[, cx]) – same as groupBy() but values are group lengths: {group1: 3, group2: 1, ...}
• no:difference(array[, array, ...]) – same as without() but accepts one or more arrays
• no:forEach(iterator[, cx]) – calls iterator on every child; returns nothing; alias: each()
• no:every(predicate[, cx]) – returns true if for every child predicate returned a truthy value
• no:filter(predicate[, cx]) – returns array of children for which predicate returned a truthy value; see pick() which returns an object
• no:find(predicate[, cx]) – returns the first child for which predicate returned a truthy value or undefined
• no:groupBy(iterator[, cx]) – returns an object with arrays of children for which iterator returned the same string (the object’s keys are those strings): {group1: [child1, child3], group2: [...]}
• no:indexBy(iterator[, cx]) – same as groupBy() but expects strings to be unique; returns {group1: child1, group2: child2, ...}; warning: missing from LoDash
• no:intersection(array[, array, ...]) – returns an array of children listed in any of the given arrays
• no:invoke(method[, arg1, arg2, ...]) – calls method of each child, giving it the passed arguments; returns an array with results of every call; see map() which calls an iterator instead; warning: LoDash’s works differently, do not use
• no:map(iterator[, cx]) – returns an array with results of calling iterator for every child; similar to invoke() but doesn’t call children’s methods
• no:max(iterator[, cx]) – ranks all children by calling iterator and returns the “highest” one
• no:min(iterator[, cx]) – same as max() but returns the “lowest” child
• no:partition(predicate) – returns an array of two arrays: first with children matching predicate, second – not matching
• no:pluck(prop) – returns array of values of the prop property of every child; warning: missing from LoDash

  pluck() is hardly useful in Sqimitive since public properties are usually within Base._opt and picking protected “_properties” has limited utility. Use map() in combination with picker() or invoke() with get():

  col.map(Sqimitive.Core.picker('get', 'opt'))   // map() + picker()
  col.invoke('get', 'opt')                       // invoke() + get()

• no:reduce(iterator, memo[, cx]) – calls iterator(memo, sqim, parentKey) for every child (returns new memo) and returns the final value of memo
• no:reject(predicate[, cx]) – the opposite of filter(), returns array of children mismatching predicate
• no:sample([n]) – returns one random child (if no arguments) or n random children (or less if have fewer); alias of shuffle()
• no:shuffle() – returns array of children in random order
• no:some(predicate[, cx]) – returns true if predicate returned a truthy value for any child
• no:sortBy(iterator[, cx]) – returns array of children sorted by their rank determined by iterator (ascending)
• no:toArray() – simply returns array of all children; same as slice() and no:values() (not exposed as a method)
• no:union(array[, array, ...]) – returns array of children plus members of all given arrays
• no:without(sqim[, sqim, ...]) – returns array of children omitting those given as arguments; same as difference() but takes objects

Methods available if mixed-in Sqimitive\Ordered:

• no:findIndex(predicate[, cx]) – returns index of the first child for which predicate returns a truthy value or -1; similar to indexOf() but takes a callback
• un:findLastIndex(predicate[, cx]) – same as findIndex() but returns index of the last child; only useful for non-_owning (see lastIndexOf()); warning: missing from NoDash
• no:first() – returns first nested child or undefined
• no:indexOf(sqim) – returns the ordinal number of sqim or -1 if it’s not nested
• no:initial([n]) – returns all but last n children (1 if no arguments)
• no:last() – returns last nested child or undefined
• no:lastIndexOf(sqim) – same as indexOf() but counts from the end; only useful for non-_owning that may have duplicate children, else lastIndexOf() is the same as indexOf()
• no:reduceRight(iterator, memo[, cx]) – same as reduce() but goes from the end
• no:rest([n]) – returns all but first n children (1 if no arguments)