WordKey(3)WordKey(3)NAMEWordKey - 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, SetDe‐
fined 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 other‐
wise.
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 oth‐
erwise.
int Merge(const WordKey& other)
Copy each defined field from other into the object, if the cor‐
responding 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 posi‐
tion 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 con‐
tiguous, 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)
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.
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( posi‐
tion ) 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
The Ht://Dig group http://dev.htdig.org/
SEE ALSOhtdb_dump(1), htdb_stat(1), htdb_load(1), mifluzdump(1), mifluzload(1),
mifluzsearch(1), mifluzdict(1), WordContext(3), WordList(3), Word‐
Dict(3), WordListOne(3), WordKeyInfo(3), WordType(3), WordDBInfo(3),
WordRecordInfo(3), WordRecord(3), WordReference(3), WordCursor(3),
WordCursorOne(3), WordMonitor(3), Configuration(3), mifluz(3)
local WordKey(3)
