kdb_plus_fixed/lib.rs
1//! As Rust is becoming a popular programming language for its performance and type safety, the desire to use
2//! it with still a maniac time-series database kdb+ is brewing. The aspiration is understandable since we know
3//! kdb+ is fast and its interface or a shared library should be fast as well. This interface was created to
4//! satisfy such a natural demand, furthermore, in a manner users do not feel any pain to use. The notrious
5//! ethoteric function names of the q/kdb+ C API is not an interest of Rust developers.
6//!
7//! *"Give us a **Rust** interface!!"*
8//!
9//! Here is your choice.
10//!
11//! This interface provides two features:
12//!
13//! - IPC interface (Rust client of q/kdb+ process)
14//! - API (build a shared library for q/kdb+)
15//!
16//! You can find detail descriptions of each feature under corresponding module page.
17
18//++++++++++++++++++++++++++++++++++++++++++++++++++//
19// >> Global Variables
20//++++++++++++++++++++++++++++++++++++++++++++++++++//
21
22pub mod qtype {
23 //! This module provides a list of q types. The motivation to contain them in a module is to
24 //! tie them up as related items rather than scattered values. Hence user should use these
25 //! indicators with `qtype::` prefix, e.g., `qtype::BOOL_LIST`.
26 //! # Note
27 //! In order to facilitate type check without overflow this module defines atom type indicator
28 //! as well as list type indicators (We don't need to compeletely mirror the C API).
29
30 use std::os::raw::c_schar;
31
32 /// Type indicator of q error
33 pub const ERROR: c_schar = -128;
34 /// Type indicator of q enum atom.
35 pub const ENUM_ATOM: c_schar = -20;
36 /// Type indicator of q time atom.
37 pub const TIME_ATOM: c_schar = -19;
38 /// Type indicator of q second atom.
39 pub const SECOND_ATOM: c_schar = -18;
40 /// Type indicator of q minute atom.
41 pub const MINUTE_ATOM: c_schar = -17;
42 /// Type indicator of q timespan atom.
43 pub const TIMESPAN_ATOM: c_schar = -16;
44 /// Type indicator of q datetime atom.
45 pub const DATETIME_ATOM: c_schar = -15;
46 /// Type indicator of q date atom.
47 pub const DATE_ATOM: c_schar = -14;
48 /// Type indicator of q month atom.
49 pub const MONTH_ATOM: c_schar = -13;
50 /// Type indicator of q timestamp atom.
51 pub const TIMESTAMP_ATOM: c_schar = -12;
52 /// Type indicator of q symbol atom.
53 pub const SYMBOL_ATOM: c_schar = -11;
54 /// Type indicator of q char atom.
55 pub const CHAR: c_schar = -10;
56 /// Type indicator of q float atom.
57 pub const FLOAT_ATOM: c_schar = -9;
58 /// Type indicator of q real atom.
59 pub const REAL_ATOM: c_schar = -8;
60 /// Type indicator of q long atom.
61 pub const LONG_ATOM: c_schar = -7;
62 /// Type indicator of q int atom.
63 pub const INT_ATOM: c_schar = -6;
64 /// Type indicator of q short atom.
65 pub const SHORT_ATOM: c_schar = -5;
66 /// Type indicator of q byte atom.
67 pub const BYTE_ATOM: c_schar = -4;
68 /// Type indicator of q GUID atom.
69 pub const GUID_ATOM: c_schar = -2;
70 /// Type indicator of q bool atom.
71 pub const BOOL_ATOM: c_schar = -1;
72 /// Type indicator of q mixed list list. Slice access type: `K`, i.e., `obj.as_mut_sice::<K>()`.
73 pub const COMPOUND_LIST: c_schar = 0;
74 /// Type indicator of q bool list list. Slice access type: `G`, i.e., `obj.as_mut_sice::<G>()`.
75 pub const BOOL_LIST: c_schar = 1;
76 /// Type indicator of q GUID list. Slice access type: `U`, i.e., `obj.as_mut_sice::<U>()`.
77 pub const GUID_LIST: c_schar = 2;
78 /// Type indicator of q byte list. Slice access type: `G`, i.e., `obj.as_mut_sice::<G>()`.
79 pub const BYTE_LIST: c_schar = 4;
80 /// Type indicator of q short list. Slice access type: `H`, i.e., `obj.as_mut_sice::<H>()`.
81 pub const SHORT_LIST: c_schar = 5;
82 /// Type indicator of q int list. Slice access type: `I`, i.e., `obj.as_mut_sice::<I>()`.
83 pub const INT_LIST: c_schar = 6;
84 /// Type indicator of q long list. Slice access type: `J`, i.e., `obj.as_mut_sice::<J>()`.
85 pub const LONG_LIST: c_schar = 7;
86 /// Type indicator of q real list. Slice access type: `E`, i.e., `obj.as_mut_sice::<E>()`.
87 pub const REAL_LIST: c_schar = 8;
88 /// Type indicator of q float list. Slice access type: `F`, i.e., `obj.as_mut_sice::<F>()`.
89 pub const FLOAT_LIST: c_schar = 9;
90 /// Type indicator of q string (char list). Slice access type: `C`, i.e., `obj.as_mut_sice::<C>()`.
91 pub const STRING: c_schar = 10;
92 /// Type indicator of q symbol list. Slice access type: `S`, i.e., `obj.as_mut_sice::<S>()`.
93 pub const SYMBOL_LIST: c_schar = 11;
94 /// Type indicator of q timestamp list. Slice access type: `J`, i.e., `obj.as_mut_sice::<J>()`.
95 pub const TIMESTAMP_LIST: c_schar = 12;
96 /// Type indicator of q month list. Slice access type: `I`, i.e., `obj.as_mut_sice::<I>()`.
97 pub const MONTH_LIST: c_schar = 13;
98 /// Type indicator of q date list. Slice access type: `I`, i.e., `obj.as_mut_sice::<I>()`.
99 pub const DATE_LIST: c_schar = 14;
100 /// Type indicator of q datetime list. Slice access type: `F`, i.e., `obj.as_mut_sice::<F>()`.
101 pub const DATETIME_LIST: c_schar = 15;
102 /// Type indicator of q timespan list. Slice access type: `J`, i.e., `obj.as_mut_sice::<J>()`.
103 pub const TIMESPAN_LIST: c_schar = 16;
104 /// Type indicator of q minute list. Slice access type: `I`, i.e., `obj.as_mut_sice::<I>()`.
105 pub const MINUTE_LIST: c_schar = 17;
106 /// Type indicator of q second list. Slice access type: `I`, i.e., `obj.as_mut_sice::<I>()`.
107 pub const SECOND_LIST: c_schar = 18;
108 /// Type indicator of q time list. Slice access type: `I`, i.e., `obj.as_mut_sice::<I>()`.
109 pub const TIME_LIST: c_schar = 19;
110 /// Type indicator of q enum list. Slice access type: `J`, i.e., `obj.as_mut_sice::<J>()`.
111 pub const ENUM_LIST: c_schar = 20;
112 /// Type indicator of q table.
113 pub const TABLE: c_schar = 98;
114 /// Type indicator of q dictionary. Slice access type: `K`, i.e., `obj.as_mut_sice::<K>()`.
115 /// - `obj.as_mut_sice::<K>()[0]`: keys
116 /// - `obj.as_mut_sice::<K>()[1]`: values
117 pub const DICTIONARY: c_schar = 99;
118 /// Type indicator of q general null
119 pub const NULL: c_schar = 101;
120 /// Type indicator of q foreign object.
121 pub const FOREIGN: c_schar = 112;
122 /// Type indicator of q sorted dictionary. Slice access type: `K`, i.e., `obj.as_mut_sice::<K>()`.
123 /// - `obj.as_mut_sice::<K>()[0]`: keys
124 /// - `obj.as_mut_sice::<K>()[1]`: values
125 pub const SORTED_DICTIONARY: c_schar = 127;
126}
127
128pub mod qattribute {
129 //! This module provides a list of q attributes. The motivation to contain them in a module is to
130 //! tie them up as related items rather than scattered values. Hence user should use these
131 //! indicators with `qattribute::` prefix, e.g., `qattribute::UNIQUE`.
132
133 use std::os::raw::c_char;
134 /// Indicates no attribute is appended on the q object.
135 pub const NONE: c_char = 0;
136 /// Sorted attribute, meaning that the q list is sorted in ascending order.
137 pub const SORTED: c_char = 1;
138 /// Unique attribute, meaning that each element in the q list has a unique value within the list.
139 pub const UNIQUE: c_char = 2;
140 /// Parted attribute, meaning that all the elements with the same value in the q object appear in a chunk.
141 pub const PARTED: c_char = 3;
142 /// Grouped attribute, meaning that the elements of the q list are grouped with their indices by values implicitly.
143 pub const GROUPED: c_char = 4;
144}
145
146pub mod qnull_base {
147 //! This module provides a list of underlying null values of q objects. The motivation to contain
148 //! them in a module is to tie them up as related items rather than scattered values. Hence user
149 //! should use these indicators with `qnull::` prefix, e.g., `qnull_base::F`.
150 //!
151 //! These values are mainly used to construct `K` object for `api` module but underlying values are
152 //! same for `ipc` module for simple types. For `ipc` module, proper null values of each type are
153 //! provided under [`qnull`](../ipc/qnull/index.html) namespace.
154
155 use std::os::raw::{c_double, c_float, c_int, c_longlong, c_short, c_uchar};
156
157 /// Null value of GUID.
158 /// # Example
159 /// ```no_run
160 /// use kdbplus::*;
161 /// use kdbplus::api::*;
162 ///
163 /// #[no_mangle]
164 /// pub extern "C" fn guid_border(_: K) -> K{
165 /// new_guid(qnull_base::U)
166 /// }
167 /// ```
168 /// ```q
169 /// q)guid_border: `libapi_examples 2: (`guid_border; 1);
170 /// q)guid_border[]
171 /// 0Ng
172 /// ```
173 pub const U: [c_uchar; 16] = [0; 16];
174
175 /// Null value of short.
176 /// # Example
177 /// ```no_run
178 /// use kdbplus::*;
179 /// use kdbplus::api::*;
180 ///
181 /// #[no_mangle]
182 /// pub extern "C" fn short_borders(_: K) -> K{
183 /// let shorts=new_list(qtype::SHORT_LIST, 3);
184 /// let shorts_slice=shorts.as_mut_slice::<H>();
185 /// shorts_slice[0]=qnull_base::H;
186 /// shorts_slice[1]=qinf_base::H;
187 /// shorts_slice[2]=qninf_base::H;
188 /// shorts
189 /// }
190 /// ```
191 /// ```q
192 /// q)short_borders: `libapi_examples 2: (`short_borders; 1);
193 /// q)short_borders[]
194 /// 0N 0W -0Wh
195 /// ```
196 pub const H: c_short = c_short::MIN;
197
198 /// Null value of int family, i.e., int, month, date, minute, second and time.
199 /// # Example
200 /// ```no_run
201 /// use kdbplus::*;
202 /// use kdbplus::api::*;
203 ///
204 /// #[no_mangle]
205 /// pub extern "C" fn int_borders(_: K) -> K{
206 /// let ints=new_list(qtype::INT_LIST, 3);
207 /// let ints_slice=ints.as_mut_slice::<I>();
208 /// ints_slice[0]=qnull_base::I;
209 /// ints_slice[1]=qinf_base::I;
210 /// ints_slice[2]=qninf_base::I;
211 /// ints
212 /// }
213 /// ```
214 /// ```q
215 /// q)int_borders: `libapi_examples 2: (`int_borders; 1);
216 /// q)int_borders[]
217 /// 0N 0W -0Wi
218 /// ```
219 pub const I: c_int = c_int::MIN;
220
221 /// Null value of long family, i.e., long, timestamp and timespan.
222 /// # Example
223 /// ```no_run
224 /// use kdbplus::*;
225 /// use kdbplus::api::*;
226 ///
227 /// #[no_mangle]
228 /// pub extern "C" fn long_borders(_: K) -> K{
229 /// let timestamps=new_list(qtype::TIMESTAMP_LIST, 3);
230 /// let timestamps_slice=timestamps.as_mut_slice::<J>();
231 /// timestamps_slice[0]=qnull_base::J;
232 /// timestamps_slice[1]=qinf_base::J;
233 /// timestamps_slice[2]=qninf_base::J;
234 /// timestamps
235 /// }
236 /// ```
237 /// ```q
238 /// q)timestamp_borders: `libapi_examples 2: (`long_borders; 1);
239 /// q)timestamp_borders[]
240 /// 0N 0W -0Wp
241 /// ```
242 pub const J: c_longlong = c_longlong::MIN;
243
244 /// Null value of real.
245 /// # Example
246 /// ```no_run
247 /// use kdbplus::*;
248 /// use kdbplus::api::*;
249 ///
250 /// #[no_mangle]
251 /// pub extern "C" fn real_borders(_: K) -> K{
252 /// let reals=new_list(qtype::REAL_LIST, 3);
253 /// let reals_slice=reals.as_mut_slice::<E>();
254 /// reals_slice[0]=qnull_base::E;
255 /// reals_slice[1]=qinf_base::E;
256 /// reals_slice[2]=qninf_base::E;
257 /// reals
258 /// }
259 /// ```
260 /// ```q
261 /// q)real_borders: `libapi_examples 2: (`real_borders; 1);
262 /// q)real_borders[]
263 /// 0N 0W -0We
264 /// ```
265 pub const E: c_float = c_float::NAN;
266
267 /// Null value of float family, i.e., float and datetime.
268 /// # Example
269 /// ```no_run
270 /// use kdbplus::*;
271 /// use kdbplus::api::*;
272 ///
273 /// #[no_mangle]
274 /// pub extern "C" fn float_borders(_: K) -> K{
275 /// let datetimes=new_list(qtype::DATETIME_LIST, 3);
276 /// let datetimes_slice=datetimes.as_mut_slice::<F>();
277 /// datetimes_slice[0]=qnull_base::F;
278 /// datetimes_slice[1]=qinf_base::F;
279 /// datetimes_slice[2]=qninf_base::F;
280 /// datetimes
281 /// }
282 /// ```
283 /// ```q
284 /// q)datetime_borders: `libapi_examples 2: (`float_borders; 1);
285 /// q)datetime_borders[]
286 /// 0N 0W -0Wz
287 /// ```
288 pub const F: c_double = c_double::NAN;
289
290 /// Null value of char.
291 /// # Example
292 /// ```no_run
293 /// use kdbplus::*;
294 /// use kdbplus::api::*;
295 ///
296 /// #[no_mangle]
297 /// pub extern "C" fn char_border(_: K) -> K{
298 /// new_char(qnull_base::C)
299 /// }
300 /// ```
301 /// ```q
302 /// q)char_border: `libapi_examples 2: (`char_border; 1);
303 /// q)char_border[]
304 /// " "
305 /// q)null char_border[]
306 /// 1b
307 /// ```
308 pub const C: char = ' ';
309
310 /// Null value of string family (symbol, string).
311 /// # Example
312 /// ```no_run
313 /// use kdbplus::*;
314 /// use kdbplus::api::*;
315 ///
316 /// #[no_mangle]
317 /// pub extern "C" fn string_borders(_: K) -> K{
318 /// let compound=new_list(qtype::COMPOUND_LIST, 2);
319 /// let compound_slice=compound.as_mut_slice::<K>();
320 /// compound_slice[0]=new_symbol(qnull_base::S);
321 /// compound_slice[1]=new_string(qnull_base::S);
322 /// compound
323 /// }
324 /// ```
325 /// ```q
326 /// q)string_borders: `libapi_examples 2: (`string_borders; 1);
327 /// q)string_borders[]
328 /// `
329 /// ""
330 /// q)null each string_borders[]
331 /// 1b
332 /// `boolean$()
333 /// ```
334 pub const S: &str = "";
335}
336
337pub mod qinf_base {
338 //! This module provides a list of q null values. The motivation to contain them in a module is to
339 //! tie them up as related items rather than scattered values. Hence user should use these
340 //! indicators with `qnull::` prefix, e.g., `qinf_base::J`.
341 //!
342 //! These values are mainly used to construct `K` object for `api` module but underlying values are
343 //! same for `ipc` module for simple types. For `ipc` module, proper infinity values of each type
344 //! are provided under [`qinf`](../ipc/qinf/index.html) namespace.
345
346 use std::os::raw::{c_double, c_float, c_int, c_longlong, c_short};
347 /// Infinity value of short.
348 /// # Example
349 /// See the example of [`qnull_base::H`](../qnull_base/constant.H.html).
350 pub const H: c_short = c_short::MAX;
351 /// Infinity value of int family, i.e., int, month, date, minute, second and time.
352 /// # Example
353 /// See the example of [`qnull_base::I`](../qnull_base/constant.I.html).
354 pub const I: c_int = c_int::MAX;
355 /// Infinity value of long family, i.e., long, timestamp and timespan.
356 /// # Example
357 /// See the example of [`qnull_base::J`](../qnull_base/constant.J.html).
358 pub const J: c_longlong = c_longlong::MAX;
359 /// Infinity value of real.
360 /// # Example
361 /// See the example of [`qnull_base::E`](../qnull_base/constant.E.html).
362 pub const E: c_float = c_float::INFINITY;
363 /// Infinity value of float family, i.e., float and datetime.
364 /// # Example
365 /// See the example of [`qnull_base::F`](../qnull_base/constant.F.html).
366 pub const F: c_double = c_double::INFINITY;
367}
368
369pub mod qninf_base {
370 //! This module provides a list of q null values. The motivation to contain them in a module is to
371 //! tie them up as related items rather than scattered values. Hence user should use these
372 //! indicators with `qnull::` prefix, e.g., `qninf_base::I`.
373 //!
374 //! These values are mainly used to construct `K` object for `api` module but underlying values are
375 //! same for `ipc` module for simple types. For `ipc` module, proper negative infinity values of
376 //! each type are provided under [`qninf`](../ipc/qninf/index.html) namespace.
377
378 use std::os::raw::{c_double, c_float, c_int, c_longlong, c_short};
379 /// Negative infinity value of short.
380 /// # Example
381 /// See the example of [`qnull_base::H`](../qnull_base/constant.H.html).
382 pub const H: c_short = -c_short::MAX;
383 /// Negative infinity value of int family, i.e., int, month, date, minute, second and time.
384 /// # Example
385 /// See the example of [`qnull_base::I`](../qnull_base/constant.I.html).
386 pub const I: c_int = -c_int::MAX;
387 /// Negative infinity value of long family, i.e., long, timestamp and timespan.
388 /// # Example
389 /// See the example of [`qnull_base::J`](../qnull_base/constant.J.html).
390 pub const J: c_longlong = -c_longlong::MAX;
391 /// Negative infinity value of real.
392 /// # Example
393 /// See the example of [`qnull_base::E`](../qnull_base/constant.E.html).
394 pub const E: c_float = c_float::NEG_INFINITY;
395 /// Negative infinity value of float family, i.e., float and datetime.
396 /// # Example
397 /// See the example of [`qnull_base::F`](../qnull_base/constant.F.html).
398 pub const F: c_double = c_double::NEG_INFINITY;
399}
400
401//++++++++++++++++++++++++++++++++++++++++++++++++++//
402// >> Export Modules
403//++++++++++++++++++++++++++++++++++++++++++++++++++//
404
405#[cfg(feature = "api")]
406pub mod api;
407
408#[cfg(feature = "ipc")]
409pub mod ipc;