Class: Farce::Abstract::Vector Abstract

Inherits:
Collection show all
Includes:
Internal::MarshalSupport::Vector
Defined in:
lib/farce/abstract/vector.rb,
lib/farce/integrations/bson.rb,
lib/farce/integrations/cbor.rb,
lib/farce/integrations/msgpack.rb,
lib/farce/integrations/shared/to_json.rb,
lib/farce/integrations/active_support/vector.rb

Overview

This class is abstract.

Superclass for concurrent indexed collections.

Negative indexes count from the end. Assignments beyond the end fill gaps with nil. Atomic updates reserve the entire vector. Reads through #[] do not wait for updates. Timeouts are finite, non-negative seconds. Nil waits indefinitely for access.

BSON Integration collapse

CBOR Integration collapse

ActiveSupport Integration collapse

Methods included from Internal::Copyable

#duplicable?

JSON Integration collapse

Instance Method Summary collapse

Methods inherited from Collection

[], #count, #empty?, #join, #length, #to_s

Instance Method Details

#&(other) ⇒ Vector

Intersect with another sequence.

Parameters:

  • other (Vector, #to_ary) —

    The other sequence.

Returns:

  • (Vector) —

    The resulting entries.



463
 
# File 'lib/farce/abstract/vector.rb', line 463

def &(other) = derive_array_operation(:&, other)

#*(other) ⇒ Vector, String

Repeat a snapshot, or join it when a String separator is supplied.

Parameters:

  • other (Integer, #to_str) —

    The non-negative repetition count or String separator.

Returns:

  • (Vector, String) —

    The repeated entries, or the joined String for a separator.



449
450
451
452
453
 
# File 'lib/farce/abstract/vector.rb', line 449

def *(other)
  separator = String.try_convert(other)
  return join(separator) if separator
  build_derived_vector(internal_vector.snapshot * other)
end

#+(other) ⇒ Vector

Concatenate a snapshot with another sequence.

Parameters:

  • other (Vector, #to_ary) —

    The other sequence.

Returns:

  • (Vector) —

    The resulting entries.



436
437
438
439
440
441
442
443
444
 
# File 'lib/farce/abstract/vector.rb', line 436

def +(other)
  snapshot = internal_vector.snapshot
  appended = if other.equal?(self)
               snapshot
             else
               reusable_operand_snapshot(other) || vector_operand(other).map { derived_storage(it) }
             end
  build_derived_vector(snapshot + appended)
end

#-(other) ⇒ Vector

Remove values present in another sequence.

Parameters:

  • other (Vector, #to_ary) —

    The other sequence.

Returns:

  • (Vector) —

    The resulting entries.



458
 
# File 'lib/farce/abstract/vector.rb', line 458

def -(other) = derive_array_operation(:-, other)

#<<(value) ⇒ self

Append a single value without a timeout.

Parameters:

  • value (BasicObject) —

    The value to append.

Returns:

  • (self) 


863
 
# File 'lib/farce/abstract/vector.rb', line 863

def <<(value) = push(value)

#[](index) ⇒ BasicObject?

Read an index without waiting for atomic-update access.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

Returns:

  • (BasicObject, nil) —

    The value, or nil for an index outside the vector.



809
 
# File 'lib/farce/abstract/vector.rb', line 809

def [](index) = internal_vector[index]

#[]=(index, value) ⇒ BasicObject

Store a value, growing the vector if necessary.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • value (BasicObject) —

    The value to store.

Returns:

  • (BasicObject) —

    The assigned value.



815
816
817
 
# File 'lib/farce/abstract/vector.rb', line 815

def []=(index, value)
  internal_vector[index] = value
end

#append(value, timeout: nil) ⇒ self, false

Append one value using the same options as #push.

Returns Self on success, or false on timeout.

Parameters:

  • value (BasicObject) —

    The value to append.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (self, false) —

    Self on success, or false on timeout.



870
 
# File 'lib/farce/abstract/vector.rb', line 870

def append(...) = push(...)

#as_extended_json(**options) ⇒ Array

Note:

This method is only available if BSON has been loaded.

Represent a snapshot as Extended JSON, forwarding BSON's format options.

Parameters:

  • options (Hash) —

    Options forwarded to Array#as_extended_json.

Returns:

  • (Array) —

    The Extended JSON representation.



33
 
# File 'lib/farce/integrations/bson.rb', line 33

def as_extended_json(**) = to_a.as_extended_json(**)

#as_json(options = nil) ⇒ Array

Note:

This methods is only available if ActiveSupport has been loaded.

Convert a snapshot to ActiveSupport's explicit JSON representation.

Parameters:

  • options (Hash, nil) (defaults to: nil) —

    Options passed to each entry's JSON conversion.

Returns:

  • (Array) —

    The JSON-compatible values.



175
 
# File 'lib/farce/integrations/active_support/vector.rb', line 175

def as_json(options = nil) = to_a.as_json(options)

#assoc(key) ⇒ Array, ...

Find the first pair whose first value equals key.

Parameters:

  • key (BasicObject) —

    The value to compare with each pair's first entry.

Returns:

  • (Array, Vector, nil) —

    The first matching pair, or nil if none matches.



85
 
# File 'lib/farce/abstract/vector.rb', line 85

def assoc(key) = find_pair(key, 0)

#at(index) ⇒ BasicObject?

Read an index without waiting for atomic-update access.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

Returns:

  • (BasicObject, nil) —

    The value, or nil for an index outside the vector.



93
 
# File 'lib/farce/abstract/vector.rb', line 93

def at(index) = self[index]

#bsearch {|value| ... } ⇒ BasicObject, ...

Binary-search the live entries and return the matching value. The entries must remain sorted. Concurrent writes can change the result.

Yields:

  • (value) —

    Test an entry in an already sorted vector. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The entry being tested.

Yield Returns:

  • (Boolean, Numeric, nil) —

    A monotonic predicate or comparison result, following Array's binary-search contract.

Returns:

  • (BasicObject, nil, Enumerator) —

    The matching entry, nil if absent, or an Enumerator.



497
498
499
500
501
502
503
504
505
506
507
508
 
# File 'lib/farce/abstract/vector.rb', line 497

def bsearch
  return enum_for(__method__) { size } unless block_given?

  candidate = nil
  index = (0...size).bsearch do |position|
    value = self[position]
    result = yield(value)
    candidate = value if result.equal?(true) || (result.is_a?(Numeric) && result.zero?)
    result
  end
  candidate if index
end

#bsearch_index {|value| ... } ⇒ Integer, ...

Binary-search the live entries and return the matching index. The entries must remain sorted. Concurrent writes can change the result.

Yields:

  • (value) —

    Test an entry in an already sorted vector. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The entry being tested.

Yield Returns:

  • (Boolean, Numeric, nil) —

    A monotonic predicate or comparison result, following Array's binary-search contract.

Returns:

  • (Integer, nil, Enumerator) —

    The matching index, nil if absent, or an Enumerator.



517
518
519
520
521
 
# File 'lib/farce/abstract/vector.rb', line 517

def bsearch_index
  return enum_for(__method__) { size } unless block_given?

  (0...size).bsearch { yield self[it] }
end

#bson_type ⇒ String

Note:

This method is only available if BSON has been loaded.

Identify this value as a BSON array when embedded in a document or array.

Returns:

  • (String) —

    The BSON array type byte.



21
 
# File 'lib/farce/integrations/bson.rb', line 21

def bson_type = ::BSON::Array::BSON_TYPE

#chunk {|value| ... } ⇒ Enumerator

Group adjacent entries by a block-generated key. Group contents are Vectors.

Yields:

  • (value) —

    Compute a grouping key for each entry.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The grouping key. Nil and :_separator omit the entry. :_alone isolates it.

Returns:

  • (Enumerator) —

    Yields keys and Vector groups. Without a block, enumerates the grouping operation.



716
717
718
719
720
721
722
723
724
725
 
# File 'lib/farce/abstract/vector.rb', line 716

def chunk(&block)
  return enum_for(__method__) { size } unless block

  Enumerator.new do |yielder|
    snapshot = internal_vector.snapshot
    snapshot.chunk { block.call(logical_value(it)) }.each do |key, group|
      yielder.yield(key, build_derived_vector(group))
    end
  end
end

#chunk_while {|left, right| ... } ⇒ Enumerator

Group adjacent entries while the block accepts each pair.

Yields:

  • (left, right) —

    Test consecutive entries. A block is required.

Yield Parameters:

  • left (BasicObject) —

    The preceding entry.

  • right (BasicObject) —

    The current entry.

Yield Returns:

  • (BasicObject) —

    A truthy value to keep the entries in one group.

Returns:

  • (Enumerator) —

    Yields same-kind Vector groups.

Raises:

  • (ArgumentError) 


733
734
735
736
737
738
739
740
741
 
# File 'lib/farce/abstract/vector.rb', line 733

def chunk_while(&block)
  raise ArgumentError, "no block given" unless block

  Enumerator.new do |yielder|
    snapshot = internal_vector.snapshot
    snapshot.chunk_while { |left, right| block.call(logical_value(left), logical_value(right)) }
      .each { yielder << build_derived_vector(it) }
  end
end

#clear ⇒ self

Remove all slots.

Returns:

  • (self) 


1002
1003
1004
1005
 
# File 'lib/farce/abstract/vector.rb', line 1002

def clear
  internal_vector.clear
  self
end

#compact ⇒ Vector

Remove nil values.

Returns:

  • (Vector) —

    A new same-kind Vector containing the result.



335
 
# File 'lib/farce/abstract/vector.rb', line 335

def compact = build_derived_vector(internal_vector.each.compact)

#compact_blank ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Returns Entries for which blank? is false, excluding nil and false.

Returns:

  • (Vector) —

    Entries for which blank? is false, excluding nil and false.



76
 
# File 'lib/farce/integrations/active_support/vector.rb', line 76

def compact_blank = reject(&:blank?)

#compare_and_set(index, expected, replacement, timeout: nil) ⇒ Boolean

Replace an existing index only if its value matches the expected value. This never grows the vector. Matching uses the configured comparison mode.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • expected (BasicObject) —

    The value that must match the current entry.

  • replacement (BasicObject) —

    The value to store on a match.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (Boolean) —

    Whether the replacement succeeded. False on timeout.



900
901
902
 
# File 'lib/farce/abstract/vector.rb', line 900

def compare_and_set(index, expected, replacement, timeout: nil)
  internal_vector.compare_and_set(index, expected, replacement, timeout:)
end

#compare_by_identity? ⇒ Boolean

Returns Whether values are compared by identity.

Returns:

  • (Boolean) —

    Whether values are compared by identity.



995
 
# File 'lib/farce/abstract/vector.rb', line 995

def compare_by_identity? = internal_vector.compare_by_identity?

#concat(*sources) ⇒ self

Append snapshots of one or more sequences and return this vector. Each append is synchronized separately. Other writers may interleave. Values use the vector's default transfer mode. Self-concatenation reuses existing storage and captures the original contents only once.

Parameters:

  • sources (Array<Vector, #to_ary>) —

    sequences to append

Returns:

  • (self) 


846
847
848
849
850
851
852
853
854
855
856
857
858
 
# File 'lib/farce/abstract/vector.rb', line 846

def concat(*sources)
  Internal::Freeze.check(self)
  own_snapshot = internal_vector.snapshot if sources.any? { it.equal?(self) }
  snapshots = sources.map do |source|
    if source.equal?(self)
      own_snapshot
    else
      reusable_operand_snapshot(source) || vector_operand(source).map { derived_storage(it) }
    end
  end
  snapshots.each { |values| values.each { internal_vector.push(it) } }
  self
end

#deconstruct ⇒ Array<BasicObject>

Return a new Array containing a logical snapshot of the values.

Returns:

  • (Array<BasicObject>) —

    A new Array of logical values.



61
 
# File 'lib/farce/abstract/vector.rb', line 61

def deconstruct = to_a

#deep_dup ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Copy entries using ActiveSupport's deep-copy rules and the Vector's storage rules. Strict Vectors reject deep copies that are not shareable.

Returns:

  • (Vector) —

    An independent same-kind Vector with deeply copied entries.



72
 
# File 'lib/farce/integrations/active_support/vector.rb', line 72

def deep_dup = map(&:deep_dup)

#difference(*others) ⇒ Vector

Remove values present in any supplied sequence.

Parameters:

  • others (Array<Vector, #to_ary>) —

    The other sequences.

Returns:

  • (Vector) —

    The resulting entries.



473
 
# File 'lib/farce/abstract/vector.rb', line 473

def difference(*others) = derive_array_operation(:difference, *others)

#dig(index, *identifiers) ⇒ BasicObject?

Recursively retrieve a nested value.

Parameters:

  • index (Integer) —

    The initial index. Negative indexes count from the end.

  • identifiers (Array<BasicObject>) —

    Indexes or keys passed to the nested value's dig method.

Returns:

  • (BasicObject, nil) —

    The nested value, or nil if an intermediate value is nil.

Raises:

  • (TypeError) 


74
75
76
77
78
79
80
 
# File 'lib/farce/abstract/vector.rb', line 74

def dig(index, *identifiers)
  value = at(index)
  return value if identifiers.empty?
  return if value.nil?
  raise TypeError, "#{value.class} does not have #dig method" unless value.respond_to?(:dig)
  value.dig(*identifiers)
end

#drop(count) ⇒ Vector

Return all entries after count entries.

Parameters:

  • count (Integer) —

    The non-negative number of entries to drop.

Returns:

  • (Vector) —

    The resulting entries.



396
 
# File 'lib/farce/abstract/vector.rb', line 396

def drop(count) = build_derived_vector(internal_vector.each.drop(count))

#drop_while {|value| ... } ⇒ Vector, Enumerator

Drop entries before the first rejected value.

Yields:

  • (value) —

    Test each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    A truthy value to continue dropping entries.

Returns:



413
414
415
416
 
# File 'lib/farce/abstract/vector.rb', line 413

def drop_while
  return enum_for(__method__) { size } unless block_given?
  build_derived_vector(internal_vector.each.drop_while { yield logical_value(it) })
end

#each {|value| ... } ⇒ self, Enumerator

Iterate over live entries, up to the length when enumeration starts. Changes can affect entries not yet visited. Indexes beyond the starting length are not visited. Each entry is read separately. The block runs without holding a collection lock.

Yields:

  • (value) —

    Called for each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (self, Enumerator) 


24
25
26
27
28
29
 
# File 'lib/farce/abstract/vector.rb', line 24

def each
  return enum_for(__method__) { size } unless block_given?

  internal_vector.each { yield logical_value(it) }
  self
end

#each_cons(count) {|window| ... } ⇒ self, Enumerator

Yield same-kind overlapping windows from live iteration.

Parameters:

  • count (Integer) —

    The positive window size.

Yields:

  • (window) —

    Visit each window. Returns an Enumerator without a block.

Yield Parameters:

  • window (Vector) —

    The current window.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (self, Enumerator)

Raises:

  • (ArgumentError) 


702
703
704
705
706
707
708
709
 
# File 'lib/farce/abstract/vector.rb', line 702

def each_cons(count)
  count = convert_vector_count(count)
  raise ArgumentError, "invalid size" unless count.positive?
  return enum_for(__method__, count) { [size - count + 1, 0].max } unless block_given?

  internal_vector.each.each_cons(count) { yield build_derived_vector(it) }
  self
end

#each_index {|index| ... } ⇒ self, Enumerator

Iterate over indexes up to the length when enumeration starts.

Yields:

  • (index) —

    Called for each index. Returns an Enumerator without a block.

Yield Parameters:

  • index (Integer) —

    The current index.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (self, Enumerator) 


36
37
38
39
40
41
 
# File 'lib/farce/abstract/vector.rb', line 36

def each_index(&)
  return enum_for(__method__) { size } unless block_given?

  size.times(&)
  self
end

#each_slice(count) {|window| ... } ⇒ self, Enumerator

Yield same-kind windows from live iteration.

Parameters:

  • count (Integer) —

    The positive window size.

Yields:

  • (window) —

    Visit each window. Returns an Enumerator without a block.

Yield Parameters:

  • window (Vector) —

    The current window.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (self, Enumerator)

Raises:

  • (ArgumentError) 


687
688
689
690
691
692
693
694
 
# File 'lib/farce/abstract/vector.rb', line 687

def each_slice(count)
  count = convert_vector_count(count)
  raise ArgumentError, "invalid slice size" unless count.positive?
  return enum_for(__method__, count) { (size + count - 1) / count } unless block_given?

  internal_vector.each.each_slice(count) { yield build_derived_vector(it) }
  self
end

#entries ⇒ Vector

Materialize enumeration as a Vector rather than an Array.

Returns:

  • (Vector) —

    A new same-kind Vector containing the result.



804
 
# File 'lib/farce/abstract/vector.rb', line 804

def entries = build_derived_vector(internal_vector.snapshot)

#excluding(*elements) ⇒ Vector Also known as: without

Note:

This methods is only available if ActiveSupport has been loaded.

Exclude entries using Array's hash-based difference semantics.

Parameters:

  • elements (Array<BasicObject>) —

    Entries to exclude, with Arrays flattened by one level.

Returns:

  • (Vector) —

    The remaining entries.



37
 
# File 'lib/farce/integrations/active_support/vector.rb', line 37

def excluding(*elements) = self - elements.flatten(1)

#fetch(index, *fallback) {|index| ... } ⇒ BasicObject

Fetch a value by index, with Array-compatible fallback behavior.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • fallback (Array<BasicObject>) —

    At most one default value for a missing index.

Yields:

  • (index) —

    Called for a missing index. Takes precedence over the default value.

Yield Parameters:

  • index (BasicObject) —

    The original index argument, before integer conversion.

Yield Returns:

  • (BasicObject) —

    The fallback value.

Returns:

  • (BasicObject) —

    The entry, default value, or block result.

Raises:

  • (IndexError) —

    If the index is absent and neither a default nor a block is supplied.



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/farce/abstract/vector.rb', line 103

def fetch(index, *fallback)
  original_index = index
  index          = convert_vector_index(index)

  if fallback.length > 1
    raise ArgumentError, "wrong number of arguments (given #{fallback.length + 1}, expected 1..2)"
  end

  warn("block supersedes default value argument") if !fallback.empty? && block_given?

  return logical_value(internal_vector.fetch(index)) if fallback.empty? && !block_given?

  stored = internal_vector.fetch(index) do
    return yield(original_index) if block_given?
    return fallback.first
  end

  logical_value(stored)
end

#fetch_values(*indexes) {|index| ... } ⇒ Vector

Fetch several values. Missing indexes are passed to the block.

Parameters:

  • indexes (Array<Integer>) —

    The indexes to fetch.

Yields:

  • (index) —

    Called for each missing index when a block is supplied.

Yield Parameters:

  • index (BasicObject) —

    The original missing index argument.

Yield Returns:

  • (BasicObject) —

    The fallback value.

Returns:

  • (Vector) —

    The requested entries and fallback values.

Raises:

  • (IndexError) —

    If an index is absent and no block is supplied.



130
131
132
133
134
135
136
137
 
# File 'lib/farce/abstract/vector.rb', line 130

def fetch_values(*indexes)
  values = if block_given?
             indexes.map { |index| internal_vector.fetch(index) { derived_storage(yield(index)) } }
           else
             indexes.map { internal_vector.fetch(it) }
           end
  build_derived_vector(values)
end

#fifth ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The fifth entry, or nil if absent.

Returns:

  • (BasicObject, nil) —

    The fifth entry, or nil if absent.



54
 
# File 'lib/farce/integrations/active_support/vector.rb', line 54

def fifth = self[4]

#filter_map {|value| ... } ⇒ Vector, Enumerator

Transform accepted values into a Vector.

Yields:

  • (value) —

    Transform each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The replacement value. Nil and false results are omitted.

Returns:



294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/farce/abstract/vector.rb', line 294

def filter_map
  return enum_for(__method__) { size } unless block_given?

  snapshot = internal_vector.snapshot
  logical  = []
  values   = []

  snapshot.each do |stored|
    value = logical_value(stored)
    logical << value
    mapped = yield(value)
    values << mapped if mapped
  end

  build_derived_from_logical(values, snapshot, logical)
end

#first(count = UNDEFINED) ⇒ BasicObject, ...

Return one value, or a Vector when a count is supplied.

Parameters:

  • count (Integer) (defaults to: UNDEFINED) —

    The maximum number of entries. Omit to return one entry.

Returns:

  • (BasicObject, Vector, nil) —

    The first entry, nil if empty, or a Vector when count is supplied.



148
149
150
151
152
153
 
# File 'lib/farce/abstract/vector.rb', line 148

def first(count = UNDEFINED)
  return self[0] if count.equal?(UNDEFINED)

  snapshot = internal_vector.snapshot
  build_derived_vector(snapshot.first(count))
end

#flat_map {|value| ... } ⇒ Vector, Enumerator Also known as: collect_concat

Transform and flatten one Array or Vector level.

Yields:

  • (value) —

    Transform each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    An Array or Vector to expand by one level, or a single value to retain.

Returns:



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/farce/abstract/vector.rb', line 316

def flat_map
  return enum_for(__method__) { size } unless block_given?

  snapshot = internal_vector.snapshot
  logical  = []
  values   = []
  snapshot.each do |stored|
    value = logical_value(stored)
    logical << value
    mapped = yield(value)
    converted = mapped.is_a?(Vector) ? mapped.to_a : Array.try_convert(mapped)
    values.concat(converted || [mapped])
  end
  build_derived_from_logical(values, snapshot, logical)
end

#forty_two ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The forty-second entry, or nil if absent.

Returns:

  • (BasicObject, nil) —

    The forty-second entry, or nil if absent.



58
 
# File 'lib/farce/integrations/active_support/vector.rb', line 58

def forty_two = self[41]

#fourth ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The fourth entry, or nil if absent.

Returns:

  • (BasicObject, nil) —

    The fourth entry, or nil if absent.



50
 
# File 'lib/farce/integrations/active_support/vector.rb', line 50

def fourth = self[3]

#from(position) ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Return entries starting at position from one snapshot.

Parameters:

  • position (Integer) —

    The starting index. Negative indexes count from the end.

Returns:

  • (Vector) —

    The tail, or an empty Vector for an out-of-range position.



15
16
17
18
 
# File 'lib/farce/integrations/active_support/vector.rb', line 15

def from(position)
  snapshot = internal_vector.snapshot
  build_derived_vector(snapshot.from(position))
end

#get(index, timeout: nil) ⇒ BasicObject?

Read an index after acquiring atomic-update access.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (BasicObject, nil) —

    The value, or nil if absent or timed out.



823
 
# File 'lib/farce/abstract/vector.rb', line 823

def get(index, timeout: nil) = internal_vector.get(index, timeout:)

#grep(pattern) {|value| ... } ⇒ Vector

Select values matched by pattern, optionally transforming them.

Parameters:

  • pattern (#===) —

    The pattern used to test each entry.

Yields:

  • (value) —

    Optionally transform each selected entry.

Yield Parameters:

  • value (BasicObject) —

    The selected entry.

Yield Returns:

  • (BasicObject) —

    The replacement value.

Returns:

  • (Vector) —

    The selected entries or their block results.



536
537
538
539
540
541
 
# File 'lib/farce/abstract/vector.rb', line 536

def grep(pattern, &)
  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  result   = block_given? ? logical.grep(pattern, &) : logical.grep(pattern)
  build_derived_from_logical(result, snapshot, logical)
end

#grep_v(pattern) {|value| ... } ⇒ Vector

Select values not matched by pattern, optionally transforming them.

Parameters:

  • pattern (#===) —

    The pattern used to test each entry.

Yields:

  • (value) —

    Optionally transform each selected entry.

Yield Parameters:

  • value (BasicObject) —

    The selected entry.

Yield Returns:

  • (BasicObject) —

    The replacement value.

Returns:

  • (Vector) —

    The selected entries or their block results.



549
550
551
552
553
554
 
# File 'lib/farce/abstract/vector.rb', line 549

def grep_v(pattern, &)
  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  result   = block_given? ? logical.grep_v(pattern, &) : logical.grep_v(pattern)
  build_derived_from_logical(result, snapshot, logical)
end

#group_by {|value| ... } ⇒ Hash{BasicObject => Vector}, Enumerator

Group live entries into same-kind Vectors.

Yields:

  • (value) —

    Compute a grouping key. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The key for the entry's group.

Returns:

  • (Hash{BasicObject => Vector}, Enumerator) —

    Keys mapped to same-kind Vector groups, or an Enumerator.



573
574
575
576
577
578
 
# File 'lib/farce/abstract/vector.rb', line 573

def group_by
  return enum_for(__method__) { size } unless block_given?

  internal_vector.each.group_by { yield logical_value(it) }
    .transform_values { build_derived_vector(it) }
end

#in_groups(number, fill_with = nil) {|group| ... } ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Divide a snapshot into a requested number of Vector groups.

Parameters:

  • number (Integer) —

    The number of groups, following ActiveSupport's validation rules.

  • fill_with (BasicObject) (defaults to: nil) —

    The padding value. False disables padding.

Yields:

  • (group) —

    Optionally visit each group after grouping the snapshot.

Yield Parameters:

  • group (Vector) —

    A same-kind Vector containing one group.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (Vector) —

    A Vector of groups, whether or not a block is supplied.



133
134
135
136
137
138
 
# File 'lib/farce/integrations/active_support/vector.rb', line 133

def in_groups(number, fill_with = nil)
  groups = active_support_groups(:in_groups, number, fill_with)
  result = build_derived_values(groups.map { build_derived_vector(it) })
  result.each { yield it } if block_given?
  result
end

#in_groups_of(number, fill_with = nil) {|group| ... } ⇒ Vector, self

Note:

This methods is only available if ActiveSupport has been loaded.

Divide a snapshot into Vector groups with a maximum size.

Parameters:

  • number (Integer) —

    The positive group size.

  • fill_with (BasicObject) (defaults to: nil) —

    The padding value. False disables padding.

Yields:

  • (group) —

    Optionally visit each group in the snapshot.

Yield Parameters:

  • group (Vector) —

    A same-kind Vector containing one group.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (Vector, self) —

    Groups without a block. With a block, the padded snapshot or self if padding is disabled.



148
149
150
151
152
153
154
 
# File 'lib/farce/integrations/active_support/vector.rb', line 148

def in_groups_of(number, fill_with = nil)
  padding = fill_with != false
  groups = active_support_groups(:in_groups_of, number, fill_with)
  return build_derived_values(groups.map { build_derived_vector(it) }) unless block_given?
  groups.each { yield build_derived_vector(it) }
  padding ? build_derived_vector(groups.flatten(1)) : self
end

#in_order_of(key, series, filter: true) ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Order a snapshot by the keys in series, preserving retained entries.

Parameters:

  • key (Symbol, #to_proc) —

    The method or callable used to extract ordering keys.

  • series (Array) —

    The desired order of keys.

  • filter (Boolean) (defaults to: true) —

    Whether to omit entries whose keys are absent from series.

Returns:

  • (Vector) —

    The ordered entries. Repeated keys repeat their groups when filtering.



106
107
108
109
110
111
 
# File 'lib/farce/integrations/active_support/vector.rb', line 106

def in_order_of(key, series, filter: true)
  snapshot = internal_vector.snapshot
  logical = snapshot.map { logical_value(it) }
  result = logical.in_order_of(key, series, filter:)
  build_derived_from_logical(result, snapshot, logical)
end

#include?(value) ⇒ Boolean Also known as: member?

Return whether a live entry equals value.

Parameters:

  • value (BasicObject) —

    The value to find using ==.

Returns:

  • (Boolean) —

    Whether a matching entry exists.



186
187
188
189
 
# File 'lib/farce/abstract/vector.rb', line 186

def include?(value)
  each { return true if array_value_equal?(it, value) }
  false
end

#including(*elements) ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Append entries to a new Vector, flattening argument Arrays by one level. New entries follow the receiver's storage rules and transfer mode.

Parameters:

  • elements (Array<BasicObject>) —

    The entries or Arrays of entries to append.

Returns:

  • (Vector) —

    The combined entries.



31
 
# File 'lib/farce/integrations/active_support/vector.rb', line 31

def including(*elements) = self + elements.flatten(1)

#index(value = UNDEFINED) {|entry| ... } ⇒ Integer, ... Also known as: find_index

Return the first matching index.

Parameters:

  • value (BasicObject) (defaults to: UNDEFINED) —

    The value to find. Omit to use the block.

Yields:

  • (entry) —

    Test each entry when value is omitted.

Yield Parameters:

  • entry (BasicObject) —

    The current entry.

Yield Returns:

  • (BasicObject) —

    A truthy value for a match.

Returns:

  • (Integer, nil, Enumerator) —

    The matching index, nil if absent, or an Enumerator without a value or block.



198
199
200
201
202
203
204
205
206
 
# File 'lib/farce/abstract/vector.rb', line 198

def index(value = UNDEFINED)
  return enum_for(__method__) { size } if value.equal?(UNDEFINED) && !block_given? # rubocop:disable Lint/ToEnumArguments

  warn("given block not used") if !value.equal?(UNDEFINED) && block_given?
  each_with_index do |entry, index|
    return index if value.equal?(UNDEFINED) ? yield(entry) : array_value_equal?(entry, value)
  end
  nil
end

#inquiry ⇒ ActiveSupport::ArrayInquirer

Note:

This methods is only available if ActiveSupport has been loaded.

Create ActiveSupport's specialized query wrapper from a logical snapshot.

Returns:

  • (ActiveSupport::ArrayInquirer) —

    An Array wrapper supporting predicate methods.



212
 
# File 'lib/farce/integrations/active_support/vector.rb', line 212

def inquiry = to_a.inquiry

#intersect?(other) ⇒ Boolean

Return whether another sequence shares any value.

Parameters:

  • other (Vector, #to_ary) —

    The other sequence.

Returns:

  • (Boolean) —

    Whether the sequences have an entry in common.



488
 
# File 'lib/farce/abstract/vector.rb', line 488

def intersect?(other) = to_a.intersect?(vector_operand(other))

#intersection(*others) ⇒ Vector

Intersect with every supplied sequence.

Parameters:

  • others (Array<Vector, #to_ary>) —

    The other sequences.

Returns:

  • (Vector) —

    The resulting entries.



478
 
# File 'lib/farce/abstract/vector.rb', line 478

def intersection(*others) = derive_array_operation(:intersection, *others)

#last(count = UNDEFINED) ⇒ BasicObject, ...

Return one value, or a Vector when a count is supplied.

Parameters:

  • count (Integer) (defaults to: UNDEFINED) —

    The maximum number of entries. Omit to return one entry.

Returns:

  • (BasicObject, Vector, nil) —

    The last entry, nil if empty, or a Vector when count is supplied.



158
159
160
161
162
163
 
# File 'lib/farce/abstract/vector.rb', line 158

def last(count = UNDEFINED)
  return self[-1] if count.equal?(UNDEFINED)

  snapshot = internal_vector.snapshot
  build_derived_vector(snapshot.last(count))
end

#map {|value| ... } ⇒ Vector, Enumerator Also known as: collect

Transform a snapshot into a Vector.

Yields:

  • (value) —

    Transform each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The replacement value.

Returns:



251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/farce/abstract/vector.rb', line 251

def map
  return enum_for(__method__) { size } unless block_given?

  snapshot = internal_vector.snapshot
  logical  = []
  mapped   = snapshot.map do |stored|
    value  = logical_value(stored)
    logical << value
    yield value
  end
  build_derived_from_logical(mapped, snapshot, logical)
end

#max(count = UNDEFINED) {|left, right| ... } ⇒ BasicObject, ...

Return one maximum, or a Vector when count is supplied.

Parameters:

  • count (Integer, nil) (defaults to: UNDEFINED) —

    The maximum result size. Omit or pass nil to return one entry.

Yields:

  • (left, right) —

    Optionally compare two entries. Without a block, uses <=>.

Yield Parameters:

  • left (BasicObject) —

    The left entry.

  • right (BasicObject) —

    The right entry.

Yield Returns:

  • (Numeric) —

    A negative number, zero, or a positive number for less than, equal to, or greater than.

Returns:

  • (BasicObject, Vector, nil) —

    One extreme entry, nil if empty, or a Vector when count is supplied.



616
617
618
619
620
621
622
623
624
 
# File 'lib/farce/abstract/vector.rb', line 616

def max(count = UNDEFINED, &)
  count = normalized_extreme_count(count)
  return super(&) if count.nil?
  return build_derived_vector([]) if count.zero?

  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  build_derived_from_logical(logical.max(count, &), snapshot, logical)
end

#max_by(count = UNDEFINED) {|value| ... } ⇒ BasicObject, ...

Return one block maximum, or a Vector when count is supplied.

Parameters:

  • count (Integer, nil) (defaults to: UNDEFINED) —

    The maximum result size. Omit or pass nil to return one entry.

Yields:

  • (value) —

    Compute a comparison key. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The key used to order the entry.

Returns:

  • (BasicObject, Vector, nil, Enumerator) —

    One extreme entry, nil if empty, a Vector for count, or an Enumerator.



654
655
656
657
658
659
660
661
662
663
664
665
666
 
# File 'lib/farce/abstract/vector.rb', line 654

def max_by(count = UNDEFINED)
  count = normalized_extreme_count(count)
  unless block_given?
    return enum_for(__method__) { size } if count.nil? # rubocop:disable Lint/ToEnumArguments
    return enum_for(__method__, count) { size }
  end
  return super() { yield it } if count.nil?
  return build_derived_vector([]) if count.zero?

  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  build_derived_from_logical(logical.max_by(count) { yield it }, snapshot, logical)
end

#maximum(key) ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Find the maximum extracted value without storing intermediate results in a Vector.

Parameters:

  • key (Symbol, #to_proc) —

    The method or callable used to extract comparison values.

Returns:

  • (BasicObject, nil) —

    The maximum, or nil if empty.



123
 
# File 'lib/farce/integrations/active_support/vector.rb', line 123

def maximum(key) = to_a.maximum(key)

#min(count = UNDEFINED) {|left, right| ... } ⇒ BasicObject, ...

Return one minimum, or a Vector when count is supplied.

Parameters:

  • count (Integer, nil) (defaults to: UNDEFINED) —

    The maximum result size. Omit or pass nil to return one entry.

Yields:

  • (left, right) —

    Optionally compare two entries. Without a block, uses <=>.

Yield Parameters:

  • left (BasicObject) —

    The left entry.

  • right (BasicObject) —

    The right entry.

Yield Returns:

  • (Numeric) —

    A negative number, zero, or a positive number for less than, equal to, or greater than.

Returns:

  • (BasicObject, Vector, nil) —

    One extreme entry, nil if empty, or a Vector when count is supplied.



599
600
601
602
603
604
605
606
607
 
# File 'lib/farce/abstract/vector.rb', line 599

def min(count = UNDEFINED, &)
  count = normalized_extreme_count(count)
  return super(&) if count.nil?
  return build_derived_vector([]) if count.zero?

  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  build_derived_from_logical(logical.min(count, &), snapshot, logical)
end

#min_by(count = UNDEFINED) {|value| ... } ⇒ BasicObject, ...

Return one block minimum, or a Vector when count is supplied.

Parameters:

  • count (Integer, nil) (defaults to: UNDEFINED) —

    The maximum result size. Omit or pass nil to return one entry.

Yields:

  • (value) —

    Compute a comparison key. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The key used to order the entry.

Returns:

  • (BasicObject, Vector, nil, Enumerator) —

    One extreme entry, nil if empty, a Vector for count, or an Enumerator.



633
634
635
636
637
638
639
640
641
642
643
644
645
 
# File 'lib/farce/abstract/vector.rb', line 633

def min_by(count = UNDEFINED)
  count = normalized_extreme_count(count)
  unless block_given?
    return enum_for(__method__) { size } if count.nil? # rubocop:disable Lint/ToEnumArguments
    return enum_for(__method__, count) { size }
  end
  return super() { yield it } if count.nil?
  return build_derived_vector([]) if count.zero?

  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  build_derived_from_logical(logical.min_by(count) { yield it }, snapshot, logical)
end

#minimum(key) ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Find the minimum extracted value without storing intermediate results in a Vector.

Parameters:

  • key (Symbol, #to_proc) —

    The method or callable used to extract comparison values.

Returns:

  • (BasicObject, nil) —

    The minimum, or nil if empty.



117
 
# File 'lib/farce/integrations/active_support/vector.rb', line 117

def minimum(key) = to_a.minimum(key)

#minmax {|left, right| ... } ⇒ Vector

Return minimum and maximum in a Vector.

Yields:

  • (left, right) —

    Optionally compare two entries. Without a block, uses <=>.

Yield Parameters:

  • left (BasicObject) —

    The left entry.

  • right (BasicObject) —

    The right entry.

Yield Returns:

  • (Numeric) —

    A negative number, zero, or a positive number for less than, equal to, or greater than.

Returns:

  • (Vector) —

    The minimum and maximum, with two nil entries for an empty vector.



586
587
588
589
590
 
# File 'lib/farce/abstract/vector.rb', line 586

def minmax(&)
  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  build_derived_from_logical(logical.minmax(&), snapshot, logical)
end

#minmax_by {|value| ... } ⇒ Vector, Enumerator

Return the block minimum and maximum in a Vector.

Yields:

  • (value) —

    Compute a comparison key. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The key used to order the entry.

Returns:

  • (Vector, Enumerator) —

    The minimum and maximum entries, two nil entries if empty, or an Enumerator.



673
674
675
676
677
678
679
 
# File 'lib/farce/abstract/vector.rb', line 673

def minmax_by
  return enum_for(__method__) { size } unless block_given?

  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  build_derived_from_logical(logical.minmax_by { yield it }, snapshot, logical)
end

#pack(format, buffer: nil) ⇒ String

Pack a logical snapshot according to format.

Returns The packed bytes, using buffer when supplied.

Parameters:

  • format (String) —

    The Array packing directives.

  • buffer (String, nil) (defaults to: nil) —

    An optional String to append the packed bytes to.

Returns:

  • (String) —

    The packed bytes, using buffer when supplied.



528
 
# File 'lib/farce/abstract/vector.rb', line 528

def pack(format, **) = to_a.pack(format, **)

#partition {|value| ... } ⇒ Vector, Enumerator

Split live entries into accepted and rejected Vectors, wrapped in a Vector.

Yields:

  • (value) —

    Classify each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    A truthy value for the accepted group, or a falsy value for the rejected group.

Returns:

  • (Vector, Enumerator) —

    A Vector containing the accepted and rejected Vectors, or an Enumerator.



561
562
563
564
565
566
 
# File 'lib/farce/abstract/vector.rb', line 561

def partition
  return enum_for(__method__) { size } unless block_given?

  accepted, rejected = internal_vector.each.partition { yield logical_value(it) }
  build_derived_values([build_derived_vector(accepted), build_derived_vector(rejected)])
end

#pick(*keys) ⇒ BasicObject, ...

Note:

This methods is only available if ActiveSupport has been loaded.

Extract keys from the first entry in a snapshot.

Parameters:

  • keys (Array<BasicObject>) —

    Keys passed to the first entry's [] method.

Returns:

  • (BasicObject, Vector, nil) —

    One value, a Vector for multiple keys, or nil if empty.



92
93
94
95
96
97
98
 
# File 'lib/farce/integrations/active_support/vector.rb', line 92

def pick(*keys)
  snapshot = internal_vector.snapshot
  return if snapshot.empty?
  entry = logical_value(snapshot.first)
  return entry[keys.first] unless keys.length > 1
  build_derived_values(keys.map { |key| entry[key] })
end

#pluck(*keys) ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Extract keys from each entry in a snapshot. Extracted values follow the receiver's storage rules and transfer mode.

Parameters:

  • keys (Array<BasicObject>) —

    Keys passed to each entry's [] method.

Returns:

  • (Vector) —

    Values for one key, or Vector rows for multiple keys.



83
84
85
86
 
# File 'lib/farce/integrations/active_support/vector.rb', line 83

def pluck(*keys)
  return map { |entry| entry[keys.first] } unless keys.length > 1
  map { |entry| build_derived_values(keys.map { |key| entry[key] }) }
end

#pop(timeout: nil) ⇒ BasicObject?

Remove and return the last value. This does not wait for an empty vector to become nonempty.

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (BasicObject, nil) —

    The last value, or nil if empty or timed out.



876
 
# File 'lib/farce/abstract/vector.rb', line 876

def pop(timeout: nil) = internal_vector.pop(timeout:)

#push(value, timeout: nil) ⇒ self, false

Append a single value.

Parameters:

  • value (BasicObject) —

    The value to append.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (self, false) —

    Self on success, or false on timeout.



836
837
838
 
# File 'lib/farce/abstract/vector.rb', line 836

def push(value, timeout: nil)
  internal_vector.push(value, timeout:) ? self : false
end

#rassoc(value) ⇒ Array, ...

Find the first pair whose second value equals value.

Parameters:

  • value (BasicObject) —

    The value to compare with each pair's second entry.

Returns:

  • (Array, Vector, nil) —

    The first matching pair, or nil if none matches.



90
 
# File 'lib/farce/abstract/vector.rb', line 90

def rassoc(value) = find_pair(value, 1)

#reject {|value| ... } ⇒ Vector, Enumerator

Remove values accepted by a block.

Yields:

  • (value) —

    Test each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    A truthy value to exclude the entry.

Returns:



283
284
285
286
287
 
# File 'lib/farce/abstract/vector.rb', line 283

def reject
  return enum_for(__method__) { size } unless block_given?

  build_derived_vector(internal_vector.each.reject { yield logical_value(it) })
end

#reverse ⇒ Vector

Return a reversed snapshot.

Returns:

  • (Vector) —

    A new same-kind Vector containing the result.



355
 
# File 'lib/farce/abstract/vector.rb', line 355

def reverse = build_derived_vector(internal_vector.snapshot.reverse)

#reverse_each {|value| ... } ⇒ self, Enumerator

Iterate over live entries from the last index when enumeration starts. Replacements and removals can affect entries not yet visited. The block runs without a collection lock.

Yields:

  • (value) —

    Called for each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (self, Enumerator) 


49
50
51
52
53
54
 
# File 'lib/farce/abstract/vector.rb', line 49

def reverse_each
  return enum_for(__method__) { size } unless block_given?

  internal_vector.reverse_each { yield logical_value(it) }
  self
end

#rfind(if_none = nil) {|value| ... } ⇒ BasicObject, ...

Find a value by searching from the end.

Parameters:

  • if_none (#call, nil) (defaults to: nil) —

    Called without arguments if no entry matches.

Yields:

  • (value) —

    Test entries from last to first.

Yield Parameters:

  • value (BasicObject) —

    The current entry.

Yield Returns:

  • (BasicObject) —

    A truthy value for a match.

Returns:

  • (BasicObject, nil, Enumerator) —

    The matching entry, the fallback result, or an Enumerator without a block.



239
240
241
242
243
244
 
# File 'lib/farce/abstract/vector.rb', line 239

def rfind(if_none = nil)
  return enum_for(__method__, if_none) { size } unless block_given?

  reverse_each { return it if yield(it) }
  if_none&.call
end

#rindex(value = UNDEFINED) {|entry| ... } ⇒ Integer, ...

Return the last matching index.

Parameters:

  • value (BasicObject) (defaults to: UNDEFINED) —

    The value to find. Omit to use the block.

Yields:

  • (entry) —

    Test each entry when value is omitted.

Yield Parameters:

  • entry (BasicObject) —

    The current entry.

Yield Returns:

  • (BasicObject) —

    A truthy value for a match.

Returns:

  • (Integer, nil, Enumerator) —

    The matching index, nil if absent, or an Enumerator without a value or block.



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/farce/abstract/vector.rb', line 215

def rindex(value = UNDEFINED)
  return enum_for(__method__) { size } if value.equal?(UNDEFINED) && !block_given? # rubocop:disable Lint/ToEnumArguments

  warn("given block not used") if !value.equal?(UNDEFINED) && block_given?
  backend = internal_vector
  index = backend.size
  while index.positive?
    index -= 1
    found = true
    stored = backend.fetch(index) { found = false }
    next unless found
    entry = logical_value(stored)
    return index if value.equal?(UNDEFINED) ? yield(entry) : array_value_equal?(entry, value)
  end
  nil
end

#rotate(count = 1) ⇒ Vector

Return a rotated snapshot.

Parameters:

  • count (Integer) (defaults to: 1) —

    The rotation distance. Negative values rotate right.

Returns:

  • (Vector) —

    The rotated entries.



360
 
# File 'lib/farce/abstract/vector.rb', line 360

def rotate(count = 1) = build_derived_vector(internal_vector.snapshot.rotate(count))

#sample(count = UNDEFINED, random: Random) ⇒ BasicObject, ...

Return one sample, or a Vector when count is supplied.

Parameters:

  • count (Integer) (defaults to: UNDEFINED) —

    The maximum sample size. Omit to return one entry.

  • random (#rand) (defaults to: Random) —

    The random number generator.

Returns:

  • (BasicObject, Vector, nil) —

    One entry, nil if empty, or a Vector when count is supplied.



427
428
429
430
431
 
# File 'lib/farce/abstract/vector.rb', line 427

def sample(count = UNDEFINED, random: Random)
  snapshot = internal_vector.snapshot
  return logical_value(snapshot.sample(random:)) if count.equal?(UNDEFINED)
  build_derived_vector(snapshot.sample(count, random:))
end

#second ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The second entry, or nil if absent.

Returns:

  • (BasicObject, nil) —

    The second entry, or nil if absent.



42
 
# File 'lib/farce/integrations/active_support/vector.rb', line 42

def second = self[1]

#second_to_last ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The second entry from the end, or nil if absent.

Returns:

  • (BasicObject, nil) —

    The second entry from the end, or nil if absent.



66
 
# File 'lib/farce/integrations/active_support/vector.rb', line 66

def second_to_last = self[-2]

#select {|value| ... } ⇒ Vector, Enumerator Also known as: filter, find_all

Keep values accepted by a block.

Yields:

  • (value) —

    Test each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    A truthy value to retain the entry.

Returns:



270
271
272
273
274
 
# File 'lib/farce/abstract/vector.rb', line 270

def select
  return enum_for(__method__) { size } unless block_given?

  build_derived_vector(internal_vector.each.select { yield logical_value(it) })
end

#shareable_values? ⇒ Boolean

Returns Whether stored values must be Ractor-shareable.

Returns:

  • (Boolean) —

    Whether stored values must be Ractor-shareable.



998
 
# File 'lib/farce/abstract/vector.rb', line 998

def shareable_values? = false

#shuffle(random: Random) ⇒ Vector

Return a shuffled snapshot.

Parameters:

  • random (#rand) (defaults to: Random) —

    The random number generator.

Returns:

  • (Vector) —

    The shuffled entries.



421
 
# File 'lib/farce/abstract/vector.rb', line 421

def shuffle(random: Random) = build_derived_vector(internal_vector.snapshot.shuffle(random:))

#size ⇒ Integer

Returns The number of slots, including nil slots.

Returns:

  • (Integer) —

    The number of slots, including nil slots.



992
 
# File 'lib/farce/abstract/vector.rb', line 992

def size = internal_vector.size

#slice(index, length = UNDEFINED) ⇒ BasicObject, ...

Return an element or subsequence without changing the hot path for #[]. Range and start-length results are Vectors.

Parameters:

  • index (Integer, Range) —

    An index, range, or start index when length is supplied.

  • length (Integer) (defaults to: UNDEFINED) —

    The maximum length of a subsequence. Omit for a single index or range.

Returns:

  • (BasicObject, Vector, nil) —

    A single entry, a Vector subsequence, or nil for an invalid slice.



170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/farce/abstract/vector.rb', line 170

def slice(index, length = UNDEFINED)
  snapshot = internal_vector.snapshot

  if length.equal?(UNDEFINED)
    result = snapshot.slice(index)
    return logical_value(result) unless index.is_a?(Range)
  else
    result = snapshot.slice(index, length)
  end

  result && build_derived_vector(result)
end

#slice_after(*arguments) {|value| ... } ⇒ Enumerator

Group a snapshot after matching entries.

Parameters:

  • arguments (Array<BasicObject>) —

    One pattern for === matching, or no arguments when using a block.

Yields:

  • (value) —

    Test each entry when no pattern is supplied.

Yield Parameters:

  • value (BasicObject) —

    The current entry.

Yield Returns:

  • (BasicObject) —

    A truthy value to split at this entry.

Returns:

  • (Enumerator) —

    Yields same-kind Vector groups.



759
760
761
 
# File 'lib/farce/abstract/vector.rb', line 759

def slice_after(*arguments, &block)
  logical_grouping_enumerator(:slice_after, arguments, block)
end

#slice_before(*arguments) {|value| ... } ⇒ Enumerator

Group a snapshot before matching entries.

Parameters:

  • arguments (Array<BasicObject>) —

    One pattern for === matching, or no arguments when using a block.

Yields:

  • (value) —

    Test each entry when no pattern is supplied.

Yield Parameters:

  • value (BasicObject) —

    The current entry.

Yield Returns:

  • (BasicObject) —

    A truthy value to split at this entry.

Returns:

  • (Enumerator) —

    Yields same-kind Vector groups.



749
750
751
 
# File 'lib/farce/abstract/vector.rb', line 749

def slice_before(*arguments, &block)
  logical_grouping_enumerator(:slice_before, arguments, block)
end

#slice_when {|left, right| ... } ⇒ Enumerator

Group a snapshot between pairs accepted by the block.

Yields:

  • (left, right) —

    Test consecutive entries. A block is required.

Yield Parameters:

  • left (BasicObject) —

    The preceding entry.

  • right (BasicObject) —

    The current entry.

Yield Returns:

  • (BasicObject) —

    A truthy value to start a new group.

Returns:

  • (Enumerator) —

    Yields same-kind Vector groups.

Raises:

  • (ArgumentError) 


769
770
771
772
 
# File 'lib/farce/abstract/vector.rb', line 769

def slice_when(&block)
  raise ArgumentError, "no block given" unless block
  logical_grouping_enumerator(:slice_when, [], block)
end

#sort {|left, right| ... } ⇒ Vector

Return a sorted snapshot.

Yields:

  • (left, right) —

    Optionally compare two entries. Without a block, uses <=>.

Yield Parameters:

  • left (BasicObject) —

    The left entry.

  • right (BasicObject) —

    The right entry.

Yield Returns:

  • (Numeric) —

    A negative number, zero, or a positive number for less than, equal to, or greater than.

Returns:

  • (Vector) —

    The sorted entries.



368
369
370
371
372
373
 
# File 'lib/farce/abstract/vector.rb', line 368

def sort(&block)
  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  sorted   = block ? logical.sort(&block) : logical.sort
  build_derived_from_logical(sorted, snapshot, logical)
end

#sort_by {|value| ... } ⇒ Vector, Enumerator

Sort a snapshot by block results.

Yields:

  • (value) —

    Compute a sort key. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The key used to order the entry.

Returns:



380
381
382
383
384
385
386
 
# File 'lib/farce/abstract/vector.rb', line 380

def sort_by
  return enum_for(__method__) { size } unless block_given?

  snapshot = internal_vector.snapshot
  logical  = snapshot.map { logical_value(it) }
  build_derived_from_logical(logical.sort_by { yield it }, snapshot, logical)
end

#split(value = nil) {|entry| ... } ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Split a snapshot at matching entries, omitting the separators.

Parameters:

  • value (BasicObject) (defaults to: nil) —

    The separator compared with ==, ignored when a block is supplied.

Yields:

  • (entry) —

    Optionally identify separator entries.

Yield Parameters:

  • entry (BasicObject) —

    The current logical entry.

Yield Returns:

  • (BasicObject) —

    A truthy value to split at this entry.

Returns:

  • (Vector) —

    A Vector of Vector groups, including empty groups between adjacent separators.



163
164
165
166
167
168
169
 
# File 'lib/farce/integrations/active_support/vector.rb', line 163

def split(value = nil)
  groups = internal_vector.snapshot.split do |stored|
    entry = logical_value(stored)
    block_given? ? yield(entry) : array_value_equal?(entry, value)
  end
  build_derived_values(groups.map { build_derived_vector(it) })
end

#store(index, value, timeout: nil) ⇒ BasicObject, false

Store a value after acquiring atomic-update access.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • value (BasicObject) —

    The value to store.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (BasicObject, false) —

    The value, or false on timeout.



830
 
# File 'lib/farce/abstract/vector.rb', line 830

def store(index, value, timeout: nil) = internal_vector.store(index, value, timeout:)

#store_if_absent(index, timeout: nil) { ... } ⇒ BasicObject?

Compute and store a value only when the index is absent or contains nil.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Yields:

  • Called without arguments to compute a value when the slot is absent or nil.

Yield Returns:

  • (BasicObject) —

    The value to store.

Returns:

  • (BasicObject, nil) —

    The existing or computed value, or nil on timeout.



891
 
# File 'lib/farce/abstract/vector.rb', line 891

def store_if_absent(index, timeout: nil, &) = internal_vector.store_if_absent(index, timeout:, &)

#swap(index, replacement, timeout: nil) ⇒ BasicObject?

Replace an index and return its previous value, growing the vector if necessary.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • replacement (BasicObject) —

    The new value.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (BasicObject, nil) —

    The previous value, or nil if absent or timed out.



883
 
# File 'lib/farce/abstract/vector.rb', line 883

def swap(index, replacement, timeout: nil) = internal_vector.swap(index, replacement, timeout:)

#take(count) ⇒ Vector

Return the first count entries.

Parameters:

  • count (Integer) —

    The non-negative number of entries to take.

Returns:

  • (Vector) —

    The resulting entries.



391
 
# File 'lib/farce/abstract/vector.rb', line 391

def take(count) = build_derived_vector(internal_vector.each.take(count))

#take_while {|value| ... } ⇒ Vector, Enumerator

Return entries before the first rejected value.

Yields:

  • (value) —

    Test each entry. Returns an Enumerator without a block.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    A truthy value to continue retaining entries.

Returns:



403
404
405
406
 
# File 'lib/farce/abstract/vector.rb', line 403

def take_while
  return enum_for(__method__) { size } unless block_given?
  build_derived_vector(internal_vector.each.take_while { yield logical_value(it) })
end

#third ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The third entry, or nil if absent.

Returns:

  • (BasicObject, nil) —

    The third entry, or nil if absent.



46
 
# File 'lib/farce/integrations/active_support/vector.rb', line 46

def third = self[2]

#third_to_last ⇒ BasicObject?

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The third entry from the end, or nil if absent.

Returns:

  • (BasicObject, nil) —

    The third entry from the end, or nil if absent.



62
 
# File 'lib/farce/integrations/active_support/vector.rb', line 62

def third_to_last = self[-3]

#to(position) ⇒ Vector

Note:

This methods is only available if ActiveSupport has been loaded.

Return entries through position from one snapshot.

Parameters:

  • position (Integer) —

    The final index. Negative indexes count from the end.

Returns:

  • (Vector) —

    The prefix, or an empty Vector for an out-of-range negative position.



24
 
# File 'lib/farce/integrations/active_support/vector.rb', line 24

def to(position) = build_derived_vector(internal_vector.snapshot.to(position))

#to_a ⇒ Array<BasicObject>

Return a new Array containing a logical snapshot of the values.

Returns:

  • (Array<BasicObject>) —

    A new Array of logical values.



58
 
# File 'lib/farce/abstract/vector.rb', line 58

def to_a = internal_vector.snapshot.map! { logical_value(it) }

#to_bson(buffer = ::BSON::ByteBuffer.new) ⇒ BSON::ByteBuffer

Note:

This method is only available if BSON has been loaded.

Serialize a snapshot using BSON's array representation. Nested value wrappers are read before encoding their BSON types and payloads.

Parameters:

  • buffer (BSON::ByteBuffer) (defaults to: ::BSON::ByteBuffer.new) —

    An optional buffer to append to.

Returns:

  • (BSON::ByteBuffer) —

    The buffer containing the encoded array.



16
 
# File 'lib/farce/integrations/bson.rb', line 16

def to_bson(buffer = ::BSON::ByteBuffer.new) = to_bson_normalized_value.to_bson(buffer)

#to_bson_normalized_value ⇒ Array

Note:

This method is only available if BSON has been loaded.

Return a snapshot with nested values normalized by BSON.

Returns:

  • (Array) —

    The normalized array.



26
 
# File 'lib/farce/integrations/bson.rb', line 26

def to_bson_normalized_value = to_a.to_bson_normalized_value

#to_cbor(*arguments) ⇒ String, ...

Note:

This method is only available if CBOR has been loaded.

Note:

On CRuby, CBOR's native encoder must run in the main Ractor.

Serialize a snapshot as a CBOR array.

Examples:

CBOR.decode(Farce::Vector.new([1, false]).to_cbor) # => [1, false]

Parameters:

  • arguments (Array<Object>) —

    Arguments forwarded to Array#to_cbor.

Returns:

  • (String, ::CBOR::Packer, nil) —

    Encoded bytes, the supplied packer, or nil when writing to IO.



19
 
# File 'lib/farce/integrations/cbor.rb', line 19

def to_cbor(...) = to_a.to_cbor(...)

#to_fs(format = :default) ⇒ String Also known as: to_formatted_s

Note:

This methods is only available if ActiveSupport has been loaded.

Format a snapshot, optionally as a database ID list.

Parameters:

  • format (Symbol) (defaults to: :default) —

    Use :db for comma-separated IDs, or :default for Array formatting.

Returns:

  • (String) —

    The formatted snapshot.



196
 
# File 'lib/farce/integrations/active_support/vector.rb', line 196

def to_fs(format = :default) = to_a.to_fs(format)

#to_h {|value| ... } ⇒ Hash

Convert pair-like entries to a Hash. Vector entries are accepted as pairs.

Yields:

  • (value) —

    Optionally transform each entry into a key-value pair.

Yield Parameters:

  • value (BasicObject) —

    The current entry.

Yield Returns:

  • (Array, Vector) —

    A two-element key-value pair.

Returns:

  • (Hash) —

    The converted pairs. Without a block, entries must be pair-like.



68
 
# File 'lib/farce/abstract/vector.rb', line 68

def to_h = to_a.to_h { normalize_hash_pair(block_given? ? yield(it) : it) }

#to_json(*arguments) ⇒ String

Note:

This method is only available if a supported JSON library has been loaded.

Serialize a logical snapshot as a JSON Array.

Returns The generated JSON.

Parameters:

  • arguments (Array<Object>) —

    Arguments forwarded to Array#to_json.

Returns:

  • (String) —

    The generated JSON.



13
 
# File 'lib/farce/integrations/shared/to_json.rb', line 13

def to_json(...) = to_a.to_json(...)

#to_msgpack(*arguments) ⇒ String, ::MessagePack::Packer

Note:

This method is only available if MessagePack has been loaded.

Serialize a snapshot as a MessagePack array.

Parameters:

  • arguments (Array<Object>) —

    Arguments forwarded to Array#to_msgpack.

Returns:

  • (String, ::MessagePack::Packer) —

    The encoded bytes or supplied packer.



16
 
# File 'lib/farce/integrations/msgpack.rb', line 16

def to_msgpack(...) = to_a.to_msgpack(...)

#to_param ⇒ String

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The snapshot's URL parameter representation, joined with slashes.

Returns:

  • (String) —

    The snapshot's URL parameter representation, joined with slashes.



179
 
# File 'lib/farce/integrations/active_support/vector.rb', line 179

def to_param = to_a.to_param

#to_query(key) ⇒ String

Note:

This methods is only available if ActiveSupport has been loaded.

Returns The encoded query string for the snapshot.

Parameters:

  • key (String) —

    The query parameter name.

Returns:

  • (String) —

    The encoded query string for the snapshot.



184
 
# File 'lib/farce/integrations/active_support/vector.rb', line 184

def to_query(key) = to_a.to_query(key)

#to_sentence(options = {}) ⇒ String

Note:

This methods is only available if ActiveSupport has been loaded.

Format a snapshot as a sentence using ActiveSupport's connectors and locale.

Parameters:

  • options (Hash) (defaults to: {}) —

    Connector and locale options accepted by Array#to_sentence.

Returns:

  • (String) —

    The formatted sentence.



190
 
# File 'lib/farce/integrations/active_support/vector.rb', line 190

def to_sentence(options = {}) = to_a.to_sentence(options)

#to_xml(options = {}) {|builder| ... } ⇒ String

Note:

This methods is only available if ActiveSupport has been loaded.

Serialize a logical snapshot with ActiveSupport's Array XML conversion. Requires ActiveSupport's optional Builder dependency, as Array#to_xml does.

Parameters:

  • options (Hash) (defaults to: {}) —

    XML options, including root, children, builder, and indentation.

Yields:

  • (builder) —

    Optionally append XML inside a nonempty collection's root element.

Yield Parameters:

  • builder (Builder::XmlMarkup) —

    The XML builder used for serialization.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (String) —

    The generated XML.



207
 
# File 'lib/farce/integrations/active_support/vector.rb', line 207

def to_xml(options = {}, &) = to_a.to_xml(options, &)

#union(*others) ⇒ Vector

Union with every supplied sequence.

Parameters:

  • others (Array<Vector, #to_ary>) —

    The other sequences.

Returns:

  • (Vector) —

    The resulting entries.



483
 
# File 'lib/farce/abstract/vector.rb', line 483

def union(*others) = derive_array_operation(:union, *others)

#uniq {|value| ... } ⇒ Vector

Remove duplicate values, retaining the first stored entry.

Yields:

  • (value) —

    Optionally compute a comparison key for each entry.

Yield Parameters:

  • value (BasicObject) —

    The current value.

Yield Returns:

  • (BasicObject) —

    The key compared using hash and eql?. Without a block, entries are compared directly.

Returns:



343
344
345
346
347
348
349
350
351
 
# File 'lib/farce/abstract/vector.rb', line 343

def uniq
  snapshot = internal_vector.snapshot
  selected = if block_given?
               snapshot.uniq { yield logical_value(it) }
             else
               snapshot.uniq { logical_value(it) }
             end
  build_derived_vector(selected)
end

#update(index, timeout: nil) {|value| ... } ⇒ BasicObject?

Atomically replace an index with the block result, growing the vector if necessary.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Yields:

  • (value) —

    Compute the replacement while holding atomic-update access.

Yield Parameters:

  • value (BasicObject, nil) —

    The current value, or nil if absent.

Yield Returns:

  • (BasicObject) —

    The replacement value.

Returns:

  • (BasicObject, nil) —

    The replacement value, or nil on timeout.



911
 
# File 'lib/farce/abstract/vector.rb', line 911

def update(index, timeout: nil, &) = internal_vector.update(index, timeout:, &)

#upsert(index, initial, timeout: nil) {|value| ... } ⇒ BasicObject?

Store initial for an absent or nil index, otherwise replace it with the block result.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • initial (BasicObject) —

    The value to store when the slot is absent or nil.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Yields:

  • (value) —

    Compute a replacement for an existing non-nil entry.

Yield Parameters:

  • value (BasicObject) —

    The current non-nil value.

Yield Returns:

  • (BasicObject) —

    The replacement value.

Returns:

  • (BasicObject, nil) —

    The stored value, or nil on timeout.



921
 
# File 'lib/farce/abstract/vector.rb', line 921

def upsert(index, initial, timeout: nil, &) = internal_vector.upsert(index, initial, timeout:, &)

#values_at(*indexes) ⇒ Vector

Select values at indexes and ranges.

Returns The selected entries, with nil for missing positions.

Parameters:

  • indexes (Array<Integer, Range>) —

    The indexes and ranges to select.

Returns:

  • (Vector) —

    The selected entries, with nil for missing positions.



143
 
# File 'lib/farce/abstract/vector.rb', line 143

def values_at(...) = build_derived_vector(internal_vector.snapshot.values_at(...))

#wait_until(index, timeout: nil) {|value| ... } ⇒ BasicObject?

Wait until a block condition matches the value at an index. Absent indexes are observed as nil. One timeout budget covers all checks and waits. The block is not interrupted.

Parameters:

  • index (Integer) —

    the index to observe. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Yield Parameters:

  • value (BasicObject, nil) —

    the current value

Yield Returns:

  • (Boolean) —

    whether the value matches

Returns:

  • (BasicObject, nil) —

    the matching value, or nil on timeout

Raises:

  • (LocalJumpError) —

    if no block is given



932
 
# File 'lib/farce/abstract/vector.rb', line 932

def wait_until(index, timeout: nil, &) = Internal.wait_until(self, index, timeout:, &)

#wait_until_changed(index, expected, timeout: nil) ⇒ BasicObject?

Wait until an index no longer matches expected. Absent indexes are observed as nil.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • expected (BasicObject) —

    The value to wait for the entry to stop matching.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (BasicObject, nil) —

    The changed value, or nil on timeout.



978
979
980
 
# File 'lib/farce/abstract/vector.rb', line 978

def wait_until_changed(index, expected, timeout: nil)
  internal_vector.wait_until_changed(index, expected, timeout:)
end

#wait_until_match(index, object, timeout: nil) ⇒ BasicObject?

Wait until object === value is true.

Parameters:

  • object (#===) —

    the pattern to match

  • index (Integer) —

    the index to observe. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Returns:

  • (BasicObject, nil) —

    the matching value, or nil on timeout



969
970
971
 
# File 'lib/farce/abstract/vector.rb', line 969

def wait_until_match(index, object, timeout: nil)
  wait_until(index, timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
end

#wait_until_non_nil(index, timeout: nil) ⇒ BasicObject?

Wait until an index contains a non-nil value.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (BasicObject, nil) —

    The non-nil value, or nil on timeout.



989
 
# File 'lib/farce/abstract/vector.rb', line 989

def wait_until_non_nil(index, timeout: nil) = internal_vector.wait_until_non_nil(index, timeout:)

#wait_until_value(index, object, timeout: nil) ⇒ BasicObject?

Wait until the current value equals an object using the configured comparison mode.

Parameters:

  • object (BasicObject, nil) —

    the value to compare with the current value

  • index (Integer) —

    the index to observe. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Returns:

  • (BasicObject, nil) —

    the matching value, or nil on timeout



960
961
962
 
# File 'lib/farce/abstract/vector.rb', line 960

def wait_until_value(index, object, timeout: nil)
  wait_until(index, timeout:) { |value| compare_by_identity? ? object.equal?(value) : object == value }
end

#wait_while(index, timeout: nil) {|value| ... } ⇒ BasicObject?

Wait while the block returns a truthy value.

Parameters:

  • index (Integer) —

    the index to observe. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Yield Parameters:

  • value (BasicObject, nil) —

    the current value

Yield Returns:

  • (BasicObject) —

    a truthy value to keep waiting, or nil or false to stop

Returns:

  • (BasicObject, nil) —

    the value when the condition becomes false, or nil on timeout

Raises:

  • (LocalJumpError) —

    if no block is given



941
942
943
944
 
# File 'lib/farce/abstract/vector.rb', line 941

def wait_while(index, timeout: nil)
  raise LocalJumpError, "no block given" unless block_given?
  wait_until(index, timeout:) { |value| !yield(value) }
end

#wait_while_match(index, object, timeout: nil) ⇒ BasicObject?

Wait while object === value is true.

Parameters:

  • object (#===) —

    the pattern to stop matching

  • index (Integer) —

    the index to observe. Negative indexes count from the end.

  • timeout (Numeric, nil) (defaults to: nil) —

    the total seconds available

Returns:

  • (BasicObject, nil) —

    the first nonmatching value, or nil on timeout



951
952
953
 
# File 'lib/farce/abstract/vector.rb', line 951

def wait_while_match(index, object, timeout: nil)
  wait_while(index, timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
end

#wait_while_value ⇒ BasicObject?

Wait until an index no longer matches expected. Absent indexes are observed as nil.

Parameters:

  • index (Integer) —

    The index. Negative indexes count from the end.

  • expected (BasicObject) —

    The value to wait for the entry to stop matching.

  • timeout (Numeric, nil) —

    The maximum wait in seconds. Nil waits indefinitely.

Returns:

  • (BasicObject, nil) —

    The changed value, or nil on timeout.



983
 
# File 'lib/farce/abstract/vector.rb', line 983

def wait_while_value(...) = wait_until_changed(...)

#zip(*others) {|row| ... } ⇒ Vector?

Zip values into Vector rows. With a block, yield rows and return nil.

Parameters:

  • others (Array<Enumerable, #to_ary>) —

    The sequences to combine with this vector.

Yields:

  • (row) —

    Optionally visit each combined row.

Yield Parameters:

  • row (Vector) —

    One entry from each sequence, padded with nil for shorter sequences.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (Vector, nil) —

    A Vector of Vector rows, or nil when a block is supplied.



780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
 
# File 'lib/farce/abstract/vector.rb', line 780

def zip(*others)
  snapshot = internal_vector.snapshot
  operands = others.map do |other|
    stored = other.equal?(self) ? snapshot : reusable_operand_snapshot(other)
    stored ? [stored, true] : [zip_operand(other, snapshot.length), false]
  end
  build_row = lambda do |stored, index|
    row = [stored]
    operands.each do |values, prepared|
      row << (prepared ? values[index] : derived_storage(values[index]))
    end
    build_derived_vector(row)
  end
  if block_given?
    snapshot.each_with_index { |stored, index| yield build_row.call(stored, index) }
    nil
  else
    rows = snapshot.each_with_index.map { |stored, index| build_row.call(stored, index) }
    build_derived_values(rows)
  end
end

#|(other) ⇒ Vector

Union with another sequence.

Parameters:

  • other (Vector, #to_ary) —

    The other sequence.

Returns:

  • (Vector) —

    The resulting entries.



468
 
# File 'lib/farce/abstract/vector.rb', line 468

def |(other) = derive_array_operation(:|, other)