Class: Y::Map

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/y/map.rb

Overview

A map can be used to store and retrieve key-value pairs.

The map is the replicated counterpart to a Hash. It supports a subset of the Hash operations, like adding, getting and deleting values by key.

Someone should not instantiate a map directly, but use Doc#get_map instead.

Examples:

doc = Y::Doc.new
map = doc.get_map("my map")

map[:hello] = "world"
puts map[:hello]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(doc = nil) ⇒ Map

Create a new map instance

Parameters:

  • doc (Y::Doc) (defaults to: nil) 


31
32
33
34
35
 
# File 'lib/y/map.rb', line 31

def initialize(doc = nil)
  @document = doc || Y::Doc.new

  super()
end

Instance Attribute Details

#document ⇒ Y::Doc

Returns The document this map belongs to.

Returns:

  • (Y::Doc) —

    The document this map belongs to



26
27
28
 
# File 'lib/y/map.rb', line 26

def document
  @document
end

Instance Method Details

#[](key) ⇒ Object

Returns:

  • (Object) 


107
108
109
 
# File 'lib/y/map.rb', line 107

def [](key)
  document.current_transaction { |tx| ymap_get(tx, key) }
end

#[]=(key, val) ⇒ void

This method returns an undefined value.



112
113
114
 
# File 'lib/y/map.rb', line 112

def []=(key, val)
  document.current_transaction { |tx| ymap_insert(tx, key, val) }
end

#attach(callback, &block) ⇒ Integer

Attach a listener to get notified about any changes to the map

Parameters:

  • callback (Proc)
  • block (Block)

Returns:

  • (Integer) 


42
43
44
45
46
 
# File 'lib/y/map.rb', line 42

def attach(callback, &block)
  return ymap_observe(callback) unless callback.nil?

  ymap_observe(block.to_proc) unless block.nil?
end

#clear ⇒ Self

Removes all map entries

Returns:

  • (Self) 


51
52
53
54
 
# File 'lib/y/map.rb', line 51

def clear
  document.current_transaction { |tx| ymap_clear(tx) }
  self
end

#delete(key) ⇒ void

This method returns an undefined value.

Deletes the entry for the given key and returns its associated value.

Examples:

Deletes the entry and return associated value


m = doc.get_map("my map")
m[:bar] = 1
m.delete(:bar) # => 1
m # => {}

Unknown key is handled in block


m = doc.get_map("my map")
m.delete(:nosuch) { |key| "Key #{key} not found" }# => "Key nosuch not found"
m # => {}

Parameters:

  • key (String, Symbol) 


75
76
77
78
79
80
81
82
 
# File 'lib/y/map.rb', line 75

def delete(key)
  value = document.current_transaction { |tx| ymap_remove(tx, key) }
  if block_given? && key?(key)
    yield key
  else
    value
  end
end

#detach(subscription_id) ⇒ void

This method returns an undefined value.

Detach listener

Parameters:

  • subscription_id (Integer) 


90
91
92
 
# File 'lib/y/map.rb', line 90

def detach(subscription_id)
  ymap_unobserve(subscription_id)
end

#each(&block) ⇒ void

This method returns an undefined value.



95
96
97
 
# File 'lib/y/map.rb', line 95

def each(&block)
  document.current_transaction { |tx| ymap_each(tx, block) }
end

#key?(key) ⇒ true, false Also known as: has_key?

Returns:

  • (true, false) 


100
101
102
 
# File 'lib/y/map.rb', line 100

def key?(key)
  document.current_transaction { |tx| ymap_contains(tx, key) }
end

#size ⇒ Integer

Returns size of map

Returns:

  • (Integer) 


119
120
121
 
# File 'lib/y/map.rb', line 119

def size
  document.current_transaction { |tx| ymap_size(tx) }
end

#to_h ⇒ Hash

Returns a Hash representation of this map

Returns:

  • (Hash) 


126
127
128
 
# File 'lib/y/map.rb', line 126

def to_h
  document.current_transaction { |tx| ymap_to_h(tx) }
end

#to_json(*_args) ⇒ String

Returns a JSON representation of map

Returns:

  • (String) —

    JSON string



133
134
135
 
# File 'lib/y/map.rb', line 133

def to_json(*_args)
  to_h.to_json
end

#ymap_clear(tx) ⇒ Object

Removes all key-value pairs from Map




# File 'lib/y/map.rb', line 137

#ymap_contains(tx, key) ⇒ Object

Check if a certain key is in the Map




# File 'lib/y/map.rb', line 142

#ymap_each(tx, proc) ⇒ Object

Iterates over all key-value pairs in Map by calling the provided proc with the key and the value as arguments.




# File 'lib/y/map.rb', line 149

#ymap_get(tx, key) ⇒ Object

Returns stored value for key or nil if none is present




# File 'lib/y/map.rb', line 156

#ymap_insert(tx, key, value) ⇒ Object

Insert value for key. In case the key already exists, the previous value will be overwritten.




# File 'lib/y/map.rb', line 163

#ymap_observe(callback) ⇒ Integer

Parameters:

  • callback (Proc)

Returns:

  • (Integer) 



# File 'lib/y/map.rb', line 171

#ymap_remove(tx, key) ⇒ Object

Removes key-value pair from Map if key exists.




# File 'lib/y/map.rb', line 176

#ymap_size(tx) ⇒ Object

Returns number of key-value pairs stored in map




# File 'lib/y/map.rb', line 182

#ymap_to_h(tx) ⇒ Object

Returns a Hash representation of the Map




# File 'lib/y/map.rb', line 188

#ymap_unobserve(subscription_id) ⇒ void

This method returns an undefined value.

Parameters:

  • subscription_id (Integer) 



# File 'lib/y/map.rb', line 194