Collections Overview

WARNING: This page may include outdated or invalid syntax. Examples are illustrative and will be updated to current Harneet standards (var/mandatory parameter types/valid function syntax).

The Harneet programming language provides a comprehensive set of data structures through its enhanced collections module. These data structures are designed for performance, memory efficiency, and ease of use, making them suitable for a wide range of applications from simple scripts to complex concurrent systems.

Available Data Structures

Core Collections

Enhanced Collections

Concurrent Collections

All data structures have thread-safe variants for concurrent applications:

• ConcurrentStack - Thread-safe stack with RWMutex
• ConcurrentQueue - Thread-safe queue with lock-free optimizations
• ConcurrentSet - Thread-safe set with concurrent hash map
• ConcurrentMap - Thread-safe map with optimized locking

Getting Started

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

package main
import fmt
import collections

// Create a stack
var stack = collections.new_stack()
stack.push(42)
stack.push("hello")
fmt.Println("Stack size:", stack.size())

// Create a queue
var queue = collections.new_queue()
queue.enqueue("first")
queue.enqueue("second")
var item = queue.dequeue()
fmt.Println("Dequeued:", item)

// Create a set
var set = collections.new_set()
set.add("apple")
set.add("banana")
set.add("apple")  // Duplicate ignored
fmt.Println("Set size:", set.size())  // 2

Performance Considerations

The enhanced collections are designed with performance in mind:

• Memory Pre-allocation: Use reserve() methods to pre-allocate memory for known sizes
• Batch Operations: Prefer bulk operations when available
• Iterator Patterns: Use iterators for efficient traversal
• Concurrent Access: Use concurrent variants for multi-threaded applications

Memory Management

Collections automatically manage memory allocation and deallocation:

• Dynamic resizing with configurable growth factors
• Automatic shrinking when collections become sparse
• Memory pooling for frequently created/destroyed collections
• Garbage collection friendly implementations

Quick Reference

Import and Creation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

import collections

// Basic collections
var stack = collections.new_stack()
var queue = collections.new_queue()
var set = collections.new_set()
var list = collections.new_linked_list()
var tree = collections.new_bst()

// Enhanced collections
var array = collections.new_array()
var map = collections.new_map()

// Concurrent collections
var c_stack = collections.new_concurrent_stack()
var c_queue = collections.new_concurrent_queue()
var c_set = collections.new_concurrent_set()
var c_map = collections.new_concurrent_map()

Common Operations

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// Size and emptiness
collection.size()
collection.is_empty()
collection.clear()

// Conversion
collection.to_array()
collection.inspect()

// Iteration (where supported)
var iter = collection.iterator()
for iter.has_next() {
    var item = iter.next()
    fmt.Println(item)
}

Performance Characteristics

Time Complexity Summary

*Average case for hash-based operations
†For head/tail operations

Space Complexity

All collections have O(n) space complexity where n is the number of elements, with additional overhead for:

• Hash tables: Load factor overhead (typically 25-50%)
• Trees: Parent/child pointers and balancing metadata
• Linked structures: Next/previous pointers
• Concurrent collections: Synchronization primitives

Best Practices

Choosing the Right Data Structure

1. Use Stack when: You need LIFO behavior, implementing recursion, or managing function calls
2. Use Queue when: You need FIFO behavior, task scheduling, or breadth-first algorithms
3. Use Set when: You need unique elements, fast membership testing, or set operations
4. Use LinkedList when: You need frequent insertion/deletion at arbitrary positions
5. Use BinarySearchTree when: You need sorted data with fast search/insert/delete operations
6. Use Enhanced Array when: You need dynamic arrays with functional programming methods
7. Use Enhanced Map when: You need high-performance key-value storage

Performance Tips

1. Pre-allocate: Use reserve() methods when you know the expected size
2. Batch operations: Use bulk methods when available (e.g., add_all(), remove_all())
3. Choose appropriate initial capacity: Avoid frequent resizing operations
4. Use concurrent collections: Only when actually needed for multi-threaded access
5. Profile memory usage: Monitor collection sizes in production applications

Error Handling

Collections follow consistent error handling patterns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// Check for errors
var result = collection.get(index)
if result.type() == "ERROR" {
    fmt.Println("Error:", result.message())
    return
}

// Safe operations
if !collection.is_empty() {
    var item = collection.pop()
}

// Bounds checking
if index >= 0 && index < collection.size() {
    var item = collection.get(index)
}

Migration Guide

If you're upgrading from basic collections to enhanced collections, see the Migration Guide for detailed instructions on updating your code.

Examples and Tutorials

• Stacks & Queues Guide - Comprehensive guide to LIFO and FIFO structures
• Sets Guide - Working with unique collections and set operations
• Linked Lists Guide - Dynamic list manipulation and iteration
• Trees Guide - Binary search trees and traversal algorithms
• Concurrent Collections Guide - Thread-safe data structures
• Performance Guide - Optimization techniques and benchmarks

API Reference

For detailed API documentation including all methods, parameters, and return types, see the individual data structure guides linked above.