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 /// Indicates no attribute is appended on the q object.
134 pub const NONE: i8 = 0;
135 /// Sorted attribute, meaning that the q list is sorted in ascending order.
136 pub const SORTED: i8 = 1;
137 /// Unique attribute, meaning that each element in the q list has a unique value within the list.
138 pub const UNIQUE: i8 = 2;
139 /// Parted attribute, meaning that all the elements with the same value in the q object appear in a chunk.
140 pub const PARTED: i8 = 3;
141 /// Grouped attribute, meaning that the elements of the q list are grouped with their indices by values implicitly.
142 pub const GROUPED: i8 = 4;
143}
144
145pub mod qnull_base {
146 //! This module provides a list of underlying null values of q objects. The motivation to contain
147 //! them in a module is to tie them up as related items rather than scattered values. Hence user
148 //! should use these indicators with `qnull::` prefix, e.g., `qnull_base::F`.
149 //!
150 //! These values are mainly used to construct `K` object for `api` module but underlying values are
151 //! same for `ipc` module for simple types. For `ipc` module, proper null values of each type are
152 //! provided under [`qnull`](../ipc/qnull/index.html) namespace.
153
154 use std::os::raw::{c_double, c_float, c_int, c_longlong, c_short, c_uchar};
155
156 /// Null value of GUID.
157 /// # Example
158 /// ```no_run
159 /// use kdbplus::*;
160 /// use kdbplus::api::*;
161 ///
162 /// #[no_mangle]
163 /// pub extern "C" fn guid_border(_: K) -> K{
164 /// new_guid(qnull_base::U)
165 /// }
166 /// ```
167 /// ```q
168 /// q)guid_border: `libapi_examples 2: (`guid_border; 1);
169 /// q)guid_border[]
170 /// 0Ng
171 /// ```
172 pub const U: [c_uchar; 16] = [0; 16];
173
174 /// Null value of short.
175 /// # Example
176 /// ```no_run
177 /// use kdbplus::*;
178 /// use kdbplus::api::*;
179 ///
180 /// #[no_mangle]
181 /// pub extern "C" fn short_borders(_: K) -> K{
182 /// let shorts=new_list(qtype::SHORT_LIST, 3);
183 /// let shorts_slice=shorts.as_mut_slice::<H>();
184 /// shorts_slice[0]=qnull_base::H;
185 /// shorts_slice[1]=qinf_base::H;
186 /// shorts_slice[2]=qninf_base::H;
187 /// shorts
188 /// }
189 /// ```
190 /// ```q
191 /// q)short_borders: `libapi_examples 2: (`short_borders; 1);
192 /// q)short_borders[]
193 /// 0N 0W -0Wh
194 /// ```
195 pub const H: c_short = c_short::MIN;
196
197 /// Null value of int family, i.e., int, month, date, minute, second and time.
198 /// # Example
199 /// ```no_run
200 /// use kdbplus::*;
201 /// use kdbplus::api::*;
202 ///
203 /// #[no_mangle]
204 /// pub extern "C" fn int_borders(_: K) -> K{
205 /// let ints=new_list(qtype::INT_LIST, 3);
206 /// let ints_slice=ints.as_mut_slice::<I>();
207 /// ints_slice[0]=qnull_base::I;
208 /// ints_slice[1]=qinf_base::I;
209 /// ints_slice[2]=qninf_base::I;
210 /// ints
211 /// }
212 /// ```
213 /// ```q
214 /// q)int_borders: `libapi_examples 2: (`int_borders; 1);
215 /// q)int_borders[]
216 /// 0N 0W -0Wi
217 /// ```
218 pub const I: c_int = c_int::MIN;
219
220 /// Null value of long family, i.e., long, timestamp and timespan.
221 /// # Example
222 /// ```no_run
223 /// use kdbplus::*;
224 /// use kdbplus::api::*;
225 ///
226 /// #[no_mangle]
227 /// pub extern "C" fn long_borders(_: K) -> K{
228 /// let timestamps=new_list(qtype::TIMESTAMP_LIST, 3);
229 /// let timestamps_slice=timestamps.as_mut_slice::<J>();
230 /// timestamps_slice[0]=qnull_base::J;
231 /// timestamps_slice[1]=qinf_base::J;
232 /// timestamps_slice[2]=qninf_base::J;
233 /// timestamps
234 /// }
235 /// ```
236 /// ```q
237 /// q)timestamp_borders: `libapi_examples 2: (`long_borders; 1);
238 /// q)timestamp_borders[]
239 /// 0N 0W -0Wp
240 /// ```
241 pub const J: c_longlong = c_longlong::MIN;
242
243 /// Null value of real.
244 /// # Example
245 /// ```no_run
246 /// use kdbplus::*;
247 /// use kdbplus::api::*;
248 ///
249 /// #[no_mangle]
250 /// pub extern "C" fn real_borders(_: K) -> K{
251 /// let reals=new_list(qtype::REAL_LIST, 3);
252 /// let reals_slice=reals.as_mut_slice::<E>();
253 /// reals_slice[0]=qnull_base::E;
254 /// reals_slice[1]=qinf_base::E;
255 /// reals_slice[2]=qninf_base::E;
256 /// reals
257 /// }
258 /// ```
259 /// ```q
260 /// q)real_borders: `libapi_examples 2: (`real_borders; 1);
261 /// q)real_borders[]
262 /// 0N 0W -0We
263 /// ```
264 pub const E: c_float = c_float::NAN;
265
266 /// Null value of float family, i.e., float and datetime.
267 /// # Example
268 /// ```no_run
269 /// use kdbplus::*;
270 /// use kdbplus::api::*;
271 ///
272 /// #[no_mangle]
273 /// pub extern "C" fn float_borders(_: K) -> K{
274 /// let datetimes=new_list(qtype::DATETIME_LIST, 3);
275 /// let datetimes_slice=datetimes.as_mut_slice::<F>();
276 /// datetimes_slice[0]=qnull_base::F;
277 /// datetimes_slice[1]=qinf_base::F;
278 /// datetimes_slice[2]=qninf_base::F;
279 /// datetimes
280 /// }
281 /// ```
282 /// ```q
283 /// q)datetime_borders: `libapi_examples 2: (`float_borders; 1);
284 /// q)datetime_borders[]
285 /// 0N 0W -0Wz
286 /// ```
287 pub const F: c_double = c_double::NAN;
288
289 /// Null value of char.
290 /// # Example
291 /// ```no_run
292 /// use kdbplus::*;
293 /// use kdbplus::api::*;
294 ///
295 /// #[no_mangle]
296 /// pub extern "C" fn char_border(_: K) -> K{
297 /// new_char(qnull_base::C)
298 /// }
299 /// ```
300 /// ```q
301 /// q)char_border: `libapi_examples 2: (`char_border; 1);
302 /// q)char_border[]
303 /// " "
304 /// q)null char_border[]
305 /// 1b
306 /// ```
307 pub const C: char = ' ';
308
309 /// Null value of string family (symbol, string).
310 /// # Example
311 /// ```no_run
312 /// use kdbplus::*;
313 /// use kdbplus::api::*;
314 ///
315 /// #[no_mangle]
316 /// pub extern "C" fn string_borders(_: K) -> K{
317 /// let compound=new_list(qtype::COMPOUND_LIST, 2);
318 /// let compound_slice=compound.as_mut_slice::<K>();
319 /// compound_slice[0]=new_symbol(qnull_base::S);
320 /// compound_slice[1]=new_string(qnull_base::S);
321 /// compound
322 /// }
323 /// ```
324 /// ```q
325 /// q)string_borders: `libapi_examples 2: (`string_borders; 1);
326 /// q)string_borders[]
327 /// `
328 /// ""
329 /// q)null each string_borders[]
330 /// 1b
331 /// `boolean$()
332 /// ```
333 pub const S: &str = "";
334}
335
336pub mod qinf_base {
337 //! This module provides a list of q null values. The motivation to contain them in a module is to
338 //! tie them up as related items rather than scattered values. Hence user should use these
339 //! indicators with `qnull::` prefix, e.g., `qinf_base::J`.
340 //!
341 //! These values are mainly used to construct `K` object for `api` module but underlying values are
342 //! same for `ipc` module for simple types. For `ipc` module, proper infinity values of each type
343 //! are provided under [`qinf`](../ipc/qinf/index.html) namespace.
344
345 use std::os::raw::{c_double, c_float, c_int, c_longlong, c_short};
346 /// Infinity value of short.
347 /// # Example
348 /// See the example of [`qnull_base::H`](../qnull_base/constant.H.html).
349 pub const H: c_short = c_short::MAX;
350 /// Infinity value of int family, i.e., int, month, date, minute, second and time.
351 /// # Example
352 /// See the example of [`qnull_base::I`](../qnull_base/constant.I.html).
353 pub const I: c_int = c_int::MAX;
354 /// Infinity value of long family, i.e., long, timestamp and timespan.
355 /// # Example
356 /// See the example of [`qnull_base::J`](../qnull_base/constant.J.html).
357 pub const J: c_longlong = c_longlong::MAX;
358 /// Infinity value of real.
359 /// # Example
360 /// See the example of [`qnull_base::E`](../qnull_base/constant.E.html).
361 pub const E: c_float = c_float::INFINITY;
362 /// Infinity value of float family, i.e., float and datetime.
363 /// # Example
364 /// See the example of [`qnull_base::F`](../qnull_base/constant.F.html).
365 pub const F: c_double = c_double::INFINITY;
366}
367
368pub mod qninf_base {
369 //! This module provides a list of q null values. The motivation to contain them in a module is to
370 //! tie them up as related items rather than scattered values. Hence user should use these
371 //! indicators with `qnull::` prefix, e.g., `qninf_base::I`.
372 //!
373 //! These values are mainly used to construct `K` object for `api` module but underlying values are
374 //! same for `ipc` module for simple types. For `ipc` module, proper negative infinity values of
375 //! each type are provided under [`qninf`](../ipc/qninf/index.html) namespace.
376
377 use std::os::raw::{c_double, c_float, c_int, c_longlong, c_short};
378 /// Negative infinity value of short.
379 /// # Example
380 /// See the example of [`qnull_base::H`](../qnull_base/constant.H.html).
381 pub const H: c_short = -c_short::MAX;
382 /// Negative infinity value of int family, i.e., int, month, date, minute, second and time.
383 /// # Example
384 /// See the example of [`qnull_base::I`](../qnull_base/constant.I.html).
385 pub const I: c_int = -c_int::MAX;
386 /// Negative infinity value of long family, i.e., long, timestamp and timespan.
387 /// # Example
388 /// See the example of [`qnull_base::J`](../qnull_base/constant.J.html).
389 pub const J: c_longlong = -c_longlong::MAX;
390 /// Negative infinity value of real.
391 /// # Example
392 /// See the example of [`qnull_base::E`](../qnull_base/constant.E.html).
393 pub const E: c_float = c_float::NEG_INFINITY;
394 /// Negative infinity value of float family, i.e., float and datetime.
395 /// # Example
396 /// See the example of [`qnull_base::F`](../qnull_base/constant.F.html).
397 pub const F: c_double = c_double::NEG_INFINITY;
398}
399
400//++++++++++++++++++++++++++++++++++++++++++++++++++//
401// >> Export Modules
402//++++++++++++++++++++++++++++++++++++++++++++++++++//
403
404#[cfg(feature = "api")]
405pub mod api;
406
407#[cfg(feature = "ipc")]
408pub mod ipc;