stl 0.6.1

Supercharge Dart & Flutter with C++ STL architecture. Unlock zero-cost primitives, associative collections, memory views, and C++23 ranges.

STL (Standard Template Library... and Beyond!)

🚀 A highly-versatile, performance-driven bank of data collections, structures, and algorithmic ranges for the Dart and Flutter ecosystem.

---

🛠️ Quick Install

dart pub add stl

or for Flutter:

flutter pub add stl

💙 Support the Project

If you find stl heavily supercharging your Dart architecture, please consider leaving a Like 👍 on pub.dev and a Star ⭐ on GitHub. It massively fuels the continuous development of this library!

🌈 The Vision

Originally inspired by the strict blueprints of the C++ Standard Template Library (STL), this package has heavily evolved into a comprehensive bank of diverse collections for all your data structure needs. Whether you require familiar sequential containers, complex associative maps, specialized utility adapters, or bleeding-edge C++23 functional ranges, stl drastically supercharges your Dart architecture! ✨

🎯 Why use this package over standard Dart tools?

• 📦 Massive Bank of Collections: Unlock custom abilities via Vector, Deque, Stack, ForwardList, and more!
• 🌀 Next-Gen Iteration: Introducing Ranges! Seamlessly generate subsets, zips, Cartesian products, and infinite loops on the fly without breaking your memory limit.
• ⚡ Deterministic Performance: Predictable time complexity ($O(1)$, $O(\log n)$, etc.) with heavily optimized system-level logic.
• 🛠 Familiar yet Dart-y API: Native Iterable mixins seamlessly integrated with perfectly replicated C++ architectural rules, wrapped cleanly in standard Dart camelCase for maximum ecosystem interoperability.
• 🎨 Ready for Everything: Perfect for logic-heavy Flutter apps, scalable game engines, dynamic state management, or enterprise backend systems.

---

📚 The Standard Library Bank

Instead of strictly separating containers, mathematics, and utilities, here is a taste of the massively diverse types available natively in stl. The library is heavily integrated, so these types interact with each other seamlessly!

