qLibc
/home/wolkykim/ws/qlibc/README.md
1 What's qLibc?
2 =============
3 
4 qLibc is currently one of the most functionally-complete, publicly-licensed
5 C/C++ libraries. The goal of the qLibc project is to provide a **simple and
6 powerful general purpose C/C++ library** that includes all kinds of containers
7 and general library routines. It provides a ready-made set of common container
8 APIs with a consistent API look.
9 
10 ## qLibc Copyright
11 
12 qLibc is published under 2-clause BSD license known as Simplified BSD License.
13 Please refer the LICENSE document included in the package for more details.
14 
15 ## API Reference
16 
17 * [qlibc Core API Reference](http://wolkykim.github.io/qlibc/doc/html/files.html)
18  * Containers for Key/Value pairs
19  * Tree Table --- in binary tree(left-leaning red-black tree) data structure.
20  * Hash Table --- in hash-based data structure.
21  * Static Hash Table --- in fixed size memory(array/mmapped/shared).
22  * List Table --- in (doubly) linked-list data structure.
23  * Containers for Objects
24  * List --- Doubly Linked List.
25  * Vector --- implements a growable array of elements.
26  * Queue --- FIFO(First In First Out) implementation.
27  * Stack --- LIFO(Last In First Out) implementation.
28  * General utilities.
29  * String --- string trimmer, modifier, replacer, case converter, pattern detectors, ...
30  * I/O --- non-blcking I/O, stream reader/writer, ...
31  * File --- file locking, file/directory hander, path correctors, ...
32  * IPC, Semaphore Shared-memory
33  * En/decoders --- Url en/decoder, Base64 en/decoder, Hex en/decoder, ...
34  * Hashes --- Murmur hases, FNV hases, MD5 hashes, ...
35  * Time --- time diff, time format converstion, ...
36 
37 * [qLibc Extension API Reference](http://wolkykim.github.io/qlibc/doc/html/files.html)
38  * Apache-style Configuration File Parser.
39  * INI-style Configuration File Parser.
40  * HTTP client.
41  * Rotating File Logger.
42  * Database(MySQL) interface.
43  * [Token-Bucket](http://en.wikipedia.org/wiki/Token_bucket)
44 
45 ## qLibc Tables at a Glance
46 
47 | Characteristics | Tree Table | Hash Table |Static Hash Table| List Table |
48 |:--------------------|:------------:|:------------:|:---------------:|:------------:|
49 | Data structure | Binary Tree | Slot Index | Block Array | Linked-List |
50 | Search complexity | O(log n) | O(1) / O(n) | O(1) / O(n) | O(n) |
51 | Insert complexity | O(log n) | O(1) / O(n) | O(1) / O(n) | O(1) |
52 | Delete complexity | O(log n) | O(1) / O(n) | O(1) / O(n) | O(n) |
53 | Space complexity | O(n) | O(n) | - | O(n) |
54 | Space allocation | Dynamic | Dynamic | Pre-allocation | Dynamic |
55 | Data Stored Sorted | Yes | No | No | Yes (option) |
56 | User comparator | Supported | - | - | Supported |
57 | Allow multi-keys | No | No | No | Yes (option) |
58 | Key stored digested | No | No | Yes | No |
59 | Search Nearest Key | Yes | No | No | No |
60 | Iterator support | Yes | Yes | Yes | Yes |
61 | Iterator visit order| min -> max | random | random | insert order |
62 | Thread-safe option | Supported | Suported | No | Supported |
63 | Runs on shared mem | No | No | Yes | No |
64 
65 ## Consistent API Look
66 
67 All container APIs have a consistent look and feel. It basically provides
68 a creator function which usually returns a pointer to a container structure.
69 Also, **all functions related to the container can be accessed through function
70 pointers inside of the container** or traditional style direct access APIs.
71 For an example,
72 
73 So, regardless of which container you use, you can simply put elements into
74 a list with `container->put(container, ...)` or you can call them using
75 direct API like qtreetbl_pub(container, ...).
76 
77 An examples below illustrates how it looks like.
78 
79 ~~~{.c}
80  // create a hash-table.
81  qhashtbl_t *tbl = qhashtbl(0, QHASHTBL_OPT_THREADSAFE);
82 
83  // add an element which key name is "score".
84  int x = 12345;
85  tbl->put(tbl, "score", &x, sizeof(int));
86 
87  // get the value of the element.
88  int *px = tbl->get(tbl, "score");
89  if(px != NULL) {
90  printf("%d\n", *px);
91  free(px);
92  }
93 
94  // release table
95  tbl->free(tbl);
96 ~~~
97 
98 Here is an identical implementation with a Linked-List-Table container.
99 You may notice that there aren't any code changes at all, except for 1 line
100 in the table creation. This is why qLibc encapsulates corresponding function
101 pointers inside of the container object.
102 
103 ~~~{.c}
104  // create a linked-list-table. THE ONLY LINE YOU NEED TO CHANGE.
105  qlisttbl_t *tbl = qlisttbl(QLISTTBL_OPT_THREADSAFE);
106 
107  // add an element which key name is "score".
108  int x = 12345;
109  tbl->put(tbl, "score", &x, sizeof(int));
110 
111  // get the value of the element.
112  int *px = tbl->get(tbl, "score");
113  if(px != NULL) {
114  printf("%d\n", *px);
115  free(px);
116  }
117 
118  // release table
119  tbl->free(tbl);
120 ~~~
121 
122 ## Looking for people to work with.
123 
124 We're looking for people who want to work together to develop and improve qLibc.
125 Currently, we have high demands on following areas.
126 
127 * Automated testing
128 * Documentation.
129 * New feature implementation.
130 
131 ## Contributors
132 
133 The following people have helped with suggestions, ideas, code or fixing bugs:
134 (in alphabetical order by first name)
135 
136 * [Anthony Tseng](https://github.com/darkdh)
137 * Cesar
138 * [Colin](https://github.com/colintd)
139 * [Charles](https://github.com/Charles0429)
140 * [Dmitry Vorobiev](https://github.com/demitsuri)
141 * HyoSup Woo
142 * [Keith Rosenberg](https://github.com/netpoetica)
143 * Krishna
144 * [Liu Zhongchao](https://github.com/haveTryTwo)
145 * Luis Jimenez
146 * Maik Beckmann
147 * RQ
148 * [Ryan Gonzalez](https://github.com/kirbyfan64)
149 * [Seungyoung Kim](https://github.com/wolkykim)
150 * Umesh
151 
152 If we have forgotten or misspelled your name, please let us know.
qlisttbl_t * qlisttbl(int options)
Create a new Q_LIST linked-list container.
Definition: qlisttbl.c:150