class Net::IMAP::ESearchResult - net-imap: Ruby Standard Library Documentation

# 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) click to toggle source
Calls superclass method

    # File net-imap-0.5.4/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

### Public Instance Methods

all → sequence set or nil click to toggle source

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`

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

count → integer or nil click to toggle source

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

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

max → integer or nil click to toggle source

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

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

min → integer or nil click to toggle source

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

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

modseq → integer or nil click to toggle source

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

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

partial → PartialResult or nil click to toggle source

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]

See also: `to_a`

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

to_a → Array of integers click to toggle source

When either `all` or `partial` contains a `SequenceSet` of message sequence numbers or UIDs, `to_a` returns that set as an array of integers.

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, `to_a` returns an empty array.

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

    # File net-imap-0.5.4/lib/net/imap/esearch_result.rb, line 47
    def to_a; all&.numbers || partial&.to_a || [] end