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 *appcfg, 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 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.

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

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

        /* Open a session for the current thread's work. */
        if ((ret = conn->open_session(conn, NULL, NULL, &session)) != 0)
                fprintf(stderr, "Error opening a session on %s: %s\n",
                    home, wiredtiger_strerror(ret));

        /* XXX Do some work... */

        /* Note: closing the connection implicitly closes open session(s). */
        if ((ret = conn->close(conn, NULL)) != 0)

Examples:

ex_extending.c.

Member Data Documentation

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;
        while (*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 */
        (void)collator; /* unused */

        *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 };

int(* WT_COLLATOR::customize)(WT_COLLATOR *collator, WT_SESSION *session, const char *uri, WT_CONFIG_ITEM *appcfg, 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.

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

If non-NULL, a callback performed when the database is closed.

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