Class: Ferret::Search::SortField

Summary

A SortField is used to sort the result-set of a search be the contents of a field. The following types of sort_field are available;

  • :auto
  • :integer
  • :float
  • :string
  • :byte
  • :doc_id
  • :score

The type of the SortField is set by passing it as a parameter to the constructor. The +:auto+ type specifies that the SortField should detect the sort type by looking at the data in the field. This is the default :type value although it is recommended that you explicitly specify the fields type.

Example

  title_sf = SortField.new(:title, :type => :string)
  rating_sf = SortField.new(:rating, :type => float, :reverse => true)

Note 1: Care should be taken when using the :auto sort-type since numbers will occur before other strings in the index so if you are sorting a field with both numbers and strings (like a title field which might have "24" and "Prison Break") then the sort_field will think it is sorting integers when it really should be sorting strings.

Note 2: When sorting by integer, integers are only 4 bytes so anything larger will cause strange sorting behaviour.

Constants

NameValue
SCORE Data_Wrap_Struct(cSortField, NULL, &frt_deref_free, (SortField *)&SORT_FIELD_SCORE)
SCORE_REV Data_Wrap_Struct(cSortField, NULL, &frt_deref_free, (SortField *)&SORT_FIELD_SCORE_REV)
DOC_ID Data_Wrap_Struct(cSortField, NULL, &frt_deref_free, (SortField *)&SORT_FIELD_DOC)
DOC_ID_REV Data_Wrap_Struct(cSortField, NULL, &frt_deref_free, (SortField *)&SORT_FIELD_DOC_REV)

Public Class Methods

SortField.new(field, options = {}) → sort_field

Create a new SortField which can be used to sort the result-set by the value in field field.

Options

:type:Default: +:auto+. Specifies how a field should be sorted. Choose from one of; +:auto+, +:integer+, +:float+, +:string+, +:byte+, +:doc_id+ or +:score+. +:auto+ will check the datatype of the field by trying to parse it into either a number or a float before settling on a string sort. String sort is locale dependent and works for multibyte character sets like UTF-8 if you have your locale set correctly.

:reverse Default: false. Set to true if you want to reverse the 

                sort.

/*
 *  call-seq:
 *     SortField.new(field, options = {}) -> sort_field
 *
 *  Create a new SortField which can be used to sort the result-set by the
 *  value in field +field+.
 *
 *  === Options
 *
 *  :type::         Default: +:auto+. Specifies how a field should be sorted.
 *                  Choose from one of; +:auto+, +:integer+, +:float+,
 *                  +:string+, +:byte+, +:doc_id+ or +:score+. +:auto+ will
 *                  check the datatype of the field by trying to parse it into
 *                  either a number or a float before settling on a string
 *                  sort. String sort is locale dependent and works for
 *                  multibyte character sets like UTF-8 if you have your
 *                  locale set correctly.
 *  :reverse        Default: false. Set to true if you want to reverse the
 *                  sort.
 */
static VALUE
frt_sf_init(int argc, VALUE *argv, VALUE self)
{
    SortField *sf;
    VALUE rfield, roptions;
    VALUE rval;
    int type = SORT_TYPE_AUTO;
    int is_reverse = false;
    char *field;

    if (rb_scan_args(argc, argv, "11", &rfield, &roptions) == 2) {
        if (Qnil != (rval = rb_hash_aref(roptions, sym_type))) {
            type = get_sort_type(rval);
        }
        if (Qnil != (rval = rb_hash_aref(roptions, sym_reverse))) {
            is_reverse = RTEST(rval);
        }
        if (Qnil != (rval = rb_hash_aref(roptions, sym_comparator))) {
            rb_raise(rb_eArgError, "Unsupported argument ':comparator'");
        }
    }
    if (NIL_P(rfield)) rb_raise(rb_eArgError, "must pass a valid field name");
    field = frt_field(rfield);

    sf = sort_field_new(field, type, is_reverse);
    if (sf->field == NULL && field) {
        sf->field = estrdup(field);
    }

    Frt_Wrap_Struct(self, NULL, &frt_sf_free, sf);
    object_add(sf, self);
    return self;
}

Public Instance Methods

sort_field.comparator → symbol

TODO: currently unsupported 

/*
 *  call-seq:
 *     sort_field.comparator -> symbol
 *
 *  TODO: currently unsupported
 */
static VALUE
frt_sf_get_comparator(VALUE self)
{
    return Qnil;
}

sort_field.name → symbol

Returns the name of the field to be sorted. 

/*
 *  call-seq:
 *     sort_field.name -> symbol
 *
 *  Returns the name of the field to be sorted.
 */
static VALUE
frt_sf_get_name(VALUE self)
{
    GET_SF();
    return sf->field ? ID2SYM(rb_intern(sf->field)) : Qnil;
}

sort_field.reverse? → bool

Return true if the field is to be reverse sorted. This attribute is set when you create the sort_field. 

/*
 *  call-seq:
 *     sort_field.reverse? -> bool
 *
 *  Return true if the field is to be reverse sorted. This attribute is set
 *  when you create the sort_field.
 */
static VALUE
frt_sf_is_reverse(VALUE self)
{
    GET_SF();
    return sf->reverse ? Qtrue : Qfalse;
}

sort_field.to_s → string

Return a human readable string describing this sort_field. 

/*
 *  call-seq:
 *     sort_field.to_s -> string
 *
 *  Return a human readable string describing this +sort_field+.
 */
static VALUE
frt_sf_to_s(VALUE self)
{
    GET_SF();
    char *str = sort_field_to_s(sf);
    VALUE rstr = rb_str_new2(str);
    free(str);
    return rstr;
}

sort_field.type → symbol

Return the type of sort. Should be one of; +:auto+, +:integer+, +:float+, +:string+, +:byte+, +:doc_id+ or +:score+. 

/*
 *  call-seq:
 *     sort_field.type -> symbol
 *  
 *  Return the type of sort. Should be one of; +:auto+, +:integer+, +:float+,
 *  +:string+, +:byte+, +:doc_id+ or +:score+.
 */
static VALUE
frt_sf_get_type(VALUE self)
{
    GET_SF();
    switch (sf->type) {
        case SORT_TYPE_BYTE:    return sym_byte;
        case SORT_TYPE_INTEGER: return sym_integer;
        case SORT_TYPE_FLOAT:   return sym_float;
        case SORT_TYPE_STRING:  return sym_string;
        case SORT_TYPE_AUTO:    return sym_auto;
        case SORT_TYPE_DOC:     return sym_doc_id;
        case SORT_TYPE_SCORE:   return sym_score;
    }
    return Qnil;
}