Class: Farce::Abstract::Vector Abstract

Inherits:

Collection

Object
Collection
Farce::Abstract::Vector

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.

Direct Known Subclasses

Local::Vector, Strict::Vector, Transaction::Vector, Unshared::Vector, Vector

JSON Integration collapse

#to_json(*arguments) ⇒ String
Serialize a logical snapshot as a JSON Array.

ActiveSupport Integration collapse

#as_json(options = nil) ⇒ Array
Convert a snapshot to ActiveSupport's explicit JSON representation.
#compact_blank ⇒ Vector
Entries for which blank? is false, excluding nil and false.
#deep_dup ⇒ Vector
Copy entries using ActiveSupport's deep-copy rules and the Vector's storage rules.
#excluding(*elements) ⇒ Vector (also: #without)
Exclude entries using Array's hash-based difference semantics.
#fifth ⇒ BasicObject^?
The fifth entry, or nil if absent.
#forty_two ⇒ BasicObject^?
The forty-second entry, or nil if absent.
#fourth ⇒ BasicObject^?
The fourth entry, or nil if absent.
#from(position) ⇒ Vector
Return entries starting at position from one snapshot.
#in_groups(number, fill_with = nil) {|group| ... } ⇒ Vector
Divide a snapshot into a requested number of Vector groups.
#in_groups_of(number, fill_with = nil) {|group| ... } ⇒ Vector, self
Divide a snapshot into Vector groups with a maximum size.
#in_order_of(key, series, filter: true) ⇒ Vector
Order a snapshot by the keys in series, preserving retained entries.
#including(*elements) ⇒ Vector
Append entries to a new Vector, flattening argument Arrays by one level.
#inquiry ⇒ ActiveSupport::ArrayInquirer
Create ActiveSupport's specialized query wrapper from a logical snapshot.
#maximum(key) ⇒ BasicObject^?
Find the maximum extracted value without storing intermediate results in a Vector.
#minimum(key) ⇒ BasicObject^?
Find the minimum extracted value without storing intermediate results in a Vector.
#pick(*keys) ⇒ BasicObject, ...
Extract keys from the first entry in a snapshot.
#pluck(*keys) ⇒ Vector
Extract keys from each entry in a snapshot.
#second ⇒ BasicObject^?
The second entry, or nil if absent.
#second_to_last ⇒ BasicObject^?
The second entry from the end, or nil if absent.
#split(value = nil) {|entry| ... } ⇒ Vector
Split a snapshot at matching entries, omitting the separators.
#third ⇒ BasicObject^?
The third entry, or nil if absent.
#third_to_last ⇒ BasicObject^?
The third entry from the end, or nil if absent.
#to(position) ⇒ Vector
Return entries through position from one snapshot.
#to_fs(format = :default) ⇒ String (also: #to_formatted_s)
Format a snapshot, optionally as a database ID list.
#to_param ⇒ String
The snapshot's URL parameter representation, joined with slashes.
#to_query(key) ⇒ String
The encoded query string for the snapshot.
#to_sentence(options = {}) ⇒ String
Format a snapshot as a sentence using ActiveSupport's connectors and locale.
#to_xml(options = {}) {|builder| ... } ⇒ String
Serialize a logical snapshot with ActiveSupport's Array XML conversion.

Methods included from Internal::Copyable

#duplicable?

Instance Method Summary collapse

