This folder contains documentation for each part of the Dartora package.
All known pages in the folder have been generated by ChatGPT.
Dartora is a utility package that was built for Dart. It provides:
Add dartora to your project:
dart pub add dartora
Then import what you need:
import 'package:dartora/dartora.dart';
// or narrowly:
import 'package:dartora/collections.dart';
import 'package:dartora/search.dart';
import 'package:dartora/math.dart';
import 'package:dartora/util.dart';
Licensed under the Apache License, Version 2.0.
Below is an outline of all modules and their APIs. Click a category to jump to its section or click an item to open its page. Items are grouped by module for easy navigation.
The collections module defines flexible iteration primitives and data structures for working with large or view‑based sequences. Key classes include:
| Item | Description |
|---|---|
| LargeIterable | Presents values from a keyed map and optional extras as a lazy sequence with random access. Supports windowing via startIndex/indexTake and transformation methods. |
| LargeList | A random‑access view over the union of a map’s values and an extra IterationHolder sequence. Provides iteration, element lookup, filtering and mapping without copying data. |
| IterableItems | Convenience subclass of LargeIterable for maps where the value type is already the desired type. Iterates values in the order of a key list without applying a modifier. |
| MultiViewList | Wraps a list so that multiple views can be created cheaply. Supports read/write access, iteration, and common list operations. |
| OrderedMap | A map that preserves insertion order. Keys are stored in a MultiViewList and values in a normal map. Provides predictable iteration order and standard map methods. |
| Iteration | An abstract mixin defining the contract for efficient, sliceable iteration. Subclasses implement sourceIterator, sourceLength and sourceGet to support windowed views. |
| IterationBase | A mutable list interface built upon Iteration. Provides list operations (insert, remove, shuffle, sort, etc.) and view operations (map, followedBy, expand, skip, take). Subclasses supply storage hooks. |
| IterationHolder | Concatenates multiple IterationBase sequences into a single list. Handles removal, replacement and insertion across segment boundaries while keeping track of offsets. |
| IterationItem | A read‑only Iteration wrapping any Iterable using elementAt() for retrieval. Useful for converting arbitrary iterables into the Iteration framework. |
| IterationList | A concrete list implementation backed by a mutable Dart list. Implements the hooks required by IterationBase. |
| IteratorBuild | Builds a standard Dart iterator from an elementAt callback with start/end indices. |
| IndexBaseIterator | Wraps any Iterable to provide an index‑based iterator using elementAt. |
| HolderIterator | Flattens a list of iterables (such as a matrix) into a single iterator. Used by Matrix and IterationHolder. |
| ImmutableIterationHolder | Presents several Iteration sequences as one read‑only concatenation. Caches the total length and forwards element access across its children. |
| IterationMap & IterationItemMap | Ordered map view classes combining Map semantics with Iteration windowing. IterationMap defines the abstract behaviour; IterationItemMap provides a concrete implementation backed by a Map and a list of keys. |
The search module implements a mini search engine with parsing, tagging and scoring. Important classes include:
| Item | Description |
|---|---|
| Searchable | Base class for objects that can be searched. Stores id, name, title, description, tags and the type (parent or child). Provides a children holder and a factory for building a default implementation. |
| ChildHolder | Holds children for a Searchable. Manages keyed storage, typed key lists, and events for adding/removing items. Provides iteration and common collection methods. |
| Search | Executes a SearchQuery against a list of Searchable items. Computes scores using SearchQueryComparison and orders results by descending score. |
| SearchQuery | Compiled representation of a user query with optional, required and forbidden words and tags. Provides scoring and validity checks. |
| QueryEngine | Parses strings into SearchQuery objects using a set of PatternItems that recognise quotes, negation, tags and wildcards. |
| QueryBuilder | A state machine used by the engine to accumulate words and tags into buckets. |
| PatternItem | Defines the behaviour of a single token in the query syntax. Controls whether the token splits, escapes, defines tags or sets required/forbidden words. |
| SearchItem | Holds a matched Searchable and its SearchQueryComparison. |
| PointedWord | Pair of a word and the points associated with matching it. Points are positive for desired words and negative for forbidden words. |
| SearchQueryComparison | Result of comparing a query against a text. Holds positive/negative points, occurrence counts and flags for missing required or containing forbidden words. |
| Tag & Tags | A named value used for tag search; Tags is a map of tag names to Tag values. |
| SearchableType | Enum for parent/child Searchable roles. |
| ChildActionType | Enum describing events fired by ChildHolder. |
| QueryType | Enum indicating whether a query word is optional, required, forbidden, or a combination. |
Math basics provide helper functions and constants for numeric operations and rounding:
| Item | Description |
|---|---|
| comparison | Defines numberCast<T>() to coerce numbers from dynamic values and wrappers around min and max for numeric types. |
| log | Implements exp, natural and base‑10 logarithms (ln, log, log2, logB) using ratio and natural logs. |
| root | Provides pow, sqrt and nthRoot functions with edge‑case handling. |
| rounding | Contains the RoundMode class for configurable rounding policies and a round() function that rounds doubles to a fixed number of decimals using a given mode. |
| constants | Defines mathematical constants e, pi, and phi as doubles. |
Advanced math includes structures and algorithms beyond basic arithmetic:
| Item | Description |
|---|---|
| BaseRadix | Represents a number in an arbitrary radix with its code (string) and numeric value. Provides conversion to/from different bases and arithmetic operations that return new BaseRadix instances. |
| Curves | Functions for growth and smoothing. stepwiseGrowth() returns an integer step with adjustable speed/length/factor parameters; sigmoidCurve() maps input through a logistic‑like curve with configurable center and baseline. |
| Matrix | A 2‑D numeric array with matrix operations: addition, subtraction, scalar and matrix multiplication, power, division, determinant, adjoint, cofactor, inverse, transpose, identity and (experimental) row echelon form. Implements Iteration to traverse elements in row‑major order. |
| Points | Classes for representing positive/negative point tallies and their stepwise modifiers. Points is an abstract base with arithmetic; UnmodifiablePoints and ModifiablePoints provide concrete implementations for immutable and mutable points. |
Utility classes provide error handling and modification tracking:
| Item | Description |
|---|---|
| ModificationListener | Tracks nested modification scopes and counts the number of modification steps. Supports start/step/end/reset operations and reports the level of modification. |
| ModificationAction & _ModCatch | Records a modification at a specific level; internal helper used by the listener. |
| ModLevel & ModResetType | Enums for modification severity and reset types. |
| BaseException, TypeException, KeyException | Structured error classes with descriptive messages for generic errors, type mismatches and invalid keys. |