stl 0.3.2

A high-performance C++ STL inspired library for Dart & Flutter. Unlock advanced data structures, functional wrappers, and C++23 ranges.

example/stl_example.dart

import 'package:stl/stl.dart';

void main() {
  print('====================================================');
  print('    💎 STL MEGA SHOWCASE & ARCHITECTURE ALBUM');
  print('====================================================\n');

  // ========================================
  // 1. DYNAMIC ARRAYS & MEMORY
  // ========================================
  print('>>> 1. CORE ARRAYS & SINGLY-LINKED LISTS <<<\n');
  
  final vec = Vector<String>(['Alpha', 'Bravo', 'Charlie', 'Delta']);
  print('• Vector initialized: ~vec evaluates to ${~vec}');
  
  // Appending and checking limits
  vec.pushBack('Echo');
  print('• Memory bounds strictly managed. Vector size is ${vec.size()}');
  
  // Vector advanced operations (assigning blocks of memory)
  final secondaryVec = Vector<String>([]);
  secondaryVec.assign(3, 'EmptySlot');
  print('• Vectors support raw memory block assigns: $secondaryVec');

  // ForwardList excels at fast shifting and removal algorithms 
  print('\n[Converting Vector into a ForwardList]');
  final list = ForwardList<String>.from(vec);
  
  // ForwardList allows ultra-fast manipulations without resizing arrays
  list.insertAfter(1, 'Bravo-Two');
  list.removeIf((val) => val.startsWith('C')); // Removes "Charlie" immediately
  list.pushFront('Zulu'); 
  print('• ForwardList after O(1) shifts: $list');
  
  // ForwardList can inherently detect and crush contiguous duplicates
  list.pushFront('Zulu');
  list.pushFront('Zulu');
  list.unique();
  print('• List crushed duplicates instantly: $list\n');

  
  // ========================================
  // 2. ADAPTERS (Deque, Queue, Stack)
  // ========================================
  print('>>> 2. CONTAINER ADAPTERS (LIFO/FIFO) <<<\n');

  // Deque serves as the legendary backbone for stacks and queues
  final deque = Deque<int>.from([10, 20, 30, 40]);
  print('• Deque Backbone: $deque');

  // Deque supports random access AND double-ended insertions
  deque.pushFront(5);
  deque.pushBack(50);
  print('• Deque after O(1) double-ended operations: $deque\n');

  // 🥞 Stack natively uses Deque logic to restrict access to LIFO (Last-In, First-Out)
  final stack1 = Stack<int>.from(deque);
  final stack2 = Stack<int>.from([999, 888]);
  stack1.push(99);
  print('• Stack 1 spawned from Deque. Pushed 99.');
  print('  Top of Stack 1 is ${stack1.top} (Ready to pop: ${stack1.pop()})');

  print('\n[Swapping entire Stacks instantly!]');
  stack1.swap(stack2); // Swaps underlying structures immediately
  print('  Stack 1 is now strictly processing: $stack1');
  print('  Stack 2 inherited the massive chain: $stack2\n');

  // 🚏 Queue restricts access to FIFO (First-In, First-Out)
  final queue = Queue<int>.from(deque);
  queue.push(100);
  print('• Queue spawned from original Deque. Pushed 100.');
  print('  Front of Queue is ${queue.front} (Ready to strictly FIFO pop: ${queue.pop()})\n');


  // ========================================
  // 3. MATHEMATICAL SETS (O(1) Lookups & Trees)
  // ========================================
  print('>>> 3. ASSOCIATIVE SETS & TREES <<<\n');

  // Creating unique arrays
  final rawData = ['Apple', 'Banana', 'Apple', 'Cherry', 'Banana', 'Date'];
  
  // 1. Standard Set (Insertion Ordered)
  final orderedSet = Set<String>.from(rawData);
  print('• Standard Set (Preserves Insertion): $orderedSet'); // Duplicates gone

  // 2. HashSet (Unordered, Hyper-Optimized O(1))
  final hashSet = HashSet<String>.from(rawData);
  print('• HashSet (No guaranteed order, raw speed): ${hashSet.toList()}');

  // 3. SortedSet (Self-balancing Binary Search Tree)
  // Let's sort them strictly by string length, descending!
  final treeSet = SortedSet<String>.from(rawData, (a, b) => b.length.compareTo(a.length));
  print('• SortedSet (Autonomous custom sorting): $treeSet');

  // Set Algebra (Intersections across different sets)
  final exoticFruits = Set<String>.from(['Cherry', 'Mango', 'Banana', 'Kiwi']);
  final intersection = orderedSet.intersection(exoticFruits);
  print('• Intersection of orderedSet and exoticFruits: ${intersection.toList()}');

  final difference = orderedSet.difference(exoticFruits);
  print('• Difference (Apples and Dates remain!): ${difference.toList()}\n');


  // ========================================
  // 4. UTILITIES (Pair & PriorityQueue)
  // ========================================
  print('>>> 4. UTILITIES & PRIORITY HEAPS <<<\n');

  // A Pair lets us strictly bind heterogeneous types (ID: String, Priority: int)
  final task1 = makePair('Login System Task', 2);
  final task2 = makePair('Update UI Colors Task', 5);
  final task3 = makePair('Critical Database Migration', 1); // 1 = highest priority

  print('• Stored compound types smoothly: $task3');

  // Let's create a custom PriorityQueue (Min-Heap) that reads the Pair's second value (the integer priority)
  final pQueue = PriorityQueue<Pair<String, int>>((a, b) {
    // Standard min-heap logic: b compared to a.
    return b.second.compareTo(a.second);
  });

  pQueue.push(task1);
  pQueue.push(task2);
  pQueue.push(task3);

  print('\n• Processing PriorityQueue via Heap Extraction:');
  while (pQueue.isNotEmpty) {
    final highestTarget = pQueue.pop();
    print('  -> Processing (Priority ${highestTarget.second}): ${highestTarget.first}');
  }
  print('');


  // ========================================
  // 5. C++23 RANGES & PIPELINING 🧬
  // ========================================
  print('>>> 5. C++23 FUNCTIONAL RANGES <<<\n');

  // NumberLine: Generate integers dynamically without loading memory arrays
  final series = NumberLine(0, 100, step: 25);
  print('• NumberLine (0 to 100, step 25): ${series.toList()}');

  // RepeatRange: Repeat a state machine value strictly
  final defaultConfigs = RepeatRange('Config_v1');
  final servers = defaultConfigs.take(3).toList();
  print('• RepeatRange limits to 3 servers: $servers');

  // ZipRange: Bind two parallel arrays perfectly (Map creation)
  final headers = Vector<String>(['id', 'status', 'token']);
  final values = [9912, 'Active', 'xyz-888-abc'];
  
  final zip = ZipRange(headers, values);
  print('\n• ZipRange merging 2 vectors strictly:');
  for (final pair in zip) {
    print('  ${pair.first}: ${pair.second}');
  }

  // ChunkRange & Stack relationship pipeline!
  // Let's chunk a large array of numbers into batches of 3, 
  // then push those fragmented packets into a Stack for LIFO processing!
  print('\n[ChunkRange -> Stack Relationship Pipeline]');
  final byteData = NumberLine(1, 10).toList(); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  final chunks = ChunkRange(byteData, 3); // [[1,2,3], [4,5,6], [7,8,9], [10]]
  
  final packetStack = Stack<List<int>>();
  for (final packet in chunks) {
    packetStack.push(packet);
  }

  // Read them back strictly in reverse!
  print('• Stack processing downloaded chunks strictly backwards:');
  while (packetStack.isNotEmpty) {
    print('  -> Decompressing Packet: ${packetStack.pop()}');
  }

  // CartesianRange: Intersect two properties
  final suits = ['♠️', '♥️', '♣️', '♦️'];
  final royals = ['Jack', 'Queen', 'King', 'Ace'];
  final deckSegment = CartesianRange(royals, suits);
  
  print('\n• CartesianRange generates combinations (Showing 10 from 16 matrix tiles):');
  print('  ${deckSegment.take(10).toList()}');

  // One final combination: PriorityQueue pushing Zipped Ranges!
  print('\n[ZipRange -> PriorityQueue Pipeline]');
  final userIds = [101, 105, 102];
  final userLevels = [80, 99, 15]; // Level 99 is highest
  final zippedUsers = ZipRange(userIds, userLevels);
  
  // Custom Max-Heap
  final levelHeap = PriorityQueue<Pair<int, int>>((a, b) => a.second.compareTo(b.second));
  
  for (final userRecord in zippedUsers) {
    levelHeap.push(userRecord);
  }

  print('• Highest level user gets processed first:');
  while (levelHeap.isNotEmpty) {
     var usr = levelHeap.pop();
     print('  -> Processed User ${usr.first} (Level ${usr.second})');
  }

  // Final interaction: Deque -> Vector -> HashSet Unique Extractor
  print('\n[Deque -> Vector -> HashSet Pipeline]');
  final dirtyDeque = Deque<String>.from(['Error', 'Warning', 'Log', 'Error', 'Error', 'Warning']);
  print('• Raw Server Logs in Deque: $dirtyDeque');
  
  // Extract to Vector for processing
  final logVector = Vector<String>(dirtyDeque.toList());
  // Offload to HashSet to instantly destroy all duplicates with O(1) mathematical speed
  final cleanSet = HashSet<String>.from(logVector);
  print('• Extracted Unique Log Signatures instantly: ${cleanSet.toList()}');
  
  print('\n====================================================');
  print(' 🎉 END OF MEGA SHOWCASE');
  print('====================================================\n');
}