--- name: "WordKey" section: "3" platform: "linux" package: "libmifluz0-dev" version: "0.24.0-9" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/WordKey" --- # WordKey(3) inverted index key. ## NAME WordKey - inverted index key. ## SYNOPSIS ``` #include #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 1 4 2 Field 1: The word identifier or if not defined Field 2 to the end: numerical value of the field or 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)](/WordKeyInfo/3.md)* ). - **inline WordKeyNum MaxValue(int position)** Convenience functions to access the maximum possible value for field at **position.** in a key (see *[WordKeyInfo(3)](/WordKeyInfo/3.md)* ). - **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)** 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( **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 The Ht://Dig group http://dev.htdig.org/ ## SEE ALSO [htdb\_dump(1)](/htdb_dump/1.md), [htdb\_stat(1)](/htdb_stat/1.md), [htdb\_load(1)](/htdb_load/1.md), [mifluzdump(1)](/mifluzdump/1.md), [mifluzload(1)](/mifluzload/1.md), [mifluzsearch(1)](/mifluzsearch/1.md), [mifluzdict(1)](/mifluzdict/1.md), [WordContext(3)](/WordContext/3.md), [WordList(3)](/WordList/3.md), [WordDict(3)](/WordDict/3.md), [WordListOne(3)](/WordListOne/3.md), [WordKeyInfo(3)](/WordKeyInfo/3.md), [WordType(3)](/WordType/3.md), [WordDBInfo(3)](/WordDBInfo/3.md), [WordRecordInfo(3)](/WordRecordInfo/3.md), [WordRecord(3)](/WordRecord/3.md), [WordReference(3)](/WordReference/3.md), [WordCursor(3)](/WordCursor/3.md), [WordCursorOne(3)](/WordCursorOne/3.md), [WordMonitor(3)](/WordMonitor/3.md), [Configuration(3)](/Configuration/3.md), [mifluz(3)](/mifluz/3.md)