Class: Farce::Abstract::Set Abstract

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

Overview

This class is abstract.

Common interface for concurrent sets backed by Farce maps.

Membership changes are atomic per element. Operations involving several elements are not atomic as a whole. Iteration streams without first copying every element. Structural changes during traversal can invalidate it. Identity comparison and normalization are fixed at construction, so this class does not provide Set#compare_by_identity or Set#reset.

BSON Integration collapse

CBOR Integration collapse

ActiveSupport Integration collapse

JSON Integration collapse

Instance Method Summary collapse

Methods inherited from Collection

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

Constructor Details

#initialize(enumerable = nil, normalize: nil, compare_by_identity: false, mode: UNDEFINED, **options) {|element| ... } ⇒ Farce::Abstract::Set

Construct a set, optionally transforming each initial element before normalization.

Parameters:

  • enumerable (#each, nil) (defaults to: nil) —

    The initial elements, or nil for an empty set.

  • normalize (Symbol, Proc, Hash, Farce::Abstract::Map, nil) (defaults to: nil) —

    The element normalizer.

  • compare_by_identity (Boolean) (defaults to: false) —

    Whether membership uses object identity.

  • mode (Symbol) (defaults to: UNDEFINED) —

    The default transfer mode for Farce::Set, Farce::SortedSet, and Farce::WeakSet. Defaults to :copy for strong sets and :raise for WeakSet.

  • options (Hash) —

    Additional options for the selected variant.

Options Hash (**options):

  • scope (Symbol) — default: :ractor —

    The scope used by Farce::Local variants.

Yields:

  • (element) —

    Optionally transform each initial element before storage.

Yield Parameters:

  • element (BasicObject) —

    An element from enumerable.

Yield Returns:

  • (BasicObject) —

    The element to normalize and store.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/farce/abstract/set.rb', line 71

def initialize(
  enumerable = nil, normalize: nil, compare_by_identity: false, mode: UNDEFINED, **options, &transform
)
  unknown = options.keys - [:scope]

  unless unknown.empty?
    label = unknown.size == 1 ? "keyword" : "keywords"
    raise ArgumentError, "unknown #{label}: #{unknown.map(&:inspect).join(", ")}"
  end

  shareable = !is_a?(Unshareable)

  validate_boolean!(:compare_by_identity, compare_by_identity)

  @compare_by_identity = compare_by_identity
  @normalizer          = Internal::KeyNormalizer.build(normalize, shareable:)
  restoring            = Internal::KeyNormalizer.restoration?(normalize)

  initialize_value_mode(mode)
  elements = input_elements(enumerable) unless enumerable.nil?
  elements.map! { transform.call(it) } if transform && elements
  elements.map! { normalize_element(it) } if elements && @normalizer && !restoring

  if value_modes?
    @map = new_map(nil, compare_keys_by_identity: false, **options)
    elements&.each { add_normalized(it) }
  else
    entries = elements&.map { [it, true] }
    @map = new_map(entries, compare_keys_by_identity: compare_by_identity, **options)
  end

  super()
end

Instance Method Details

#<=>(other) ⇒ Integer?

Compare sets by the subset relation.

Parameters:

  • other (BasicObject) —

    The object to compare against.

Returns:

  • (Integer, nil) —

    -1 for a proper subset, 0 for equal sets, 1 for a proper superset, or nil when neither relation holds or other is not a set.



469
470
471
472
473
474
 
# File 'lib/farce/abstract/set.rb', line 469

def <=>(other)
  return unless set_like?(other)
  return 0  if self == other
  return -1 if proper_subset?(other)
  1 if proper_superset?(other)
end

#==(other) ⇒ Boolean

Return whether this set has the same members as another set.

Parameters:

  • other (BasicObject) —

    The object to compare against.

Returns:

  • (Boolean) —

    Whether other is a Farce set with compatible comparison settings and equal members.



543
544
545
546
547
548
549
 
# File 'lib/farce/abstract/set.rb', line 543

def ==(other)
  return true if equal?(other)
  return false unless other.is_a?(Abstract::Set) && size == other.size
  return false unless comparison_compatible?(other)
  index = other.equality_index
  equality_index.each_key.all? { index.key?(it) }
end

#^(other) ⇒ Farce::Abstract::Set

Return a same-kind set containing elements present in exactly one operand.

Parameters:

  • other (#each) —

    The other collection of elements.

Returns:



394
395
396
397
 
# File 'lib/farce/abstract/set.rb', line 394

def ^(other)
  other = empty_copy.merge(other)
  (self - other).merge(other - self)
end

#add(element, mode: UNDEFINED) ⇒ self Also known as: <<

Add an element and return self.

Parameters:

  • element (BasicObject) —

    The element to normalize and store.

  • mode (Symbol, nil) (defaults to: UNDEFINED) —

    Override the transfer mode for this insertion. Only Farce::Set, Farce::SortedSet, and Farce::WeakSet accept this option. Nil uses the set's default.

Returns:

  • (self) —

    The set.



157
158
159
160
161
 
# File 'lib/farce/abstract/set.rb', line 157

def add(element, mode: UNDEFINED)
  check_frozen!
  add_normalized(normalize_element(element), mode:)
  self
end

#add?(element, mode: UNDEFINED) ⇒ self?

Add an absent element and return self, or nil if it was already present.

Parameters:

  • element (BasicObject) —

    The element to normalize and store.

  • mode (Symbol, nil) (defaults to: UNDEFINED) —

    Override the transfer mode for this insertion. Only Farce::Set, Farce::SortedSet, and Farce::WeakSet accept this option. Nil uses the set's default.

Returns:

  • (self, nil) —

    The set if added, otherwise nil.



169
170
171
172
173
 
# File 'lib/farce/abstract/set.rb', line 169

def add?(element, mode: UNDEFINED) # rubocop:disable Naming/PredicateMethod
  check_frozen!
  added = add_normalized?(normalize_element(element), mode:)
  self if added
end

#as_extended_json(**options) ⇒ Array

Note:

This method is only available if BSON has been loaded.

Represent current members as Extended JSON, forwarding BSON's format options.

Parameters:

  • options (Hash) —

    Options forwarded to Array#as_extended_json.

Returns:

  • (Array) —

    The Extended JSON representation.



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

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 the elements through ActiveSupport's Array JSON conversion.

Returns The JSON-compatible values.

Parameters:

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

    Options passed to each element's JSON conversion.

Returns:

  • (Array) —

    The JSON-compatible values.



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

def as_json(...) = to_a.as_json(...)

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



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

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

#classify {|element| ... } ⇒ Hash{BasicObject => Farce::Abstract::Set}, Enumerator

Group elements by the block result.

Yields:

  • (element) —

    Choose a group for each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    The group key.

Returns:

  • (Hash{BasicObject => Farce::Abstract::Set}, Enumerator) —

    Group keys mapped to same-kind subsets, or an Enumerator without a block.



482
483
484
485
486
487
488
489
490
491
 
# File 'lib/farce/abstract/set.rb', line 482

def classify
  return enum_for(__method__) { size } unless block_given?
  groups = {}
  each_stored do |stored_key, stored_value|
    element = public_stored(stored_key, stored_value)
    key = yield element
    (groups[key] ||= empty_copy).add_stored(stored_key, stored_value)
  end
  groups
end

#clear ⇒ self

Remove all elements and return self.

Returns:

  • (self) 


234
235
236
237
238
 
# File 'lib/farce/abstract/set.rb', line 234

def clear
  check_frozen!
  @map.clear
  self
end

#compact_blank ⇒ Farce::Abstract::Set

Note:

This methods is only available if ActiveSupport has been loaded.

Return a same-kind set without blank elements.

Returns:



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

def compact_blank = reject(&:blank?)

#compact_blank! ⇒ self

Note:

This methods is only available if ActiveSupport has been loaded.

Remove blank elements and return self.

Returns:

  • (self) 


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

def compact_blank! = delete_if(&:blank?)

#compare_by_identity? ⇒ Boolean

Return whether membership uses object identity.

Returns:

  • (Boolean) —

    Whether identity comparison is enabled.



534
 
# File 'lib/farce/abstract/set.rb', line 534

def compare_by_identity? = @compare_by_identity

#deep_dup ⇒ Farce::Abstract::Set

Note:

This methods is only available if ActiveSupport has been loaded.

Deeply copy elements into a set of the same kind with the same settings. Copied elements pass through the set's normal storage rules. Weak results do not keep copied heap elements alive by themselves.

Returns:



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

def deep_dup = map_canonical(&:deep_dup)

#delete(element) ⇒ self

Remove an element and return self.

Parameters:

  • element (BasicObject) —

    The element to normalize and look up.

Returns:

  • (self) —

    The set.



178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/farce/abstract/set.rb', line 178

def delete(element)
  check_frozen!
  element = normalize_element(element)
  if value_modes?
    key = lookup_key(element)
    @map.delete(key) unless MISSING_KEY.equal?(key)
  else
    @map.delete(element)
  end
  self
end

#delete?(element) ⇒ self?

Remove an element and return self, or nil if it was absent.

Parameters:

  • element (BasicObject) —

    The element to normalize and look up.

Returns:

  • (self, nil) —

    The set if removed, otherwise nil.



193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/farce/abstract/set.rb', line 193

def delete?(element) # rubocop:disable Naming/PredicateMethod
  check_frozen!
  element = normalize_element(element)
  removed = if value_modes?
              key = lookup_key(element)
              @map.delete(key) unless MISSING_KEY.equal?(key)
            else
              @map.delete(element)
            end
  self if removed
end

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

Remove elements accepted by the block.

Yields:

  • (element) —

    Test each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    A truthy value to remove the element.

Returns:

  • (self, Enumerator) —

    The set, or an Enumerator without a block.



277
278
279
280
281
282
 
# File 'lib/farce/abstract/set.rb', line 277

def delete_if
  return enum_for(__method__) { size } unless block_given?
  check_frozen!
  each_stored { |key, value| @map.delete(key) if yield(public_stored(key, value)) }
  self
end

#difference(enumerable) ⇒ Farce::Abstract::Set Also known as: -

Return a same-kind set without elements from the enumerable.

Parameters:

  • enumerable (#each) —

    The elements to exclude.

Returns:



377
 
# File 'lib/farce/abstract/set.rb', line 377

def difference(enumerable) = dup.subtract(enumerable)

#disjoint?(other) ⇒ Boolean

Return whether this set and another set-like object share no elements.

Parameters:

Returns:

  • (Boolean) —

    Whether the relation holds.

Raises:

  • (ArgumentError) —

    If other is not a Farce or Ruby set.



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

def disjoint?(other) = !intersect?(other)

#divide({ |element| ... }) {|element| ... } ⇒ Farce::Unshared::Set #divide({ |left, right| ... }) {|left, right| ... } ⇒ Farce::Unshared::Set #divide ⇒ Enumerator

Divide elements into same-kind subsets. The outer result is an Unshared::Set that holds the subsets strongly.

Overloads:

  • #divide({ |element| ... }) {|element| ... } ⇒ Farce::Unshared::Set

    Group elements that produce the same block result.

    Yields:

    • (element) —

      Choose a group for each element.

    Yield Parameters:

    • element (BasicObject) —

      The current element.

    Yield Returns:

    • (BasicObject) —

      The group key.

    Returns:

  • #divide({ |left, right| ... }) {|left, right| ... } ⇒ Farce::Unshared::Set

    Compute strongly connected components using a two-argument block.

    Yields:

    • (left, right) —

      Test the directed relation between two elements.

    Yield Parameters:

    • left (BasicObject) —

      The source element.

    • right (BasicObject) —

      The candidate related element.

    Yield Returns:

    • (BasicObject) —

      A truthy value when left is related to right.

    Returns:

  • #divide ⇒ Enumerator

    Returns An Enumerator that divides the set when given a block.

    Returns:

    • (Enumerator) —

      An Enumerator that divides the set when given a block.



511
512
513
514
515
516
517
518
519
520
521
 
# File 'lib/farce/abstract/set.rb', line 511

def divide(&block)
  return enum_for(__method__) { size } unless block
  groups = if block.arity == 2
             # Ruby 3.4 also requires TSort here, inside Set#divide.
             require "tsort"
             divide_by_relation(&block)
           else
             classify(&block).values
           end
  Farce::Unshared::Set.new(groups)
end

#duplicable? ⇒ Boolean

Note:

This methods is only available if ActiveSupport has been loaded.

Returns true.

Returns:

  • (Boolean) —

    true



43
 
# File 'lib/farce/integrations/active_support/duplicable.rb', line 43

def duplicable? = true

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

Iterate over the elements currently present without first copying all elements.

Yields:

  • (element) —

    Visit each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (void) —

    The result is ignored.

Returns:

  • (self, Enumerator) —

    The set, or an Enumerator without a block.



222
223
224
225
226
 
# File 'lib/farce/abstract/set.rb', line 222

def each
  return enum_for(__method__) { size } unless block_given?
  each_element { yield it }
  self
end

#eql?(other) ⇒ Boolean

Compare membership using eql?.

Parameters:

  • other (BasicObject) —

    The object to compare against.

Returns:

  • (Boolean) —

    Whether other is a Farce set with compatible comparison settings and equal members.



554
555
556
557
558
559
560
 
# File 'lib/farce/abstract/set.rb', line 554

def eql?(other)
  return true if equal?(other)
  return false unless other.is_a?(Abstract::Set) && size == other.size
  return false unless comparison_compatible?(other)
  index = other.equality_index
  equality_index.each_key.all? { index.key?(it) }
end

#excluding(*elements) ⇒ Farce::Abstract::Set Also known as: without

Note:

This methods is only available if ActiveSupport has been loaded.

Return a same-kind set without the supplied elements. Array arguments are flattened by one level.

Parameters:

  • elements (Array<BasicObject>) —

    Elements or Arrays of elements to remove.

Returns:



38
 
# File 'lib/farce/integrations/active_support/set.rb', line 38

def excluding(*elements) = difference(elements.flatten(1))

#flatten ⇒ Farce::Abstract::Set

Return a flattened same-kind set.

Returns:

Raises:

  • (ArgumentError) —

    If a nested set contains itself recursively.



526
527
528
529
530
 
# File 'lib/farce/abstract/set.rb', line 526

def flatten
  copy = empty_copy
  flatten_into(self, copy, ::Set.new.compare_by_identity)
  copy
end

#hash ⇒ Integer

Return an order-independent hash derived from the members.

Returns:

  • (Integer) —

    The hash code.



564
565
566
567
568
569
570
571
572
573
 
# File 'lib/farce/abstract/set.rb', line 564

def hash
  guard = recursion_guard(:farce_set_hash_guard)
  return 0 if guard.key?(self)
  guard[self] = true
  entered     = true
  set         = ::Set.new
  set.merge(equality_index.keys).hash
ensure
  guard&.delete(self) if entered
end

#include?(element) ⇒ Boolean Also known as: member?, ===

Return whether an element is present.

Parameters:

  • element (BasicObject) —

    The element to normalize and look up.

Returns:

  • (Boolean) —

    Whether the normalized element is present.



208
209
210
211
212
213
 
# File 'lib/farce/abstract/set.rb', line 208

def include?(element)
  element = normalize_element(element)
  return @map.key?(element) unless value_modes?
  key = lookup_key(element)
  !MISSING_KEY.equal?(key) && @map.key?(key)
end

#including(*elements) ⇒ Farce::Abstract::Set

Note:

This methods is only available if ActiveSupport has been loaded.

Return a same-kind set with elements added. Array arguments are flattened by one level.

Parameters:

  • elements (Array<BasicObject>) —

    Elements or Arrays of elements to add.

Returns:



32
 
# File 'lib/farce/integrations/active_support/set.rb', line 32

def including(*elements) = union(elements.flatten(1))

#intersect?(other) ⇒ Boolean

Return whether this set and another set-like object share an element.

Parameters:

Returns:

  • (Boolean) —

    Whether the relation holds.

Raises:

  • (ArgumentError) —

    If other is not a Farce or Ruby set.



451
452
453
454
455
456
457
 
# File 'lib/farce/abstract/set.rb', line 451

def intersect?(other)
  validate_set_like(other)
  left  = equality_index
  right = relation_index(other)
  left, right = right, left if right.size < left.size
  left.each_key.any? { right.key?(it) }
end

#intersection(*enumerables) ⇒ Farce::Abstract::Set Also known as: &

Return a same-kind set containing elements also present in every enumerable.

Parameters:

  • enumerables (Array<#each>) —

    The collections whose members must be present.

Returns:



383
384
385
386
387
388
 
# File 'lib/farce/abstract/set.rb', line 383

def intersection(*enumerables)
  copy = dup
  indexes = enumerables.map { membership_index(it) }
  copy.filter_stored! { |key, _| indexes.all? { it.key?(key) } }
  copy
end

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

Keep elements accepted by the block.

Yields:

  • (element) —

    Test each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    A truthy value to keep the element.

Returns:

  • (self, Enumerator) —

    The set, or an Enumerator without a block.



289
290
291
292
293
294
 
# File 'lib/farce/abstract/set.rb', line 289

def keep_if
  return enum_for(__method__) { size } unless block_given?
  check_frozen!
  each_stored { |key, value| @map.delete(key) unless yield(public_stored(key, value)) }
  self
end

#merge(*enumerables) ⇒ self

Add all elements yielded by each enumerable.

Parameters:

  • enumerables (Array<#each>) —

    The collections of elements to add.

Returns:

  • (self) —

    The set.



243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/farce/abstract/set.rb', line 243

def merge(*enumerables)
  check_frozen!
  enumerables.each do |enumerable|
    if canonical_compatible?(enumerable)
      enumerable.each_stored { |key, value| add_stored(key, value) }
    else
      each_input(enumerable) { add(it) }
    end
  end
  self
end

#proper_subset?(other) ⇒ Boolean Also known as: <

Return whether this is a proper subset of the other set-like object.

Parameters:

Returns:

  • (Boolean) —

    Whether the relation holds.

Raises:

  • (ArgumentError) —

    If other is not a Farce or Ruby set.



415
416
417
418
419
420
 
# File 'lib/farce/abstract/set.rb', line 415

def proper_subset?(other)
  validate_set_like(other)
  left  = equality_index
  right = relation_index(other)
  left.size < right.size && left.each_key.all? { right.key?(it) }
end

#proper_superset?(other) ⇒ Boolean Also known as: >

Return whether this is a proper superset of the other set-like object.

Parameters:

Returns:

  • (Boolean) —

    Whether the relation holds.

Raises:

  • (ArgumentError) —

    If other is not a Farce or Ruby set.



439
440
441
442
443
444
 
# File 'lib/farce/abstract/set.rb', line 439

def proper_superset?(other)
  validate_set_like(other)
  left  = equality_index
  right = relation_index(other)
  left.size > right.size && right.each_key.all? { left.key?(it) }
end

#reject {|element| ... } ⇒ Farce::Abstract::Set, Enumerator

Return a same-kind set without elements accepted by the block.

Yields:

  • (element) —

    Test each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    A truthy value to exclude the element.

Returns:



312
313
314
315
 
# File 'lib/farce/abstract/set.rb', line 312

def reject
  return enum_for(__method__) { size } unless block_given?
  dup.filter_backend! { !yield(it) }
end

#reject! {|element| ... } ⇒ self, ...

Remove elements accepted by the block, returning nil when unchanged.

Yields:

  • (element) —

    Test each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    A truthy value to remove the element.

Returns:

  • (self, nil, Enumerator) —

    The changed set, nil if unchanged, or an Enumerator without a block.



322
323
324
325
326
327
328
329
330
 
# File 'lib/farce/abstract/set.rb', line 322

def reject!
  return enum_for(__method__) { size } unless block_given?
  check_frozen!
  changed = false
  each_stored do |key, value|
    changed = true if yield(public_stored(key, value)) && @map.delete(key)
  end
  self if changed
end

#select {|element| ... } ⇒ Farce::Abstract::Set, Enumerator Also known as: filter

Return a same-kind set containing elements accepted by the block.

Yields:

  • (element) —

    Test each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    A truthy value to keep the element.

Returns:



301
302
303
304
 
# File 'lib/farce/abstract/set.rb', line 301

def select
  return enum_for(__method__) { size } unless block_given?
  dup.filter_backend! { yield it }
end

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

Keep elements accepted by the block, returning nil when unchanged.

Yields:

  • (element) —

    Test each element. Returns an Enumerator without a block.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    A truthy value to keep the element.

Returns:

  • (self, nil, Enumerator) —

    The changed set, nil if unchanged, or an Enumerator without a block.



337
338
339
340
341
342
343
344
345
 
# File 'lib/farce/abstract/set.rb', line 337

def select!
  return enum_for(__method__) { size } unless block_given?
  check_frozen!
  changed = false
  each_stored do |key, value|
    changed = true if !yield(public_stored(key, value)) && @map.delete(key)
  end
  self if changed
end

#size ⇒ Integer

Return the number of elements currently present.

Returns:

  • (Integer) 


230
 
# File 'lib/farce/abstract/set.rb', line 230

def size = @map.size

#subset?(other) ⇒ Boolean Also known as: <=

Return whether every element is present in the other set-like object.

Parameters:

Returns:

  • (Boolean) —

    Whether the relation holds.

Raises:

  • (ArgumentError) —

    If other is not a Farce or Ruby set.



403
404
405
406
407
408
 
# File 'lib/farce/abstract/set.rb', line 403

def subset?(other)
  validate_set_like(other)
  left  = equality_index
  right = relation_index(other)
  left.size <= right.size && left.each_key.all? { right.key?(it) }
end

#subtract(enumerable) ⇒ self

Remove every element yielded by enumerable.

Parameters:

  • enumerable (#each) —

    The elements to remove.

Returns:

  • (self) —

    The set.



258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/farce/abstract/set.rb', line 258

def subtract(enumerable)
  check_frozen!
  if canonical_compatible?(enumerable)
    retained = membership_index(enumerable)
    @map.delete_if { |element, _| retained.key?(element) }
  else
    each_input(enumerable) do |element|
      key = lookup_key(normalize_element(element))
      @map.delete(key) unless MISSING_KEY.equal?(key)
    end
  end
  self
end

#superset?(other) ⇒ Boolean Also known as: >=

Return whether all elements of the other set-like object are present.

Parameters:

Returns:

  • (Boolean) —

    Whether the relation holds.

Raises:

  • (ArgumentError) —

    If other is not a Farce or Ruby set.



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

def superset?(other)
  validate_set_like(other)
  left  = equality_index
  right = relation_index(other)
  left.size >= right.size && right.each_key.all? { left.key?(it) }
end

#to_a ⇒ Array<BasicObject>

Return the elements in an Array.

Returns:

  • (Array<BasicObject>) —

    The observed elements.



350
 
# File 'lib/farce/abstract/set.rb', line 350

def to_a = each.to_a

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

Note:

This method is only available if BSON has been loaded.

Serialize current members 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.



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

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 current members with nested values normalized by BSON.

Returns:

  • (Array) —

    The normalized array.



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

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 current members as a CBOR array.

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.



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

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

#to_json(*arguments) ⇒ String

Note:

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

Serialize current members as a JSON Array.

Returns The generated JSON.

Parameters:

  • arguments (Array<Object>) —

    Arguments forwarded to Array#to_json.

Returns:

  • (String) —

    The generated JSON.



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

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 current members as a MessagePack array.

Parameters:

  • arguments (Array<Object>) —

    Arguments forwarded to Array#to_msgpack.

Returns:

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

    The encoded bytes or supplied packer.



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

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

#to_param ⇒ String

Note:

This methods is only available if ActiveSupport has been loaded.

Return the elements' ActiveSupport parameter representation.

Returns:

  • (String) 


51
 
# File 'lib/farce/integrations/active_support/set.rb', line 51

def to_param = to_a.to_param

#to_query(key) ⇒ String

Note:

This methods is only available if ActiveSupport has been loaded.

Encode the elements as repeated query parameters under a key.

Parameters:

  • key (String, Symbol) —

    The query parameter name.

Returns:

  • (String) —

    The encoded query string.



57
 
# File 'lib/farce/integrations/active_support/set.rb', line 57

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

#to_set(klass = ::Set, *arguments, **options) {|element| ... } ⇒ ::Set, Farce::Abstract::Set

Convert to a Ruby Set, or to an explicitly requested set class.

Parameters:

  • klass (Class) (defaults to: ::Set) —

    The target set class. Defaults to Ruby's ::Set.

  • arguments (Array<BasicObject>) —

    Additional positional arguments for its constructor.

  • options (Hash) —

    Keyword arguments for its constructor.

Yields:

  • (element) —

    Optionally transform elements through the target constructor.

Yield Parameters:

  • element (BasicObject) —

    The current element.

Yield Returns:

  • (BasicObject) —

    The element to store in the target set.

Returns:

  • (::Set, Farce::Abstract::Set) —

    A new Ruby Set by default. An explicit target class matching self returns self when no arguments, options, or block are supplied. Otherwise, returns a new instance of klass.



362
363
364
365
 
# File 'lib/farce/abstract/set.rb', line 362

def to_set(klass = ::Set, *arguments, **options, &)
  return self if klass == self.class && arguments.empty? && options.empty? && !block_given?
  klass.new(self, *arguments, **options, &)
end

#union(*enumerables) ⇒ Farce::Abstract::Set Also known as: |, +

Return a same-kind set containing elements from either operand.

Parameters:

  • enumerables (Array<#each>) —

    The collections of elements to include.

Returns:



370
 
# File 'lib/farce/abstract/set.rb', line 370

def union(*enumerables) = dup.merge(*enumerables)

#weak? ⇒ Boolean

Return whether elements are held weakly.

Returns:

  • (Boolean) —

    Whether the set retains elements weakly.



538
 
# File 'lib/farce/abstract/set.rb', line 538

def weak? = @map.weak_keys?