/*
 *  call-seq:
 *     searcher.search_each(query, options = {}) {|doc_id, score| do_something}
 *         -> total_hits
 *
 *  Run a query through the Searcher on the index. A TopDocs object is
 *  returned with the relevant results. The +query+ is a Query object. The
 *  Searcher#search_each method yields the internal document id (used to
 *  reference documents in the Searcher object like this; +searcher[doc_id]+)
 *  and the search score for that document. It is possible for the score to be
 *  greater than 1.0 for some queries and taking boosts into account. This
 *  method will also normalize scores to the range 0.0..1.0 when the max-score
 *  is greater than 1.0. Here are the options;
 *
 *  === Options
 *
 *  :offset::       Default: 0. The offset of the start of the section of the
 *                  result-set to return. This is used for paging through
 *                  results. Let's say you have a page size of 10. If you
 *                  don't find the result you want among the first 10 results
 *                  then set +:offset+ to 10 and look at the next 10 results,
 *                  then 20 and so on.
 *  :limit::        Default: 10. This is the number of results you want
 *                  returned, also called the page size. Set +:limit+ to
 *                  +:all+ to return all results
 *  :sort::         A Sort object or sort string describing how the field
 *                  should be sorted. A sort string is made up of field names
 *                  which cannot contain spaces and the word "DESC" if you
 *                  want the field reversed, all separated by commas. For
 *                  example; "rating DESC, author, title". Note that Ferret
 *                  will try to determine a field's type by looking at the
 *                  first term in the index and seeing if it can be parsed as
 *                  an integer or a float. Keep this in mind as you may need
 *                  to specify a fields type to sort it correctly. For more
 *                  on this, see the documentation for SortField
 *  :filter::       a Filter object to filter the search results with
 *  :filter_proc::  a filter Proc is a Proc which takes the doc_id, the score
 *                  and the Searcher object as its parameters and returns a
 *                  Boolean value specifying whether the result should be
 *                  included in the result set.
 */
static VALUE
frt_sea_search_each(int argc, VALUE *argv, VALUE self)
{
    int i;
    Query *q;
    float max_score;
    TopDocs *td;
    VALUE rquery, roptions, rtotal_hits;
    GET_SEA();

    rb_scan_args(argc, argv, "11", &rquery, &roptions);

    rb_thread_critical = Qtrue;

    Data_Get_Struct(rquery, Query, q);
    td = frt_sea_search_internal(q, roptions, sea);

    max_score = (td->max_score > 1.0) ? td->max_score : 1.0;

    /* yield normalized scores */
    for (i = 0; i < td->size; i++) {
        rb_yield_values(2, INT2FIX(td->hits[i]->doc),
                        rb_float_new((double)(td->hits[i]->score/max_score)));
    }

    rtotal_hits = INT2FIX(td->total_hits);
    td_destroy(td);

    rb_thread_critical = 0;

    return rtotal_hits;
}