How to convert a nested hash to immutable in Crystal?

Use the `.from` method as shown in the README: `Immutable.from({:key => 'value'})` returns an immutable Map with nested structures converted, preserving the original data without manual copying.

Immutable Vector vs Crystal Array performance comparison?

Immutable Vector offers O(Log32) lookups and updates with structural sharing for thread safety, while Crystal Array provides O(1) for many operations but requires locks for concurrency. Choose based on thread-safety needs vs raw speed.

When should I use transient in the Immutable library?

Use transient for bulk updates, as it temporarily enables mutable operations to improve performance. The README shows examples with 1000-time loops where transient reduces overhead compared to repeated immutable modifications.

Is Immutable::Map thread-safe without any locks?

Yes, because it's immutable, so multiple threads can read or create copies concurrently without locks. The README explicitly states this inherent thread-safety due to persistent data structures.

How do I install the Immutable library in a Crystal project?

Add it to your shard.yml as shown: specify `immutable` under dependencies with the GitHub URL. Then run `shards install` to integrate it seamlessly with your Crystal setup.

What are the main limitations of using Immutable in Crystal?

It only supports Vector and Map data structures, so you might miss sets or queues. Also, the O(Log32) complexity, while efficient, isn't as fast as O(1) for some high-performance use cases with mutable collections.

immutable — Crystal Immutable Data Structures

What is immutable?

Immutable is a library providing efficient, thread-safe immutable data structures for the Crystal programming language. It implements persistent collections like Vector (array-like) and Map (hash-like) where modifications return new copies while preserving the original, enabling functional programming patterns with structural sharing for performance.

Target Audience

Crystal developers building concurrent applications, functional programming enthusiasts, or anyone needing thread-safe collections without locking overhead.

Value Proposition

Developers choose Immutable for its performance-optimized persistent data structures, inherent thread safety, and seamless integration with Crystal's ecosystem, offering a functional alternative to mutable collections.

Thread-safe, persistent, immutable collections for the Crystal language

Use Cases

Best For

Building concurrent Crystal applications without locking mechanisms
Implementing functional programming patterns with persistent data structures
Creating thread-safe collections for shared data access
Optimizing performance with structural sharing for frequent collection modifications
Converting nested arrays and hashes into immutable versions
Performing bulk updates efficiently using transient interfaces

Not Ideal For

Applications performing millions of small, sequential updates to large collections where mutable in-place changes are preferred for raw speed
Projects with strict real-time latency requirements that cannot tolerate even near-constant O(Log32) overhead for lookups and updates
Teams heavily reliant on Crystal's standard mutable Array and Hash APIs without concurrency needs, as switching adds unnecessary complexity

Pros & Cons

Pros

Inherent Thread Safety

Immutability guarantees safe concurrent access without locks, making it ideal for multi-threaded Crystal applications as highlighted in the README's emphasis on thread-safe design.

Efficient Structural Sharing

Modifications return copies via structural sharing, minimizing memory overhead and performance hits compared to deep copies, with implementations like vector tries ensuring O(Log32) operations.

Optimized Bulk Updates

The transient interface allows for faster bulk modifications by temporarily using mutable operations, as demonstrated in the usage examples for handling thousands of updates efficiently.

Seamless Nested Conversion

The `.from` method easily converts nested arrays and hashes into immutable versions, integrating with existing Crystal code without manual restructuring.

Cons

Limited Data Structure Variety

Only Vector and Map are implemented, lacking other common immutable collections like sets or queues, which might require additional libraries or workarounds.

Logarithmic Complexity Overhead

Despite being near-constant, operations have O(Log32) complexity, which can be slower than O(1) for mutable collections in performance-critical scenarios, as noted in the implementation details.

API Divergence from Standards

While similar to Array and Hash, the immutable API has differences (e.g., `.set` instead of assignment) that require code changes and learning effort for developers accustomed to mutable paradigms.

Frequently Asked Questions

What is immutable?

Target Audience

Crystal developers building concurrent applications, functional programming enthusiasts, or anyone needing thread-safe collections without locking overhead.

Value Proposition

Use Cases

Best For

Building concurrent Crystal applications without locking mechanisms
Implementing functional programming patterns with persistent data structures
Creating thread-safe collections for shared data access
Optimizing performance with structural sharing for frequent collection modifications
Converting nested arrays and hashes into immutable versions
Performing bulk updates efficiently using transient interfaces

Not Ideal For

Applications performing millions of small, sequential updates to large collections where mutable in-place changes are preferred for raw speed
Projects with strict real-time latency requirements that cannot tolerate even near-constant O(Log32) overhead for lookups and updates
Teams heavily reliant on Crystal's standard mutable Array and Hash APIs without concurrency needs, as switching adds unnecessary complexity

Pros & Cons

Pros

Inherent Thread Safety

Immutability guarantees safe concurrent access without locks, making it ideal for multi-threaded Crystal applications as highlighted in the README's emphasis on thread-safe design.

Efficient Structural Sharing

Modifications return copies via structural sharing, minimizing memory overhead and performance hits compared to deep copies, with implementations like vector tries ensuring O(Log32) operations.

Optimized Bulk Updates

The transient interface allows for faster bulk modifications by temporarily using mutable operations, as demonstrated in the usage examples for handling thousands of updates efficiently.

Seamless Nested Conversion

The `.from` method easily converts nested arrays and hashes into immutable versions, integrating with existing Crystal code without manual restructuring.

Cons

Limited Data Structure Variety

Only Vector and Map are implemented, lacking other common immutable collections like sets or queues, which might require additional libraries or workarounds.

Logarithmic Complexity Overhead

Despite being near-constant, operations have O(Log32) complexity, which can be slower than O(1) for mutable collections in performance-critical scenarios, as noted in the implementation details.

API Divergence from Standards

While similar to Array and Hash, the immutable API has differences (e.g., `.set` instead of assignment) that require code changes and learning effort for developers accustomed to mutable paradigms.

Frequently Asked Questions

immutable

What is immutable?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

immutable

What is immutable?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?