Type	Category	Description
🚂 Vector<T>		Dynamic array with contiguous memory behavior, strict bounds checking, and powerful modifiers.
📍 Point		Represents an exact 2D coordinate (x, y) in Euclidean space utilizing precise vector math.
👯 Pair<T1, T2>		Native C++ utility structure to hold heterogeneous objects. Features gorgeous Dart 3 Record translation.
🔢 I8 -> I64		Zero-cost signed integer wrappers. Provides automatic arithmetic wrap-around and strict bounds.
🧮 cmath		Missing mathematically safe operations including clamp(), lerp(), and overflow-safe robust hypot() updated with over 100 new functions as part of the project target-200.
🗺️ HashMap<K, V>		Unordered key-value map utilizing a fast hash table under the hood, matching std::unordered_map.
⭕ Circle		Computes absolute Pi area boundaries natively supporting affine transformations via CRTP.
🔍 <algorithm>		Brings lowerBound(), rotate(), nextPermutation() and more to dynamically mutate any Iterable.
🌭 Deque<T>		Double-ended queue allowing extremely fast front/back algorithmic insertions without reallocation.
✨ Optional<T>		A beautifully sealed functional wrapper representing possibly-absent values without raw null checks.
🔢 U8 -> U64		Zero-cost unsigned integer variants mathematically bounding state within non-negative bit frames.
🔲 Rectangle		Basic bounding box dimensions implicitly supporting translations, scaling, and centroid physics.
🧲 Complex		Full-scale complex numbers implementation with operator overloading and utility algorithms.
🌲 SortedSet<T>		Tree-based strictly sorted unique container mirroring C++ std::set. Keeps data autonomously ordered.
🔀 Variant<T0...>		Type-safe discriminated union handling distinct architectural alternatives elegantly via switches.
🔺 Triangle		Evaluates Herons theorem natively from coordinates, dynamically supporting spatial rotation.
🥞 Stack<T>		Custom LIFO (Last-In, First-Out) adapter. Operates flawlessly over any given sequence.
🔢 Int8 -> Int64		Hardware-backed signed equivalents dynamically enforcing strict boundaries natively via OS/V8 buffers.
📜 StringView		Zero-allocation string reference utility enabling high-performance substring manipulations.
📂 MultiMap<K, V>		Sorted tree container mapping keys to multiple values natively matching std::multimap.
📐 Polygon		Exact polygon structure generating precise surface areas dynamically utilizing the Shoelace formula.
🔬 number_theory		Highly-optimized logic for gcd(), lcm(), isPrime(), primeFactorization(), and midpoint().
🔗 SList<T>		Doubly linked list enabling $O(1)$ bidirectional manipulations mirroring C++ std::list.
👽 Any		Generic type-safe bounding box safely encapsulating abstract data with strictly enforced extraction.
☄️ Ellipse		Advanced shape beautifully approximating mathematical perimeters implicitly employing Ramanujan's formula.
🛡️ Expected<T,E>		Functional wrapper representing either a value or an error. Mimics C++23 <expected> exception-free design.
🗃️ Tuple		Flexible C++ std::tuple adapter smoothly bridging heterogeneous collections and Dart 3 records natively.
⚡ <functional>		Standard function objects (Plus, Less, LogicalAnd, etc.) and invoke utility for algorithmic pipelines.
⚠️ <stdexcept>		Standard C++ exception hierarchy (LogicError, RuntimeError, InvalidArgument, etc.) natively in Dart.
🎲 <random>		Predictable C++ style random number generation utilities featuring StdRandom, custom seeding, and bounded ranges.
⏱️ <chrono>		Highly portable C++ style SystemClock and SteadyClock for time tracking across Native and Web targets.
🧮 <ratio>		Compile-time friendly exact rational fractions (Ratio) and standard SI prefix multipliers (milli, micro).
🔄 <iterator>		Adapter hooks bridging iterables (ReverseIterator, BackInsertIterator) for fluent mutations.
🔢 IotaRange		Lazy integer sequence [start, end) — infinite when end is omitted. Mirrors std::views::iota.
1️⃣ SingleRange<T>		Wraps exactly one value as a one-element range. Mirrors std::views::single.
✂️ SplitRange<T>		Splits an iterable on a delimiter, yielding List<T> segments. Mirrors std::views::split.
🗂️ ChunkByRange<T>		Groups consecutive elements into chunks while a binary predicate holds. Mirrors std::views::chunk_by.
🔑 KeysRange<K,V>		Extracts keys from Pair<K,V> iterables. Composes with HashMap, SortedMap, MultiMap. Mirrors std::views::keys.
💎 ValuesRange<K,V>		Extracts values from Pair<K,V> iterables. Dual complement of KeysRange. Mirrors std::views::values.

---

---

📐 Geometry Module — Computational Geometry & Linear Algebra

The flagship non-C++ feature of stl. Going far beyond anything in the C++ standard, the geometry module is a complete computational geometry and linear algebra engine — inspired by CGAL, GLM, and game engine math libraries.

🗺️ 2D Shapes & Primitives

Class	Description
Point<T>	2D vector with +, -, *, /, dot, cross, normalize(), lerp(), angleTo(), midpointTo()
Circle	Area, perimeter, containsPoint(), intersectsCircle(), tangentLength(), affine transforms
Rectangle	Area, containsPoint(), intersects(), corners (4 vertices), affine transforms
Triangle	Heron's formula, circumcenter, incenter, circumradius, inradius, isAcute/Right/Obtuse/Equilateral/Isoceles
Polygon	Shoelace area, isConvex, containsPoint() (ray casting), area-weighted centroid
Ellipse	Ramanujan perimeter, area, affine transforms
LineSegment	Length, midpoint, intersection tests
Ray2D	origin, direction, at(t), intersectSegment(), intersectCircle()
Capsule	Stadium shape via spine + radius, area, perimeter, containsPoint()
Arc	Circular arc: arcLength, chordLength, containsAngle()
QuadraticBezier	Degree-2 Bézier: evaluate(t), derivative(t), arcLength(), splitAt(t)
CubicBezier	Degree-3 Bézier: evaluate(t), derivative(t), arcLength(), splitAt(t)

🌐 3D Primitives

