Class: Y::Array

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

Overview

An array can be used to store and retrieve elements.

The array is the replicated counterpart to a Ruby Array. It supports a subset of the Ruby Array operations, like adding, getting and deleting values by position or ranges.

Someone should not instantiate an array directly, but use Doc#get_array instead.

Examples:

doc = Y::Doc.new
array = doc.get_array("my array")

array << 1
array.push(2)
array.concat([3, 4, 5])

array.to_a == [1, 2, 3, 4, 5] # true

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(doc = nil) ⇒ Array

Create a new array instance

Parameters:

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


33
34
35
36
37
 
# File 'lib/y/array.rb', line 33

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

  super()
end

Instance Attribute Details

#document ⇒ Y::Doc

Returns The document this array belongs to.

Returns:

  • (Y::Doc) —

    The document this array belongs to



28
29
30
 
# File 'lib/y/array.rb', line 28

def document
  @document
end

Instance Method Details

#<<(value, *values) ⇒ void Also known as: push

This method returns an undefined value.

Adds an element to the end of the array

Parameters:

  • value (true, false, Float, Integer, String, ::Array, Hash) 


59
60
61
62
63
64
 
# File 'lib/y/array.rb', line 59

def <<(value, *values)
  document.current_transaction do |tx|
    yarray_push_back(tx, value)
    values.each { |v| yarray_push_back(tx, v) }
  end
end

#[](index) ⇒ true, ...

Retrieves element at position

Returns:

  • (true, false, Float, Integer, String, Array, Hash) 


42
43
44
 
# File 'lib/y/array.rb', line 42

def [](index)
  document.current_transaction { |tx| yarray_get(tx, index) }
end

#[]=(index, value) ⇒ void

This method returns an undefined value.

Inserts value at position

Parameters:

  • index (Integer)
  • value (true, false, Float, Integer, String, Array, Hash) 


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

def []=(index, value)
  document.current_transaction { |tx| yarray_insert(tx, index, value) }
end

#attach(&block) ⇒ Integer

Attach listener to array changes

Examples:

Listen to changes in array type

local = Y::Doc.new

arr = local.get_array("my array")
arr.attach { |delta| pp delta }

local.transact do
  arr << 1
end

Parameters:

  • block (Block)

Returns:

  • (Integer) 


80
81
82
83
84
 
# File 'lib/y/array.rb', line 80

def attach(&block)
  raise "provide block" unless block

  yarray_observe(block.to_proc)
end

#concat(*other_arrays) ⇒ void

This method returns an undefined value.

Adds to array all elements from each Array in other_arrays.

If one of the arguments isn't an Array, it is silently ignored.

Examples:

Add multiple values to array

doc = Y::Doc.new
arr = doc.get_array("my array")
arr.concat([1, 2, 3])

arr.to_a == [1, 2, 3] # true

Parameters:



99
100
101
102
103
104
105
106
107
 
# File 'lib/y/array.rb', line 99

def concat(*other_arrays)
  document.current_transaction do |tx|
    combined = other_arrays.reduce([]) do |values, arr|
      values.concat(arr) if arr.is_a?(::Array)
    end

    yarray_insert_range(tx, yarray_length(tx), combined)
  end
end

#detach(subscription_id) ⇒ void

This method returns an undefined value.

Detach listener

Parameters:

  • subscription_id (Integer) 


113
114
115
 
# File 'lib/y/array.rb', line 113

def detach(subscription_id)
  yarray_unobserve(subscription_id)
end

#each ⇒ void

This method returns an undefined value.



118
119
120
 
# File 'lib/y/array.rb', line 118

def each(...)
  document.current_transaction { |tx| yarray_each(tx, ...) }
end

#empty? ⇒ true, false

Check if the array is empty

Returns:

  • (true, false) 


125
126
127
 
# File 'lib/y/array.rb', line 125

def empty?
  size.zero?
end

#first ⇒ true, ...

Returns first element in array if there is at least one

Returns:

  • (true, false, Float, Integer, String, ::Array, Hash, nil) 


132
133
134
 
