class Net::IMAP::SearchResult

An array of sequence numbers returned by Net::IMAP#search, or unique identifiers returned by Net::IMAP#uid_search.

For backward compatibility, SearchResult inherits from Array.

Attributes

modseq[R]

A modification sequence number, as described by the CONDSTORE extension in [RFC7162 §3.1.6].

Public Class Methods

[](*seq_nums, modseq: nil) click to toggle source

Returns a SearchResult populated with the given seq_nums.

Net::IMAP::SearchResult[1, 3, 5, modseq: 9]
# => Net::IMAP::SearchResult[1, 3, 5, modseq: 9]

# File lib/net/imap/search_result.rb, line 16
def self.[](*seq_nums, modseq: nil)
  new(seq_nums, modseq: modseq)
end

new(seq_nums, modseq: nil) click to toggle source

Returns a SearchResult populated with the given seq_nums.

Net::IMAP::SearchResult.new([1, 3, 5], modseq: 9)
# => Net::IMAP::SearchResult[1, 3, 5, modseq: 9]

Calls superclass method

# File lib/net/imap/search_result.rb, line 29
def initialize(seq_nums, modseq: nil)
  super(seq_nums.to_ary.map { Integer _1 })
  @modseq = Integer modseq if modseq
end

Public Instance Methods

==(other) click to toggle source

Returns whether other is a SearchResult with the same values and the same modseq. The order of numbers is irrelevant.

Net::IMAP::SearchResult[123, 456, modseq: 789] ==
  Net::IMAP::SearchResult[123, 456, modseq: 789]
# => true
Net::IMAP::SearchResult[123, 456, modseq: 789] ==
  Net::IMAP::SearchResult[456, 123, modseq: 789]
# => true

Net::IMAP::SearchResult[123, 456, modseq: 789] ==
  Net::IMAP::SearchResult[987, 654, modseq: 789]
# => false
Net::IMAP::SearchResult[123, 456, modseq: 789] ==
  Net::IMAP::SearchResult[1, 2, 3, modseq: 9999]
# => false

SearchResult can be compared directly with Array, if modseq is nil and the array is sorted.

Net::IMAP::SearchResult[9, 8, 6, 4, 1] == [1, 4, 6, 8, 9] # => true
Net::IMAP::SearchResult[3, 5, 7, modseq: 99] == [3, 5, 7] # => false

Note that Array#== does require matching order and ignores modseq.

[9, 8, 6, 4, 1] == Net::IMAP::SearchResult[1, 4, 6, 8, 9] # => false
[3, 5, 7] == Net::IMAP::SearchResult[3, 5, 7, modseq: 99] # => true

# File lib/net/imap/search_result.rb, line 62
def ==(other)
  (modseq ?
   other.is_a?(self.class) && modseq == other.modseq :
   other.is_a?(Array)) &&
    size == other.size &&
    sort == other.sort
end

eql?(other) click to toggle source

Hash equality. Unlike ==, order will be taken into account.

Calls superclass method

# File lib/net/imap/search_result.rb, line 77
def eql?(other)
  return super if modseq.nil?
  self.class == other.class && hash == other.hash
end

hash click to toggle source

Hash equality. Unlike ==, order will be taken into account.

Calls superclass method

# File lib/net/imap/search_result.rb, line 71
def hash
  return super if modseq.nil?
  [super, self.class, modseq].hash
end

inspect click to toggle source

Returns a string that represents the SearchResult.

Net::IMAP::SearchResult[123, 456, 789].inspect
# => "[123, 456, 789]"

Net::IMAP::SearchResult[543, 210, 678, modseq: 2048].inspect
# => "Net::IMAP::SearchResult[543, 210, 678, modseq: 2048]"

Calls superclass method

# File lib/net/imap/search_result.rb, line 90
def inspect
  return super if modseq.nil?
  "%s[%s, modseq: %p]" % [self.class, join(", "), modseq]
end

pretty_print(pp) click to toggle source

Calls superclass method

# File lib/net/imap/search_result.rb, line 123
def pretty_print(pp)
  return super if modseq.nil?
  pp.text self.class.name + "["
  pp.group_sub do
    pp.nest(2) do
      pp.breakable ""
      each do |num|
        pp.pp num
        pp.text ","
        pp.fill_breakable
      end
      pp.breakable ""
      pp.text "modseq: "
      pp.pp modseq
    end
    pp.breakable ""
    pp.text "]"
  end
end

to_s(type = "SEARCH") click to toggle source

Returns a string that follows the formal IMAP syntax.

data = Net::IMAP::SearchResult[2, 8, 32, 128, 256, 512]
data.to_s           # => "* SEARCH 2 8 32 128 256 512"
data.to_s("SEARCH") # => "* SEARCH 2 8 32 128 256 512"
data.to_s("SORT")   # => "* SORT 2 8 32 128 256 512"
data.to_s(nil)      # => "2 8 32 128 256 512"

data = Net::IMAP::SearchResult[1, 3, 16, 1024, modseq: 2048].to_s
data.to_s           # => "* SEARCH 1 3 16 1024 (MODSEQ 2048)"
data.to_s("SORT")   # => "* SORT 1 3 16 1024 (MODSEQ 2048)"
data.to_s           # => "1 3 16 1024 (MODSEQ 2048)"

# File lib/net/imap/search_result.rb, line 108
def to_s(type = "SEARCH")
  str = +""
  str << "* %s " % [type.to_str] unless type.nil?
  str << join(" ")
  str << " (MODSEQ %d)" % [modseq] if modseq
  -str
end

to_sequence_set click to toggle source

Converts the SearchResult into a SequenceSet.

Net::IMAP::SearchResult[9, 1, 2, 4, 10, 12, 3, modseq: 123_456]
  .to_sequence_set
# => Net::IMAP::SequenceSet["1:4,9:10,12"]

# File lib/net/imap/search_result.rb, line 121
def to_sequence_set; SequenceSet[*self] end