A collection of values stored in sorted order using a binary tree.

A SortedSet is a splay tree, using the top-down splaying algorithm from “Self-adjusting Binary Search Trees” by Sleator and Tarjan. Instead of traversing the tree, every algorithm rotates until the node of interest surfaces to the root node. This tends to cause the most frequently used nodes to stay toward the top over time.

SortedSet instances fly the isSorted and isSet flags.

Design notes

This collection was designed based on analysis of two other JavaScript splay tree implementations, but further augmented to incrementally track the length of every subtree.

• a SplayTree impementation buried in Fedor Indutny’s super-secret Callgrind. This implementation uses parent references.
• a SplayTree implementation adapted by Paolo Fragomeni from the V8 project and based on the top-down splaying algorithm from "Self-adjusting Binary Search Trees" by Sleator and Tarjan. This does not use or require parent references, so I favored it over Fedor Indutny’s style.

Properties

length

The number of items in this collection.

Methods

push(...values)

Adds values to the end of a collection.

pop()

Removes a value from the end of a collection, and returns that value.

shift()

Removes a value from the beginning of a collection, and returns that value.

unshift(...values)

Adds values to the beginning of a collection.

union(values)

Returns the set of values including all values from both of these sets.

intersection(values)

Returns the set of values that are in both of these sets.

difference(values)

Returns the set of values that are in this set, excluding the values that are also in the other set.

symmetricDifference(values)

Returns the set of values that are only in one of these sets.

has(value)

Whether an equivalent value exists in this collection.

get(value)

Retrieves the equivalent value from the collection.

delete(value)

Deletes the first equivalent value. Returns whether the key was found and successfully deleted.

remove(value)

An alias for delete(value) on sets that increases the overlap with the W3C DOMTokenList interface, implemented by classList.

contains(value)

An alias for has(value) on sets that increases the overlap with the W3C DOMTokenList interface, implemented by classList.

toggle(value)

Toggles the existence of a value in a set.

addEach(values|map)

Copies values or entries from another collection into this collection, and then returns this.

deleteEach(values|keys, equals?)

Deletes every value or every value for each key. Returns the number of successful deletions.

deleteAll(value, equals?)

Deletes every value equivalent to the given value from the collection.

slice(start?, end?)

Returns an array of the values contained in the half-open interval [start, end), that is, including the start and excluding the end.

splice(start, length, ...values)

Replaces a length of values from a starting position with the given variadic values, and returns the values that were replaced as an array.

swap(start, length, values?)

Replaces a length of values from a starting position with the given values.

clear()

Deletes all of the values in the collection.

indexOf(value)

Returns the position of a value, or -1 if the value is not found.

find(value, equals?, start?)

Finds the first equivalent value.

findValue(value, equals?, start?)

Finds the first equivalent value.

findLeast()

Finds the smallest value, returning the node at which it was found, or undefined.

findLeastGreaterThan(value)

Finds the smallest value greater than the given value, returning the node at which it was found, or undefined.

findLeastGreaterThanOrEqual(value)

Finds the smallest value greater than or equal to the given value, returning the node at which it was found, or undefined.

findGreatest()

Finds the largest value, returning the node at which it was found, or undefined.

findLGreatestLessThan(value)

Finds the largest value less than the given value, returning the node at which it was found, or undefined.

findGreatestLessThanOrEqual(value)

Finds the largest value less than or equal to the given value, returning the node at which it was found, or undefined.

iterate|iterator()

Iterates every value in this collection.

forEach(callback, thisp?)

Calls the callback for each entry in the collection.

map(callback, thisp?)

Returns an array of the respective return values of a callback for each entry in this collection.

filter(callback, thisp?)

Returns an array with each value from this collection that passes the given test.

reduce(callback, basis)

Aggregates every value in this collection with the result collected up to that index.

reduceRight(callback, basis)

Aggregates every value in this collection, from right to left.

