class Net::IMAP::ESearchResult

An “extended search” response (ESEARCH). ESearchResult should be returned (instead of SearchResult) by IMAP#search, IMAP#uid_search, IMAP#sort, and IMAP#uid_sort under any of the following conditions:

Return options were specified for IMAP#search or IMAP#uid_search. The server must support a search extension which allows RFC4466 return options, such as ESEARCH, PARTIAL, or IMAP4rev2.
Return options were specified for IMAP#sort or IMAP#uid_sort. The server must support the ESORT extension [RFC5267].

NOTE: IMAP#search and IMAP#uid_search do not support ESORT yet.
The server supports IMAP4rev2 but not IMAP4rev1, or IMAP4rev2 has been enabled. IMAP4rev2 requires ESEARCH results.

Note that some servers may claim to support a search extension which requires an ESEARCH result, such as PARTIAL, but still only return a SEARCH result when return options are specified.

Some search extensions may result in the server sending ESearchResult responses after the initiating command has completed. Use IMAP#add_response_handler to handle these responses.

Attributes

data [R]

Search return data, as an array of [name, value] pairs. Most return data corresponds to a search return option with the same name.

Note that some return data names may be used more than once per result.

This data can be more simply retrieved by min, max, all, count, modseq, and other methods.

tag [R]

The tag string for the command that caused this response to be returned.

When nil, this response was not caused by a particular command.

uid [R]

Indicates whether data in this response refers to UIDs (when true) or to message sequence numbers (when false).

uid? [R]

Indicates whether data in this response refers to UIDs (when true) or to message sequence numbers (when false).

Public Class Methods

new (tag: nil, uid: nil, data: nil)

Source

# File lib/net/imap/esearch_result.rb, line 29
def initialize(tag: nil, uid: nil, data: nil)
  tag  => String       | nil; tag = -tag if tag
  uid  => true | false | nil; uid = !!uid
  data => Array        | nil; data ||= []; data.freeze
  super
end

Calls superclass method

Public Instance Methods

all → sequence set or nil

Source

# File lib/net/imap/esearch_result.rb, line 147
def all;        data.assoc("ALL")&.last        end

A SequenceSet containing all message sequence numbers or UIDs that satisfy the SEARCH criteria.

Returns nil when the associated search command has no results, or when the ALL return option was not specified but other return options were.

Requires ESEARCH [RFC4731] or IMAP4rev2 [RFC9051].

See also: to_a

count → integer or nil

Source

# File lib/net/imap/esearch_result.rb, line 158
def count;      data.assoc("COUNT")&.last      end

Returns the number of messages that satisfy the SEARCH criteria.

Returns nil when the associated search command has no results, or when the COUNT return option wasn’t specified.

Requires ESEARCH [RFC4731] or IMAP4rev2 [RFC9051].

each (&)

Source

# File lib/net/imap/esearch_result.rb, line 80
def each(&)
  return to_enum(__callee__) unless block_given?
  to_sequence_set.each_number(&)
  self
end

When either all or partial contains a SequenceSet of message sequence numbers or UIDs, each yields each integer in the set.

When both all and partial are nil, either because the server returned no results or because ALL and PARTIAL were not included in the IMAP#search RETURN options, each does not yield.

Note that SearchResult also implements each, so it can be used without checking if the server returned SEARCH or ESEARCH data.

max → integer or nil

Source

# File lib/net/imap/esearch_result.rb, line 133
def max;        data.assoc("MAX")&.last        end

The highest message number/UID that satisfies the SEARCH criteria.

Returns nil when the associated search command has no results, or when the MAX return option wasn’t specified.

Requires ESEARCH [RFC4731] or IMAP4rev2 [RFC9051].

min → integer or nil

Source

# File lib/net/imap/esearch_result.rb, line 122
def min;        data.assoc("MIN")&.last        end

The lowest message number/UID that satisfies the SEARCH criteria.

Returns nil when the associated search command has no results, or when the MIN return option wasn’t specified.

Requires ESEARCH [RFC4731] or IMAP4rev2 [RFC9051].

modseq → integer or nil

Source

# File lib/net/imap/esearch_result.rb, line 173
def modseq;     data.assoc("MODSEQ")&.last     end

The highest mod-sequence of all messages being returned.

Returns nil when the associated search command has no results, or when the MODSEQ search criterion wasn’t specified.

Note that there is no search return option for MODSEQ. It will be returned whenever the CONDSTORE extension has been enabled. Using the MODSEQ search criteria will implicitly enable CONDSTORE.

Requires CONDSTORE [RFC7162] and ESEARCH [RFC4731].

partial → PartialResult or nil

Source

# File lib/net/imap/esearch_result.rb, line 215
def partial;    data.assoc("PARTIAL")&.last    end

A PartialResult containing a subset of the message sequence numbers or UIDs that satisfy the SEARCH criteria.

Requires PARTIAL [RFC9394] or CONTEXT=SEARCH/CONTEXT=SORT [RFC5267]