Class: Net::IMAP::SearchResult

Inherits:
Array
  • Object
show all
Defined in:
lib/net/imap/search_result.rb

Overview

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.

Compatibility with ESearchResult

Note that both SearchResult and ESearchResult implement each, to_a, and to_sequence_set. These methods can be used regardless of whether the server returns SEARCH or ESEARCH data (or no data).

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(seq_nums, modseq: nil) ⇒ SearchResult

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]



35
36
37
38
 
# File 'lib/net/imap/search_result.rb', line 35

def initialize(seq_nums, modseq: nil)
  super(seq_nums.to_ary.map { Integer _1 })
  @modseq = Integer modseq if modseq
end

Instance Attribute Details

#modseq ⇒ Object (readonly)

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



29
30
31
 
# File 'lib/net/imap/search_result.rb', line 29

def modseq
  @modseq
end

Class Method Details

.[](*seq_nums, modseq: nil) ⇒ Object

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]



22
23
24
 
# File 'lib/net/imap/search_result.rb', line 22

def self.[](*seq_nums, modseq: nil)
  new(seq_nums, modseq: modseq)
end

Instance Method Details

#==(other) ⇒ Object

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



68
69
70
71
72
73
 
# File 'lib/net/imap/search_result.rb', line 68

def ==(other)
  other.is_a?(Array) &&
    modseq == (other.modseq if other.respond_to?(:modseq)) &&
    size == other.size &&
    sort == other.sort
end

#eql?(other) ⇒ Boolean

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

Returns:

  • (Boolean) 


82
83
84
85
 
# File 'lib/net/imap/search_result.rb', line 82

def eql?(other)
  return super if modseq.nil?
  self.class == other.class && hash == other.hash
end

#hash ⇒ Object

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



76
77
78
79
 
# File 'lib/net/imap/search_result.rb', line 76

def hash
  return super if modseq.nil?
  [super, self.class, modseq].hash
end

#inspect ⇒ Object

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]"



95
96
97
98
 
# File 'lib/net/imap/search_result.rb', line 95

def inspect
  return super if modseq.nil?
  "%s[%s, modseq: %p]" % [self.class, join(", "), modseq]
end

#pretty_print(pp) ⇒ Object 



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/net/imap/search_result.rb', line 128

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") ⇒ Object

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]
data.to_s           # => "* SEARCH 1 3 16 1024 (MODSEQ 2048)"
data.to_s("SORT")   # => "* SORT 1 3 16 1024 (MODSEQ 2048)"
data.to_s(nil)      # => "1 3 16 1024 (MODSEQ 2048)"



113
114
115
116
117
118
119
 
# File 'lib/net/imap/search_result.rb', line 113

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 ⇒ Object

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"]



126
 
# File 'lib/net/imap/search_result.rb', line 126

def to_sequence_set; SequenceSet[*self] end