#&(other) ⇒ Vector
Intersect with another sequence.
#*(other) ⇒ Vector, String
Repeat a snapshot, or join it when a String separator is supplied.
#+(other) ⇒ Vector
Concatenate a snapshot with another sequence.
#-(other) ⇒ Vector
Remove values present in another sequence.
#<<(value) ⇒ self
Append a single value without a timeout.
#<=>(other) ⇒ Integer^?
Compare logical entries lexicographically, as with Array.
#[](index, length = UNDEFINED) ⇒ BasicObject, ...
Read an index without waiting for atomic-update access, or return a slice snapshot.
#[]=(index, value, replacement = UNDEFINED) ⇒ BasicObject
Store a value or replace a slice atomically, growing the vector if necessary.
#append(*values, timeout: nil) ⇒ self, false
Append values using the same options as #push.
#as_extended_json(**options) ⇒ Array
Represent a snapshot as Extended JSON, forwarding BSON's format options.
#assoc(key) ⇒ Array, ...
Find the first pair whose first value equals key.
#at(index) ⇒ BasicObject, ...
Read an index without waiting for atomic-update access, or return a slice snapshot.
#bsearch {|value| ... } ⇒ BasicObject, ...
Binary-search the live entries and return the matching value.
#bsearch_index {|value| ... } ⇒ Integer, ...
Binary-search the live entries and return the matching index.
#bson_type ⇒ String
Identify this value as a BSON array when embedded in a document or array.
#chunk {|value| ... } ⇒ Enumerator
Group adjacent entries by a block-generated key.
#chunk_while {|left, right| ... } ⇒ Enumerator
Group adjacent entries while the block accepts each pair.
#clear ⇒ self
Remove all slots.
#combination(count) {|tuple| ... } ⇒ self, Enumerator
Visit combinations of entries in a snapshot.
#compact ⇒ Vector
Remove nil values.
#compact! ⇒ self^?
Remove nil entries atomically.
#compare_and_set(index, expected, replacement, timeout: nil) ⇒ Boolean
Replace an existing index only if its value matches the expected value.
#compare_by_identity? ⇒ Boolean
Whether values are compared by identity.
#concat(*sources) ⇒ self
Append snapshots of one or more sequences and return this vector.
#deconstruct ⇒ Array<BasicObject>
Return a new Array containing a logical snapshot of the values.
#delete(value) {|value| ... } ⇒ BasicObject^?
Remove all matching values using the configured comparison mode.
#delete_at(index) ⇒ BasicObject^?
Remove the entry at an index and shift later entries left atomically.
#delete_if {|value| ... } ⇒ self, Enumerator
Atomically remove entries for which the block returns a truthy value.
#difference(*others) ⇒ Vector
Remove values present in any supplied sequence.
#dig(index, *identifiers) ⇒ BasicObject^?
Recursively retrieve a nested value.
#drop(count) ⇒ Vector
Return all entries after count entries.
#drop_while {|value| ... } ⇒ Vector, Enumerator
Drop entries before the first rejected value.
#each {|value| ... } ⇒ self, Enumerator
Iterate over live entries, up to the length when enumeration starts.
#each_cons(count) {|window| ... } ⇒ self, Enumerator
Yield same-kind overlapping windows from live iteration.
#each_index {|index| ... } ⇒ self, Enumerator
Iterate over indexes up to the length when enumeration starts.
#each_slice(count) {|window| ... } ⇒ self, Enumerator
Yield same-kind windows from live iteration.
#entries ⇒ Vector
Materialize enumeration as a Vector rather than an Array.
#fetch(index, *fallback) {|index| ... } ⇒ BasicObject
Fetch a value by index, with Array-compatible fallback behavior.
#fetch_values(*indexes) {|index| ... } ⇒ Vector
Fetch several values.
#fill(*arguments) ⇒ self
Fill all or part of the vector atomically, growing it when necessary.
#filter_map {|value| ... } ⇒ Vector, Enumerator
Transform accepted values into a Vector.
#first(count = UNDEFINED) ⇒ BasicObject, ...
Return one value, or a Vector when a count is supplied.
#flat_map {|value| ... } ⇒ Vector, Enumerator (also: #collect_concat)
Transform and flatten one Array or Vector level.
#flatten(level = -1)) ⇒ Vector
Expand nested Arrays and Vectors into a new Vector.
#flatten!(level = -1)) ⇒ self^?
Expand nested Arrays and Vectors atomically.
#get(index, timeout: nil) ⇒ BasicObject^?
Read an index after acquiring atomic-update access.
#grep(pattern) {|value| ... } ⇒ Vector
Select values matched by pattern, optionally transforming them.
#grep_v(pattern) {|value| ... } ⇒ Vector
Select values not matched by pattern, optionally transforming them.
#group_by {|value| ... } ⇒ Hash{BasicObject => Vector}, Enumerator
Group live entries into same-kind Vectors.
#include?(value) ⇒ Boolean (also: #member?)
Return whether a live entry equals value.
#index(value = UNDEFINED) {|entry| ... } ⇒ Integer, ... (also: #find_index)
Return the first matching index.
#insert(index, *values) ⇒ self
Insert values before an index atomically.
#intersect?(other) ⇒ Boolean
Return whether another sequence shares any value.
#intersection(*others) ⇒ Vector
Intersect with every supplied sequence.
#keep_if {|value| ... } ⇒ self, Enumerator
Keep entries accepted by the block, publishing the result atomically.
#last(count = UNDEFINED) ⇒ BasicObject, ...
Return one value, or a Vector when a count is supplied.
#map {|value| ... } ⇒ Vector, Enumerator (also: #collect)
Transform a snapshot into a Vector.
#map! {|value| ... } ⇒ self, Enumerator (also: #collect!)
Replace each entry with the block result, publishing all replacements together.
#max(count = UNDEFINED) {|left, right| ... } ⇒ BasicObject, ...
Return one maximum, or a Vector when count is supplied.
#max_by(count = UNDEFINED) {|value| ... } ⇒ BasicObject, ...
Return one block maximum, or a Vector when count is supplied.
#min(count = UNDEFINED) {|left, right| ... } ⇒ BasicObject, ...
Return one minimum, or a Vector when count is supplied.
#min_by(count = UNDEFINED) {|value| ... } ⇒ BasicObject, ...
Return one block minimum, or a Vector when count is supplied.
#minmax {|left, right| ... } ⇒ Vector
Return minimum and maximum in a Vector.
#minmax_by {|value| ... } ⇒ Vector, Enumerator
Return the block minimum and maximum in a Vector.
#pack(format, buffer: nil) ⇒ String
Pack a logical snapshot according to format.
#partition {|value| ... } ⇒ Vector, Enumerator
Split live entries into accepted and rejected Vectors, wrapped in a Vector.
#permutation(count = UNDEFINED) {|tuple| ... } ⇒ self, Enumerator
Visit permutations of entries in a snapshot.
#pop(count = UNDEFINED, timeout: nil) ⇒ BasicObject, ...
Remove and return the last value, or a Vector of the last count values, atomically.
#product(*others) {|tuple| ... } ⇒ Vector, self
Produce tuples containing one entry from each sequence.
#push(value = UNDEFINED, *rest, timeout: nil) ⇒ self, false
Append values atomically.
#rassoc(value) ⇒ Array, ...
Find the first pair whose second value equals value.
#reject {|value| ... } ⇒ Vector, Enumerator
Remove values accepted by a block.
#reject! {|value| ... } ⇒ self, ...
Remove entries accepted by the block, returning nil if no entry was removed.
#repeated_combination(count) {|tuple| ... } ⇒ self, Enumerator
Visit combinations that may reuse entries in a snapshot.
#repeated_permutation(count) {|tuple| ... } ⇒ self, Enumerator
Visit permutations that may reuse entries in a snapshot.
#replace(source) ⇒ self
Replace all entries atomically with the contents of another sequence.
#reverse ⇒ Vector
Return a reversed snapshot.
#reverse! ⇒ self
Reverse all entries atomically.
#reverse_each {|value| ... } ⇒ self, Enumerator
Iterate over live entries from the last index when enumeration starts.
#rfind(if_none = nil) {|value| ... } ⇒ BasicObject, ...
Find a value by searching from the end.
#rindex(value = UNDEFINED) {|entry| ... } ⇒ Integer, ...
Return the last matching index.
#rotate(count = 1) ⇒ Vector
Return a rotated snapshot.
#rotate!(count = 1) ⇒ self
Rotate all entries atomically.
#sample(count = UNDEFINED, random: Random) ⇒ BasicObject, ...
Return one sample, or a Vector when count is supplied.
#select {|value| ... } ⇒ Vector, Enumerator (also: #filter, #find_all)
Keep values accepted by a block.
#select! {|value| ... } ⇒ self, ... (also: #filter!)
Keep entries accepted by the block, returning nil if no entry was removed.
#shareable_values? ⇒ Boolean
Whether stored values must be Ractor-shareable.
#shift(count = UNDEFINED) ⇒ BasicObject, ...
Remove the first entry, or the first count entries, atomically.
#shuffle(random: Random) ⇒ Vector
Return a shuffled snapshot.
#shuffle!(random: Random) ⇒ self
Shuffle all entries atomically without transferring retained values again.
#size ⇒ Integer
The number of slots, including nil slots.
#slice(index, length = UNDEFINED) ⇒ BasicObject, ...
Return an element or subsequence from a snapshot.
#slice!(index, length = UNDEFINED) ⇒ BasicObject, ...
Remove a range of entries atomically.
#slice_after(*arguments) {|value| ... } ⇒ Enumerator
Group a snapshot after matching entries.
#slice_before(*arguments) {|value| ... } ⇒ Enumerator
Group a snapshot before matching entries.
#slice_when {|left, right| ... } ⇒ Enumerator
Group a snapshot between pairs accepted by the block.
#sort {|left, right| ... } ⇒ Vector
Return a sorted snapshot.
#sort! {|left, right| ... } ⇒ self
Sort all entries atomically using logical values.
#sort_by {|value| ... } ⇒ Vector, Enumerator
Sort a snapshot by block results.
#sort_by! {|value| ... } ⇒ self, Enumerator
Sort all entries atomically by the block result.
#store(index, value, timeout: nil) ⇒ BasicObject, false
Store a value after acquiring atomic-update access.
#store_if_absent(index, timeout: nil) { ... } ⇒ BasicObject^?
Compute and store a value only when the index is absent or contains nil.
#swap(index, replacement, timeout: nil) ⇒ BasicObject^?
Replace an index and return its previous value, growing the vector if necessary.
#take(count) ⇒ Vector
Return the first count entries.
#take_while {|value| ... } ⇒ Vector, Enumerator
Return entries before the first rejected value.
#to_a ⇒ Array<BasicObject>
Return a new Array containing a logical snapshot of the values.
#to_ary ⇒ Array<BasicObject>
Return an Array snapshot for implicit Array conversion, such as [].concat(vector).
#to_bson(buffer = ::BSON::ByteBuffer.new) ⇒ BSON::ByteBuffer
Serialize a snapshot using BSON's array representation.
#to_bson_normalized_value ⇒ Array
Return a snapshot with nested values normalized by BSON.
#to_cbor(*arguments) ⇒ String, ...
Serialize a snapshot as a CBOR array.
#to_h {|value| ... } ⇒ Hash
Convert pair-like entries to a Hash.
#to_msgpack(*arguments) ⇒ String, ::MessagePack::Packer
Serialize a snapshot as a MessagePack array.
#transpose ⇒ Vector
Transpose rows represented by Arrays or Vectors.
#union(*others) ⇒ Vector
Union with every supplied sequence.
#uniq {|value| ... } ⇒ Vector
Remove duplicate values, retaining the first stored entry.
#uniq! {|value| ... } ⇒ self^?
Remove duplicate entries atomically, retaining the first stored entry.
#unshift(*values) ⇒ self (also: #prepend)
Prepend values atomically using the vector's default transfer mode.
#update(index, timeout: nil) {|value| ... } ⇒ BasicObject^?
Atomically replace an index with the block result, growing the vector if necessary.
#upsert(index, initial, timeout: nil) {|value| ... } ⇒ BasicObject^?
Store initial for an absent or nil index, otherwise replace it with the block result.
#values_at(*indexes) ⇒ Vector
Select values at indexes and ranges.
#wait_until(index, timeout: nil) {|value| ... } ⇒ BasicObject^?
Wait until a block condition matches the value at an index.
#wait_until_changed(index, expected, timeout: nil) ⇒ BasicObject^?
Wait until an index no longer matches expected.
#wait_until_match(index, object, timeout: nil) ⇒ BasicObject^?
Wait until object === value is true.
#wait_until_non_nil(index, timeout: nil) ⇒ BasicObject^?
Wait until an index contains a non-nil value.
#wait_until_value(index, object, timeout: nil) ⇒ BasicObject^?
Wait until the current value equals an object using the configured comparison mode.
#wait_while(index, timeout: nil) {|value| ... } ⇒ BasicObject^?
Wait while the block returns a truthy value.
#wait_while_match(index, object, timeout: nil) ⇒ BasicObject^?
Wait while object === value is true.
#wait_while_value ⇒ BasicObject^?
Wait until an index no longer matches expected.
#zip(*others) {|row| ... } ⇒ Vector^?
Zip values into Vector rows.
#|(other) ⇒ Vector
Union with another sequence.

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.

