+ $rs = $conn->search_pqf('@attr 1=4 mineral');
+ $n = $rs->size();
+ for $i (1 .. $n) {
+ $rec = $rs->record($i-1);
+ print $rec->render();
+ }
+
+A ResultSet object represents the set of zero or more records
+resulting from a search, and is the means whereby these records can be
+retrieved. A ResultSet object may maintain client side cache or some,
+less, none, all or more of the server's records: in general, this is
+supposed to an implementaton detail of no interest to a typical
+application, although more sophisticated applications do have
+facilities for messing with the cache. Most applications will only
+need the C<size()>, C<record()> and C<sort()> methods.
+
+There is no C<new()> method nor any other explicit constructor. The
+only way to create a new ResultSet is by using C<search()> (or
+C<search_pqf()>) on a Connection.
+
+See the description of the C<Result Set> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.4
+
+=head3 Methods
+
+=head4 option()
+
+ $rs->option(elementSetName => "f");
+
+Allows options to be set into, and read from, a ResultSet, just like
+the Connection class's C<option()> method. There is no
+C<option_binary()> method for ResultSet objects.
+
+ResultSet options are listed at
+http://indexdata.com/yaz/doc/zoom.resultsets.tkl
+
+=head4 size()
+
+ print "Found ", $rs->size(), " records\n";
+
+Returns the number of records in the result set.
+
+=head4 record() / record_immediate()
+
+ $rec = $rs->record(0);
+ $rec2 = $rs->record_immediate(0);
+ $rec3 = $rs->record_immediate(1)
+ or print "second record wasn't in cache\n";
+
+The C<record()> method returns a C<ZOOM::Record> object representing
+a record from result-set, whose position is indicated by the argument
+passed in. This is a zero-based index, so that legitimate values
+range from zero to C<$rs->size()-1>.
+
+The C<record_immediate()> API is identical, but it never invokes a
+network operation, merely returning the record from the ResultSet's
+cache if it's already there, or an undefined value otherwise. So if
+you use this method, B<you must always check the return value>.
+
+=head4 records()
+
+ $rs->records(0, 10, 0);
+ for $i (0..10) {
+ print $rs->record_immediate($i)->render();
+ }
+
+ @nextseven = $rs->records(10, 7, 1);
+
+The C<record_immediate()> method only fetches records from the cache,
+whereas C<record()> fetches them from the server if they have not
+already been cached; but the ZOOM module has to guess what the most
+efficient strategy for this is. It might fetch each record, alone
+when asked for: that's optimal in an application that's only
+interested in the top hit from each search, but pessimal for one that
+wants to display a whole list of results. Conversely, the software's
+strategy might be always to ask for blocks of a twenty records:
+that's great for assembling long lists of things, but wasteful when
+only one record is wanted. The problem is that the ZOOM module can't
+tell, when you call C<$rs->record()>, what your intention is.
+
+But you can tell it. The C<records()> method fetches a sequence of
+records, all in one go. It takes three arguments: the first is the
+zero-based index of the first record in the sequence, the second is
+the number of records to fetch, and the third is a boolean indication
+of whether or not to return the retrieved records as well as adding
+them to the cache. (You can always pass 1 for this if you like, and
+Perl will discard the unused return value, but there is a small
+efficiency gain to be had by passing 0.)
+
+Once the records have been retrieved from the server
+(i.e. C<records()> has completed without throwing an exception), they
+can be fetched much more efficiently using C<record()> - or
+C<record_immediate()>, which is then guaranteed to succeed.
+
+=head4 cache_reset()
+
+ $rs->cache_reset()
+
+Resets the ResultSet's record cache, so that subsequent invocations of
+C<record_immediate()> will fail. I struggle to imagine a real
+scenario where you'd want to do this.
+
+=head4 sort()
+
+ if ($rs->sort("yaz", "1=4 >i 1=21 >s") < 0) {
+ die "sort failed";
+ }
+
+Sorts the ResultSet in place (discarding any cached records, as they
+will in general be sorted into a different position). There are two
+arguments: the first is a string indicating the type of the
+sort-specification, and the second is the specification itself.
+
+The C<sort()> method returns 0 on success, or -1 if the
+sort-specification is invalid.
+
+At present, the only supported sort-specification type is C<yaz>.
+Such a specification consists of a space-separated sequence of keys,
+each of which itself consists of two space-separated words (so that
+the total number of words in the sort-specification is even). The two
+words making up each key are a field and a set of flags. The field
+can take one of two forms: if it contains an C<=> sign, then it is a
+BIB-1 I<type>=I<value> pair specifying which field to sort
+(e.g. C<1=4> for a title sort); otherwise it is sent for the server to
+interpret as best it can. The word of flags is made up from one or
+more of the following: C<s> for case sensitive, C<i> for case
+insensitive; C<<> for ascending order and C<E<gt>> for descending
+order.
+
+For example, the sort-specification in the code-fragment above will
+sort the records in C<$rs> case-insensitively in descending order of
+title, with records having equivalent titles sorted case-sensitively
+in ascending order of subject. (The BIB-1 access points 4 and 21
+represent title and subject respectively.)
+
+=head4 destroy()
+
+ $rs->destroy()
+
+Destroys a ResultSet object, freeing its resources. It is an error to
+reuse a ResultSet that has been C<destroy()>ed.