|
|
@@ -1,6 +1,85 @@
|
|
|
# Invercargill
|
|
|
|
|
|
-This library provides an Enumerable type that aims to make working with data sets
|
|
|
-much less cogniatively taxing while using Vala.
|
|
|
+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
|
|
|
|
|
|
-More to come
|