Class	Description
Point3D	3D vector with +, -, *, /, dot(), cross(), normalize(), lerp(), distanceTo()
Sphere3D	Volume ($\frac{4}{3}\pi r^3$), surface area ($4\pi r^2$), containsPoint(), intersectsSphere()
Plane3D	Normal + distance form, distanceTo(), reflect(), project(), containsPoint()
Ray3D	at(t), intersectSphere(), intersectPlane()
Triangle3D	normal, area, centroid, containsPoint() (barycentric), toTriangle()

🔢 Linear Algebra

Class	Description
Matrix2x2	Determinant, inverse, transpose, rotation(angle), full arithmetic
Matrix3x3	Determinant, inverse (cofactor), rotationX/Y/Z(angle), full arithmetic
Matrix4x4	Homogeneous transforms: translation(), scale(), perspective(), transform(Point3D)
Quaternion	Unit quaternion: slerp(), fromAxisAngle(), toMatrix3x3(), toEulerAngles(), conjugate, inverse

⚙️ Computational Geometry Algorithms

Function	Algorithm	Complexity
convexHull(points)	Graham scan	$O(n \log n)$
closestPairOfPoints(points)	Divide & conquer	$O(n \log n)$
segmentIntersection(a, b)	Parametric test	$O(1)$
pointInPolygon(p, poly)	Ray casting	$O(n)$
triangulate(polygon)	Ear clipping	$O(n^2)$

🎓 Example — 3D Pipeline: Quaternion Rotation + Matrix Transform + Ray–Sphere Intersection

import 'package:stl/stl.dart';
import 'dart:math' as math;

void main() {
  // ── 2D Bézier Curve ─────────────────────────────────────────────────────────
  final bezier = CubicBezier(
    p0: Point(x: 0.0, y: 0.0),
    p1: Point(x: 1.0, y: 2.0),
    p2: Point(x: 3.0, y: 3.0),
    p3: Point(x: 4.0, y: 0.0),
  );
  final mid = bezier.evaluate(0.5);
  print('Bézier midpoint: $mid');              // Point(2.0, 1.875)
  print('Arc length ≈ ${bezier.arcLength(100).toStringAsFixed(3)}');

  // ── 2D Convex Hull ───────────────────────────────────────────────────────────
  final cloud = [
    Point(x: 0.0, y: 0.0), Point(x: 1.0, y: 1.0),
    Point(x: 2.0, y: 0.5), Point(x: 0.5, y: 2.0),
    Point(x: 1.5, y: 1.5), Point(x: -1.0, y: 0.5),
  ];
  final hull = convexHull(cloud);
  print('Convex hull: ${hull.length} vertices');

  // ── 3D Quaternion Rotation ───────────────────────────────────────────────────
  //  Rotate point P = (1, 0, 0) by 90° around the Y-axis.
  //  Expected result: (0, 0, -1)
  final q = Quaternion.fromAxisAngle(
    axis: Point3D(x: 0, y: 1, z: 0),
    angle: math.pi / 2,
  );
  final p = Point3D(x: 1, y: 0, z: 0);
  final rotated = q.rotate(p);
  print('Rotated: $rotated');                  // Point3D(≈0, 0, ≈-1)

  // ── Matrix4x4 Transform Pipeline ────────────────────────────────────────────
  //  Build a model matrix: translate(2,3,0) * rotateZ(45°) * scale(2)
  final model = Matrix4x4.translation(tx: 2, ty: 3, tz: 0)
      .multiply(Matrix4x4.rotationZ(math.pi / 4))
      .multiply(Matrix4x4.scale(sx: 2, sy: 2, sz: 2));
  final vertex = model.transform(Point3D(x: 1, y: 0, z: 0));
  print('Transformed vertex: $vertex');

  // ── Ray–Sphere Intersection ──────────────────────────────────────────────────
  final ray = Ray3D(
    origin: Point3D(x: -5, y: 0, z: 0),
    direction: Point3D(x: 1, y: 0, z: 0),
  );
  final sphere = Sphere3D(center: Point3D(x: 0, y: 0, z: 0), radius: 1.0);
  final hit = ray.intersectSphere(sphere);
  print('Ray hits sphere at t=${hit?.toStringAsFixed(3)}'); // t=4.000

  // ── Triangle Circumcenter ────────────────────────────────────────────────────
  final tri = Triangle(
    p1: Point(x: 0.0, y: 0.0),
    p2: Point(x: 4.0, y: 0.0),
    p3: Point(x: 0.0, y: 3.0),
  );
  print('Circumcenter: ${tri.circumcenter}');  // Point(2.0, 1.5)
  print('Inradius: ${tri.inradius.toStringAsFixed(3)}');

  // ── Polygon Convexity & Point-in-Polygon ─────────────────────────────────────
  final square = Polygon([
    Point(x: 0.0, y: 0.0), Point(x: 4.0, y: 0.0),
    Point(x: 4.0, y: 4.0), Point(x: 0.0, y: 4.0),
  ]);
  print('Is convex: ${square.isConvex}');       // true
  print('Contains (2,2): ${square.containsPoint(Point(x: 2.0, y: 2.0))}'); // true
}