719	# File 'lib/farce/abstract/vector.rb', line 719 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.

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

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.

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

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.

714	# File 'lib/farce/abstract/vector.rb', line 714 def -(other) = derive_array_operation(:-, other)

#<<(value) ⇒ `self`

Append a single value without a timeout.

Parameters:

value (BasicObject) —
The value to append.

Returns:

(self)

1135	# File 'lib/farce/abstract/vector.rb', line 1135 def <<(value) = push(value)

#<=>(other) ⇒ `Integer`^?

Compare logical entries lexicographically, as with Array.

Parameters:

other (Vector, #to_ary) —
The sequence to compare against.

Returns:

(Integer, nil) —
A negative number, zero, a positive number, or nil if incomparable.

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

def <=>(other)
  return 0 if equal?(other)
  compare_vector(other)
end

#[](index, length = UNDEFINED) ⇒ `BasicObject`, ...

Read an index without waiting for atomic-update access, or return a slice snapshot.

Parameters:

index (Integer, Range) —
The index, start index, or range. Negative indexes count from the end.
length (Integer) (defaults to: UNDEFINED) —
The slice length. Omit for a single index or range.

Returns:

(BasicObject, Vector, nil) —
The logical value, a slice Vector, or nil if absent.

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

def [](index, length = UNDEFINED)
  return internal_vector[index] if length.equal?(UNDEFINED) && !index.is_a?(Range)
  slice(index, length)
end

#[]=(index, value, replacement = UNDEFINED) ⇒ `BasicObject`

Store a value or replace a slice atomically, growing the vector if necessary. Slice replacements accept a Vector, Array-like object, or one scalar value.

Parameters:

index (Integer, Range) —
The index, start index, or range.
value (BasicObject, Integer) —
The assigned value, or the slice length for three arguments.
replacement (BasicObject) (defaults to: UNDEFINED) —
The replacement for the three-argument form.

Returns:

(BasicObject) —
The assigned value or replacement sequence.

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

def []=(index, value, replacement = UNDEFINED)
  if replacement.equal?(UNDEFINED) && !index.is_a?(Range)
    internal_vector[index] = value
  else
    assign_vector_slice(index, value, replacement)
  end
end

#append(*values, timeout: nil) ⇒ `self`, `false`

Append values using the same options as #push.

Returns Self on success, or false on timeout.

Parameters:

values (Array<BasicObject>) —
The values 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.

1142	# File 'lib/farce/abstract/vector.rb', line 1142 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.

125	# File 'lib/farce/abstract/vector.rb', line 125 def assoc(key) = find_pair(key, 0)

#at(index) ⇒ `BasicObject`, ...

Read an index without waiting for atomic-update access, or return a slice snapshot.

Parameters:

index (Integer, Range) —
The index, start index, or range. Negative indexes count from the end.
length (Integer) —
The slice length. Omit for a single index or range.

Returns:

(BasicObject, Vector, nil) —
The logical value, a slice Vector, or nil if absent.

133	# File 'lib/farce/abstract/vector.rb', line 133 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.

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

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.

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

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.

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

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)

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

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)

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

