Wraps any JavaScript iterable (i.e. an object that has a Symbol.iterator property) to
provide a common iterface, regardless of the underlying concrete type. Where possible and
apporpriate this interface matches the built-in Array. Thus,
you can call the same Iterant#map on an Array, a
MarkLogic Seqeunce, or a generator—anything that’s iterable. Type-specific Iterant
extensions override the built-in methods to provide implementations that delegate to their
wrapped concrete types.
Iterant:
An new
Iterant
instance the wraps the passed in iterable
Iterant(
cts.collections() // Any iterable, such as Array, Map, generator function, etc.
)
.filter(c => true) // Not very discriminating
.map(c => { return { name: c, count: cts.frequency(c) }})
.sort((a, b) => b.count - a.count)
.reduce((prev, item) => prev + '\r' + item.count + ': ' + item.name, '');
Whether an object is iterable. Only checks for Symbol.iterator. This
won’t catch the case where a function implicitly returns a duck-typed
iterator. Note that strings are iterable by defintion in the language spec.
(any)
Any object, including
null
or
undefined
(boolean?)
Don’t consider a string iterable. Be careful how you employ this.
boolean:
Whether the object is iterable
Iterant.isIterable([1, 2, 3]); // true
Iterant.isIterable('asdf'); // true, unfortunately
Iterant.isIterable('asdf', true) // false
Iterant.isIterable((function*(){})()) // true
Iterant.isIterable({a: 'A'}) // false
Gets the iterator associated with the underlying concrete iterable.
The type name that shows up in {@Obejct#toString}.
Applys a function to each item of the current iterable and returns a new iterable.
(function)
The function to apply
(any?
= null)
What
this
should mean when calling
fct
(i.e. the first parameter of
Function.prototype.call
)
Iterable:
A new
Iterable
containing the mapped items
Accumulate an aggregate value over all of an Iterable instance’s items.
(any)
The initial value
any:
The accumlated value
Iterant([1, 2, 3])
.reduce((prev, item) => prev + item, 0);
// First iteration: (0, 1) => 1
// Second iteration: (1, 2) => 3
// Third iteration: (3, 3) => 6
// Final result: 6
Get a subsection of an Iterant as an Iterant as
new Iterant. The default implementation naïvely loops from
the start of the Iterant to the end. Subclasses delegate to
more efficient implementations, delegating to the backing {@Iterable}.
(number)
The zero-based index where to start
(number?)
The zero-based index before which to stop. Defaults to the rest of the {@Iterant}, which could be infinite. (Don’t do that.)
Iterant:
A new
Iterant
Evaluates each item using a supplied predicate function. Returns a new
{@Iterant} containing only items for which the predicate returns true.
Warning: filter is almost always better implemented as an upstream query when
you’re working with data from a database.
(any?)
Iterant:
A new
Iterant
with only the matching items
Concatenates items onto the end of an Iterant, returning a new Iterant instance. Iterable instances are flattened. Other types are appended as-is.
(...any)
Items to concatenate
Iterant:
A new
Iterant
instance
Iterant([1, 2, 3])
.concat(4, 5, [6, 7]);
// Iterant([1, 2, 3, 4, 5, 6, 7])
Sorts the items based on a user-supplied comparator function.
Warning: It’s almost always better to sort upstream. The default implementation eagerly instantiates an Array and sorts using Array#sort.
(function?)
A function that compares values pairwise.
The default converts both values to
string
and compares codepoints.
a (any) The current itemb (any) The next itemnumber - -1 if a < b, 1 if a > b, and 0 if they’re equal.IterantArray:
A sorted {@IterantArray}
Converts an Iterant to an Array. This is a pass-through for Array~from that’s convenient for chaining.
function* gen() { for(let i = 0; i < 10; i++) { yield [String(i), i]; }};
Iterant(new Map(gen))
.toArray();
=>
[ [ '0', 0 ],
[ '1', 1 ],
[ '2', 2 ],
[ '3', 3 ],
[ '4', 4 ],
[ '5', 5 ],
[ '6', 6 ],
[ '7', 7 ],
[ '8', 8 ],
[ '9', 9 ] ]
An IterantArray extends Iterant with functionality specific to built-in JavaScript Array instances.
Extends Iterant
IterantArray:
A new
IterantArray
Delegates to Array#slice and returns a new IterantArray.
IterantArray:
IterantArray:
An IterantSequence extends Iterant with functionality specific to MarkLogic Sequence instances.
Extends Iterant
IterantSequence:
A new
IterantSequence
Returns a shallow copy of a portion of the Iterant into a new
IterantSequence object selected from begin to end, not including end.
slice does not modify the original IterantSequence.
The implementation delegates to fn.subsequence() under the covers.
(number?)
Zero-based start index. Only positive integers are supported.
(number?)
Zero-based end index, not inclusive.
IterantSequence:
A shallow copy of the sliced
Sequence
const seq = xdmp.databases(); // Sequence<xs.unsignedLong>
const itr = IterantSequence(seq); // IterantSequence<Sequence<xs.unsignedLong>>
itr
.slice(2, 4) // IterantSequence<xs.unsignedLong>
.map(xdmp.databaseName) // Iterant<Generator<string>>
.toArray() // Array<string>
// ["Meters" , "Triggers"]
Iterable
is a protocol which when implemented allows a JavaScript object to define
their iteration behavior, such as what values are looped over in a for..of
loop or iterall's forEach function. Many built-in types
implement the Iterable protocol, including Array and Map.
While described by the ES2015 version of JavaScript it can be utilized by any version of JavaScript.
Type: Object
(any)
(function (): Iterator<T>)
: A method which produces an Iterator for this Iterable.
Iterator is a protocol which describes a standard way to produce a sequence of values, typically the values of the Iterable represented by this Iterator.
While described by the ES2015 version of JavaScript it can be utilized by any version of JavaScript.
Type: Object
(any)
(function (): {value: T, done: boolean})
: A method which produces either the next value in a sequence or a result
where the
done
property is
true
indicating the end of the Iterator.