Invercargill/README.md

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:

   meson setup src build
   ninja -C build
   

3. Install the library:

   ninja -C install
   

License

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

Testing

The library includes comprehensive test suites:

• Integration tests for core functionality
• Speed tests to ensure optimal performance