def clear
  internal_vector.clear
  self
end

#combination(count) {|tuple| ... } ⇒ `self`, `Enumerator`

Visit combinations of entries in a snapshot.

Parameters:

count (Integer) —
The number of entries per combination.

Yields:

(tuple) —
Visit each combination. Returns a sized Enumerator without a block.

Yield Parameters:

tuple (Vector) —
A same-kind Vector containing the combination.

Yield Returns:

(void) —
The result is ignored.

Returns:

(self, Enumerator)

561	# File 'lib/farce/abstract/vector.rb', line 561 def combination(count, &block) = vector_combinations(__method__, [count], block)

#compact ⇒ `Vector`

Remove nil values.

Returns:

(Vector) —
A new same-kind Vector containing the result.

591	# File 'lib/farce/abstract/vector.rb', line 591 def compact = build_derived_vector(internal_vector.each.compact)

#compact! ⇒ `self`^?

Remove nil entries atomically.

Returns:

(self, nil) —
Self if entries were removed, otherwise nil.

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

def compact!
  changed = mutate_vector(&:compact!)
  self if changed
end

#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.



1261
1262
1263

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

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.

1356	# File 'lib/farce/abstract/vector.rb', line 1356 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)

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

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.

65	# File 'lib/farce/abstract/vector.rb', line 65 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)

#delete(value) {|value| ... } ⇒ `BasicObject`^?

Remove all matching values using the configured comparison mode. Other writers wait until the comparison finishes. Reads can observe the original values. Comparison callbacks must not write to this vector.

Parameters:

value (BasicObject) —
The value to remove.

Yields:

(value) —
Called only when no entry matches, after releasing update access.

Yield Parameters:

value (BasicObject) —
The requested value.

Yield Returns:

(BasicObject) —
The fallback result.

Returns:

(BasicObject, nil) —
The last removed value, or the fallback result. Nil if absent without a block.

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

def delete(value)
  expected = deletion_comparison(value)
  removed = UNDEFINED
  mutate_vector do |values|
    values.delete_if do |stored|
      next false unless deletion_match?(stored, expected)
      removed = stored
      true
    end
  end
  return logical_value(removed) unless removed.equal?(UNDEFINED)
  yield(value) if block_given?
end

#delete_at(index) ⇒ `BasicObject`^?

Remove the entry at an index and shift later entries left atomically.

Parameters:

index (Integer) —
The index. Negative indexes count from the end.

Returns:

(BasicObject, nil) —
The removed logical value, or nil if absent.

1186	# File 'lib/farce/abstract/vector.rb', line 1186 def delete_at(index) = logical_value(mutate_vector { it.delete_at(index) })

#delete_if {|value| ... } ⇒ `self`, `Enumerator`

Atomically remove entries for which the block returns a truthy value. The block runs without a collection lock. Other writers wait for update access. The block must not write to this vector. Reads can observe the original values. If the block raises, no entries are removed.

Yields:

(value) —
Called once for each logical value. Returns an Enumerator without a block.

Yield Parameters:

value (BasicObject) —
The current value.

Yield Returns:

(BasicObject) —
A truthy value to remove the entry.

Returns:

(self, Enumerator)

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

def delete_if
  return enum_for(__method__) { size } unless block_given?
  mutate_vector { |values| values.delete_if { yield logical_value(it) } }
  self
end

#difference(*others) ⇒ `Vector`

Remove values present in any supplied sequence.

Parameters:

others (Array<Vector, #to_ary>) —
The other sequences.

Returns:

(Vector) —
The resulting entries.

729	# File 'lib/farce/abstract/vector.rb', line 729 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)

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

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.

652	# File 'lib/farce/abstract/vector.rb', line 652 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:

(Vector, Enumerator)

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

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)

# 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)

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

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)

# 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)

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

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.

