🪷 TrueSet Class

🪷 TrueSet Class — A Rich Set

TrueSet is a multiset-like collection where item equivalence is determined by a user-provided representation function (repr). Unlike JavaScript’s native Set, a TrueSet groups items by equivalence classes while keeping them sorted, enumerable, and optionally duplicated.

Internally, it delegates storage to a powerful Classifier, which handles hierarchical keys and custom sorting.

Overview

A TrueSet behaves like a sorted collection:

  • Equivalence is determined by repr(item)
  • Multiple equivalent items may coexist
  • Classes and items are sorted according to the underlying Classifier
  • Supports both collection and queue interfaces
  • Fully iterable (in forward or reverse order)
import { TrueSet } from "@fizzwiz/sorted";

Constructor

new TrueSet(repr, classifier?)

Parameters

  • repr: function(any): any A function returning the equivalence key for an item. Items with the same key belong to the same class.

  • classifier (optional): Classifier The internal classifier instance. Defaults to a fresh Classifier.

Example

const ts = new TrueSet(x => x.length);
ts.add("hi");
ts.add("yo");

Both strings share length 2, so they belong to the same class. Nonetheless they coexist by default.

Properties

.classifier

A public instance of Classifier. Useful for advanced inspection, traversal, or classifier-level operations.

Methods

[Symbol.iterator]()

Iterates over all stored items in sorted order.

for (const item of ts) console.log(item);

n()

Returns the total number of stored items (including duplicates).

has(item)

Checks whether any equivalent item exists.

ts.has("abc");

add(item, xTimes = 1)

Adds the item one or multiple times.

ts.add("hello", 3);

Returns the instance (chainable).

remove(item, xTimes = Infinity)

Removes up to xTimes items equivalent to item. Returns true if any removal occurs.

ts.remove("hello", 1);

get(item)

Iterates all the equivalent items.

clear()

Removes all items.

Queue Interface

peek(first = true)

Returns (without removing) the first or last item.

const smallest = ts.peek();
const largest = ts.peek(false);

poll(first = true)

Returns and removes the first or last item.

const smallest = ts.poll();
const largest = ts.poll(false);

reverse()

Returns an iterator of all items in reverse order.

for (const v of ts.reverse()) console.log(v);

Example Usage

const repr = x => Math.floor(x);
const ts = new TrueSet(repr);

ts.add(3.99);
ts.add(3.14);
ts.add(2.1);

console.log([...ts]);
// -> [2.1, 3.99, 3.14]

When to Use TrueSet

Use TrueSet when you need:

  • Object equivalence beyond native identity
  • Multiset semantics
  • Statistical insights about the frequency of each item, aggregated by representation
  • Runtime aggregation and selection of items in parallel evolving populations

TrueSet shines in classification, statistics, and population evolution.


Comments

Post a Comment

Popular posts from this blog

🧠 Contemplating a True Set

🧠 Equivalence in JavaScript: Contemplating a True Set In JavaScript,   equivalence   behaves differently depending on whether you're working with primitive or non-primitive types. For   primitives —such as numbers, booleans, strings, and symbols—equivalence is determined by comparing actual values. If two variables hold the same value, they are considered equivalent. However, for   objects and arrays , equivalence is   by reference . Two arrays   [0]   and   [0]   are not considered equal because they are separate instances, even though they contain identical content. 🔬 Snippet 1: Equivalence by Value and by Reference new Set ([ 0 , 0 ]); // => Set { 0 } new Set ([[ 0 ], [ 0 ]]); // => Set { [0], [0] } JavaScript’s   Set   treats the two   0   values as equivalent but considers   [0]   and   [0]   as distinct because they are different object instances. This reveals JavaScript’s mini...
Read more

🧱 v0.0.0-dev.1 — First Brick

🧱 v0.0.0-dev.1 — First Brick We’re excited to announce the   first prerelease   of   @fizzwiz/sorted :   v0.0.0-dev.1   — the   First Brick   in what aims to become a foundational library for   priority-aware collections   and   custom equivalence models . This release introduces the core building blocks: 🔧 Core Abstractions Collection   – a base interface for iterable containers Queue   – an extension for prioritizing and structuring exploration 📦 Concrete Implementations ArrayQueue   – a simple queue based on insertion order SortedArray   – a comparator-based queue maintaining sorted state These implementations offer different   notions of equivalence   — by insertion order or by comparator — laying the groundwork for more powerful models based on   representation functions , coming soon. 🧪 This is a   prerelease , but it’s ready to explore. Your early feedback will help guide the evolution o...
Read more

☯️ v0.0.0-dev.3 — Classifier & TrueSet

☯️ v0.0.0-dev.3 — Classifier & TrueSet We’re thrilled to announce   v0.0.0-dev.3   of   @fizzwiz/sorted , introducing two powerful new abstractions:   Classifier   and   TrueSet . This release takes the library far beyond simple sorted collections, enabling   hierarchical keys ,   prefix queries , and   representation-based equivalence . 🔧 Core Enhancements Classifier   — a rich, multidimensional map A   Classifier   stores entries whose keys are   arrays (any iterable) . It supports: Storing multiple items per key Efficient   prefix queries   with wildcards Sorted traversal of both keys and items Flexible equivalence via custom sorting rules TrueSet   — a representation-based set A   TrueSet   defines equivalence using a   representation function   ( repr ). It enables: Equivalence among   objects , not just primitives Aggregation of equivalent items in sorted, enumerable class...
Read more