# kyotocabinet::IndexDB Class Reference

Index database. More...

`#include <kcdbext.h>`

List of all members.

## Public Member Functions

| IndexDB ()
| Default constructor.
virtual | ~IndexDB ()
| Destructor.
BasicDB::Error | error () const
| Get the last happened error.
void | set_error (const char *file, int32_t line, const char *func, BasicDB::Error::Code code, const char *message)
| Set the error information.
void | set_error (BasicDB::Error::Code code, const char *message)
| Set the error information without source code information.
bool | open (const std::string &path=":", uint32_t mode=BasicDB::OWRITER|BasicDB::OCREATE)
| Open a database file.
bool | close ()
| Close the database file.
bool | set (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Set the value of a record.
bool | set (const std::string &key, const std::string &value)
| Set the value of a record.
bool | add (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Add a record.
bool | add (const std::string &key, const std::string &value)
| Set the value of a record.
bool | replace (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Replace the value of a record.
bool | replace (const std::string &key, const std::string &value)
| Replace the value of a record.
bool | append (const char *kbuf, size_t ksiz, const char *vbuf, size_t vsiz)
| Append the value of a record.
bool | append (const std::string &key, const std::string &value)
| Set the value of a record.
bool | remove (const char *kbuf, size_t ksiz)
| Remove a record.
bool | remove (const std::string &key)
| Remove a record.
char * | get (const char *kbuf, size_t ksiz, size_t *sp)
| Retrieve the value of a record.
bool | get (const std::string &key, std::string *value)
| Retrieve the value of a record.
bool | synchronize (bool hard=false, BasicDB::FileProcessor *proc=NULL)
| Synchronize updated contents with the file and the device.
bool | clear ()
| Remove all records.
int64_t | count ()
| Get the number of records.
int64_t | size ()
| Get the size of the database file.
std::string | path ()
| Get the path of the database file.
bool | status (std::map< std::string, std::string > *strmap)
| Get the miscellaneous status information.
PolyDB * | reveal_inner_db ()
| Reveal the inner database object.
BasicDB::Cursor * | cursor ()
| Create a cursor object.
void | log (const char *file, int32_t line, const char *func, BasicDB::Logger::Kind kind, const char *message)
| Write a log message.
bool | tune_logger (BasicDB::Logger *logger, uint32_t kinds=BasicDB::Logger::WARN|BasicDB::Logger::ERROR)
| Set the internal logger.
bool | tune_meta_trigger (BasicDB::MetaTrigger *trigger)
| Set the internal meta operation trigger.

## Protected Member Functions

void | report (const char *file, int32_t line, const char *func, const char *format,...)
| Report a message for debugging.

## Detailed Description

Index database.

Note:
  This class is designed to implement an indexing storage with an efficient appending operation for the existing record values. This class is a wrapper of the polymorphic database, featuring buffering mechanism to alleviate IO overhead in the database layer. This class can be inherited but overwriting methods is forbidden. Before every database operation, it is necessary to call the IndexDB::open method in order to open a database file and connect the database object to it. To avoid data missing or corruption, it is important to close every database file by the IndexDB::close method when the database is no longer in use. It is forbidden for multible database objects in a process to open the same database at the same time. It is forbidden to share a database object with child processes.

## Constructor & Destructor Documentation

kyotocabinet::IndexDB::IndexDB | ( |  | ) | `[explicit]`

Default constructor.

virtual kyotocabinet::IndexDB::~IndexDB | ( |  | ) | `[virtual]`

Destructor.

Note:
  If the database is not closed, it is closed implicitly.

## Member Function Documentation

BasicDB::Error kyotocabinet::IndexDB::error | ( |  | ) | const

Get the last happened error.

Returns:
  the last happened error.

void kyotocabinet::IndexDB::set_error | ( | const char * | file,
|  | int32_t | line,
|  | const char * | func,
|  | BasicDB::Error::Code | code,
|  | const char * | message
| ) |  |

Set the error information.

Parameters:

  file | the file name of the program source code.
  line | the line number of the program source code.
  func | the function name of the program source code.
  code | an error code.
  message | a supplement message.

void kyotocabinet::IndexDB::set_error | ( | BasicDB::Error::Code | code,
|  | const char * | message
| ) |  |

Set the error information without source code information.

Parameters:

  code | an error code.
  message | a supplement message.

bool kyotocabinet::IndexDB::open | ( | const std::string & | path = `":"`,
|  | uint32_t | mode = `BasicDB::OWRITER | BasicDB::OCREATE`
| ) |  |

Open a database file.

Parameters:

  path | the path of a database file. The same as with PolyDB. In addition, the following tuning parameters are supported. "idxclim" specifies the limit size of the internal cache. "idxcbnum" the bucket number of the internal cache. "idxdbnum" specifies the number of internal databases. "idxtmppath' specifies the path of the temporary directory.
  mode | the connection mode. The same as with PolyDB.

Returns:
  true on success, or false on failure.

Note:
  Every opened database must be closed by the IndexDB::close method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

bool kyotocabinet::IndexDB::close | ( |  | ) |

Close the database file.

Returns:
  true on success, or false on failure.

bool kyotocabinet::IndexDB::set | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Set the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, a new record is created. If the corresponding record exists, the value is overwritten.

bool kyotocabinet::IndexDB::set | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |

Set the value of a record.

Note:
  Equal to the original DB::set method except that the parameters are std::string.

bool kyotocabinet::IndexDB::add | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Add a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, a new record is created. If the corresponding record exists, the record is not modified and false is returned.

bool kyotocabinet::IndexDB::add | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |

Set the value of a record.

Note:
  Equal to the original DB::add method except that the parameters are std::string.

bool kyotocabinet::IndexDB::replace | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Replace the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, no new record is created and false is returned. If the corresponding record exists, the value is modified.

bool kyotocabinet::IndexDB::replace | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |

Replace the value of a record.

Note:
  Equal to the original DB::replace method except that the parameters are std::string.

bool kyotocabinet::IndexDB::append | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | const char * | vbuf,
|  | size_t | vsiz
| ) |  |

Append the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  vbuf | the pointer to the value region.
  vsiz | the size of the value region.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, a new record is created. If the corresponding record exists, the given value is appended at the end of the existing value.

bool kyotocabinet::IndexDB::append | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |

Set the value of a record.

Note:
  Equal to the original DB::append method except that the parameters are std::string.

bool kyotocabinet::IndexDB::remove | ( | const char * | kbuf,
|  | size_t | ksiz
| ) |  |

Remove a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.

Returns:
  true on success, or false on failure.

Note:
  If no record corresponds to the key, false is returned.

bool kyotocabinet::IndexDB::remove | ( | const std::string & | key | ) |

Remove a record.

Note:
  Equal to the original DB::remove method except that the parameter is std::string.

char* kyotocabinet::IndexDB::get | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | size_t * | sp
| ) |  |

Retrieve the value of a record.

Parameters:

  kbuf | the pointer to the key region.
  ksiz | the size of the key region.
  sp | the pointer to the variable into which the size of the region of the return value is assigned.

Returns:
  the pointer to the value region of the corresponding record, or NULL on failure.

Note:
  If no record corresponds to the key, NULL is returned. Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a C-style string. Because the region of the return value is allocated with the the new[] operator, it should be released with the delete[] operator when it is no longer in use.

bool kyotocabinet::IndexDB::get | ( | const std::string & | key,
|  | std::string * | value
| ) |  |

Retrieve the value of a record.

Note:
  Equal to the original DB::get method except that the first parameters is the key string and the second parameter is a string to contain the result and the return value is bool for success.

bool kyotocabinet::IndexDB::synchronize | ( | bool | hard = `false`,
|  | BasicDB::FileProcessor * | proc = `NULL`
| ) |  |

Synchronize updated contents with the file and the device.

Parameters:

  hard | true for physical synchronization with the device, or false for logical synchronization with the file system.
  proc | a postprocessor object. If it is NULL, no postprocessing is performed.

Returns:
  true on success, or false on failure.

Note:
  The operation of the postprocessor is performed atomically and other threads accessing the same record are blocked. To avoid deadlock, any explicit database operation must not be performed in this function.

bool kyotocabinet::IndexDB::clear | ( |  | ) |

Remove all records.

Returns:
  true on success, or false on failure.

int64_t kyotocabinet::IndexDB::count | ( |  | ) |

Get the number of records.

Returns:
  the number of records, or -1 on failure.

int64_t kyotocabinet::IndexDB::size | ( |  | ) |

Get the size of the database file.

Returns:
  the size of the database file in bytes, or -1 on failure.

std::string kyotocabinet::IndexDB::path | ( |  | ) |

Get the path of the database file.

Returns:
  the path of the database file, or an empty string on failure.

bool kyotocabinet::IndexDB::status | ( | std::map< std::string, std::string > * | strmap | ) |

Get the miscellaneous status information.

Parameters:

  strmap | a string map to contain the result.

Returns:
  true on success, or false on failure.

PolyDB* kyotocabinet::IndexDB::reveal_inner_db | ( |  | ) |

Reveal the inner database object.

Returns:
  the inner database object, or NULL on failure.

BasicDB::Cursor* kyotocabinet::IndexDB::cursor | ( |  | ) |

Create a cursor object.

Returns:
  the return value is the created cursor object.

Note:
  Because the object of the return value is allocated by the constructor, it should be released with the delete operator when it is no longer in use.

void kyotocabinet::IndexDB::log | ( | const char * | file,
|  | int32_t | line,
|  | const char * | func,
|  | BasicDB::Logger::Kind | kind,
|  | const char * | message
| ) |  |

Write a log message.

Parameters:

  file | the file name of the program source code.
  line | the line number of the program source code.
  func | the function name of the program source code.
  kind | the kind of the event. Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.
  message | the supplement message.

bool kyotocabinet::IndexDB::tune_logger | ( | BasicDB::Logger * | logger,
|  | uint32_t | kinds = `BasicDB::Logger::WARN | BasicDB::Logger::ERROR`
| ) |  |

Set the internal logger.

Parameters:

  logger | the logger object.
  kinds | kinds of logged messages by bitwise-or: Logger::DEBUG for debugging, Logger::INFO for normal information, Logger::WARN for warning, and Logger::ERROR for fatal error.

Returns:
  true on success, or false on failure.

bool kyotocabinet::IndexDB::tune_meta_trigger | ( | BasicDB::MetaTrigger * | trigger | ) |

Set the internal meta operation trigger.

Parameters:

  trigger | the trigger object.

Returns:
  true on success, or false on failure.

void kyotocabinet::IndexDB::report | ( | const char * | file,
|  | int32_t | line,
|  | const char * | func,
|  | const char * | format,
|  |  | ...
| ) |  | `[protected]`

Report a message for debugging.

Parameters:

  file | the file name of the program source code.
  line | the line number of the program source code.
  func | the function name of the program source code.
  format | the printf-like format string.
  ... | used according to the format string.