1060	# File 'lib/farce/abstract/vector.rb', line 1060 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.

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

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.

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

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]

#fill(value, start = 0, length = size) ⇒ `self` #fill(start = 0, length = size) {|index| ... } ⇒ `self`

Fill all or part of the vector atomically, growing it when necessary. The block must not write to this vector.

Overloads:

#fill(value, start = 0, length = size) ⇒ self
Parameters:
- value (BasicObject) —
  The fill value.
- start (Integer, Range) (defaults to: 0) —
  The start index or range.
- length (Integer) (defaults to: size) —
  The number of entries to fill.
#fill(start = 0, length = size) {|index| ... } ⇒ self
Parameters:
- start (Integer, Range) (defaults to: 0) —
  The start index or range.
- length (Integer) (defaults to: size) —
  The number of entries to fill.
Yields:
- (index) —
  Compute a value for each filled position.
Yield Parameters:
- index (Integer) —
  The current index.
Yield Returns:
- (BasicObject) —
  The fill value.

Returns:

(self)

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

def fill(*arguments)
  mutate_vector do |values|
    if block_given?
      values.fill(*arguments) { derived_storage(yield(it)) }
    else
      raise ArgumentError, "wrong number of arguments (given 0, expected 1..3)" if arguments.empty?
      values.fill(derived_storage(arguments.first), *arguments.drop(1))
    end
  end
  self
end

#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:

(Vector, Enumerator)

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

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.

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

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:

(Vector, Enumerator)

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

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

#flatten(level = -1)) ⇒ `Vector`

Expand nested Arrays and Vectors into a new Vector.

Parameters:

level (Integer) (defaults to: -1)) —
The maximum depth. Negative values expand every level.

Returns:

(Vector) —
The flattened logical values.

Raises:

(ArgumentError) —
If the expanded graph is recursive.

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

def flatten(level = -1)
  snapshot = internal_vector.snapshot
  logical = snapshot.map { logical_value(it) }
  retained = retained_storage_index(snapshot, logical)
  flattened = flatten_vector_values(logical, level, retained)
  build_derived_vector(sequence_storage(flattened, retained))
end

#flatten!(level = -1)) ⇒ `self`^?

Expand nested Arrays and Vectors atomically.

Parameters:

level (Integer) (defaults to: -1)) —
The maximum depth. Negative values expand every level.

Returns:

(self, nil) —
Self if nesting was expanded, otherwise nil.

Raises:

(ArgumentError) —
If the expanded graph is recursive.

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

def flatten!(level = -1)
  changed = mutate_vector do |values|
    logical = values.map { logical_value(it) }
    retained = retained_storage_index(values, logical)
    flattened = flatten_vector_values(logical, level, retained)
    next if flattened.equal?(logical)
    values.replace(sequence_storage(flattened, retained))
  end
  self if changed
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.

# 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.

1089	# File 'lib/farce/abstract/vector.rb', line 1089 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.

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

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.

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

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.

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

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.

# 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.

# 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.

# 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.

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

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.

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

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

#insert(index, *values) ⇒ `self`

Insert values before an index atomically. Negative indexes count from the end.

Parameters:

index (Integer) —
The insertion index. -1 appends values.
values (Array<BasicObject>) —
The values to insert.

Returns:

(self)

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

def insert(index, *values)
  mutate_vector { it.insert(index, *values.map { derived_storage(it) }) }
  self
end

#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.

744	# File 'lib/farce/abstract/vector.rb', line 744 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.

734	# File 'lib/farce/abstract/vector.rb', line 734 def intersection(others) = derive_array_operation(:intersection, others)

#keep_if {|value| ... } ⇒ `self`, `Enumerator`

Keep entries accepted by the block, publishing the result atomically. The block must not write to this vector.

Yields:

(value) —
Test each logical value. Returns an Enumerator without a block.

Yield Parameters:

value (BasicObject) —
The current value.

Yield Returns:

(BasicObject) —
A truthy value to retain the entry.

Returns:

(self, Enumerator)

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

def keep_if
  return enum_for(__method__) { size } unless block_given?
  mutate_vector { |values| values.keep_if { yield logical_value(it) } }
  self
end

#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.

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

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:

(Vector, Enumerator)

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

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

#map! {|value| ... } ⇒ `self`, `Enumerator` Also known as: collect!

Replace each entry with the block result, publishing all replacements together. The block must not write to this vector. Failure leaves the stored entries unchanged.

Yields:

(value) —
Transform each logical value. Returns an Enumerator without a block.

Yield Parameters:

value (BasicObject) —
The current value.

Yield Returns:

(BasicObject) —
The replacement value.

Returns:

(self, Enumerator)

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

def map!
  return enum_for(__method__) { size } unless block_given?
  mutate_vector do |values|
    logical = values.map { logical_value(it) }
    mapped = logical.map { yield it }
    values.replace(storage_from_logical(mapped, values, logical))
  end
  self
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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

784	# File 'lib/farce/abstract/vector.rb', line 784 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.

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

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

#permutation(count = UNDEFINED) {|tuple| ... } ⇒ `self`, `Enumerator`

Visit permutations of entries in a snapshot.

Parameters:

count (Integer) (defaults to: UNDEFINED) —
The number of entries per permutation. Defaults to the vector's length.

Yields:

(tuple) —
Visit each permutation. Returns a sized Enumerator without a block.

Yield Parameters:

tuple (Vector) —
A same-kind Vector containing the permutation.

Yield Returns:

(void) —
The result is ignored.

Returns:

(self, Enumerator)



577
578
579

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

def permutation(count = UNDEFINED, &block)
  vector_combinations(__method__, count.equal?(UNDEFINED) ? [] : [count], block)
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.

# 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.

# 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(count = UNDEFINED, timeout: nil) ⇒ `BasicObject`, ...

Remove and return the last value, or a Vector of the last count values, atomically. This does not wait for an empty vector to become nonempty.

Parameters:

