Skip to content

📚 Impove SequenceSet docs #420

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 24, 2025
Merged

📚 Impove SequenceSet docs #420

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
779f356
📚 Consistently use "element" or "entry" vs "object"
nevans Feb 18, 2025
1d99e40
📚 Consistently use "sets" or "other" vs "object"
nevans Feb 18, 2025
6ce9f1b
📚 Improved SequenceSet[*inputs] documentation
nevans Feb 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 62 additions & 60 deletions lib/net/imap/sequence_set.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ class IMAP
#
# <i>Set membership:</i>
# - #include? (aliased as #member?):
# Returns whether a given object (nz-number, range, or <tt>*</tt>) is
# Returns whether a given element (nz-number, range, or <tt>*</tt>) is
# contained by the set.
# - #include_star?: Returns whether the set contains <tt>*</tt>.
#
Expand Down Expand Up @@ -239,13 +239,13 @@ class IMAP
# These methods do not modify +self+.
#
# - #| (aliased as #union and #+): Returns a new set combining all members
# from +self+ with all members from the other object.
# from +self+ with all members from the other set.
# - #& (aliased as #intersection): Returns a new set containing all members
# common to +self+ and the other object.
# common to +self+ and the other set.
# - #- (aliased as #difference): Returns a copy of +self+ with all members
# in the other object removed.
# in the other set removed.
# - #^ (aliased as #xor): Returns a new set containing all members from
# +self+ and the other object except those common to both.
# +self+ and the other set except those common to both.
# - #~ (aliased as #complement): Returns a new set containing all members
# that are not in +self+
# - #limit: Returns a copy of +self+ which has replaced <tt>*</tt> with a
Expand All @@ -258,17 +258,17 @@ class IMAP
#
# These methods always update #string to be fully sorted and coalesced.
#
# - #add (aliased as #<<): Adds a given object to the set; returns +self+.
# - #add?: If the given object is not an element in the set, adds it and
# - #add (aliased as #<<): Adds a given element to the set; returns +self+.
# - #add?: If the given element is not fully included the set, adds it and
# returns +self+; otherwise, returns +nil+.
# - #merge: Merges multiple elements into the set; returns +self+.
# - #merge: Adds all members of the given sets into this set; returns +self+.
# - #complement!: Replaces the contents of the set with its own #complement.
#
# <i>Order preserving:</i>
#
# These methods _may_ cause #string to not be sorted or coalesced.
#
# - #append: Adds a given object to the set, appending it to the existing
# - #append: Adds the given entry to the set, appending it to the existing
# string, and returns +self+.
# - #string=: Assigns a new #string value and replaces #elements to match.
# - #replace: Replaces the contents of the set with the contents
Expand All @@ -279,13 +279,14 @@ class IMAP
# sorted and coalesced.
#
# - #clear: Removes all elements in the set; returns +self+.
# - #delete: Removes a given object from the set; returns +self+.
# - #delete?: If the given object is an element in the set, removes it and
# - #delete: Removes a given element from the set; returns +self+.
# - #delete?: If the given element is included in the set, removes it and
# returns it; otherwise, returns +nil+.
# - #delete_at: Removes the number at a given offset.
# - #slice!: Removes the number or consecutive numbers at a given offset or
# range of offsets.
# - #subtract: Removes each given object from the set; returns +self+.
# - #subtract: Removes all members of the given sets from this set; returns
# +self+.
# - #limit!: Replaces <tt>*</tt> with a given maximum value and removes all
# members over that maximum; returns +self+.
#
Expand Down Expand Up @@ -318,9 +319,12 @@ class SequenceSet
class << self

# :call-seq:
# SequenceSet[*values] -> valid frozen sequence set
# SequenceSet[*inputs] -> valid frozen sequence set
#
# Returns a frozen SequenceSet, constructed from +values+.
# Returns a frozen SequenceSet, constructed from +inputs+.
#
# When only a single valid frozen SequenceSet is given, that same set is
# returned.
#
# An empty SequenceSet is invalid and will raise a DataFormatError.
#
Expand Down Expand Up @@ -690,16 +694,16 @@ def ~; remain_frozen dup.complement! end
alias complement :~

# :call-seq:
# add(object) -> self
# add(element) -> self
# self << other -> self
#
# Adds a range or number to the set and returns +self+.
#
# #string will be regenerated. Use #merge to add many elements at once.
#
# Related: #add?, #merge, #union
def add(object)
tuple_add input_to_tuple object
def add(element)
tuple_add input_to_tuple element
normalize!
end
alias << add
Expand All @@ -708,38 +712,38 @@ def add(object)
#
# Unlike #add, #merge, or #union, the new value is appended to #string.
# This may result in a #string which has duplicates or is out-of-order.
def append(object)
def append(entry)
modifying!
tuple = input_to_tuple object
tuple = input_to_tuple entry
entry = tuple_to_str tuple
string unless empty? # write @string before tuple_add
tuple_add tuple
@string = -(@string ? "#{@string},#{entry}" : entry)
self
end

