WYRDTEK Home Features Reference Downloads About


Reference/es_mbs_new

Syntax

int es_mbs_new( struct es_mbb *fb, int stype, struct es_mbs **res );

Arguments

struct es_mbb *fb Field-binding collection.
int stype Sort type. See list below.
struct es_mbs **res Assigned result. Passed by reference.

Return Codes

ES_ERROR_NONE Success. No errors.
ES_ERROR_UNKNOWNSORTTYPE Invalid sort type.

Description

Construct a new sorted iterator from a field-binding and sort type stype.

One or more sort keys are selected by calling es_mbs_add().

Sorted iterators are subsequently destroyed via es_mbs_delete().

Sort Types

The behaviour of es_mbs_beginfetch() and es_mbs_incfetch() in iterating over the rows of a node in some sorted order varies depending on the sort type stype. The list of valid sort types include:
ES_ORDER_ASC Ascending sort. A sort-order of all rows is pre-generated when es_mbs_beginfetch() is called. The next row in the generated sort-order is fetched upon each successive call to es_mbs_incfetch().
ES_ORDER_DESC Descending sort. A sort-order of all rows is pre-generated when es_mbs_beginfetch() is called. The next row in the generated sort-order is fetched upon each successive call to es_mbs_incfetch().
ES_ORDER_TOP Find top row. Only the top or minimum row is retrieved when es_mbs_beginfetch() is called. The next minimum row is retrieved upon each successive call to es_mbs_incfetch().
ES_ORDER_BOTTOM Find bottom row. Only the bottom or maximum row is retrieved when es_mbs_beginfetch() is called. The next maximum row is retrieved upon each successive call to es_mbs_incfetch().

ES_ORDER_ASC and ES_ORDER_TOP are functionally equivalent as is ES_ORDER_DESC and ES_ORDER_BOTTOM. ES_ORDER_ASC and ES_ORDER_DESC can be more efficient, however, if the objective is to iterative over all rows, whereas ES_ORDER_TOP and ES_ORDER_BOTTOM can be more efficient if the objective is to fetch just the first few (eg. to find the top 5 sales figures).

[Back To Reference] [Back To Reference/es_mbs]