1 /************************************************************************************************* 2 * C language binding 3 * Copyright (C) 2009-2012 Mikio Hirabayashi 4 * This file is part of Kyoto Cabinet. 5 * This program is free software: you can redistribute it and/or modify it under the terms of 6 * the GNU General Public License as published by the Free Software Foundation, either version 7 * 3 of the License, or any later version. 8 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; 9 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 10 * See the GNU General Public License for more details. 11 * You should have received a copy of the GNU General Public License along with this program. 12 * If not, see <http://www.gnu.org/licenses/>. 13 *************************************************************************************************/ 14 15 16 #ifndef _KCLANGC_H /* duplication check */ 17 #define _KCLANGC_H 18 19 #if defined(__cplusplus) 20 extern "C" { 21 #endif 22 23 #if !defined(__STDC_LIMIT_MACROS) 24 #define __STDC_LIMIT_MACROS 1 /**< enable limit macros for C++ */ 25 #endif 26 27 #include <assert.h> 28 #include <ctype.h> 29 #include <errno.h> 30 #include <float.h> 31 #include <limits.h> 32 #include <locale.h> 33 #include <math.h> 34 #include <setjmp.h> 35 #include <stdarg.h> 36 #include <stddef.h> 37 #include <stdio.h> 38 #include <stdlib.h> 39 #include <signal.h> 40 #include <string.h> 41 #include <time.h> 42 #include <stdint.h> 43 44 45 /** 46 * C wrapper of polymorphic database. 47 */ 48 typedef struct { 49 void* db; /**< dummy member */ 50 } KCDB; 51 52 53 /** 54 * C wrapper of polymorphic cursor. 55 */ 56 typedef struct { 57 void* cur; /**< dummy member */ 58 } KCCUR; 59 60 61 /** 62 * Binary string of byte array. 63 */ 64 typedef struct { 65 char* buf; /**< pointer to the data region */ 66 size_t size; /**< size of the data region */ 67 } KCSTR; 68 69 70 /** 71 * Key-Value record. 72 */ 73 typedef struct { 74 KCSTR key; /**< key string */ 75 KCSTR value; /**< value string */ 76 } KCREC; 77 78 79 /** 80 * Error codes. 81 */ 82 enum { 83 KCESUCCESS, /**< success */ 84 KCENOIMPL, /**< not implemented */ 85 KCEINVALID, /**< invalid operation */ 86 KCENOREPOS, /**< no repository */ 87 KCENOPERM, /**< no permission */ 88 KCEBROKEN, /**< broken file */ 89 KCEDUPREC, /**< record duplication */ 90 KCENOREC, /**< no record */ 91 KCELOGIC, /**< logical inconsistency */ 92 KCESYSTEM, /**< system error */ 93 KCEMISC = 15 /**< miscellaneous error */ 94 }; 95 96 97 /** 98 * Open modes. 99 */ 100 enum { 101 KCOREADER = 1 << 0, /**< open as a reader */ 102 KCOWRITER = 1 << 1, /**< open as a writer */ 103 KCOCREATE = 1 << 2, /**< writer creating */ 104 KCOTRUNCATE = 1 << 3, /**< writer truncating */ 105 KCOAUTOTRAN = 1 << 4, /**< auto transaction */ 106 KCOAUTOSYNC = 1 << 5, /**< auto synchronization */ 107 KCONOLOCK = 1 << 6, /**< open without locking */ 108 KCOTRYLOCK = 1 << 7, /**< lock without blocking */ 109 KCONOREPAIR = 1 << 8 /**< open without auto repair */ 110 }; 111 112 113 /** 114 * Merge modes. 115 */ 116 enum { 117 KCMSET, /**< overwrite the existing value */ 118 KCMADD, /**< keep the existing value */ 119 KCMREPLACE, /**< modify the existing record only */ 120 KCMAPPEND /**< append the new value */ 121 }; 122 123 124 /** The package version. */ 125 extern const char* const KCVERSION; 126 127 128 /** Special pointer for no operation by the visiting function. */ 129 extern const char* const KCVISNOP; 130 131 132 /** Special pointer to remove the record by the visiting function. */ 133 extern const char* const KCVISREMOVE; 134 135 136 /** 137 * Call back function to visit a full record. 138 * @param kbuf the pointer to the key region. 139 * @param ksiz the size of the key region. 140 * @param vbuf the pointer to the value region. 141 * @param vsiz the size of the value region. 142 * @param sp the pointer to the variable into which the size of the region of the return 143 * value is assigned. 144 * @param opq an opaque pointer. 145 * @return If it is the pointer to a region, the value is replaced by the content. If it 146 * is KCVISNOP, nothing is modified. If it is KCVISREMOVE, the record is removed. 147 */ 148 typedef const char* (*KCVISITFULL)(const char* kbuf, size_t ksiz, 149 const char* vbuf, size_t vsiz, size_t* sp, void* opq); 150 151 152 /** 153 * Call back function to visit an empty record. 154 * @param kbuf the pointer to the key region. 155 * @param ksiz the size of the key region. 156 * @param sp the pointer to the variable into which the size of the region of the return 157 * value is assigned. 158 * @param opq an opaque pointer. 159 * @return If it is the pointer to a region, the value is replaced by the content. If it 160 * is KCVISNOP or KCVISREMOVE, nothing is modified. 161 */ 162 typedef const char* (*KCVISITEMPTY)(const char* kbuf, size_t ksiz, size_t* sp, void* opq); 163 164 165 /** 166 * Call back function to process the database file. 167 * @param path the path of the database file. 168 * @param count the number of records. 169 * @param size the size of the available region. 170 * @param opq an opaque pointer. 171 * @return true on success, or false on failure. 172 */ 173 typedef int32_t (*KCFILEPROC)(const char* path, int64_t count, int64_t size, void* opq); 174 175 176 /** 177 * Allocate a region on memory. 178 * @param size the size of the region. 179 * @return the pointer to the allocated region. The region of the return value should be 180 * released with the kcfree function when it is no longer in use. 181 */ 182 void* kcmalloc(size_t size); 183 184 185 /** 186 * Release a region allocated in the library. 187 * @param ptr the pointer to the region. 188 */ 189 void kcfree(void* ptr); 190 191 192 /** 193 * Get the time of day in seconds. 194 * @return the time of day in seconds. The accuracy is in microseconds. 195 */ 196 double kctime(void); 197 198 199 /** 200 * Convert a string to an integer. 201 * @param str specifies the string. 202 * @return the integer. If the string does not contain numeric expression, 0 is returned. 203 */ 204 int64_t kcatoi(const char* str); 205 206 207 /** 208 * Convert a string with a metric prefix to an integer. 209 * @param str the string, which can be trailed by a binary metric prefix. "K", "M", "G", "T", 210 * "P", and "E" are supported. They are case-insensitive. 211 * @return the integer. If the string does not contain numeric expression, 0 is returned. If 212 * the integer overflows the domain, INT64_MAX or INT64_MIN is returned according to the 213 * sign. 214 */ 215 int64_t kcatoix(const char* str); 216 217 218 /** 219 * Convert a string to a real number. 220 * @param str specifies the string. 221 * @return the real number. If the string does not contain numeric expression, 0.0 is 222 * returned. 223 */ 224 double kcatof(const char* str); 225 226 227 /** 228 * Get the hash value by MurMur hashing. 229 * @param buf the source buffer. 230 * @param size the size of the source buffer. 231 * @return the hash value. 232 */ 233 uint64_t kchashmurmur(const void* buf, size_t size); 234 235 236 /** 237 * Get the hash value by FNV hashing. 238 * @param buf the source buffer. 239 * @param size the size of the source buffer. 240 * @return the hash value. 241 */ 242 uint64_t kchashfnv(const void* buf, size_t size); 243 244 245 /** 246 * Calculate the levenshtein distance of two regions. 247 * @param abuf the pointer to the region of one buffer. 248 * @param asiz the size of the region of one buffer. 249 * @param bbuf the pointer to the region of the other buffer. 250 * @param bsiz the size of the region of the other buffer. 251 * @param utf flag to treat keys as UTF-8 strings. 252 * @return the levenshtein distance of two regions. 253 */ 254 size_t kclevdist(const void* abuf, size_t asiz, const void* bbuf, size_t bsiz, int32_t utf); 255 256 257 /** 258 * Get the quiet Not-a-Number value. 259 * @return the quiet Not-a-Number value. 260 */ 261 double kcnan(); 262 263 264 /** 265 * Get the positive infinity value. 266 * @return the positive infinity value. 267 */ 268 double kcinf(); 269 270 271 /** 272 * Check a number is a Not-a-Number value. 273 * @return true for the number is a Not-a-Number value, or false if not. 274 */ 275 int32_t kcchknan(double num); 276 277 278 /** 279 * Check a number is an infinity value. 280 * @return true for the number is an infinity value, or false if not. 281 */ 282 int32_t kcchkinf(double num); 283 284 285 /** 286 * Get the readable string of an error code. 287 * @param code the error code. 288 * @return the readable string of the error code. 289 */ 290 const char* kcecodename(int32_t code); 291 292 293 /** 294 * Create a polymorphic database object. 295 * @return the created database object. 296 * @note The object of the return value should be released with the kcdbdel function when it is 297 * no longer in use. 298 */ 299 KCDB* kcdbnew(void); 300 301 302 /** 303 * Destroy a database object. 304 * @param db the database object. 305 */ 306 void kcdbdel(KCDB* db); 307 308 309 /** 310 * Open a database file. 311 * @param db a database object. 312 * @param path the path of a database file. If it is "-", the database will be a prototype 313 * hash database. If it is "+", the database will be a prototype tree database. If it is ":", 314 * the database will be a stash database. If it is "*", the database will be a cache hash 315 * database. If it is "%", the database will be a cache tree database. If its suffix is 316 * ".kch", the database will be a file hash database. If its suffix is ".kct", the database 317 * will be a file tree database. If its suffix is ".kcd", the database will be a directory 318 * hash database. If its suffix is ".kcf", the database will be a directory tree database. 319 * If its suffix is ".kcx", the database will be a plain text database. Otherwise, this 320 * function fails. Tuning parameters can trail the name, separated by "#". Each parameter is 321 * composed of the name and the value, separated by "=". If the "type" parameter is specified, 322 * the database type is determined by the value in "-", "+", ":", "*", "%", "kch", "kct", 323 * "kcd", kcf", and "kcx". All database types support the logging parameters of "log", 324 * "logkinds", and "logpx". The prototype hash database and the prototype tree database do 325 * not support any other tuning parameter. The stash database supports "bnum". The cache 326 * hash database supports "opts", "bnum", "zcomp", "capcnt", "capsiz", and "zkey". The cache 327 * tree database supports all parameters of the cache hash database except for capacity 328 * limitation, and supports "psiz", "rcomp", "pccap" in addition. The file hash database 329 * supports "apow", "fpow", "opts", "bnum", "msiz", "dfunit", "zcomp", and "zkey". The file 330 * tree database supports all parameters of the file hash database and "psiz", "rcomp", 331 * "pccap" in addition. The directory hash database supports "opts", "zcomp", and "zkey". 332 * The directory tree database supports all parameters of the directory hash database and 333 * "psiz", "rcomp", "pccap" in addition. The plain text database does not support any other 334 * tuning parameter. 335 * @param mode the connection mode. KCOWRITER as a writer, KCOREADER as a reader. 336 * The following may be added to the writer mode by bitwise-or: KCOCREATE, which means 337 * it creates a new database if the file does not exist, KCOTRUNCATE, which means it 338 * creates a new database regardless if the file exists, KCOAUTOTRAN, which means each 339 * updating operation is performed in implicit transaction, KCOAUTOSYNC, which means 340 * each updating operation is followed by implicit synchronization with the file system. The 341 * following may be added to both of the reader mode and the writer mode by bitwise-or: 342 * KCONOLOCK, which means it opens the database file without file locking, 343 * KCOTRYLOCK, which means locking is performed without blocking, KCONOREPAIR, which 344 * means the database file is not repaired implicitly even if file destruction is detected. 345 * @return true on success, or false on failure. 346 * @note The tuning parameter "log" is for the original "tune_logger" and the value specifies 347 * the path of the log file, or "-" for the standard output, or "+" for the standard error. 348 * "logkinds" specifies kinds of logged messages and the value can be "debug", "info", "warn", 349 * or "error". "logpx" specifies the prefix of each log message. "opts" is for "tune_options" 350 * and the value can contain "s" for the small option, "l" for the linear option, and "c" for 351 * the compress option. "bnum" corresponds to "tune_bucket". "zcomp" is for "tune_compressor" 352 * and the value can be "zlib" for the ZLIB raw compressor, "def" for the ZLIB deflate 353 * compressor, "gz" for the ZLIB gzip compressor, "lzo" for the LZO compressor, "lzma" for the 354 * LZMA compressor, or "arc" for the Arcfour cipher. "zkey" specifies the cipher key of the 355 * compressor. "capcount" is for "cap_count". "capsize" is for "cap_size". "psiz" is for 356 * "tune_page". "rcomp" is for "tune_comparator" and the value can be "lex" for the lexical 357 * comparator or "dec" for the decimal comparator. "pccap" is for "tune_page_cache". "apow" 358 * is for "tune_alignment". "fpow" is for "tune_fbp". "msiz" is for "tune_map". "dfunit" is 359 * for "tune_defrag". Every opened database must be closed by the kcdbclose method when it is 360 * no longer in use. It is not allowed for two or more database objects in the same process to 361 * keep their connections to the same database file at the same time. 362 */ 363 int32_t kcdbopen(KCDB* db, const char* path, uint32_t mode); 364 365 366 /** 367 * Close the database file. 368 * @param db a database object. 369 * @return true on success, or false on failure. 370 */ 371 int32_t kcdbclose(KCDB* db); 372 373 374 /** 375 * Get the code of the last happened error. 376 * @param db a database object. 377 * @return the code of the last happened error. 378 */ 379 int32_t kcdbecode(KCDB* db); 380 381 382 /** 383 * Get the supplement message of the last happened error. 384 * @param db a database object. 385 * @return the supplement message of the last happened error. 386 */ 387 const char* kcdbemsg(KCDB* db); 388 389 390 /** 391 * Accept a visitor to a record. 392 * @param db a database object. 393 * @param kbuf the pointer to the key region. 394 * @param ksiz the size of the key region. 395 * @param fullproc a call back function to visit a record. 396 * @param emptyproc a call back function to visit an empty record space. 397 * @param opq an opaque pointer to be given to the call back functions. 398 * @param writable true for writable operation, or false for read-only operation. 399 * @return true on success, or false on failure. 400 * @note The operation for each record is performed atomically and other threads accessing the 401 * same record are blocked. To avoid deadlock, any explicit database operation must not be 402 * performed in this function. 403 */ 404 int32_t kcdbaccept(KCDB* db, const char* kbuf, size_t ksiz, 405 KCVISITFULL fullproc, KCVISITEMPTY emptyproc, void* opq, int32_t writable); 406 407 408 /** 409 * Accept a visitor to multiple records at once. 410 * @param db a database object. 411 * @param keys specifies an array of binary strings of the keys. 412 * @param knum specifies the number of the keys. 413 * @param fullproc a call back function to visit a record. 414 * @param emptyproc a call back function to visit an empty record space. 415 * @param opq an opaque pointer to be given to the call back functions. 416 * @param writable true for writable operation, or false for read-only operation. 417 * @return true on success, or false on failure. 418 * @note The operations for specified records are performed atomically and other threads 419 * accessing the same records are blocked. To avoid deadlock, any explicit database operation 420 * must not be performed in this function. 421 */ 422 int32_t kcdbacceptbulk(KCDB* db, const KCSTR* keys, size_t knum, 423 KCVISITFULL fullproc, KCVISITEMPTY emptyproc, 424 void* opq, int32_t writable); 425 426 427 /** 428 * Iterate to accept a visitor for each record. 429 * @param db a database object. 430 * @param fullproc a call back function to visit a record. 431 * @param opq an opaque pointer to be given to the call back function. 432 * @param writable true for writable operation, or false for read-only operation. 433 * @return true on success, or false on failure. 434 * @note The whole iteration is performed atomically and other threads are blocked. To avoid 435 * deadlock, any explicit database operation must not be performed in this function. 436 */ 437 int32_t kcdbiterate(KCDB* db, KCVISITFULL fullproc, void* opq, int32_t writable); 438 439 440 /** 441 * Scan each record in parallel. 442 * @param db a database object. 443 * @param fullproc a call back function to visit a record. 444 * @param opq an opaque pointer to be given to the call back function. 445 * @param thnum the number of worker threads. 446 * @return true on success, or false on failure. 447 * @note This function is for reading records and not for updating ones. The return value of 448 * the visitor is just ignored. To avoid deadlock, any explicit database operation must not 449 * be performed in this function. 450 */ 451 int32_t kcdbscanpara(KCDB* db, KCVISITFULL fullproc, void* opq, size_t thnum); 452 453 454 /** 455 * Set the value of a record. 456 * @param db a database object. 457 * @param kbuf the pointer to the key region. 458 * @param ksiz the size of the key region. 459 * @param vbuf the pointer to the value region. 460 * @param vsiz the size of the value region. 461 * @return true on success, or false on failure. 462 * @note If no record corresponds to the key, a new record is created. If the corresponding 463 * record exists, the value is overwritten. 464 */ 465 int32_t kcdbset(KCDB* db, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 466 467 468 /** 469 * Add a record. 470 * @param db a database object. 471 * @param kbuf the pointer to the key region. 472 * @param ksiz the size of the key region. 473 * @param vbuf the pointer to the value region. 474 * @param vsiz the size of the value region. 475 * @return true on success, or false on failure. 476 * @note If no record corresponds to the key, a new record is created. If the corresponding 477 * record exists, the record is not modified and false is returned. 478 */ 479 int32_t kcdbadd(KCDB* db, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 480 481 482 /** 483 * Replace the value of a record. 484 * @param db a database object. 485 * @param kbuf the pointer to the key region. 486 * @param ksiz the size of the key region. 487 * @param vbuf the pointer to the value region. 488 * @param vsiz the size of the value region. 489 * @return true on success, or false on failure. 490 * @note If no record corresponds to the key, no new record is created and false is returned. 491 * If the corresponding record exists, the value is modified. 492 */ 493 int32_t kcdbreplace(KCDB* db, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 494 495 496 /** 497 * Append the value of a record. 498 * @param db a database object. 499 * @param kbuf the pointer to the key region. 500 * @param ksiz the size of the key region. 501 * @param vbuf the pointer to the value region. 502 * @param vsiz the size of the value region. 503 * @return true on success, or false on failure. 504 * @note If no record corresponds to the key, a new record is created. If the corresponding 505 * record exists, the given value is appended at the end of the existing value. 506 */ 507 int32_t kcdbappend(KCDB* db, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 508 509 510 /** 511 * Add a number to the numeric value of a record. 512 * @param db a database object. 513 * @param kbuf the pointer to the key region. 514 * @param ksiz the size of the key region. 515 * @param num the additional number. 516 * @param orig the origin number if no record corresponds to the key. If it is INT64_MIN and 517 * no record corresponds, this function fails. If it is INT64_MAX, the value is set as the 518 * additional number regardless of the current value. 519 * @return the result value, or INT64_MIN on failure. 520 * @note The value is serialized as an 8-byte binary integer in big-endian order, not a decimal 521 * string. If existing value is not 8-byte, this function fails. 522 */ 523 int64_t kcdbincrint(KCDB* db, const char* kbuf, size_t ksiz, int64_t num, int64_t orig); 524 525 526 /** 527 * Add a number to the numeric value of a record. 528 * @param db a database object. 529 * @param kbuf the pointer to the key region. 530 * @param ksiz the size of the key region. 531 * @param num the additional number. 532 * @param orig the origin number if no record corresponds to the key. If it is negative 533 * infinity and no record corresponds, this function fails. If it is positive infinity, the 534 * value is set as the additional number regardless of the current value. 535 * @return the result value, or Not-a-number on failure. 536 * @note The value is serialized as an 16-byte binary fixed-point number in big-endian order, 537 * not a decimal string. If existing value is not 16-byte, this function fails. 538 */ 539 double kcdbincrdouble(KCDB* db, const char* kbuf, size_t ksiz, double num, double orig); 540 541 542 /** 543 * Perform compare-and-swap. 544 * @param db a database object. 545 * @param kbuf the pointer to the key region. 546 * @param ksiz the size of the key region. 547 * @param ovbuf the pointer to the old value region. NULL means that no record corresponds. 548 * @param ovsiz the size of the old value region. 549 * @param nvbuf the pointer to the new value region. NULL means that the record is removed. 550 * @param nvsiz the size of new old value region. 551 * @return true on success, or false on failure. 552 */ 553 int32_t kcdbcas(KCDB* db, const char* kbuf, size_t ksiz, 554 const char* ovbuf, size_t ovsiz, const char* nvbuf, size_t nvsiz); 555 556 557 /** 558 * Remove a record. 559 * @param db a database object. 560 * @param kbuf the pointer to the key region. 561 * @param ksiz the size of the key region. 562 * @return true on success, or false on failure. 563 * @note If no record corresponds to the key, false is returned. 564 */ 565 int32_t kcdbremove(KCDB* db, const char* kbuf, size_t ksiz); 566 567 568 /** 569 * Retrieve the value of a record. 570 * @param db a database object. 571 * @param kbuf the pointer to the key region. 572 * @param ksiz the size of the key region. 573 * @param sp the pointer to the variable into which the size of the region of the return 574 * value is assigned. 575 * @return the pointer to the value region of the corresponding record, or NULL on failure. 576 * @note If no record corresponds to the key, NULL is returned. Because an additional zero 577 * code is appended at the end of the region of the return value, the return value can be 578 * treated as a C-style string. The region of the return value should be released with the 579 * kcfree function when it is no longer in use. 580 */ 581 char* kcdbget(KCDB* db, const char* kbuf, size_t ksiz, size_t* sp); 582 583 584 /** 585 * Check the existence of a record. 586 * @param db a database object. 587 * @param kbuf the pointer to the key region. 588 * @param ksiz the size of the key region. 589 * @return the size of the value, or -1 on failure. 590 */ 591 int32_t kcdbcheck(KCDB* db, const char* kbuf, size_t ksiz); 592 593 594 /** 595 * Retrieve the value of a record. 596 * @param db a database object. 597 * @param kbuf the pointer to the key region. 598 * @param ksiz the size of the key region. 599 * @param vbuf the pointer to the buffer into which the value of the corresponding record is 600 * written. 601 * @param max the size of the buffer. 602 * @return the size of the value, or -1 on failure. 603 */ 604 int32_t kcdbgetbuf(KCDB* db, const char* kbuf, size_t ksiz, char* vbuf, size_t max); 605 606 607 /** 608 * Retrieve the value of a record and remove it atomically. 609 * @param db a database object. 610 * @param kbuf the pointer to the key region. 611 * @param ksiz the size of the key region. 612 * @param sp the pointer to the variable into which the size of the region of the return 613 * value is assigned. 614 * @return the pointer to the value region of the corresponding record, or NULL on failure. 615 * @note If no record corresponds to the key, NULL is returned. Because an additional zero 616 * code is appended at the end of the region of the return value, the return value can be 617 * treated as a C-style string. The region of the return value should be released with the 618 * kcfree function when it is no longer in use. 619 */ 620 char* kcdbseize(KCDB* db, const char* kbuf, size_t ksiz, size_t* sp); 621 622 623 /** 624 * Store records at once. 625 * @param db a database object. 626 * @param recs the records to store. 627 * @param rnum specifies the number of the records. 628 * @param atomic true to perform all operations atomically, or false for non-atomic operations. 629 * @return the number of stored records, or -1 on failure. 630 */ 631 int64_t kcdbsetbulk(KCDB* db, const KCREC* recs, size_t rnum, int32_t atomic); 632 633 634 /** 635 * Remove records at once. 636 * @param db a database object. 637 * @param keys the keys of the records to remove. 638 * @param knum specifies the number of the keys. 639 * @param atomic true to perform all operations atomically, or false for non-atomic operations. 640 * @return the number of removed records, or -1 on failure. 641 */ 642 int64_t kcdbremovebulk(KCDB* db, const KCSTR* keys, size_t knum, int32_t atomic); 643 644 645 /** 646 * Retrieve records at once. 647 * @param db a database object. 648 * @param keys the keys of the records to retrieve. 649 * @param knum specifies the number of the keys. 650 * @param recs an array to contain the result. Its size must be sufficient. 651 * @param atomic true to perform all operations atomically, or false for non-atomic operations. 652 * @return the number of retrieved records, or -1 on failure. 653 * @note The regions of the key and the value of each element of the result should be released 654 * with the kcfree function when it is no longer in use. 655 */ 656 int64_t kcdbgetbulk(KCDB* db, const KCSTR* keys, size_t knum, KCREC* recs, int32_t atomic); 657 658 659 /** 660 * Synchronize updated contents with the file and the device. 661 * @param db a database object. 662 * @param hard true for physical synchronization with the device, or false for logical 663 * synchronization with the file system. 664 * @param proc a postprocessor call back function. If it is NULL, no postprocessing is 665 * performed. 666 * @param opq an opaque pointer to be given to the call back function. 667 * @return true on success, or false on failure. 668 * @note The operation of the postprocessor is performed atomically and other threads accessing 669 * the same record are blocked. To avoid deadlock, any explicit database operation must not 670 * be performed in this function. 671 */ 672 int32_t kcdbsync(KCDB* db, int32_t hard, KCFILEPROC proc, void* opq); 673 674 675 /** 676 * Occupy database by locking and do something meanwhile. 677 * @param db a database object. 678 * @param writable true to use writer lock, or false to use reader lock. 679 * @param proc a processor object. If it is NULL, no processing is performed. 680 * @param opq an opaque pointer to be given to the call back function. 681 * @return true on success, or false on failure. 682 * @note The operation of the processor is performed atomically and other threads accessing 683 * the same record are blocked. To avoid deadlock, any explicit database operation must not 684 * be performed in this function. 685 */ 686 int32_t kcdboccupy(KCDB* db, int32_t writable, KCFILEPROC proc, void* opq); 687 688 689 /** 690 * Create a copy of the database file. 691 * @param db a database object. 692 * @param dest the path of the destination file. 693 * @return true on success, or false on failure. 694 */ 695 int32_t kcdbcopy(KCDB* db, const char* dest); 696 697 698 /** 699 * Begin transaction. 700 * @param db a database object. 701 * @param hard true for physical synchronization with the device, or false for logical 702 * synchronization with the file system. 703 * @return true on success, or false on failure. 704 */ 705 int32_t kcdbbegintran(KCDB* db, int32_t hard); 706 707 708 /** 709 * Try to begin transaction. 710 * @param db a database object. 711 * @param hard true for physical synchronization with the device, or false for logical 712 * synchronization with the file system. 713 * @return true on success, or false on failure. 714 */ 715 int32_t kcdbbegintrantry(KCDB* db, int32_t hard); 716 717 718 /** 719 * End transaction. 720 * @param db a database object. 721 * @param commit true to commit the transaction, or false to abort the transaction. 722 * @return true on success, or false on failure. 723 */ 724 int32_t kcdbendtran(KCDB* db, int32_t commit); 725 726 727 /** 728 * Remove all records. 729 * @param db a database object. 730 * @return true on success, or false on failure. 731 */ 732 int32_t kcdbclear(KCDB* db); 733 734 735 /** 736 * Dump records into a file. 737 * @param db a database object. 738 * @param dest the path of the destination file. 739 * @return true on success, or false on failure. 740 */ 741 int32_t kcdbdumpsnap(KCDB* db, const char* dest); 742 743 744 /** 745 * Load records from a file. 746 * @param db a database object. 747 * @param src the path of the source file. 748 * @return true on success, or false on failure. 749 */ 750 int32_t kcdbloadsnap(KCDB* db, const char* src); 751 752 753 /** 754 * Get the number of records. 755 * @param db a database object. 756 * @return the number of records, or -1 on failure. 757 */ 758 int64_t kcdbcount(KCDB* db); 759 760 761 /** 762 * Get the size of the database file. 763 * @param db a database object. 764 * @return the size of the database file in bytes, or -1 on failure. 765 */ 766 int64_t kcdbsize(KCDB* db); 767 768 769 /** 770 * Get the path of the database file. 771 * @param db a database object. 772 * @return the path of the database file, or an empty string on failure. 773 * @note The region of the return value should be released with the kcfree function when it is 774 * no longer in use. 775 */ 776 char* kcdbpath(KCDB* db); 777 778 779 /** 780 * Get the miscellaneous status information. 781 * @param db a database object. 782 * @return the result string of tab saparated values, or NULL on failure. Each line consists of 783 * the attribute name and its value separated by a tab character. 784 * @note The region of the return value should be released with the kcfree function when it is 785 * no longer in use. 786 */ 787 char* kcdbstatus(KCDB* db); 788 789 790 /** 791 * Get keys matching a prefix string. 792 * @param db a database object. 793 * @param prefix the prefix string. 794 * @param strary an array to contain the result. Its size must be sufficient. 795 * @param max the maximum number to retrieve. 796 * @return the number of retrieved keys or -1 on failure. 797 * @note The region of each element of the result should be released with the kcfree function 798 * when it is no longer in use. 799 */ 800 int64_t kcdbmatchprefix(KCDB* db, const char* prefix, char** strary, size_t max); 801 802 803 /** 804 * Get keys matching a regular expression string. 805 * @param db a database object. 806 * @param regex the regular expression string. 807 * @param strary an array to contain the result. Its size must be sufficient. 808 * @param max the maximum number to retrieve. 809 * @return the number of retrieved keys or -1 on failure. 810 * @note The region of each element of the result should be released with the kcfree function 811 * when it is no longer in use. 812 */ 813 int64_t kcdbmatchregex(KCDB* db, const char* regex, char** strary, size_t max); 814 815 816 /** 817 * Get keys similar to a string in terms of the levenshtein distance. 818 * @param db a database object. 819 * @param origin the origin string. 820 * @param range the maximum distance of keys to adopt. 821 * @param utf flag to treat keys as UTF-8 strings. 822 * @param strary an array to contain the result. Its size must be sufficient. 823 * @param max the maximum number to retrieve. 824 * @return the number of retrieved keys or -1 on failure. 825 * @note The region of each element of the result should be released with the kcfree function 826 * when it is no longer in use. 827 */ 828 int64_t kcdbmatchsimilar(KCDB* db, const char* origin, uint32_t range, int32_t utf, 829 char** strary, size_t max); 830 831 832 /** 833 * Merge records from other databases. 834 * @param db a database object. 835 * @param srcary an array of the source detabase objects. 836 * @param srcnum the number of the elements of the source array. 837 * @param mode the merge mode. KCMSET to overwrite the existing value, KCMADD to keep the 838 * existing value, KCMREPLACE to modify the existing record only, KCMAPPEND to append the new 839 * value. 840 * @return true on success, or false on failure. 841 */ 842 int32_t kcdbmerge(KCDB* db, KCDB** srcary, size_t srcnum, uint32_t mode); 843 844 845 /** 846 * Create a polymorphic cursor object. 847 * @param db a database object. 848 * @return the return value is the created cursor object. 849 * @note The object of the return value should be released with the kccurdel function when it is 850 * no longer in use. 851 */ 852 KCCUR* kcdbcursor(KCDB* db); 853 854 855 /** 856 * Destroy a cursor object. 857 * @param cur the cursor object. 858 */ 859 void kccurdel(KCCUR* cur); 860 861 862 /** 863 * Accept a visitor to the current record. 864 * @param cur a cursor object. 865 * @param fullproc a call back function to visit a record. 866 * @param opq an opaque pointer to be given to the call back functions. 867 * @param writable true for writable operation, or false for read-only operation. 868 * @param step true to move the cursor to the next record, or false for no move. 869 * @return true on success, or false on failure. 870 * @note The operation for each record is performed atomically and other threads accessing 871 * the same record are blocked. To avoid deadlock, any explicit database operation must not 872 * be performed in this function. 873 */ 874 int32_t kccuraccept(KCCUR* cur, KCVISITFULL fullproc, void* opq, 875 int32_t writable, int32_t step); 876 877 878 /** 879 * Set the value of the current record. 880 * @param cur a cursor object. 881 * @param vbuf the pointer to the value region. 882 * @param vsiz the size of the value region. 883 * @param step true to move the cursor to the next record, or false for no move. 884 * @return true on success, or false on failure. 885 */ 886 int32_t kccursetvalue(KCCUR* cur, const char* vbuf, size_t vsiz, int32_t step); 887 888 889 /** 890 * Remove the current record. 891 * @param cur a cursor object. 892 * @return true on success, or false on failure. 893 * @note If no record corresponds to the key, false is returned. The cursor is moved to the 894 * next record implicitly. 895 */ 896 int32_t kccurremove(KCCUR* cur); 897 898 899 /** 900 * Get the key of the current record. 901 * @param cur a cursor object. 902 * @param sp the pointer to the variable into which the size of the region of the return value 903 * is assigned. 904 * @param step true to move the cursor to the next record, or false for no move. 905 * @return the pointer to the key region of the current record, or NULL on failure. 906 * @note If the cursor is invalidated, NULL is returned. Because an additional zero 907 * code is appended at the end of the region of the return value, the return value can be 908 * treated as a C-style string. The region of the return value should be released with the 909 * kcfree function when it is no longer in use. 910 */ 911 char* kccurgetkey(KCCUR* cur, size_t* sp, int32_t step); 912 913 914 /** 915 * Get the value of the current record. 916 * @param cur a cursor object. 917 * @param sp the pointer to the variable into which the size of the region of the return value 918 * is assigned. 919 * @param step true to move the cursor to the next record, or false for no move. 920 * @return the pointer to the value region of the current record, or NULL on failure. 921 * @note If the cursor is invalidated, NULL is returned. Because an additional zero 922 * code is appended at the end of the region of the return value, the return value can be 923 * treated as a C-style string. The region of the return value should be released with the 924 * kcfree function when it is no longer in use. 925 */ 926 char* kccurgetvalue(KCCUR* cur, size_t* sp, int32_t step); 927 928 929 /** 930 * Get a pair of the key and the value of the current record. 931 * @param cur a cursor object. 932 * @param ksp the pointer to the variable into which the size of the region of the return 933 * value is assigned. 934 * @param vbp the pointer to the variable into which the pointer to the value region is 935 * assigned. 936 * @param vsp the pointer to the variable into which the size of the value region is 937 * assigned. 938 * @param step true to move the cursor to the next record, or false for no move. 939 * @return the pointer to the pair of the key region, or NULL on failure. 940 * @note If the cursor is invalidated, NULL is returned. Because an additional zero code is 941 * appended at the end of each region of the key and the value, each region can be treated 942 * as a C-style string. The region of the return value should be released with the kcfree 943 * function when it is no longer in use. 944 */ 945 char* kccurget(KCCUR* cur, size_t* ksp, const char** vbp, size_t* vsp, int32_t step); 946 947 948 /** 949 * Get a pair of the key and the value of the current record and remove it atomically. 950 * @param cur a cursor object. 951 * @param ksp the pointer to the variable into which the size of the region of the return 952 * value is assigned. 953 * @param vbp the pointer to the variable into which the pointer to the value region is 954 * assigned. 955 * @param vsp the pointer to the variable into which the size of the value region is 956 * assigned. 957 * @return the pointer to the pair of the key region, or NULL on failure. 958 * @note If the cursor is invalidated, NULL is returned. Because an additional zero code is 959 * appended at the end of each region of the key and the value, each region can be treated 960 * as a C-style string. The region of the return value should be released with the kcfree 961 * function when it is no longer in use. The cursor is moved to the next record implicitly. 962 */ 963 char* kccurseize(KCCUR* cur, size_t* ksp, const char** vbp, size_t* vsp); 964 965 966 /** 967 * Jump the cursor to the first record for forward scan. 968 * @param cur a cursor object. 969 * @return true on success, or false on failure. 970 */ 971 int32_t kccurjump(KCCUR* cur); 972 973 974 /** 975 * Jump the cursor to a record for forward scan. 976 * @param cur a cursor object. 977 * @param kbuf the pointer to the key region. 978 * @param ksiz the size of the key region. 979 * @return true on success, or false on failure. 980 */ 981 int32_t kccurjumpkey(KCCUR* cur, const char* kbuf, size_t ksiz); 982 983 984 /** 985 * Jump the cursor to the last record for backward scan. 986 * @param cur a cursor object. 987 * @return true on success, or false on failure. 988 * @note This method is dedicated to tree databases. Some database types, especially hash 989 * databases, may provide a dummy implementation. 990 */ 991 int32_t kccurjumpback(KCCUR* cur); 992 993 994 /** 995 * Jump the cursor to a record for backward scan. 996 * @param cur a cursor object. 997 * @param kbuf the pointer to the key region. 998 * @param ksiz the size of the key region. 999 * @return true on success, or false on failure. 1000 * @note This method is dedicated to tree databases. Some database types, especially hash 1001 * databases, will provide a dummy implementation. 1002 */ 1003 int32_t kccurjumpbackkey(KCCUR* cur, const char* kbuf, size_t ksiz); 1004 1005 1006 /** 1007 * Step the cursor to the next record. 1008 * @param cur a cursor object. 1009 * @return true on success, or false on failure. 1010 */ 1011 int32_t kccurstep(KCCUR* cur); 1012 1013 1014 /** 1015 * Step the cursor to the previous record. 1016 * @param cur a cursor object. 1017 * @return true on success, or false on failure. 1018 * @note This method is dedicated to tree databases. Some database types, especially hash 1019 * databases, may provide a dummy implementation. 1020 */ 1021 int32_t kccurstepback(KCCUR* cur); 1022 1023 1024 /** 1025 * Get the database object. 1026 * @param cur a cursor object. 1027 * @return the database object. 1028 */ 1029 KCDB* kccurdb(KCCUR* cur); 1030 1031 1032 /** 1033 * Get the code of the last happened error. 1034 * @param cur a cursor object. 1035 * @return the code of the last happened error. 1036 */ 1037 int32_t kccurecode(KCCUR* cur); 1038 1039 1040 /** 1041 * Get the supplement message of the last happened error. 1042 * @param cur a cursor object. 1043 * @return the supplement message of the last happened error. 1044 */ 1045 const char* kccuremsg(KCCUR* cur); 1046 1047 1048 /** 1049 * C wrapper of index database. 1050 */ 1051 typedef struct { 1052 void* db; /**< dummy member */ 1053 } KCIDX; 1054 1055 1056 /** 1057 * Create an index database object. 1058 * @return the created database object. 1059 * @note The object of the return value should be released with the kcidxdel function when it is 1060 * no longer in use. 1061 */ 1062 KCIDX* kcidxnew(void); 1063 1064 1065 /** 1066 * Destroy a database object. 1067 * @param idx the database object. 1068 */ 1069 void kcidxdel(KCIDX* idx); 1070 1071 1072 /** 1073 * Open a database file. 1074 * @param idx a database object. 1075 * @param path the path of a database file. The same as with the polymorphic database. 1076 * @param mode the connection mode. The same as with the polymorphic database. 1077 * @return true on success, or false on failure. 1078 */ 1079 int32_t kcidxopen(KCIDX* idx, const char* path, uint32_t mode); 1080 1081 1082 /** 1083 * Close the database file. 1084 * @param idx a database object. 1085 * @return true on success, or false on failure. 1086 */ 1087 int32_t kcidxclose(KCIDX* idx); 1088 1089 1090 /** 1091 * Get the code of the last happened error. 1092 * @param idx a database object. 1093 * @return the code of the last happened error. 1094 */ 1095 int32_t kcidxecode(KCIDX* idx); 1096 1097 1098 /** 1099 * Get the supplement message of the last happened error. 1100 * @param idx a database object. 1101 * @return the supplement message of the last happened error. 1102 */ 1103 const char* kcidxemsg(KCIDX* idx); 1104 1105 1106 /** 1107 * Set the value of a record. 1108 * @param idx a database object. 1109 * @param kbuf the pointer to the key region. 1110 * @param ksiz the size of the key region. 1111 * @param vbuf the pointer to the value region. 1112 * @param vsiz the size of the value region. 1113 * @return true on success, or false on failure. 1114 * @note If no record corresponds to the key, a new record is created. If the corresponding 1115 * record exists, the value is overwritten. 1116 */ 1117 int32_t kcidxset(KCIDX* idx, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1118 1119 1120 /** 1121 * Add a record. 1122 * @param idx a database object. 1123 * @param kbuf the pointer to the key region. 1124 * @param ksiz the size of the key region. 1125 * @param vbuf the pointer to the value region. 1126 * @param vsiz the size of the value region. 1127 * @return true on success, or false on failure. 1128 * @note If no record corresponds to the key, a new record is created. If the corresponding 1129 * record exists, the record is not modified and false is returned. 1130 */ 1131 int32_t kcidxadd(KCIDX* idx, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1132 1133 1134 /** 1135 * Replace the value of a record. 1136 * @param idx a database object. 1137 * @param kbuf the pointer to the key region. 1138 * @param ksiz the size of the key region. 1139 * @param vbuf the pointer to the value region. 1140 * @param vsiz the size of the value region. 1141 * @return true on success, or false on failure. 1142 * @note If no record corresponds to the key, no new record is created and false is returned. 1143 * If the corresponding record exists, the value is modified. 1144 */ 1145 int32_t kcidxreplace(KCIDX* idx, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1146 1147 1148 /** 1149 * Append the value of a record. 1150 * @param idx a database object. 1151 * @param kbuf the pointer to the key region. 1152 * @param ksiz the size of the key region. 1153 * @param vbuf the pointer to the value region. 1154 * @param vsiz the size of the value region. 1155 * @return true on success, or false on failure. 1156 * @note If no record corresponds to the key, a new record is created. If the corresponding 1157 * record exists, the given value is appended at the end of the existing value. 1158 */ 1159 int32_t kcidxappend(KCIDX* idx, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1160 1161 1162 /** 1163 * Remove a record. 1164 * @param idx a database object. 1165 * @param kbuf the pointer to the key region. 1166 * @param ksiz the size of the key region. 1167 * @return true on success, or false on failure. 1168 * @note If no record corresponds to the key, false is returned. 1169 */ 1170 int32_t kcidxremove(KCIDX* idx, const char* kbuf, size_t ksiz); 1171 1172 1173 /** 1174 * Retrieve the value of a record. 1175 * @param idx a database object. 1176 * @param kbuf the pointer to the key region. 1177 * @param ksiz the size of the key region. 1178 * @param sp the pointer to the variable into which the size of the region of the return 1179 * value is assigned. 1180 * @return the pointer to the value region of the corresponding record, or NULL on failure. 1181 * @note If no record corresponds to the key, NULL is returned. Because an additional zero 1182 * code is appended at the end of the region of the return value, the return value can be 1183 * treated as a C-style string. The region of the return value should be released with the 1184 * kcfree function when it is no longer in use. 1185 */ 1186 char* kcidxget(KCIDX* idx, const char* kbuf, size_t ksiz, size_t* sp); 1187 1188 1189 /** 1190 * Synchronize updated contents with the file and the device. 1191 * @param idx a database object. 1192 * @param hard true for physical synchronization with the device, or false for logical 1193 * synchronization with the file system. 1194 * @param proc a postprocessor call back function. If it is NULL, no postprocessing is 1195 * performed. 1196 * @param opq an opaque pointer to be given to the call back function. 1197 * @return true on success, or false on failure. 1198 * @note The operation of the postprocessor is performed atomically and other threads accessing 1199 * the same record are blocked. To avoid deadlock, any explicit database operation must not 1200 * be performed in this function. 1201 */ 1202 int32_t kcidxsync(KCIDX* idx, int32_t hard, KCFILEPROC proc, void* opq); 1203 1204 1205 /** 1206 * Remove all records. 1207 * @param idx a database object. 1208 * @return true on success, or false on failure. 1209 */ 1210 int32_t kcidxclear(KCIDX* idx); 1211 1212 1213 /** 1214 * Get the number of records. 1215 * @param idx a database object. 1216 * @return the number of records, or -1 on failure. 1217 */ 1218 int64_t kcidxcount(KCIDX* idx); 1219 1220 1221 /** 1222 * Get the size of the database file. 1223 * @param idx a database object. 1224 * @return the size of the database file in bytes, or -1 on failure. 1225 */ 1226 int64_t kcidxsize(KCIDX* idx); 1227 1228 1229 /** 1230 * Get the path of the database file. 1231 * @param idx a database object. 1232 * @return the path of the database file, or an empty string on failure. 1233 * @note The region of the return value should be released with the kcfree function when it is 1234 * no longer in use. 1235 */ 1236 char* kcidxpath(KCIDX* idx); 1237 1238 1239 /** 1240 * Get the miscellaneous status information. 1241 * @param idx a database object. 1242 * @return the result string of tab saparated values, or NULL on failure. Each line consists of 1243 * the attribute name and its value separated by a tab character. 1244 * @note The region of the return value should be released with the kcfree function when it is 1245 * no longer in use. 1246 */ 1247 char* kcidxstatus(KCIDX* idx); 1248 1249 1250 /** 1251 * Reveal the inner database object. 1252 * @return the inner database object, or NULL on failure. 1253 */ 1254 KCDB* kcidxrevealinnerdb(KCIDX* idx); 1255 1256 1257 /** 1258 * C wrapper of memory-saving string hash map. 1259 */ 1260 typedef struct { 1261 void* map; /**< dummy member */ 1262 } KCMAP; 1263 1264 1265 /** 1266 * C wrapper of iterator of memory-saving string hash map. 1267 */ 1268 typedef struct { 1269 void* iter; /**< dummy member */ 1270 } KCMAPITER; 1271 1272 1273 /** 1274 * C wrapper of sorter of memory-saving string hash map. 1275 */ 1276 typedef struct { 1277 void* iter; /**< dummy member */ 1278 } KCMAPSORT; 1279 1280 1281 /** 1282 * Create a string hash map object. 1283 * @param bnum the number of buckets of the hash table. If it is not more than 0, the default 1284 * setting 31 is specified. 1285 * @return the created map object. 1286 * @note The object of the return value should be released with the kcmapdel function when it is 1287 * no longer in use. 1288 */ 1289 KCMAP* kcmapnew(size_t bnum); 1290 1291 1292 /** 1293 * Destroy a map object. 1294 * @param map the map object. 1295 */ 1296 void kcmapdel(KCMAP* map); 1297 1298 1299 /** 1300 * Set the value of a record. 1301 * @param map the map object. 1302 * @param kbuf the pointer to the key region. 1303 * @param ksiz the size of the key region. 1304 * @param vbuf the pointer to the value region. 1305 * @param vsiz the size of the value region. 1306 * @note If no record corresponds to the key, a new record is created. If the corresponding 1307 * record exists, the value is overwritten. 1308 */ 1309 void kcmapset(KCMAP* map, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1310 1311 1312 /** 1313 * Add a record. 1314 * @param map the map object. 1315 * @param kbuf the pointer to the key region. 1316 * @param ksiz the size of the key region. 1317 * @param vbuf the pointer to the value region. 1318 * @param vsiz the size of the value region. 1319 * @return true on success, or false on failure. 1320 * @note If no record corresponds to the key, a new record is created. If the corresponding 1321 * record exists, the record is not modified and false is returned. 1322 */ 1323 int32_t kcmapadd(KCMAP* map, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1324 1325 1326 /** 1327 * Replace the value of a record. 1328 * @param map the map object. 1329 * @param kbuf the pointer to the key region. 1330 * @param ksiz the size of the key region. 1331 * @param vbuf the pointer to the value region. 1332 * @param vsiz the size of the value region. 1333 * @return true on success, or false on failure. 1334 * @note If no record corresponds to the key, no new record is created and false is returned. 1335 * If the corresponding record exists, the value is modified. 1336 */ 1337 int32_t kcmapreplace(KCMAP* map, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1338 1339 1340 /** 1341 * Append the value of a record. 1342 * @param map the map object. 1343 * @param kbuf the pointer to the key region. 1344 * @param ksiz the size of the key region. 1345 * @param vbuf the pointer to the value region. 1346 * @param vsiz the size of the value region. 1347 * @note If no record corresponds to the key, a new record is created. If the corresponding 1348 * record exists, the given value is appended at the end of the existing value. 1349 */ 1350 void kcmapappend(KCMAP* map, const char* kbuf, size_t ksiz, const char* vbuf, size_t vsiz); 1351 1352 1353 /** 1354 * Remove a record. 1355 * @param map the map object. 1356 * @param kbuf the pointer to the key region. 1357 * @param ksiz the size of the key region. 1358 * @return true on success, or false on failure. 1359 * @note If no record corresponds to the key, false is returned. 1360 */ 1361 int32_t kcmapremove(KCMAP* map, const char* kbuf, size_t ksiz); 1362 1363 1364 /** 1365 * Retrieve the value of a record. 1366 * @param map the map object. 1367 * @param kbuf the pointer to the key region. 1368 * @param ksiz the size of the key region. 1369 * @param sp the pointer to the variable into which the size of the region of the return 1370 * value is assigned. 1371 * @return the pointer to the value region of the corresponding record, or NULL on failure. 1372 */ 1373 const char* kcmapget(KCMAP* map, const char* kbuf, size_t ksiz, size_t* sp); 1374 1375 1376 /** 1377 * Remove all records. 1378 * @param map the map object. 1379 */ 1380 void kcmapclear(KCMAP* map); 1381 1382 1383 /** 1384 * Get the number of records. 1385 * @param map the map object. 1386 * @return the number of records. 1387 */ 1388 size_t kcmapcount(KCMAP* map); 1389 1390 1391 /** 1392 * Create a string hash map iterator object. 1393 * @param map a map object. 1394 * @return the return value is the created iterator object. 1395 * @note The object of the return value should be released with the kcmapiterdel function when 1396 * it is no longer in use. 1397 * @note This object will not be invalidated even when the map object is updated once. 1398 * However, phantom records may be retrieved if they are removed after creation of each iterator. 1399 */ 1400 KCMAPITER* kcmapiterator(KCMAP* map); 1401 1402 1403 /** 1404 * Destroy an iterator object. 1405 * @param iter the iterator object. 1406 */ 1407 void kcmapiterdel(KCMAPITER* iter); 1408 1409 1410 /** 1411 * Get the key of the current record. 1412 * @param iter the iterator object. 1413 * @param sp the pointer to the variable into which the size of the region of the return 1414 * value is assigned. 1415 * @return the pointer to the key region of the current record, or NULL on failure. 1416 */ 1417 const char* kcmapitergetkey(KCMAPITER* iter, size_t* sp); 1418 1419 1420 /** 1421 * Get the value of the current record. 1422 * @param iter the iterator object. 1423 * @param sp the pointer to the variable into which the size of the region of the return 1424 * value is assigned. 1425 * @return the pointer to the value region of the current record, or NULL on failure. 1426 */ 1427 const char* kcmapitergetvalue(KCMAPITER* iter, size_t* sp); 1428 1429 1430 /** 1431 * Get a pair of the key and the value of the current record. 1432 * @param iter the iterator object. 1433 * @param ksp the pointer to the variable into which the size of the region of the return 1434 * value is assigned. 1435 * @param vbp the pointer to the variable into which the pointer to the value region is 1436 * assigned. 1437 * @param vsp the pointer to the variable into which the size of the value region is 1438 * assigned. 1439 * @return the pointer to the key region, or NULL on failure. 1440 */ 1441 const char* kcmapiterget(KCMAPITER* iter, size_t* ksp, const char** vbp, size_t* vsp); 1442 1443 1444 /** 1445 * Step the cursor to the next record. 1446 * @param iter the iterator object. 1447 */ 1448 void kcmapiterstep(KCMAPITER* iter); 1449 1450 1451 /** 1452 * Create a string hash map sorter object. 1453 * @param map a map object. 1454 * @return the return value is the created sorter object. 1455 * @note The object of the return value should be released with the kcmapsortdel function when 1456 * it is no longer in use. 1457 * @note This object will not be invalidated even when the map object is updated once. 1458 * However, phantom records may be retrieved if they are removed after creation of each sorter. 1459 */ 1460 KCMAPSORT* kcmapsorter(KCMAP* map); 1461 1462 1463 /** 1464 * Destroy an sorter object. 1465 * @param sort the sorter object. 1466 */ 1467 void kcmapsortdel(KCMAPSORT* sort); 1468 1469 1470 /** 1471 * Get the key of the current record. 1472 * @param sort the sorter object. 1473 * @param sp the pointer to the variable into which the size of the region of the return 1474 * value is assigned. 1475 * @return the pointer to the key region of the current record, or NULL on failure. 1476 */ 1477 const char* kcmapsortgetkey(KCMAPSORT* sort, size_t* sp); 1478 1479 1480 /** 1481 * Get the value of the current record. 1482 * @param sort the sorter object. 1483 * @param sp the pointer to the variable into which the size of the region of the return 1484 * value is assigned. 1485 * @return the pointer to the value region of the current record, or NULL on failure. 1486 */ 1487 const char* kcmapsortgetvalue(KCMAPSORT* sort, size_t* sp); 1488 1489 1490 /** 1491 * Get a pair of the key and the value of the current record. 1492 * @param sort the sorter object. 1493 * @param ksp the pointer to the variable into which the size of the region of the return 1494 * value is assigned. 1495 * @param vbp the pointer to the variable into which the pointer to the value region is 1496 * assigned. 1497 * @param vsp the pointer to the variable into which the size of the value region is 1498 * assigned. 1499 * @return the pointer to the key region, or NULL on failure. 1500 */ 1501 const char* kcmapsortget(KCMAPSORT* sort, size_t* ksp, const char** vbp, size_t* vsp); 1502 1503 1504 /** 1505 * Step the cursor to the next record. 1506 * @param sort the sorter object. 1507 */ 1508 void kcmapsortstep(KCMAPSORT* sort); 1509 1510 1511 /** 1512 * C wrapper of memory-saving string hash map. 1513 */ 1514 typedef struct { 1515 void* list; /**< dummy member */ 1516 } KCLIST; 1517 1518 1519 /** 1520 * Create a string array list object. 1521 * @return the created list object. 1522 * @note The object of the return value should be released with the kclistdel function when it is 1523 * no longer in use. 1524 */ 1525 KCLIST* kclistnew(); 1526 1527 1528 /** 1529 * Destroy a list object. 1530 * @param list the list object. 1531 */ 1532 void kclistdel(KCLIST* list); 1533 1534 1535 /** 1536 * Insert a record at the bottom of the list. 1537 * @param list the list object. 1538 * @param buf the pointer to the record region. 1539 * @param size the size of the record region. 1540 */ 1541 void kclistpush(KCLIST* list, const char* buf, size_t size); 1542 1543 1544 /** 1545 * Remove a record at the bottom of the list. 1546 * @param list the list object. 1547 * @return true if the operation success, or false if there is no record in the list. 1548 */ 1549 int32_t kclistpop(KCLIST* list); 1550 1551 1552 /** 1553 * Insert a record at the top of the list. 1554 * @param list the list object. 1555 * @param buf the pointer to the record region. 1556 * @param size the size of the record region. 1557 */ 1558 void kclistunshift(KCLIST* list, const char* buf, size_t size); 1559 1560 1561 /** 1562 * Remove a record at the top of the list. 1563 * @param list the list object. 1564 * @return true if the operation success, or false if there is no record in the list. 1565 */ 1566 int32_t kclistshift(KCLIST* list); 1567 1568 1569 /** 1570 * Insert a record at the position of the given index of the list. 1571 * @param list the list object. 1572 * @param buf the pointer to the record region. 1573 * @param size the size of the record region. 1574 * @param idx the index of the position. It must be equal to or less than the number of 1575 * records. 1576 */ 1577 void kclistinsert(KCLIST* list, const char* buf, size_t size, size_t idx); 1578 1579 1580 /** 1581 * Remove a record at the position of the given index of the list. 1582 * @param list the list object. 1583 * @param idx the index of the position. It must be less than the number of records. 1584 */ 1585 void kclistremove(KCLIST* list, size_t idx); 1586 1587 1588 /** 1589 * Retrieve a record at the position of the given index of the list. 1590 * @param list the list object. 1591 * @param idx the index of the position. It must be less than the number of records. 1592 * @param sp the pointer to the variable into which the size of the region of the return 1593 * value is assigned. 1594 * @return the pointer to the region of the retrieved record. 1595 */ 1596 const char* kclistget(KCLIST* list, size_t idx, size_t* sp); 1597 1598 1599 /** 1600 * Remove all records. 1601 * @param list the list object. 1602 */ 1603 void kclistclear(KCLIST* list); 1604 1605 1606 /** 1607 * Get the number of records. 1608 * @param list the list object. 1609 * @return the number of records. 1610 */ 1611 size_t kclistcount(KCLIST* list); 1612 1613 1614 #if defined(__cplusplus) 1615 } 1616 #endif 1617 1618 #endif /* duplication check */ 1619 1620 /* END OF FILE */ 1621