# File 'lib/y/array.rb', line 132

def first
  document.current_transaction { |tx| yarray_get(tx, 0) }
end

#last ⇒ true, ...

Returns last element in array if there is at least one element

Returns:

  • (true, false, Float, Integer, String, ::Array, Hash, nil) 


139
140
141
142
143
144
145
146
 
# File 'lib/y/array.rb', line 139

def last
  document.current_transaction do |tx|
    len = yarray_length(tx)
    return yarray_get(tx, len - 1) if len.positive?

    nil
  end
end

#pop(n = nil) ⇒ void

This method returns an undefined value.

Removes last (n) element(s) from array

Parameters:

  • n (Integer, nil) (defaults to: nil) —

    Number of elements to remove



154
155
156
157
158
159
160
 
# File 'lib/y/array.rb', line 154

def pop(n = nil)
  document.current_transaction do |tx|
    len = yarray_length(tx)
    yarray_remove(tx, len - 1) if n.nil?
    yarray_remove_range(tx, len - n, n) unless n.nil?
  end
end

#shift(n = nil) ⇒ void

This method returns an undefined value.

Removes first (n) element(s) from array

Parameters:

  • n (Integer, nil) (defaults to: nil) —

    Number of elements to remove



172
173
174
175
176
177
178
 
# File 'lib/y/array.rb', line 172

def shift(n = nil)
  document.current_transaction do |tx|
    yarray_remove(tx, 0) if n.nil?

    yarray_remove_range(tx, 0, n) unless nil?
  end
end

#size ⇒ Integer Also known as: length

Size of array

Returns:

  • (Integer) 


185
186
187
 
# File 'lib/y/array.rb', line 185

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

#slice!(n) ⇒ void #slice!(start, length) ⇒ void #slice!(range) ⇒ void

This method returns an undefined value.

Removes one or more elements from array

Attention: In comparison to Array#slice, #slice! will not return the values that got removed. Even this being technically possible, it requires us to read the elements before removing them, which is not desirable in most situations.

Examples:

Removes a single element

doc = Y::Doc.new

arr = doc.get_text("my array")
arr << 1
arr << 2
arr << 3

arr.slice!(1)

arr.to_a == [1, 3] # true

Overloads:

  • #slice!(n) ⇒ void

    Removes nth element from array

  • #slice!(start, length) ⇒ void

    Removes a range of elements

  • #slice!(range) ⇒ void

    Removes a range of elements



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/y/array.rb', line 222

def slice!(*args)
  document.current_transaction do |tx| # rubocop:disable Metrics/BlockLength
    if args.empty?
      raise ArgumentError,
            "Provide one of `index`, `range`, `start, length` as arguments"
    end

    if args.size == 1
      arg = args.first

      if arg.is_a?(Range)
        if arg.exclude_end?
          yarray_remove_range(tx, arg.first,
                              arg.last - arg.first)
        end
        unless arg.exclude_end?
          yarray_remove_range(tx, arg.first,
                              arg.last + 1 - arg.first)
        end
        return nil
      end

      if arg.is_a?(Numeric)
        yarray_remove(tx, arg.to_int)
        return nil
      end
    end

    if args.size == 2
      first, second = args

      if first.is_a?(Numeric) && second.is_a?(Numeric)
        yarray_remove_range(tx, first, second)
        return nil
      end
    end

    raise ArgumentError, "Please check your arguments, can't slice."
  end
end

#to_a ⇒ Array<true, false, Float, Integer, String, ::Array, Hash>

Convert this array to a Ruby Array

Returns:

  • (Array<true, false, Float, Integer, String, ::Array, Hash>) 


268
269
270
 
# File 'lib/y/array.rb', line 268

def to_a
  document.current_transaction { |tx| yarray_to_a(tx) }
end

#unshift(value) ⇒ void Also known as: prepend

This method returns an undefined value.

Adds an element to the beginning of the array



275
276
277
 
# File 'lib/y/array.rb', line 275

def unshift(value)
  document.current_transaction { |tx| yarray_push_front(tx, value) }
end