group(callback, thisp?, equals?)

Returns an array of [key, class] entries where every value from the collection is placed into the same equivalence class if they return the same key through the given callback.

some(callback, thisp?)

Returns whether any entry in this collection passes a given test.

every(callback, thisp?)

Returns whether every entry in this collection passes a given test.

any()

Returns whether any value in the collection is truthy.

all()

Returns whether all values in the collection are truthy.

one()

Returns one, arbitrary value from this collection, or undefined if there are none.

only()

Returns the only value in this collection, or undefined if there is more than one value, or if there are no values in the collection.

sorted(compare?)

Returns a sorted array of the values in this collection.

reversed()

Returns a copy of this collection with the values in reverse order.

join(delimiter?)

Returns a string of all the values in the collection delimited by the given string.

sum(zero?)

Returns the sum of all values in this collection.

average()

Returns the arithmetic mean of the collection, by computing its sum and the count of values and returning the quotient.

min()

Returns the smallest value in this collection.

max()

Returns the largest value in this collection.

zip(...iterables)

Returns an array of the respective values in this collection and in each collection provided as an argument.

enumerate(start?)

Returns an array of [index, value] entries for each value in this collection, counting all values from the given index.

concat(...iterables)

Returns a new collection of the same type containing all the values of itself and the values of any number of other iterable collections in order.

flatten()

Assuming that this is a collection of collections, returns a new collection that contains all the values of each nested collection in order.

toArray()

Returns an array of each value in this collection.

toObject()

Returns an object with each property name and value corresponding to the entries in this collection.

toJSON()

Used by JSON.stringify to create a JSON representation of the collection.

equals(value, equals?)

Returns whether this collection is equivalent to the given collection.

clone(depth?, memo?)

Creates a deep replica of this collection.

constructClone(values?)

Creates a shallow clone of this collection.

contentCompare(left, right)

The compare function used by this collection to determine how to order its own values.

contentEquals(left, right)

The equals function used to check whether values in this collection are equivalent.

splay(value)

Rotates a splay tree until the value is at the root, or would be between the root and one of its children.

splayIndex(index)

Rotates the tree until the node at a given index floats to the top.

sortedSetLog(...)

Writes a tree describing the internal state of the sorted set splay tree.

addRangeChangeListener(listener, token?, beforeChange?)

Adds a listener for when values are added or removed at any position.

removeRangeChangeListener(listener, token?, beforeChange?)

Unregisters a range change listener provided by addRangeChangeListener.

dispatchRangeChange(plus, minus, index, beforeChange?)

Informs range change listeners that values were removed then added at an index.

addBeforeRangeChangeListener(listener, token?)

Adds a listener for before values are added or removed at any position.

removeBeforeRangeChangeListener(listener, token?)

Unregisters a range change listener provided by addBeforeRangeChangeListener or addRangeChangeListener with the beforeChange flag.

dispatchBeforeRangeChange(plus, minus, index)

Informs range change listeners that values will be removed then added at an index.

addOwnPropertyChangeListener(key, listener, beforeChange?)

Adds a listener for an owned property with the given name.

addBeforeOwnPropertyChangeListener(name, listener)

Adds a listener for before a property changes.

removeOwnPropertyChangeListener(name, listener, beforeChange?)

Unregisters a property change listener provided by addOwnPropertyChangeListener.

removeBeforeOwnPropertyChangeListener(key, listener)

Unregisters a property change listener provided by addBeforeOwnPropertyChangeListener or addOwnPropertyChangeListener with the beforeChange flag.

dispatchOwnPropertyChange(key, value, beforeChange?)

Informs property change listeners that the value for a property name has changed.

dispatchBeforeOwnPropertyChange(key, value)

Informs property change listeners that the value for a property name will change.

makePropertyObservable(name)

May perform internal changes necessary to dispatch property changes for a particular name.

var SortedSet = require("collections/sorted-set");