count (Integer) (defaults to: UNDEFINED) —
The maximum number of values. Omit to return one value.
timeout (Numeric, nil) (defaults to: nil) —
The maximum wait in seconds. Nil waits indefinitely.

Returns:

(BasicObject, Vector, nil) —
Removed values, or nil if empty without a count or timed out.

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

def pop(count = UNDEFINED, timeout: nil)
  if count.equal?(UNDEFINED)
    backend = internal_vector
    return timeout.nil? ? backend.pop : backend.pop(timeout:)
  end
  pop_values(count, timeout:)
end

#product(*others) {|tuple| ... } ⇒ `Vector`, `self`

Produce tuples containing one entry from each sequence.

Parameters:

others (Array<Vector, #to_ary>) —
The other sequences.

Yields:

(tuple) —
Optionally visit each tuple instead of collecting results.

Yield Parameters:

tuple (Vector) —
A same-kind Vector containing the tuple.

Yield Returns:

(void) —
The result is ignored.

Returns:

(Vector, self) —
Collected tuples, or self when a block is supplied.

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

def product(*others)
  snapshot = internal_vector.snapshot
  logical = snapshot.map { logical_value(it) }
  retained = retained_storage_index(snapshot, logical)
  operands = others.map { sequence_operand(it, retained) }
  if block_given?
    logical.product(*operands) { yield build_derived_vector(sequence_storage(it, retained)) }
    self
  else
    tuples = logical.product(*operands).map { build_derived_vector(sequence_storage(it, retained)) }
    build_derived_values(tuples)
  end
end

#push(value = UNDEFINED, *rest, timeout: nil) ⇒ `self`, `false`

Append values atomically. Calls with one value use the scalar backend path.

Parameters:

value (BasicObject) (defaults to: UNDEFINED) —
The first value. Omit to leave contents unchanged.
rest (Array<BasicObject>) —
Additional values 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.

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

def push(value = UNDEFINED, *rest, timeout: nil)
  if rest.empty? && !value.equal?(UNDEFINED)
    backend = internal_vector
    completed = timeout.nil? ? backend.push(value) : backend.push(value, timeout:)
    return completed ? self : false
  end
  push_values(value.equal?(UNDEFINED) ? rest : [value, *rest], timeout:)
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.

130	# File 'lib/farce/abstract/vector.rb', line 130 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:

(Vector, Enumerator)

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

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

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

#reject! {|value| ... } ⇒ `self`, ...

Remove entries accepted by the block, returning nil if no entry was removed. The block must not write to this vector.

Yields:

(value) —
Test each logical value. Returns an Enumerator without a block.

Yield Parameters:

value (BasicObject) —
The current value.

Yield Returns:

(BasicObject) —
A truthy value to remove the entry.

Returns:

(self, nil, Enumerator)

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

def reject!
  return enum_for(__method__) { size } unless block_given?
  changed = mutate_vector { |values| values.reject! { yield logical_value(it) } }
  self if changed
end

#repeated_combination(count) {|tuple| ... } ⇒ `self`, `Enumerator`

Visit combinations that may reuse entries in a snapshot.

Parameters:

count (Integer) —
The number of entries per combination.

Yields:

(tuple) —
Visit each combination. Returns a sized Enumerator without a block.

Yield Parameters:

tuple (Vector) —
A same-kind Vector containing the combination.

Yield Returns:

(void) —
The result is ignored.

Returns:

(self, Enumerator)

569	# File 'lib/farce/abstract/vector.rb', line 569 def repeated_combination(count, &block) = vector_combinations(__method__, [count], block)

#repeated_permutation(count) {|tuple| ... } ⇒ `self`, `Enumerator`

Visit permutations that may reuse entries in a snapshot.

Parameters:

count (Integer) —
The number of entries per permutation.

Yields:

(tuple) —
Visit each permutation. Returns a sized Enumerator without a block.

Yield Parameters:

tuple (Vector) —
A same-kind Vector containing the permutation.

Yield Returns:

(void) —
The result is ignored.

Returns:

(self, Enumerator)

587	# File 'lib/farce/abstract/vector.rb', line 587 def repeated_permutation(count, &block) = vector_combinations(__method__, [count], block)

#replace(source) ⇒ `self`

Replace all entries atomically with the contents of another sequence.

Parameters:

source (Vector, #to_ary) —
The replacement sequence.

Returns:

(self)

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

def replace(source)
  mutate_vector { |values| values.replace(source.equal?(self) ? values : operand_storage(source)) }
  self
end

#reverse ⇒ `Vector`

Return a reversed snapshot.

Returns:

(Vector) —
A new same-kind Vector containing the result.

611	# File 'lib/farce/abstract/vector.rb', line 611 def reverse = build_derived_vector(internal_vector.snapshot.reverse)

#reverse! ⇒ `self`

Reverse all entries atomically.

Returns:

(self)

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

def reverse!
  mutate_vector(&:reverse!)
  self
end

#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)

# 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.

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

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.

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

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.

616	# File 'lib/farce/abstract/vector.rb', line 616 def rotate(count = 1) = build_derived_vector(internal_vector.snapshot.rotate(count))

#rotate!(count = 1) ⇒ `self`

Rotate all entries atomically.

Parameters:

count (Integer) (defaults to: 1) —
The rotation distance. Negative values rotate right.

Returns:

(self)

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

def rotate!(count = 1)
  mutate_vector { it.rotate!(count) }
  self
end

#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.

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

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:

(Vector, Enumerator)

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

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

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

#select! {|value| ... } ⇒ `self`, ... Also known as: filter!

Keep entries accepted by the block, returning nil if no entry was removed. The block must not write to this vector.

Yields:

(value) —
Test each logical value. Returns an Enumerator without a block.

Yield Parameters:

value (BasicObject) —
The current value.

Yield Returns:

(BasicObject) —
A truthy value to retain the entry.

Returns:

(self, nil, Enumerator)

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

def select!
  return enum_for(__method__) { size } unless block_given?
  changed = mutate_vector { |values| values.select! { yield logical_value(it) } }
  self if changed
end

#shareable_values? ⇒ `Boolean`

Returns Whether stored values must be Ractor-shareable.

Returns:

(Boolean) —
Whether stored values must be Ractor-shareable.

1359	# File 'lib/farce/abstract/vector.rb', line 1359 def shareable_values? = false

#shift(count = UNDEFINED) ⇒ `BasicObject`, ...

Remove the first entry, or the first count entries, atomically.

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 of removed entries.

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

def shift(count = UNDEFINED)
  result = mutate_vector { count.equal?(UNDEFINED) ? it.shift : it.shift(count) }
  count.equal?(UNDEFINED) ? logical_value(result) : build_derived_vector(result)
end

#shuffle(random: Random) ⇒ `Vector`

Return a shuffled snapshot.

Parameters:

random (#rand) (defaults to: Random) —
The random number generator.

Returns:

(Vector) —
The shuffled entries.

677	# File 'lib/farce/abstract/vector.rb', line 677 def shuffle(random: Random) = build_derived_vector(internal_vector.snapshot.shuffle(random:))

#shuffle!(random: Random) ⇒ `self`

Shuffle all entries atomically without transferring retained values again.

Parameters:

random (#rand) (defaults to: Random) —
The random number generator.

Returns:

(self)

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

def shuffle!(random: Random)
  mutate_vector { it.shuffle!(random:) }
  self
end

#size ⇒ `Integer`

Returns The number of slots, including nil slots.

Returns:

(Integer) —
The number of slots, including nil slots.

1353	# File 'lib/farce/abstract/vector.rb', line 1353 def size = internal_vector.size

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

Return an element or subsequence from a snapshot. 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.

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

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!(index, length = UNDEFINED) ⇒ `BasicObject`, ...

Remove a range of entries atomically.

Parameters:

index (Integer, Range) —
The index, start index, or range.
length (Integer) (defaults to: UNDEFINED) —
The number of entries. Omit for a single index or range.

Returns:

(BasicObject, Vector, nil) —
The removed entry, a Vector of removed entries, or nil if absent.

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

def slice!(index, length = UNDEFINED)
  result = mutate_vector { length.equal?(UNDEFINED) ? it.slice!(index) : it.slice!(index, length) }
  return if result.nil?
  length.equal?(UNDEFINED) && !index.is_a?(Range) ? logical_value(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.



1015
1016
1017

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

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.



1005
1006
1007

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

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)

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

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.

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

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! {|left, right| ... } ⇒ `self`

Sort all entries atomically using logical values. The comparison block must not write to this vector.

Yields:

(left, right) —
Optionally compare two entries. Otherwise uses <=>.

Yield Parameters:

left (BasicObject) —
The left entry.
right (BasicObject) —
The right entry.

Yield Returns:

(Numeric) —
A negative number, zero, or a positive number.

Returns:

(self)

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

def sort!(&block)
  mutate_vector do |values|
    logical = values.map { logical_value(it) }
    sorted = block ? logical.sort(&block) : logical.sort
    values.replace(storage_from_logical(sorted, values, logical))
  end
  self
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:

(Vector, Enumerator)

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

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

#sort_by! {|value| ... } ⇒ `self`, `Enumerator`

Sort all entries atomically by the block result. The block must not write to this vector.

Yields:

(value) —
Compute a key. Returns an Enumerator without a block.

Yield Parameters:

value (BasicObject) —
The current logical value.

Yield Returns:

(BasicObject) —
The sort key.

Returns:

(self, Enumerator)

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

def sort_by!
  return enum_for(__method__) { size } unless block_given?
  mutate_vector { |values| values.sort_by! { yield logical_value(it) } }
  self
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.

# 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.

1096	# File 'lib/farce/abstract/vector.rb', line 1096 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.

1252	# File 'lib/farce/abstract/vector.rb', line 1252 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.

1244	# File 'lib/farce/abstract/vector.rb', line 1244 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.

647	# File 'lib/farce/abstract/vector.rb', line 647 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:

(Vector, Enumerator)

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

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_ary ⇒ `Array<BasicObject>`

Return an Array snapshot for implicit Array conversion, such as [].concat(vector).

Returns:

(Array<BasicObject>) —
A new Array of logical values.

62	# File 'lib/farce/abstract/vector.rb', line 62 def to_ary = to_a

#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.

108	# File 'lib/farce/abstract/vector.rb', line 108 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, &)

#transpose ⇒ `Vector`

Transpose rows represented by Arrays or Vectors.

Returns:

(Vector) —
A Vector containing same-kind column Vectors.

Raises:

(IndexError) —
If rows have different lengths.

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

def transpose
  retained = {}.compare_by_identity
  rows = to_a.map { sequence_operand(it, retained) }
  columns = rows.transpose.map { build_derived_vector(sequence_storage(it, retained)) }
  build_derived_values(columns)
end

#union(*others) ⇒ `Vector`

Union with every supplied sequence.

Parameters:

others (Array<Vector, #to_ary>) —
The other sequences.

Returns:

(Vector) —
The resulting entries.

739	# File 'lib/farce/abstract/vector.rb', line 739 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:

(Vector)

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

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

#uniq! {|value| ... } ⇒ `self`^?

Remove duplicate entries atomically, retaining the first stored entry. The block must not write to this vector.

Yields:

(value) —
Optionally compute a key for each logical value.

Yield Parameters:

value (BasicObject) —
The current value.

Yield Returns:

(BasicObject) —
The key compared using hash and eql?.

Returns:

(self, nil) —
Self if entries were removed, otherwise nil.

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

def uniq!
  changed = mutate_vector do |values|
    values.uniq! { block_given? ? yield(logical_value(it)) : logical_value(it) }
  end
  self if changed
end

#unshift(*values) ⇒ `self` Also known as: prepend

Prepend values atomically using the vector's default transfer mode.

Parameters:

values (Array<BasicObject>) —
The values to prepend.

Returns:

(self)

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

def unshift(*values)
  mutate_vector { it.unshift(*values.map { derived_storage(it) }) }
  self
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.

1272	# File 'lib/farce/abstract/vector.rb', line 1272 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.

1282	# File 'lib/farce/abstract/vector.rb', line 1282 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.

183	# File 'lib/farce/abstract/vector.rb', line 183 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

1293	# File 'lib/farce/abstract/vector.rb', line 1293 def wait_until(index, timeout: nil, &) = Internal.wait_until(internal_vector, 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.



1339
1340
1341

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

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



1330
1331
1332

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

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.

1350	# File 'lib/farce/abstract/vector.rb', line 1350 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



1321
1322
1323

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

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

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

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



1312
1313
1314

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

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.

1344	# File 'lib/farce/abstract/vector.rb', line 1344 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.

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

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.

724	# File 'lib/farce/abstract/vector.rb', line 724 def \|(other) = derive_array_operation(:\|, other)

Class: Farce::Abstract::Vector Abstract

Overview

Direct Known Subclasses

JSON Integration collapse

ActiveSupport Integration collapse

Methods included from Internal::Copyable

Instance Method Summary collapse

Methods inherited from Collection

Instance Method Details

#&(other) ⇒ Vector

#*(other) ⇒ Vector, String

#+(other) ⇒ Vector

#-(other) ⇒ Vector

#<<(value) ⇒ self

#<=>(other) ⇒ Integer?

#[](index, length = UNDEFINED) ⇒ BasicObject, ...

#[]=(index, value, replacement = UNDEFINED) ⇒ BasicObject

#append(*values, timeout: nil) ⇒ self, false

#as_extended_json(**options) ⇒ Array

#as_json(options = nil) ⇒ Array

#assoc(key) ⇒ Array, ...

#at(index) ⇒ BasicObject, ...

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

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

#bson_type ⇒ String

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

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

#clear ⇒ self

#combination(count) {|tuple| ... } ⇒ self, Enumerator

#compact ⇒ Vector

#compact! ⇒ self?

#compact_blank ⇒ Vector

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

#compare_by_identity? ⇒ Boolean

#concat(*sources) ⇒ self

#deconstruct ⇒ Array<BasicObject>

#deep_dup ⇒ Vector

#delete(value) {|value| ... } ⇒ BasicObject?

#delete_at(index) ⇒ BasicObject?

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

#difference(*others) ⇒ Vector

#dig(index, *identifiers) ⇒ BasicObject?

#drop(count) ⇒ Vector

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

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

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

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

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

#entries ⇒ Vector

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

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

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

#fifth ⇒ BasicObject?

#fill(value, start = 0, length = size) ⇒ self #fill(start = 0, length = size) {|index| ... } ⇒ self

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

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

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

#flatten(level = -1)) ⇒ Vector

#flatten!(level = -1)) ⇒ self?

#forty_two ⇒ BasicObject?

#fourth ⇒ BasicObject?

#from(position) ⇒ Vector

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

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

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

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

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

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

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

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

#including(*elements) ⇒ Vector

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

#inquiry ⇒ ActiveSupport::ArrayInquirer

#insert(index, *values) ⇒ self

#intersect?(other) ⇒ Boolean

#intersection(*others) ⇒ Vector

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

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

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

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

#&(other) ⇒ `Vector`

#*(other) ⇒ `Vector`, `String`

#+(other) ⇒ `Vector`

#-(other) ⇒ `Vector`

#<<(value) ⇒ `self`

#<=>(other) ⇒ `Integer`^?

#[](index, length = UNDEFINED) ⇒ `BasicObject`, ...

#[]=(index, value, replacement = UNDEFINED) ⇒ `BasicObject`

#append(*values, timeout: nil) ⇒ `self`, `false`

#as_extended_json(**options) ⇒ `Array`

#as_json(options = nil) ⇒ `Array`

#assoc(key) ⇒ `Array`, ...

#at(index) ⇒ `BasicObject`, ...

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

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

#bson_type ⇒ `String`

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

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

#clear ⇒ `self`

#combination(count) {|tuple| ... } ⇒ `self`, `Enumerator`

#compact ⇒ `Vector`

#compact! ⇒ `self`^?

#compact_blank ⇒ `Vector`

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

#compare_by_identity? ⇒ `Boolean`

#concat(*sources) ⇒ `self`

#deconstruct ⇒ `Array<BasicObject>`

#deep_dup ⇒ `Vector`

#delete(value) {|value| ... } ⇒ `BasicObject`^?

#delete_at(index) ⇒ `BasicObject`^?

#delete_if {|value| ... } ⇒ `self`, `Enumerator`

#difference(*others) ⇒ `Vector`

#dig(index, *identifiers) ⇒ `BasicObject`^?

#drop(count) ⇒ `Vector`

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

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

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

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

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

#entries ⇒ `Vector`

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

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

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

#fifth ⇒ `BasicObject`^?

#fill(value, start = 0, length = size) ⇒ `self` #fill(start = 0, length = size) {|index| ... } ⇒ `self`

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

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

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

#flatten(level = -1)) ⇒ `Vector`

#flatten!(level = -1)) ⇒ `self`^?

#forty_two ⇒ `BasicObject`^?

#fourth ⇒ `BasicObject`^?

#from(position) ⇒ `Vector`

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

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

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

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

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

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

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

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

#including(*elements) ⇒ `Vector`

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

#inquiry ⇒ `ActiveSupport::ArrayInquirer`

#insert(index, *values) ⇒ `self`

#intersect?(other) ⇒ `Boolean`

#intersection(*others) ⇒ `Vector`

#keep_if {|value| ... } ⇒ `self`, `Enumerator`

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

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

#map! {|value| ... } ⇒ `self`, `Enumerator` Also known as: collect!

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

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

#maximum(key) ⇒ `BasicObject`^?

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

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

#minimum(key) ⇒ `BasicObject`^?

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

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

#pack(format, buffer: nil) ⇒ `String`