stl 0.5.4

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 20 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.

---

🧬 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]

---

💻 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.