123456789_123456789_123456789_123456789_123456789_

Class: Net::IMAP::ESearchResult

Relationships & Source Files
Namespace Children
Classes:
PartialResult
Inherits: Object
Defined in: lib/net/imap/esearch_result.rb

Overview

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

  • Return options were specified for #search or #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 #sort or #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 #add_response_handler to handle these responses.

Compatibility with SearchResult

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

Class Method Summary

Instance Method Summary

Constructor Details

.new(tag: nil, uid: nil, data: nil) ⇒ ESearchResult

[ GitHub ] 

  


# File 'lib/net/imap/esearch_result.rb', line 35



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


  







Instance Method Details



  

    #all  ⇒ sequence set?   



  

    
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

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 153



def all;        data.assoc("ALL")&.last        end


  








  

    #count  ⇒ Integer?   



  

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

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 164



def count;      data.assoc("COUNT")&.last      end


  








  

    #each  
  



  

    
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 Net::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.


Related: #to_sequence_set, #to_a, #all, #partial

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 86



def each(&)
  return to_enum(__callee__) unless block_given?
  to_sequence_set.each_number(&)
  self
end


  








  

    #max  ⇒ Integer?   



  

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

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 139



def max;        data.assoc("MAX")&.last        end


  








  

    #min  ⇒ Integer?   



  

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

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 128



def min;        data.assoc("MIN")&.last        end


  








  

    #modseq  ⇒ Integer?   



  

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

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 179



def modseq;     data.assoc("MODSEQ")&.last     end


  








  

    #partial  ⇒ PartialResult?   



  

    
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

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 221



def partial;    data.assoc("PARTIAL")&.last    end


  








  

    #to_a  ⇒ Array of integers   



  

    
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 neither ALL or PARTIAL were included
in the Net::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.


Related: #each, #to_sequence_set, #all, #partial

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 55



def to_a; to_sequence_set.numbers end


  








  

    #to_sequence_set  ⇒ SequenceSet?   



  

    
When either #all or #partial contains a SequenceSet of message sequence
numbers or UIDs, to_sequence_set returns that sequence set.


When both #all and #partial are nil, either because the server
returned no results or because neither ALL or PARTIAL were included
in the Net::IMAP#search RETURN options, #to_sequence_set returns
SequenceSet.empty.


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


Related: #each, #to_a, #all, #partial

  



  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 71



def to_sequence_set
  all || partial&.to_sequence_set || SequenceSet.empty
end


  








  

    #uid?  
  

  [ GitHub ]


  

  


# File 'lib/net/imap/esearch_result.rb', line 106



alias uid? uid