---

🧬 Ranges Module (Inspired by C++23)

Welcome to functional magic! Inspired deeply by C++23 std::views, our Ranges module allows you to cleanly manipulate, combine, generate, and stream data iteratively without aggressively eager memory consumption. Operations are performed lazily, bringing algorithmic elegance to your pipeline.

🔥 Spotlight Ranges

📐 NumberLine (Iota)

Mimicking std::views::iota. Generate precise linear layouts of floating-point boundaries, or standard integer jumps, in mathematically optimized $O(1)$ operations instead of building massive explicit arrays.

// Custom Step Increment of 4 (0 to 20):
final evens = NumberLine(0, 20, step: 4);
print(evens.toList()); // [0, 4, 8, 12, 16]

// Highly mathematically optimized checks:
print(evens.contains(12)); // True! (Does NOT iterate over memory)

🔗 ZipRange (Parallel Iteration)

Mimics std::views::zip. Dynamically clamp two different structured iterables together until the shortest one expires. Phenomenal for generating maps!

final keys = ['Player1', 'Player2', 'Player3'];
final scores = [9500, 8400]; // Uneven length!

final zipped = ZipRange(keys, scores);
final scoreMap = Map.fromEntries(zipped.map((p) => p.toMapEntry()));
// Results: {'Player1': 9500, 'Player2': 8400}

🔲 ChunkRange (Data Fragmentation)

Mimics std::views::chunk. Need to batch network packets or paginate rendering blocks? ChunkRange divides collections precisely into requested sizing constraints.

final data = [1, 2, 3, 4, 5, 6, 7];
final pagination = ChunkRange(data, 3);
print(pagination.toList()); 
// Results: [[1, 2, 3], [4, 5, 6], [7]]

🧩 CartesianRange (Combinations)

Mimics std::views::cartesian_product. Produces flat combinatorial intersections elegantly.

final suits = ['Hearts', 'Spades'];
final ranks = ['King', 'Queen'];

final deck = CartesianRange(suits, ranks);
// Yields Pairs: (Hearts, King), (Hearts, Queen), (Spades, King), (Spades, Queen)

♾️ RepeatRange (Infinite Streams)

Mimics std::views::repeat. Repeat specific data continuously or infinitely. Perfect for mock data pipelines!

final zeroes = RepeatRange(0);
print(zeroes.take(5).toList()); // [0, 0, 0, 0, 0]

✂️ TakeRange & DropRange (Slicing)

Mimics std::views::take and std::views::drop. Extract or ignore sections of an iterable pipeline iteratively without explicitly allocating memory-heavy sublists.

final data = NumberLine(1, 10).toList();
final middle = TakeRange(DropRange(data, 3), 4);
print(middle.toList()); // [4, 5, 6, 7]

🧪 FilterRange & TransformRange (Functional Hooks)

Mimics std::views::filter and std::views::transform. Eagerly processes data dynamically through custom conditional predicates and data type mutating hooks.

final data = [1, 2, 3, 4, 5];
// Keep evens, then multiply by 10
final tens = TransformRange<int, int>(FilterRange(data, (int n) => n % 2 == 0), (int n) => n * 10);
print(tens.toList()); // [20, 40]

🌊 JoinRange (Stream Flattening)

Mimics std::views::join. Instantly reassembles an iterable of iterables back into a perfectly contiguous 1-dimensional functional flow without recursive allocations.

final arrays = [[1, 2], [], [3, 4, 5], [6]];
final stream = JoinRange(arrays);
print(stream.toList()); // [1, 2, 3, 4, 5, 6]

