WiredTiger: WT_COLLATOR Struct Reference

| Version 3.1.0

Fork me on GitHub Join my user group
List of all members | Public Attributes
WT_COLLATOR Struct Reference
WiredTiger Extension API

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.