/ 
immutable-0.0.3
River stage zero No dependents
/ immutable

NAME

immutable - Immutable Data Structures for Perl

SYNOPSIS

use immutable ':all';

$hash1 = imap(k1 => 123, k2 => 456);
$k1 = $hash->{k1};                      # 123

$hash1->{k3} = 789;                     # Error
$hash2 = $hash1->set(k3 => 789);        # Correct
$hash2->get('k3');                      # 789

delete $hash2->{k3};                    # Error
$hash3 = $hash2->del('k3');             # Correct

$string = "$hash3";                     # <immutable::map 2 94394857332096>
$id = $hash3->id;                       # 94394857332096
$num = $hash3->size;                    # 2
$hash3->is_empty;                       # false

DESCRIPTION

The immutable module provides immutable versions of native Perl data structures.

Immutable data makes programs easier to reason about, and is foundational for functional programming and concurrency.

Immutable objects support both a tied interface (for use with Perl object access syntax) and an OO interface.

Mutating operation like $h-{x} = 1> and delete $h-{x}> will throw errors. You need to use the OO methods like $h-set(x => 1)> and $h-del('x')> which will return a new immutable::map immutable hash object. By throwing errors on these operations, it will make things obvious when you pass them to existing code that tries to do a mutating operation.

EXPORTS

The immutable module exports a number of sugar functions for creating new immutable objects.

  • iobj

    Create an immutable object from a plain scalar object.

    $ihash = iobj $hash;

  • imap

    Create an immutable hash (immutable::map) object. Takes an even number (0 to n) of key and value arguments.

    • $ihash = imap; # Empty hash

    • `$ihash = imap x => 1, y => 2;

  • iseq

    Immutable array. Not implemented yet.

  • ilist

    Immutable lazy list. Not implemented yet.

  • istr

    Immutable string. Not implemented yet.

  • inum

    Immutable number. Not implemented yet.

  • ibool

    Immutable boolean. Not implemented yet.

OBJECT OPERATIONS AND METHODS

Each types of immutable object has a class with various methods. The immutable objects are also tied so they respond to Perl syntax and keyword functions appropriately.

IMMUTABLE::MAP

  • new

    Takes a list of zero or more key/value scalars. Returns a new immutable::map hashref object that is also tied.

  • $imap-{key}>

    Get the hash/map value associated with the key.

  • $imap-get('key')>

    Same as above using method call.

  • $imap-{key} = $val>

    Not allowed. Throws an error.

  • $imap-set(key => $value, ...)>

    Clones the map and adds the key value pairs to it.

    Calling this with no args creates an equivalent clone of the caller.

  • delete $imap-{key}>

    Not allowed. Throws an error.

  • $imap-del('key')>

    Clones the map and deletes the key pair from it.

  • $imap-id>

    Returns an integer id number for the map.

  • $imap-size>

    Returns the number of key value pairs in the map.

  • $imap-is_empty>

    Returns true if the map is empty.

STATUS

This module is new and too incomplete, buggy and slow to use for any real code.

It is being developed for use in Lingy, a Perl implementation of Clojure, which needs immutable data types.

Only immutable maps are support in this early version.

Very little effort is currently placed on performance and memory usage. The intent is to use performant and memory efficient XS based algorithms once the API stabilizes.

COPYRIGHT AND LICENSE

Copyright 2023 by Ingy döt Net

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html