🔢 IotaRange (Lazy Integer Sequences)

Mimics std::views::iota. Generates a lazy bounded or infinite integer sequence without allocating any backing array. Essential for index generation and arithmetic progressions.

// Bounded sequence [0, 5)
print(IotaRange(0, 5).toList()); // [0, 1, 2, 3, 4]

// Infinite sequence — safe via take()
print(IotaRange(10).take(4).toList()); // [10, 11, 12, 13]

1️⃣ SingleRange (One-Element Views)

Mimics std::views::single. Wraps a single value as a range, making it composable with every other range adapter without allocating a list.

final seed = SingleRange(42);
print(seed.toList()); // [42]

// Compose with JoinRange to prepend a value
final result = JoinRange([SingleRange(0), IotaRange(1, 4)]);
print(result.toList()); // [0, 1, 2, 3]

✂️ SplitRange (Delimiter Splitting)

Mimics std::views::split. Splits any iterable on a delimiter element, yielding each segment as a List<T>. Works on integers, strings, or any comparable element type.

final csv = [1, 0, 2, 3, 0, 4];
final segments = SplitRange(csv, 0);
print(segments.toList()); // [[1], [2, 3], [4]]

// String characters
final words = SplitRange('hello world'.split(''), ' ');
// [['h','e','l','l','o'], ['w','o','r','l','d']]

🗂️ ChunkByRange (Predicate Grouping)

Mimics std::views::chunk_by. Groups consecutive elements into List<T> chunks while a binary predicate pred(prev, curr) returns true, starting a new chunk the moment it fails.

final data = [1, 1, 2, 2, 2, 3, 1, 1];
// Group runs of equal values
final groups = ChunkByRange(data, (a, b) => a == b);
print(groups.toList()); // [[1, 1], [2, 2, 2], [3], [1, 1]]

// Group ascending runs
final runs = ChunkByRange([1, 2, 3, 1, 2], (a, b) => b >= a);
print(runs.toList()); // [[1, 2, 3], [1, 2]]

🔑 KeysRange & ValuesRange (Map Projection)

Mimics std::views::keys and std::views::values. Project the keys or values out of any Pair<K, V> iterable, composing seamlessly with HashMap, SortedMap, and MultiMap.

final map = SortedMap<String, int>((a, b) => a.compareTo(b));
map['alpha'] = 1;
map['beta'] = 2;
map['gamma'] = 3;

// Extract only keys
print(KeysRange(map).toList()); // [alpha, beta, gamma]

// Extract only values
print(ValuesRange(map).toList()); // [1, 2, 3]

---

💻 Spotlight Integrations

By blending C++ architectures with Dart's IterableMixin, stl gives you incredible syntactical power:

🚂 Vector Memory Architecture

final vec = Vector<String>(['Apple', 'Banana']);
vec.pushBack('Cherry');
vec.popBack();
print(vec.front()); // "Apple"

👯 The Powerful Pair & Dart 3 Records

// Effortless Pair initialization
var duo = makePair(99, 'Balloons');

// Native Dart 3 tuple/record unwrapping
var (count, item) = duo.record;

// Native deep equality
var sibling = makePair(99, 'Balloons');
print(duo == sibling); // True!

🥞 Iterable Adapters (Stack)

final stack = Stack<int>.from([1, 2, 3]); // Top element is 3
var removed = stack.pop(); // Removes and returns 3

// Instantly iterable safely from top-to-bottom! 
for (var item in stack) {
  print(item); // 2, then 1
}

🌲 Autonomous Self-Balancing Sets (SortedSet)

final sorted = SortedSet<String>((a, b) => b.length.compareTo(a.length));
sorted.insert("Strawberry");
sorted.insert("Apple"); 
sorted.insert("A");

print(sorted.toList()); 
// ["Strawberry", "Apple", "A"] (Sorting strictly maintained on insert!)

---

💖 Contributing

Want to see an exotic data structure, an algorithmic graph traversal, or a missing std::ranges feature added to the library? We emphatically welcome pull requests, bug reports, and issue tickets. Let's make this the most powerful and scalable system-level algorithms repository in the Flutter and Dart ecosystem! 🌟

Engineered with passion for Dart & Flutter architectures.