WT_COLLATOR Struct Reference

The interface implemented by applications to provide custom ordering of records. More...

Public Attributes
int(*	compare )(WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *key1, const WT_ITEM *key2, int *cmp)
	Callback to compare keys. More...
int(*	customize )(WT_COLLATOR *collator, WT_SESSION *session, const char *uri, WT_CONFIG_ITEM *passcfg, WT_COLLATOR **customp)
	If non-NULL, this callback is called to customize the collator for each data source. More...
int(*	terminate )(WT_COLLATOR *collator, WT_SESSION *session)
	If non-NULL a callback performed when the data source is closed for customized extractors otherwise when the database is closed. More...

Detailed Description

The interface implemented by applications to provide custom ordering of records.

Applications register their implementation with WiredTiger by calling WT_CONNECTION::add_collator. See Custom Collators for more information.

    error_check(conn->add_collator(conn, "nocase", &nocasecoll, NULL));

    error_check(conn->add_collator(conn, "prefix10", &pcoll10.iface, NULL));

    /* Open a session for the current thread's work. */
    error_check(conn->open_session(conn, NULL, NULL, &session));

    /* Do some work... */

    error_check(conn->close(conn, NULL));

Examples:

ex_extending.c.

Member Data Documentation

compare

int(* WT_COLLATOR::compare) (WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *key1, const WT_ITEM *key2, int *cmp)

Callback to compare keys.

Parameters

[out]

cmp

set to -1 if key1 < key2, 0 if key1 == key2, 1 if key1 > key2.

Returns

zero for success, non-zero to indicate an error.

/*
 * A simple example of the collator API: compare the keys as strings.
 */
static int
my_compare(WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *value1, const WT_ITEM *value2,
  int *cmp)
{
    const char *p1, *p2;

    /* Unused parameters */
    (void)collator;
    (void)session;

    p1 = (const char *)value1->data;
    p2 = (const char *)value2->data;
    for (; *p1 != '\0' && *p1 == *p2; ++p1, ++p2)
        ;

    *cmp = (int)*p2 - (int)*p1;
    return (0);
}

/* A simple case insensitive comparator. */
static int
__compare_nocase(
  WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *v1, const WT_ITEM *v2, int *cmp)
{
    const char *s1 = (const char *)v1->data;
    const char *s2 = (const char *)v2->data;

    (void)session;  /* unused variable */
    (void)collator; /* unused variable */

    *cmp = strcasecmp(s1, s2);
    return (0);
}

static WT_COLLATOR nocasecoll = {__compare_nocase, NULL, NULL};

/*
 * Comparator that only compares the first N prefix characters of the string. This has associated
 * data, so we need to extend WT_COLLATOR.
 */
typedef struct {
    WT_COLLATOR iface;
    uint32_t maxlen;
} PREFIX_COLLATOR;

static int
__compare_prefixes(
  WT_COLLATOR *collator, WT_SESSION *session, const WT_ITEM *v1, const WT_ITEM *v2, int *cmp)
{
    PREFIX_COLLATOR *pcoll = (PREFIX_COLLATOR *)collator;
    const char *s1 = (const char *)v1->data;
    const char *s2 = (const char *)v2->data;

    (void)session; /* unused */

    *cmp = strncmp(s1, s2, pcoll->maxlen);
    return (0);
}

static PREFIX_COLLATOR pcoll10 = {{__compare_prefixes, NULL, NULL}, 10};

customize

int(* WT_COLLATOR::customize) (WT_COLLATOR *collator, WT_SESSION *session, const char *uri, WT_CONFIG_ITEM *passcfg, WT_COLLATOR **customp)

If non-NULL, this callback is called to customize the collator for each data source.

If the callback returns a non-NULL collator, that instance is used instead of this one for all comparisons.

terminate

int(* WT_COLLATOR::terminate) (WT_COLLATOR *collator, WT_SESSION *session)

If non-NULL a callback performed when the data source is closed for customized extractors otherwise when the database is closed.

The WT_COLLATOR::terminate callback is intended to allow cleanup, the handle will not be subsequently accessed by WiredTiger.