# Invercargill

Invercargill is a comprehensive data manipulation library for the Vala programming language. It provides an Enumerable type that makes working with data sets significantly more intuitive and less cognitively taxing. The library offers a rich set of functional programming tools for data transformation, querying, and manipulation.

I write a lot of random projects in Vala, and since I work with C# professionally I am very familiar with the sorts of operations it provides in its `IEnumerable` interface. I wasn't particularly satisfied with LibGee so I decided I would roll my own library and name it after New Zealand's southernmost city; Invercargill! I took heavy inspiration from the C# `IEnumerable` interface in developing this library but also added some unique functions and structures where appropriate to adapt to the neuances of the Vala language.

## Features

- **Functional Programming Paradigm**: Chain operations elegantly with a fluent API design
- **Data Structures**: Comprehensive collection of optimized data structures including Buffers, Vectors, Series, Dictionaries, Sets, and more
- **Query Operations**: Extensive set of query operations similar to LINQ, including filtering, projection, aggregation, sorting, and grouping
- **Parallel Processing**: Built-in support for parallel operations to leverage multi-core processors
- **Memory Efficiency**: Lazy evaluation and caching mechanisms for optimal memory usage
- **Error Handling**: Comprehensive error handling with custom exception types

## Key Components

### Core Enumerable
The central `Enumerable<T>` class provides the foundation for all data operations, supporting:
- Iteration and enumeration
- Transformation and projection
- Filtering and selection
- Aggregation and reduction
- Set operations (union, intersection, difference)
- Sorting and ordering
- Partitioning and grouping

### Data Structures
- **Buffer**: Fixed-size array implementation with type-safe access and bounds checking
- **Series**: Linked list implementation supporting efficient insertion at both ends and in-order traversal
- **Vector**: Dynamic array with automatic resizing, supporting indexed access and efficient insertion/removal
- **Dictionary**: Key-value store built on HashSet, allowing custom hash and equality functions for keys
- **HashSet**: Hash table implementation with collision handling, automatic resizing, and tombstone-based deletion
- **PriorityQueue**: Min-heap implementation with thread-safe push/pop operations and blocking behavior
- **RingBuffer**: Fixed-size circular buffer supporting infinite iteration by wrapping around to the start
- **Fifo/Lifo**: Thread-safe queue and stack implementations with blocking operations and support for unblocking
- **SortedSeries**: Red-black tree implementation maintaining sorted order with efficient insertion, deletion, and traversal

### Modifiers
Rich set of operations for data manipulation:
- **Filter**: `where()`, `from()`, `until()`
- **Transform**: `select()`, `select_many()`, `cast()`, `of_type()`
- **Set Operations**: `combine()`, `common()`, `exclude()`, `distinct()`
- **Ordering**: `sort()`, `order_by()`, `reverse()`
- **Partitioning**: `take()`, `skip()`, `chunk()`, `window()`
- **Combination**: `zip()`, `concat()`, `interleave()`, `cycle()`

### Specialized Features
- **Attempts**: Safe operation handling with error recovery
- **Promotions**: Type promotion system for specialized operations
- **Parallel Processing**: Multi-threaded operations for performance
- **Debugging**: Comprehensive debugging utilities for development

## Installation

### Prerequisites
- Vala compiler
- Meson build system
- Ninja build tool
- GLib development libraries

### Building from Source

1. Clone the repository
2. Run the build script:
   ```bash
   meson setup src build
   ninja -C build
   ```

3. Install the library:
   ```bash
   ninja -C install
   ```

## License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). See the [LICENSE](LICENSE) file for details.

## Testing

The library includes comprehensive test suites:
- Integration tests for core functionality
- Speed tests to ensure optimal performance