Module: Immutable

Defined in:
lib/immutable/list.rb,
lib/immutable/trie.rb,
lib/immutable/_core.rb,
lib/immutable/deque.rb,
lib/immutable/nested.rb,
lib/immutable/version.rb,
lib/immutable/undefined.rb,
lib/immutable/enumerable.rb,
lib/immutable/sorted_set.rb

Defined Under Namespace

Modules: Enumerable, List, Undefined Classes: Cons, Deque, Hash, LazyList, Partitioned, Partitioner, Realizable, Set, SortedSet, Splitter, Trie, Vector

Constant Summary collapse

EmptyTrie = 
Trie.new(0).freeze
EmptyHash =

The canonical empty ‘Hash`. Returned by `Hash[]` when invoked with no arguments; also returned by `Hash.empty`. Prefer using this one rather than creating many empty hashes using `Hash.new`.

Immutable::Hash.empty
EmptyVector =

The canonical empty ‘Vector`. Returned by `Vector[]` when invoked with no arguments; also returned by `Vector.empty`. Prefer using this one rather than creating many empty vectors using `Vector.new`.

Immutable::Vector.empty
EmptySet =

The canonical empty ‘Set`. Returned by `Set[]` when invoked with no arguments; also returned by `Set.empty`. Prefer using this one rather than creating many empty sets using `Set.new`.

Immutable::Set.empty
EmptyDeque =

The canonical empty ‘Deque`. Returned by `Deque[]` when invoked with no arguments; also returned by `Deque.empty`. Prefer using this one rather than creating many empty deques using `Deque.new`.

Immutable::Deque.empty
VERSION =

Current released gem version. Note that master will often have the same value as a release gem but with different code.

'0.2.0'
EmptySortedSet =

The canonical empty ‘SortedSet`. Returned by `SortedSet[]` when invoked with no arguments; also returned by `SortedSet.empty`. Prefer using this one rather than creating many empty sorted sets using `SortedSet.new`.

Immutable::SortedSet.empty

Class Method Summary collapse

Class Method Details

.enumerate(enum) ⇒ List

Turn an ‘Enumerator` into a `Immutable::List`. The result is a lazy collection where the values are memoized as they are generated.

If your code uses multiple threads, you need to make sure that the returned lazy collection is realized on a single thread only. Otherwise, a ‘FiberError` will be raised. After the collection is realized, it can be used from other threads as well.

Examples:

def rg; loop { yield rand(100) }; end
Immutable.enumerate(to_enum(:rg)).take(10)

Parameters:

  • enum (Enumerator) —

    The object to iterate over

Returns:



92
93
94
95
96
97
98
99
100
 
# File 'lib/immutable/list.rb', line 92

def enumerate(enum)
  LazyList.new do
    begin
      Cons.new(enum.next, enumerate(enum))
    rescue StopIteration
      EmptyList
    end
  end
end

.from(obj) ⇒ Hash, ...

Create a nested Immutable data structure from a nested Ruby object ‘obj`. This method recursively “walks” the Ruby object, converting Ruby `Hash` to Hash, Ruby `Array` to Vector, Ruby `Set` to Set, and Ruby `SortedSet` to SortedSet. Other objects are left as-is.

Examples:

h = Immutable.from({ "a" => [1, 2], "b" => "c" })
# => Immutable::Hash["a" => Immutable::Vector[1, 2], "b" => "c"]

Returns:



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/immutable/nested.rb', line 24

def from(obj)
  case obj
  when ::Hash
    res = obj.map { |key, value| [from(key), from(value)] }
    Immutable::Hash.new(res)
  when Immutable::Hash
    obj.map { |key, value| [from(key), from(value)] }
  when ::Array
    res = obj.map { |element| from(element) }
    Immutable::Vector.new(res)
  when ::Struct
    from(obj.to_h)
  when ::SortedSet
    # This clause must go before ::Set clause, since ::SortedSet is a ::Set.
    res = obj.map { |element| from(element) }
    Immutable::SortedSet.new(res)
  when ::Set
    res = obj.map { |element| from(element) }
    Immutable::Set.new(res)
  when Immutable::Vector, Immutable::Set, Immutable::SortedSet
    obj.map { |element| from(element) }
  else
    obj
  end