# :call-seq: add?(object) -> self or nil
# :call-seq: add?(element) -> self or nil
#
# Adds a range or number to the set and returns +self+. Returns +nil+
# when the object is already included in the set.
# when the element is already included in the set.
#
# #string will be regenerated. Use #merge to add many elements at once.
#
# Related: #add, #merge, #union, #include?
def add?(object)
add object unless include? object
def add?(element)
add element unless include? element
end

# :call-seq: delete(object) -> self
# :call-seq: delete(element) -> self
#
# Deletes the given range or number from the set and returns +self+.
#
# #string will be regenerated after deletion. Use #subtract to remove
# many elements at once.
#
# Related: #delete?, #delete_at, #subtract, #difference
def delete(object)
tuple_subtract input_to_tuple object
def delete(element)
tuple_subtract input_to_tuple element
normalize!
end

Expand Down Expand Up @@ -775,8 +779,8 @@ def delete(object)
# #string will be regenerated after deletion.
#
# Related: #delete, #delete_at, #subtract, #difference, #disjoint?
def delete?(object)
tuple = input_to_tuple object
def delete?(element)
tuple = input_to_tuple element
if tuple.first == tuple.last
return unless include_tuple? tuple
tuple_subtract tuple
Expand Down Expand Up @@ -820,33 +824,31 @@ def slice!(index, length = nil)
deleted
end

# Merges all of the elements that appear in any of the +inputs+ into the
# Merges all of the elements that appear in any of the +sets+ into the
# set, and returns +self+.
#
# The +inputs+ may be any objects that would be accepted by ::new:
# non-zero 32 bit unsigned integers, ranges, <tt>sequence-set</tt>
# formatted strings, other sequence sets, or enumerables containing any of
# these.
# The +sets+ may be any objects that would be accepted by ::new: non-zero
# 32 bit unsigned integers, ranges, <tt>sequence-set</tt> formatted
# strings, other sequence sets, or enumerables containing any of these.
#
# #string will be regenerated after all inputs have been merged.
# #string will be regenerated after all sets have been merged.
#
# Related: #add, #add?, #union
def merge(*inputs)
tuples_add input_to_tuples inputs
def merge(*sets)
tuples_add input_to_tuples sets
normalize!
end

# Removes all of the elements that appear in any of the given +objects+
# from the set, and returns +self+.
# Removes all of the elements that appear in any of the given +sets+ from
# the set, and returns +self+.
#
# The +objects+ may be any objects that would be accepted by ::new:
# non-zero 32 bit unsigned integers, ranges, <tt>sequence-set</tt>
# formatted strings, other sequence sets, or enumerables containing any of
# these.
# The +sets+ may be any objects that would be accepted by ::new: non-zero
# 32 bit unsigned integers, ranges, <tt>sequence-set</tt> formatted
# strings, other sequence sets, or enumerables containing any of these.
#
# Related: #difference
def subtract(*objects)
tuples_subtract input_to_tuples objects
def subtract(*sets)
tuples_subtract input_to_tuples sets
normalize!
end

Expand Down Expand Up @@ -1386,30 +1388,30 @@ def initialize_dup(other)
super
end

def input_to_tuple(obj)
obj = input_try_convert obj
case obj
when *STARS, Integer then [int = to_tuple_int(obj), int]
when Range then range_to_tuple(obj)
when String then str_to_tuple(obj)
def input_to_tuple(entry)
entry = input_try_convert entry
case entry
when *STARS, Integer then [int = to_tuple_int(entry), int]
when Range then range_to_tuple(entry)
when String then str_to_tuple(entry)
else
raise DataFormatError, "expected number or range, got %p" % [obj]
raise DataFormatError, "expected number or range, got %p" % [entry]
end
end

def input_to_tuples(obj)
obj = input_try_convert obj
case obj
when *STARS, Integer, Range then [input_to_tuple(obj)]
when String then str_to_tuples obj
when SequenceSet then obj.tuples
when Set then obj.map { [to_tuple_int(_1)] * 2 }
when Array then obj.flat_map { input_to_tuples _1 }
def input_to_tuples(set)
set = input_try_convert set
case set
when *STARS, Integer, Range then [input_to_tuple(set)]
when String then str_to_tuples set
when SequenceSet then set.tuples
when Set then set.map { [to_tuple_int(_1)] * 2 }
when Array then set.flat_map { input_to_tuples _1 }
when nil then []
else
raise DataFormatError,
"expected nz-number, range, string, or enumerable; " \
"got %p" % [obj]
"got %p" % [set]
end
end

Expand Down