NAME

WordKey - inverted index key.

SYNOPSIS

#include <WordKey.h>
#define WORD_KEY_DOCID    1
#define WORD_KEY_LOCATION 2
WordList* words = ...;
WordKey key = words->Key("word 100 20");
WordKey searchKey;
words->Dict()->SerialExists("dog", searchKey.Get(WORD_KEY_WORD));
searchKey.Set(WORD_KEY_LOCATION, 5);
WordCursor* cursor = words->Key(searchKey);

DESCRIPTION

Describes the key used to store a entry in the inverted index. Each field in the key has a bit in the set member that says if it is set or not. This bit allows to say that a particular field is undefined regardless of the actual value stored. The methods IsDefined, SetDefined and Undefined are used to manipulate the defined status of a field. The Pack and Unpack methods are used to convert to and from the disk storage representation of the key.

Although constructors may be used, the prefered way to create a WordKey object is by using the WordContext::Key method.

The following constants are defined:

WORD_KEY_WORD: the index of the word identifier with the key for Set and Get methods.
WORD_KEY_VALUE_INVALID: a value that is invalid for any field of the key.

ASCII FORMAT

The ASCII description is a string with fields separated by tabs or white space.

Example: 200 <UNDEF> 1 4 2
Field 1: The word identifier or <UNDEF> if not defined
Field 2 to the end: numerical value of the field or <UNDEF> if
                    not defined

METHODS

WordKey(WordContext* ncontext)

Constructor. Build an empty key. The ncontext argument must be a pointer to a valid WordContext object.

WordKey(WordContext* ncontext, const String& desc)

Constructor. Initialize from an ASCII description of a key. See ASCII FORMAT section. The ncontext argument must be a pointer to a valid WordContext object.

void Clear()

Reset to empty key.

inline int NFields() const

Convenience functions to access the total number of fields in a key (see WordKeyInfo(3) ).

inline WordKeyNum MaxValue(int position)

Convenience functions to access the maximum possible value for field at position. in a key (see WordKeyInfo(3) ).

inline WordContext* GetContext()

Return a pointer to the WordContext object used to create this instance.

inline const WordContext* GetContext() const

Return a pointer to the WordContext object used to create this instance as a const.

inline WordKeyNum Get(int position) const

Return value of numerical field at position as const.

inline WordKeyNum& Get(int position)

Return value of numerical field at position.

inline const WordKeyNum & operator[] (int position) const

Return value of numerical field at position as const.

inline WordKeyNum & operator[] (int position)

Return value of numerical field at position.

inline void Set(int position, WordKeyNum val)

Set value of numerical field at position to val.

int IsDefined(int position) const

Returns true if field at position is defined , false otherwise.

void SetDefined(int position)

Value in field position becomes defined. A bit is set in the bit field describing the defined/undefined state of the value and the actual value of the field is not modified.

void Undefined(int position)

Value in field position becomes undefined. A bit is set in the bit field describing the defined/undefined state of the value and the actual value of the field is not modified.

int Set(const String& bufferin)

Set the whole structure from ASCII string in bufferin. See ASCII FORMAT section. Return OK if successfull, NOTOK otherwise.

int Get(String& bufferout) const

Convert the whole structure to an ASCII string description in bufferout. See ASCII FORMAT section. Return OK if successfull, NOTOK otherwise.

String Get() const

Convert the whole structure to an ASCII string description and return it. See ASCII FORMAT section.

int Unpack(const char* string, int length)

Set structure from disk storage format as found in string buffer or length length. Return OK if successfull, NOTOK otherwise.

inline int Unpack(const String& data)

Set structure from disk storage format as found in data string. Return OK if successfull, NOTOK otherwise.

int Pack(String& data) const

Convert object into disk storage format as found in and place the result in data string. Return OK if successfull, NOTOK otherwise.

int Merge(const WordKey& other)

Copy each defined field from other into the object, if the corresponding field of the object is not defined. Return OK if successfull, NOTOK otherwise.

int PrefixOnly()

Undefine all fields found after the first undefined field. The resulting key has a set of defined fields followed by undefined fields. Returns NOTOK if the word is not defined because the resulting key would be empty and this is considered an error. Returns OK on success.

int SetToFollowing(int position = WORD_FOLLOWING_MAX)

Implement ++ on a key.

It behaves like arithmetic but follows these rules:

position
- 1

If position is not specified it is equivalent to NFields() - 1. It returns OK if successfull, NOTOK if position out of range or WORD_FOLLOWING_ATEND if the maximum possible value was reached.

int Filled() const

Return true if all the fields are defined , false otherwise.

int Empty() const

Return true if no fields are defined , false otherwise.

int Equal(const WordKey& other) const

Return true if the object and other are equal. Only fields defined in both keys are compared.

int ExactEqual(const WordKey& other) const

Return true if the object and other are equal. All fields are compared. If a field is defined in object and not defined in the object, the key are not considered equal.

int Cmp(const WordKey& other) const

Compare object and other as in strcmp. Undefined fields are ignored. Returns a positive number if object is greater than other , zero if they are equal, a negative number if object is lower than other.

int PackEqual(const WordKey& other) const

Return true if the object and other are equal. The packed string are compared. An undefined numerical field will be 0 and therefore undistinguishable from a defined field whose value is 0.

int Outbound(int position, int increment)

Return true if adding increment in field at position makes it overflow or underflow, false if it fits.

int Overflow(int position, int increment)

Return true if adding positive increment to field at position makes it overflow, false if it fits.

int Underflow(int position, int increment)

Return true if subtracting positive increment to field at position makes it underflow, false if it fits.

int Prefix() const

Return OK if the key may be used as a prefix for search. In other words return OK if the fields set in the key are all contiguous, starting from the first field. Otherwise returns NOTOK

static int Compare(WordContext* context, const String& a, const String& b)

Compare a and b in the Berkeley DB fashion. a and b are packed keys. The semantics of the returned int is as of strcmp and is driven by the key description found in WordKeyInfo. Returns a positive number if a is greater than b , zero if they are equal, a negative number if a is lower than b.

static int Compare(WordContext* context, const unsigned char *a, int a_length, const unsigned char *b, int b_length)

int Diff(const WordKey& other, int& position, int& lower)

Compare object defined fields with other key defined fields only, ignore fields that are not defined in object or other. Return 1 if different 0 if equal. If different, position is set to the field number that differ, lower is set to 1 if Get( position ) is lower than other.Get( position ) otherwise lower is set to 0.

int Write(FILE* f) const

Print object in ASCII form on f (uses Get method). See ASCII FORMAT section.

void Print() const

Print object in ASCII form on stdout (uses Get method). See ASCII FORMAT section.

AUTHORS

Loic Dachary loic@gnu.org