---
name: "swkey"
section: "3"
platform: "linux"
package: "libsword-dev"
version: "1.5.3-3woody2"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/swkey"
---

# swkey(3)

SWKey is the basis for all types of keys for indexing into modules (e.g.

## NAME

SWKey - SWKey is the basis for all types of keys for indexing into modules (e.g.

## SYNOPSIS

`#include <swkey.h>`

Inherits **SWObject**.

Inherited by **ListKey**, **StrKey**, and **VerseKey**.

### Public Methods

**SWKey** (const char \*ikey=0)\
 *initializes instance of SWKey.* **SWKey** (SWKey const &k)\
 *Copy Constructor.* virtual **~SWKey** ()\
 *Destructor, cleans up this instance of SWKey.* virtual SWKey\* **clone** () const\
 *Returns a copy of this SWKey object.* char **Persist** () const\
 *Gets whether this object itself persists within a module that it was used to SetKey or just a copy.* char **Persist** (char ikey)\
 *Set/gets whether this object itself persists within a module that it was used to SetKey or just a copy.* virtual char **Error** ()\
 *Gets and clears error status.* virtual void **setText** (const char \*ikey)\
 *Equates this SWKey to a character string.* virtual void **copyFrom** (const SWKey &ikey)\
 *Equates this SWKey to another SWKey object.* virtual const char\* **getText** () const\
 *returns text key if (char \*) cast is requested.* virtual int **compare** (const SWKey &ikey)\
 *Compares another* **VerseKey** object. virtual bool **equals** (const SWKey &ikey)\
 *Compares another* **VerseKey** object. virtual void **setPosition** (SW\_POSITION)\
 virtual void **decrement** (int steps=1)\
 *Decrements key a number of entries.* virtual void **increment** (int steps=1)\
 *Increments key a number of entries.* virtual char **Traversable** ()\
 virtual long **Index** () const\
 *Use this function to get te current position withing a module.* virtual long **Index** (long iindex)\

### Protected Attributes

char\* **keytext**\
 char **persist**\
 char **error**\

### Private Methods

void **init** ()\

### Private Attributes

long **index**\

### Static Private Attributes

**SWClass** **classdef**\

## DETAILED DESCRIPTION

SWKey is the basis for all types of keys for indexing into modules (e.g.

verse, word, place, etc.)

Definition at line 76 of file swkey.h.

## CONSTRUCTOR & DESTRUCTOR DOCUMENTATION

### SWKey::SWKey (const char \* ikey = 0)

initializes instance of SWKey.

**Parameters:**

- *ikey*

  text key

### SWKey::SWKey (SWKey const & k)

Copy Constructor.

**Parameters:**

- *The*

  SWKey object to copy.

## MEMBER FUNCTION DOCUMENTATION

### char SWKey::Error ()` [virtual]`

Gets and clears error status.

**Returns:**  error status

### long SWKey::Index () const` [inline, virtual]`

Use this function to get te current position withing a module.

Here's a small example how to use this function and Index(long). This function uses the GerLut module and chooses a random verse from the Bible and returns it.

```
 const char* randomVerse() {
   VerseKey vk;
   SWMgr mgr;
   LocaleMgr::systemLocaleMgr.setDefaultLocaleName("de");
   SWModule* module = mgr->Modules("GerLut");
   srand( time(0) );
   const double newIndex = (double(rand())/RAND_MAX)*(24108+8224);
   vk.Index(newIndex);
   module->SetKey(vk);
   char* text;
   sprintf(text, "%s: %s",(const char*)vk ,module->StripText(&vk));
   return text;
```

Reimplemented in **ListKey**, and **VerseKey**.

Definition at line 204 of file swkey.h.

Referenced by ListKey::Index().

### char SWKey::Persist (char ikey)

Set/gets whether this object itself persists within a module that it was used to SetKey or just a copy.

(1 - persists in module; 0 - a copy is attempted

**Parameters:**

- *ipersist*

  value which to set persist; \[-1\] - only get

**Returns:**  value of persist

### char SWKey::Persist () const

Gets whether this object itself persists within a module that it was used to SetKey or just a copy.

(1 - persists in module; 0 - a copy is attempted

**Returns:**  value of persist

### SWKey \* SWKey::clone () const` [virtual]`

Returns a copy of this SWKey object.

This is useful to get a 1:1 copy of an SWKey based object.

**Returns:**  SWKey

Reimplemented in **ListKey**, and **VerseKey**.

### int SWKey::compare (const SWKey & ikey)` [virtual]`

Compares another **VerseKey** object.

**Parameters:**

- *ikey*

  key to compare with this one

**Returns:**  \>0 if this key is greater than compare key; \<0 if this key is smaller than compare key; 0 if the keys are the same

Reimplemented in **VerseKey**.

Referenced by equals().

### void SWKey::copyFrom (const SWKey & ikey)` [virtual]`

Equates this SWKey to another SWKey object.

**Parameters:**

- *ikey*

  other swkey object

Reimplemented in **ListKey**, and **VerseKey**.

Referenced by ListKey::copyFrom().

### void SWKey::decrement (int step = 1)` [virtual]`

Decrements key a number of entries.

**Parameters:**

- *steps*

  Number of entries to jump backward

**Returns:**  \*this

Reimplemented in **ListKey**, and **VerseKey**.

### bool SWKey::equals (const SWKey & ikey)` [inline, virtual]`

Compares another **VerseKey** object.

**Parameters:**

- *ikey*

  key to compare with this one

**Returns:**  true if the keys are the same

Definition at line 163 of file swkey.h.

### void SWKey::increment (int step = 1)` [virtual]`

Increments key a number of entries.

**Parameters:**

- *increment*

  Number of entries to jump forward

**Returns:**  \*this

Reimplemented in **ListKey**, and **VerseKey**.

### void SWKey::setText (const char \* ikey)` [virtual]`

Equates this SWKey to a character string.

**Parameters:**

- *ikey*

  string to set this key to

Reimplemented in **VerseKey**.

Referenced by VerseKey::setText().

## AUTHOR

Generated automatically by Doxygen for The Sword Project from the source code.