end

.interval(from, to) ⇒ List

Construct a list of consecutive integers.

Examples:

Immutable.interval(5,9)
# => Immutable::List[5, 6, 7, 8, 9]

Parameters:

  • from (Integer) —

    Start value, inclusive

  • to (Integer) —

    End value, inclusive

Returns:



36
37
38
39
 
# File 'lib/immutable/list.rb', line 36

def interval(from, to)
  return EmptyList if from > to
  interval_exclusive(from, to.next)
end

.iterate(item) {|previous| ... } ⇒ List

Create an infinite list where each item is derived from the previous one, using the provided block

Examples:

Immutable.iterate(0) { |i| i.next }.take(5)
# => Immutable::List[0, 1, 2, 3, 4]

Parameters:

  • item (Object) —

    Starting value

Yield Parameters:

  • previous (Object) —

    The previous value

Yield Returns:

  • (Object) —

    The next value

Returns:



74
75
76
 
# File 'lib/immutable/list.rb', line 74

def iterate(item, &block)
  LazyList.new { Cons.new(item, iterate(yield(item), &block)) }
end

.repeat(item) ⇒ List

Create an infinite list repeating the same item indefinitely

Examples:

Immutable.repeat(:chunky).take(4)
=> Immutable::List[:chunky, :chunky, :chunky, :chunky]

Returns:



48
49
50
 
# File 'lib/immutable/list.rb', line 48

def repeat(item)
  LazyList.new { Cons.new(item, repeat(item)) }
end

.replicate(number, item) ⇒ List

Create a list that contains a given item a fixed number of times

Examples:

Immutable.replicate(3, :hamster)
#=> Immutable::List[:hamster, :hamster, :hamster]

Returns:



59
60
61
 
# File 'lib/immutable/list.rb', line 59

def replicate(number, item)
  repeat(item).take(number)
end

.stream(&block) ⇒ List

Create a lazy, infinite list.

The given block is called as necessary to return successive elements of the list.

Examples:

Immutable.stream { :hello }.take(3)
# => Immutable::List[:hello, :hello, :hello]

Returns:



22
23
24
25
 
# File 'lib/immutable/list.rb', line 22

def stream(&block)
  return EmptyList unless block_given?
  LazyList.new { Cons.new(yield, stream(&block)) }
end

.to_ruby(obj) ⇒ ::Hash, ...

Create a Ruby object from Immutable data. This method recursively “walks” the Immutable object, converting Hash to Ruby ‘Hash`, Vector and Deque to Ruby `Array`, Set to Ruby `Set`, and SortedSet to Ruby `SortedSet`. Other objects are left as-is.

Examples:

h = Immutable.to_ruby(Immutable.from({ "a" => [1, 2], "b" => "c" }))
# => { "a" => [1, 2], "b" => "c" }

Returns:

  • (::Hash, ::Array, ::Set, ::SortedSet, Object) 


61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/immutable/nested.rb', line 61

def to_ruby(obj)
  case obj
  when Immutable::Hash, ::Hash
    obj.each_with_object({}) { |keyval, hash| hash[to_ruby(keyval[0])] = to_ruby(keyval[1]) }
  when Immutable::Vector, ::Array
    obj.each_with_object([]) { |element, arr| arr << to_ruby(element) }
  when Immutable::Set, ::Set
    obj.each_with_object(::Set.new) { |element, set| set << to_ruby(element) }
  when Immutable::SortedSet, ::SortedSet
    obj.each_with_object(::SortedSet.new) { |element, set| set << to_ruby(element) }
  when Immutable::Deque
    obj.to_a.tap { |arr| arr.map! { |element| to_ruby(element) }}
  else
    obj
  end
end