kdb_c_api/native.rs
1//! This module exposes bare C API functions. As most of them are provided with a "safe" wrapper
2//! function with an intuitive name and intuitive implementation for Rust, there is no gain to
3//! darely use these functions.
4//!
5//! The only exceptions are `k` and `knk` which are not provided with a "safe" wrapper because
6//! these functions are using elipsis (`...`) as their argument.
7
8//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++//
9// Load Libraries //
10//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++//
11
12use super::{S, const_S, U, I, J, F, V, K};
13
14//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++//
15// External C Functions //
16//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++//
17
18extern "C"{
19
20 //%% Constructors %%//vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv/
21
22 /// Creates an atom of the specified type.
23 pub fn ka(qtype: I) -> K;
24
25 /// Constructor of q bool object.
26 /// # Example
27 /// ```no_run
28 /// use kdb_c_api::*;
29 /// use kdb_c_api::native::*;
30 ///
31 /// #[no_mangle]
32 /// pub extern "C" fn create_bool(_: K) -> K{
33 /// unsafe{kb(1)}
34 /// }
35 /// ```
36 /// ```q
37 /// q)yes: libc_api_examples 2: (`create_bool; 1);
38 /// q)yes[]
39 /// 1b
40 /// ```
41 pub fn kb(boolean: I) -> K;
42
43 /// Constructor of q GUID object.
44 /// # Example
45 /// ```no_run
46 /// use kdb_c_api::*;
47 /// use kdb_c_api::native::*;
48 ///
49 /// #[no_mangle]
50 /// pub extern "C" fn create_guid(_: K) -> K{
51 /// unsafe{ku(U::new([0x1e_u8, 0x11, 0x17, 0x0c, 0x42, 0x24, 0x25, 0x2c, 0x1c, 0x14, 0x1e, 0x22, 0x4d, 0x3d, 0x46, 0x24]))}
52 /// }
53 /// ```
54 /// ```q
55 /// q)create_guid: libc_api_examples 2: (`create_guid; 1);
56 /// q)create_guid[]
57 /// 1e11170c-4224-252c-1c14-1e224d3d4624
58 /// ```
59 pub fn ku(array: U) -> K;
60
61 /// Constructor of q byte object.
62 /// # Example
63 /// ```no_run
64 /// use kdb_c_api::*;
65 /// use kdb_c_api::native::*;
66 ///
67 /// #[no_mangle]
68 /// pub extern "C" fn create_byte(_: K) -> K{
69 /// unsafe{kg(0x3c)}
70 /// }
71 /// ```
72 /// ```q
73 /// q)create_byte: libc_api_examples 2: (`create_byte; 1);
74 /// q)create_byte[]
75 /// 0x3c
76 /// ```
77 pub fn kg(byte: I) -> K;
78
79 /// Constructor of q short object.
80 /// # Example
81 /// ```no_run
82 /// use kdb_c_api::*;
83 /// use kdb_c_api::native::*;
84 ///
85 /// #[no_mangle]
86 /// pub extern "C" fn create_short(_: K) -> K{
87 /// unsafe{kh(-144)}
88 /// }
89 /// ```
90 /// ```q
91 /// q)shortage: libc_api_examples 2: (`create_short; 1);
92 /// q)shortage[]
93 /// -144h
94 /// ```
95 pub fn kh(short: I) -> K;
96
97 /// Constructor of q int object.
98 /// # Example
99 /// ```no_run
100 /// use kdb_c_api::*;
101 /// use kdb_c_api::native::*;
102 ///
103 /// #[no_mangle]
104 /// pub extern "C" fn create_int(_: K) -> K{
105 /// unsafe{ki(86400000)}
106 /// }
107 /// ```
108 /// ```q
109 /// q)trvial: libc_api_examples 2: (`create_int; 1);
110 /// q)trivial[]
111 /// 86400000i
112 /// ```
113 pub fn ki(int: I) -> K;
114
115 /// Constructor of q long object.
116 /// # Example
117 /// ```no_run
118 /// use kdb_c_api::*;
119 /// use kdb_c_api::native::*;
120 ///
121 /// #[no_mangle]
122 /// pub extern "C" fn create_long(_: K) -> K{
123 /// unsafe{kj(-668541276001729000)}
124 /// }
125 /// ```
126 /// ```q
127 /// q)lengthy: libc_api_examples 2: (`create_long; 1);
128 /// q)lengthy[]
129 /// -668541276001729000
130 /// ```
131 pub fn kj(long: J) -> K;
132
133 /// Constructor of q real object.
134 /// # Example
135 /// ```no_run
136 /// use kdb_c_api::*;
137 /// use kdb_c_api::native::*;
138 ///
139 /// #[no_mangle]
140 /// pub extern "C" fn create_real(_: K) -> K{
141 /// unsafe{ke(0.00324)}
142 /// }
143 /// ```
144 /// ```q
145 /// q)reality: libc_api_examples 2: (`create_real; 1);
146 /// q)reality[]
147 /// 0.00324e
148 /// ```
149 pub fn ke(real: F) -> K;
150
151 /// Constructor of q float object.
152 /// # Example
153 /// ```
154 /// use kdb_c_api::*;
155 /// use kdb_c_api::native::*;
156 ///
157 /// #[no_mangle]
158 /// pub extern "C" fn create_float(_: K) -> K{
159 /// unsafe{kf(-6302.620)}
160 /// }
161 /// ```
162 /// ```q
163 /// q)coffee_float: libc_api_examples 2: (`create_float; 1);
164 /// q)coffee_float[]
165 /// -6302.62
166 /// ```
167 pub fn kf(float: F) -> K;
168
169 /// Constructor of q char object.
170 /// # Example
171 /// ```no_run
172 /// use kdb_c_api::*;
173 /// use kdb_c_api::native::*;
174 ///
175 /// #[no_mangle]
176 /// pub extern "C" fn create_char(_: K) -> K{
177 /// unsafe{kc('q' as I)}
178 /// }
179 /// ```
180 /// ```q
181 /// q)quiz: libc_api_examples 2: (`create_char; 1);
182 /// q)quiz[]
183 /// "q"
184 /// ```
185 pub fn kc(character: I) -> K;
186
187 /// Constructor of q symbol object.
188 /// # Example
189 /// ```no_run
190 /// use kdb_c_api::*;
191 /// use kdb_c_api::native::*;
192 ///
193 /// #[no_mangle]
194 /// pub extern "C" fn create_symbol(_: K) -> K{
195 /// unsafe{ks(str_to_S!("symbolism"))}
196 /// }
197 /// ```
198 /// ```q
199 /// q)formal: libc_api_examples 2: (`create_symbol; 1);
200 /// q)formal[]
201 /// `symbolism
202 /// q)`symbolism ~ formal[]
203 /// 1b
204 /// ```
205 pub fn ks(symbol: S) -> K;
206
207 /// Constructor of q timestamp from elapsed time in nanoseconds since kdb+ epoch (`2000.01.01`) or timespan object from nanoseconds.
208 /// ```no_run
209 /// use kdb_c_api::*;
210 /// use kdb_c_api::native::*;
211 ///
212 /// #[no_mangle]
213 /// pub extern "C" fn create_timestamp(_: K) -> K{
214 /// // 2015.03.16D00:00:00:00.000000000
215 /// unsafe{ktj(-qtype::TIMESTAMP as I, 479779200000000000)}
216 /// }
217 ///
218 /// #[no_mangle]
219 /// pub extern "C" fn create_timespan(_: K) -> K{
220 /// // -1D01:30:00.001234567
221 /// unsafe{ktj(-qtype::TIMESPAN as I, -91800001234567)}
222 /// }
223 /// ```
224 /// ```q
225 /// q)hanko: libc_api_examples 2: (`create_timestamp; 1);
226 /// q)hanko[]
227 /// 2015.03.16D00:00:00.000000000
228 /// q)duration: libc_api_examples 2: (`create_timespan; 1);
229 /// q)duration[]
230 /// -1D01:30:00.001234567
231 /// ```
232 pub fn ktj(qtype: I, nanoseconds: J) -> K;
233
234 /// Constructor of q date object.
235 /// # Example
236 /// ```no_run
237 /// use kdb_c_api::*;
238 /// use kdb_c_api::native::*;
239 ///
240 /// #[no_mangle]
241 /// pub extern "C" fn create_date(_: K) -> K{
242 /// // 1999.12.25
243 /// unsafe{kd(-7)}
244 /// }
245 /// ```
246 /// ```q
247 /// q)christmas_at_the_END: libc_api_examples 2: (`create_date; 1);
248 /// q)christmas_at_the_END[]
249 /// 1999.12.25
250 /// ```
251 pub fn kd(date: I) -> K;
252
253 /// Constructor of q datetime object from the number of days since kdb+ epoch (`2000.01.01`).
254 /// ```no_run
255 /// use kdb_c_api::*;
256 /// use kdb_c_api::native::*;
257 ///
258 /// #[no_mangle]
259 /// pub extern "C" fn create_datetime(_: K) -> K{
260 /// // 2015.03.16T12:00:00:00.000
261 /// unsafe{kz(5553.5)}
262 /// }
263 /// ```
264 /// ```q
265 /// q)omega_date: libc_api_examples 2: (`create_datetime; 1);
266 /// q)omega_date[]
267 /// 2015.03.16T12:00:00.000
268 /// ```
269 pub fn kz(datetime: F) -> K;
270
271 /// Constructor of q time object.
272 /// # Example
273 /// ```no_run
274 /// use kdb_c_api::*;
275 /// use kdb_c_api::native::*;
276 ///
277 /// #[no_mangle]
278 /// pub extern "C" fn create_time(_: K) -> K{
279 /// // -01:30:00.123
280 /// unsafe{kt(-5400123)}
281 /// }
282 /// ```
283 /// ```q
284 /// q)ancient: libc_api_examples 2: (`create_time; 1);
285 /// q)ancient[]
286 /// -01:30:00.123
287 /// ```
288 pub fn kt(milliseconds: I) -> K;
289
290 /// Constructor of q compound list.
291 /// # Example
292 /// See the example of [`xD`](fn.xD.html).
293 pub fn knk(qtype: I, ...) -> K;
294
295 /// Constructor of q simple list.
296 /// # Example
297 /// See the example of [`xD`](fn.xD.html).
298 pub fn ktn(qtype: I, length: J) -> K;
299
300 /// Constructor of q string object.
301 /// # Example
302 /// ```no_run
303 /// use kdb_c_api::*;
304 /// use kdb_c_api::native::*;
305 ///
306 /// #[no_mangle]
307 /// pub extern "C" fn create_string(_: K) -> K{
308 /// unsafe{kp(str_to_S!("this is a text."))}
309 /// }
310 /// ```
311 /// ```q
312 /// q)text: libc_api_examples 2: (`create_string; 1);
313 /// q)text[]
314 /// "this is a text."
315 /// ```
316 pub fn kp(chararray: S) -> K;
317
318 /// Constructor if q string object with a fixed length.
319 /// # Example
320 /// ```no_run
321 /// use kdb_c_api::*;
322 /// use kdb_c_api::native::*;
323 ///
324 /// #[no_mangle]
325 /// pub extern "C" fn create_string2(_: K) -> K{
326 /// unsafe{kpn(str_to_S!("The meeting was too long and I felt it s..."), 24)}
327 /// }
328 /// ```
329 /// ```q
330 /// q)speak_inwardly: libc_api_examples 2: (`create_string2; 1);
331 /// q)speak_inwardly[]
332 /// "The meeting was too long"
333 /// ```
334 pub fn kpn(chararray: S, length: J) -> K;
335
336 /// Constructor of q table object from q dictionary object.
337 /// # Note
338 /// Basically this is a `flip` command of q. Hence the value of the dictionary must have
339 /// lists as its elements.
340 /// ```no_run
341 /// use kdb_c_api::*;
342 /// use kdb_c_api::native::*;
343 ///
344 /// #[no_mangle]
345 /// pub extern "C" fn create_table(_: K) -> K{
346 /// let keys=unsafe{ktn(qtype::SYMBOL as I, 2)};
347 /// let keys_slice=keys.as_mut_slice::<S>();
348 /// keys_slice[0]=unsafe{ss(str_to_S!("time"))};
349 /// keys_slice[1]=unsafe{ss(str_to_S!("temperature"))};
350 /// let values=unsafe{knk(2)};
351 /// let time=unsafe{ktn(qtype::TIMESTAMP as I, 3)};
352 /// // 2003.10.10D02:24:19.167018272 2006.05.24D06:16:49.419710368 2008.08.12D23:12:24.018691392
353 /// time.as_mut_slice::<J>().copy_from_slice(&[119067859167018272_i64, 201766609419710368, 271897944018691392]);
354 /// let temperature=unsafe{ktn(qtype::FLOAT as I, 3)};
355 /// temperature.as_mut_slice::<F>().copy_from_slice(&[22.1_f64, 24.7, 30.5]);
356 /// values.as_mut_slice::<K>().copy_from_slice(&[time, temperature]);
357 /// unsafe{xT(xD(keys, values))}
358 /// }
359 /// ```
360 /// ```q
361 /// q)climate_change: libc_api_examples 2: (`create_table; 1);
362 /// q)climate_change[]
363 /// time temperature
364 /// -----------------------------------------
365 /// 2003.10.10D02:24:19.167018272 22.1
366 /// 2006.05.24D06:16:49.419710368 24.7
367 /// 2008.08.12D23:12:24.018691392 30.5
368 /// ```
369 pub fn xT(dictionary: K) -> K;
370
371 /// Constructor of simple q table object from q keyed table object.
372 /// # Example
373 /// ```no_run
374 /// use kdb_c_api::*;
375 /// use kdb_c_api::native::*;
376 ///
377 /// #[no_mangle]
378 /// pub extern "C" fn create_table(_: K) -> K{
379 /// let keys=unsafe{ktn(qtype::SYMBOL as I, 2)};
380 /// let keys_slice=keys.as_mut_slice::<S>();
381 /// keys_slice[0]=unsafe{ss(str_to_S!("time"))};
382 /// keys_slice[1]=unsafe{ss(str_to_S!("temperature"))};
383 /// let values=unsafe{knk(2)};
384 /// let time=unsafe{ktn(qtype::TIMESTAMP as I, 3)};
385 /// // 2003.10.10D02:24:19.167018272 2006.05.24D06:16:49.419710368 2008.08.12D23:12:24.018691392
386 /// time.as_mut_slice::<J>().copy_from_slice(&[119067859167018272_i64, 201766609419710368, 271897944018691392]);
387 /// let temperature=unsafe{ktn(qtype::FLOAT as I, 3)};
388 /// temperature.as_mut_slice::<F>().copy_from_slice(&[22.1_f64, 24.7, 30.5]);
389 /// values.as_mut_slice::<K>().copy_from_slice(&[time, temperature]);
390 /// unsafe{xT(xD(keys, values))}
391 /// }
392 ///
393 /// #[no_mangle]
394 /// pub extern "C" fn create_keyed_table(dummy: K) -> K{
395 /// unsafe{knt(1, create_table(dummy))}
396 /// }
397 ///
398 /// #[no_mangle]
399 /// pub extern "C" fn keyed_to_simple_table(dummy: K) -> K{
400 /// unsafe{ktd(create_keyed_table(dummy))}
401 /// }
402 /// ```
403 /// ```q
404 /// q)unkey: libc_api_examples 2: (`keyed_to_simple_table; 1);
405 /// q)unkey[]
406 /// time temperature
407 /// -----------------------------------------
408 /// 2003.10.10D02:24:19.167018272 22.1
409 /// 2006.05.24D06:16:49.419710368 24.7
410 /// 2008.08.12D23:12:24.018691392 30.5
411 /// ```
412 pub fn ktd(keyedtable: K) -> K;
413
414 /// Constructor of q keyed table object.
415 /// # Example
416 /// ```no_run
417 /// use kdb_c_api::*;
418 /// use kdb_c_api::native::*;
419 ///
420 /// #[no_mangle]
421 /// pub extern "C" fn create_table(_: K) -> K{
422 /// let keys=unsafe{ktn(qtype::SYMBOL as I, 2)};
423 /// let keys_slice=keys.as_mut_slice::<S>();
424 /// keys_slice[0]=unsafe{ss(str_to_S!("time"))};
425 /// keys_slice[1]=unsafe{ss(str_to_S!("temperature"))};
426 /// let values=unsafe{knk(2)};
427 /// let time=unsafe{ktn(qtype::TIMESTAMP as I, 3)};
428 /// // 2003.10.10D02:24:19.167018272 2006.05.24D06:16:49.419710368 2008.08.12D23:12:24.018691392
429 /// time.as_mut_slice::<J>().copy_from_slice(&[119067859167018272_i64, 201766609419710368, 271897944018691392]);
430 /// let temperature=unsafe{ktn(qtype::FLOAT as I, 3)};
431 /// temperature.as_mut_slice::<F>().copy_from_slice(&[22.1_f64, 24.7, 30.5]);
432 /// values.as_mut_slice::<K>().copy_from_slice(&[time, temperature]);
433 /// unsafe{xT(xD(keys, values))}
434 /// }
435 ///
436 /// #[no_mangle]
437 /// pub extern "C" fn create_keyed_table(dummy: K) -> K{
438 /// unsafe{knt(1, create_table(dummy))}
439 /// }
440 /// ```
441 /// ```q
442 /// q)locker: libc_api_examples 2: (`create_keyed_table; 1);
443 /// q)locker[]
444 /// time | temperature
445 /// -----------------------------| -----------
446 /// 2003.10.10D02:24:19.167018272| 22.1
447 /// 2006.05.24D06:16:49.419710368| 24.7
448 /// 2008.08.12D23:12:24.018691392| 30.5
449 /// ```
450 pub fn knt(keynum: J, table: K) -> K;
451
452 /// Constructor of q dictionary object.
453 /// # Example
454 /// ```no_run
455 /// use kdb_c_api::*;
456 /// use kdb_c_api::native::*;
457 ///
458 /// #[no_mangle]
459 /// pub extern "C" fn create_dictionary() -> K{
460 /// let keys=unsafe{ktn(qtype::INT as I, 2)};
461 /// keys.as_mut_slice::<I>()[0..2].copy_from_slice(&[0, 1]);
462 /// let values=unsafe{knk(2)};
463 /// let date_list=unsafe{ktn(qtype::DATE as I, 3)};
464 /// // 2000.01.01 2000.01.02 2000.01.03
465 /// date_list.as_mut_slice::<I>()[0..3].copy_from_slice(&[0, 1, 2]);
466 /// let string=unsafe{kp(str_to_S!("I'm afraid I would crash the application..."))};
467 /// values.as_mut_slice::<K>()[0..2].copy_from_slice(&[date_list, string]);
468 /// unsafe{xD(keys, values)}
469 /// }
470 /// ```
471 /// ```q
472 /// q)create_dictionary: `libc_api_examples 2: (`create_dictionary; 1);
473 /// q)create_dictionary[]
474 /// 0| 2000.01.01 2000.01.02 2000.01.03
475 /// 1| "I'm afraid I would crash the application..."
476 /// ```
477 pub fn xD(keys: K, values: K) -> K;
478
479 /// Constructor of q error.
480 /// # Example
481 /// ```no_run
482 /// use kdb_c_api::*;
483 /// use kdb_c_api::native::*;
484 ///
485 /// pub extern "C" fn thai_kick(_: K) -> K{
486 /// unsafe{
487 /// krr(null_terminated_str_to_const_S("Thai kick unconditionally!!\0"))
488 /// }
489 /// }
490 /// ```
491 /// ```q
492 /// q)monstrous: `libc_api_examples 2: (`thai_kick; 1);
493 /// q)monstrous[]
494 /// 'Thai kick unconditionally!!
495 /// [0] monstrous[]
496 /// ^
497 /// ```
498 pub fn krr(message: const_S) -> K;
499
500 /// Similar to krr but this function appends a system-error message to string S before passing it to `krr`.
501 pub fn orr(message: const_S) -> K;
502
503 /// Add a raw value to a q simple list and returns a pointer to the (potentially reallocated) `K` object.
504 /// # Example
505 /// ```no_run
506 /// use kdb_c_api::*;
507 /// use kdb_c_api::native::*;
508 ///
509 /// #[no_mangle]
510 /// pub extern "C" fn create_simple_list(_: K) -> K{
511 /// let mut list=unsafe{ktn(qtype::TIMESTAMP as I, 0)};
512 /// for i in 0..5{
513 /// let mut timestamp=86400000000000 * i as J;
514 /// unsafe{ja(&mut list, std::mem::transmute::<*mut J, *mut V>(&mut timestamp))};
515 /// }
516 /// list
517 /// }
518 /// ```
519 /// # Note
520 /// For symbol list, use [`js`](#fn.js).
521 pub fn ja(list: *mut K, value: *mut V) -> K;
522
523 /// Append a q list object to a q list.
524 /// Returns a pointer to the (potentially reallocated) `K` object.
525 /// ```no_run
526 /// use kdb_c_api::*;
527 /// use kdb_c_api::native::*;
528 ///
529 /// #[no_mangle]
530 /// pub extern "C" fn concat_list(mut list1: K, list2: K) -> K{
531 /// unsafe{
532 /// jv(&mut list1, list2);
533 /// r1(list1)
534 /// }
535 /// }
536 /// ```
537 /// ```q
538 /// q)glue: `libc_api_examples 2: (`concat_list; 2);
539 /// q)glue[(::; `metals; `fire); ("clay"; 316)]
540 /// ::
541 /// `metals
542 /// `fire
543 /// "clay"
544 /// 316
545 /// q)glue[1 2 3; 4 5]
546 /// 1 2 3 4 5
547 /// q)glue[`a`b`c; `d`e]
548 /// `a`b`c`d`e
549 /// ```
550 pub fn jv(list1: *mut K, list2: K) -> K;
551
552 /// Add a q object to a q compound list.
553 /// Returns a pointer to the (potentially reallocated) `K` object.
554 /// # Example
555 /// ```
556 /// use kdb_c_api::*;
557 /// use kdb_c_api::native::*;
558 ///
559 /// #[no_mangle]
560 /// pub extern "C" fn create_compound_list(_: K) -> K{
561 /// unsafe{
562 /// let mut list=knk(0);
563 /// jk(&mut list, ks(str_to_S!("1st")));
564 /// jk(&mut list, ki(2));
565 /// jk(&mut list, kpn(str_to_S!("3rd"), "3rd".chars().count() as i64));
566 /// list
567 /// }
568 /// }
569 /// ```
570 /// ```q
571 /// q)ranks: `libc_api_examples 2: (`create_compound_list; 1);
572 /// q)ranks[]
573 /// `1st
574 /// 2i
575 /// "3rd"
576 /// ```
577 /// # Note
578 /// In this example we did not allocate an array as `knk(0)` to use `jk`. As `knk` initializes the
579 /// internal list size `n` with its argument, preallocating memory with `knk` and then using `jk` will crash.
580 /// If you want to allocate a memory in advance, you can substitute a value after converting
581 /// the q list object into a slice with [`as_mut_slice`](../trait.KUtility.html#tymethod.as_mut_slice).
582 pub fn jk(list: *mut K, value: K) -> K;
583
584 /// Add an internalized char array to a symbol list.
585 /// Returns a pointer to the (potentially reallocated) `K` object.
586 /// # Example
587 /// ```no_run
588 /// use kdb_c_api::*;
589 /// use kdb_c_api::native::*;
590 ///
591 /// #[no_mangle]
592 /// pub extern "C" fn create_symbol_list(_: K) -> K{
593 /// unsafe{
594 /// let mut list=ktn(qtype::SYMBOL as I, 0);
595 /// js(&mut list, ss(str_to_S!("Abraham")));
596 /// js(&mut list, ss(str_to_S!("Isaac")));
597 /// js(&mut list, ss(str_to_S!("Jacob")));
598 /// js(&mut list, sn(str_to_S!("Josephine"), 6));
599 /// list
600 /// }
601 /// }
602 /// ```
603 /// ```q
604 /// q)summon:`libc_api_examples 2: (`create_symbol_list; 1)
605 /// q)summon[]
606 /// `Abraham`Isaac`Jacob`Joseph
607 /// q)`Abraham`Isaac`Jacob`Joseph ~ summon[]
608 /// 1b
609 /// ```
610 /// # Note
611 /// In this example we did not allocate an array as `ktn(qtype::SYMBOL as I, 0)` to use `js`. As `ktn` initializes
612 /// the internal list size `n` with its argument, preallocating memory with `ktn` and then using `js` will crash.
613 /// If you want to allocate a memory in advance, you can substitute a value after converting the q list object
614 /// into a slice with [`as_mut_slice`](../trait.KUtility.html#tymethod.as_mut_slice).
615 pub fn js(list: *mut K, symbol: S) -> K;
616
617 /// Intern `n` chars from a char array.
618 /// Returns an interned char array and should be used to add char array to a symbol vector.
619 /// # Example
620 /// See the example of [`js`](fn.js.html).
621 pub fn sn(string: S, n: I) -> S;
622
623 /// Intern a null-terminated char array.
624 /// Returns an interned char array and should be used to add char array to a symbol vector.
625 /// # Example
626 /// See the example of [`js`](fn.js.html).
627 pub fn ss(string: S) -> S;
628
629 /// Capture (and reset) error string into usual error object.
630 /// # Example
631 /// ```no_run
632 /// use kdb_c_api::*;
633 /// use kdb_c_api::native::*;
634 ///
635 /// extern "C" fn catchy(func: K, args: K) -> K{
636 /// unsafe{
637 /// let result=ee(dot(func, args));
638 /// if (*result).qtype == qtype::ERROR{
639 /// println!("error: {}", S_to_str((*result).value.symbol));
640 /// // Decrement reference count of the error object
641 /// r0(result);
642 /// KNULL
643 /// }
644 /// else{
645 /// result
646 /// }
647 /// }
648 /// }
649 /// ```
650 /// ```q
651 /// q)catchy: `libc_api_examples 2: (`catchy; 2);
652 /// q)catchy[$; ("J"; "42")]
653 /// 42
654 /// q)catchy[+; (1; `a)]
655 /// error: type
656 /// ```
657 pub fn ee(result: K) -> K;
658
659 //%% IPC Functions %%//vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv/
660
661 /// Send a text query or evaluate the text query in a process which are loading the shared library.
662 /// As this library is purposed to build shared object, the only choice of `socket` is `0`. This
663 /// executes against the kdb+ process in which it is loaded.
664 /// ```
665 /// use kdb_c_api::*;
666 /// use kdb_c_api::native::*;
667 ///
668 /// #[no_mangle]
669 /// pub extern "C" fn dictionary_list_to_table() -> K{
670 /// let dicts=unsafe{knk(3)};
671 /// let dicts_slice=dicts.as_mut_slice::<K>();
672 /// for i in 0..3{
673 /// let keys=unsafe{ktn(qtype::SYMBOL as I, 2)};
674 /// let keys_slice=keys.as_mut_slice::<S>();
675 /// keys_slice[0]=unsafe{ss(str_to_S!("a"))};
676 /// keys_slice[1]=unsafe{ss(str_to_S!("b"))};
677 /// let values=unsafe{ktn(qtype::INT as I, 4)};
678 /// values.as_mut_slice::<I>()[0..2].copy_from_slice(&[i*10, i*100]);
679 /// dicts_slice[i as usize]=unsafe{xD(keys, values)};
680 /// }
681 /// // Format list of dictionary as a table.
682 /// // ([] a: 0 10 20i; b: 0 100 200i)
683 /// unsafe{k(0, str_to_S!("{[dicts] -1 _ dicts, (::)}"), dicts, KNULL)}
684 /// }
685 /// ```
686 /// ```q
687 /// q)unfortunate_fact: `libc_api_examples 2: (`dictionary_list_to_table; 1);
688 /// q)unfortunate_fact[]
689 /// a b
690 /// ------
691 /// 0 0
692 /// 10 100
693 /// 20 200
694 /// ```
695 pub fn k(socket: I, query: const_S,...) -> K;
696
697 /// Serialize q object and return serialized q byte list object on success: otherwise null.
698 /// Mode is either of:
699 /// - -1: Serialize within the same process.
700 /// - 1: retain enumerations, allow serialization of timespan and timestamp: Useful for passing data between threads
701 /// - 2: unenumerate, allow serialization of timespan and timestamp
702 /// - 3: unenumerate, compress, allow serialization of timespan and timestamp
703 /// # Example
704 /// ```no_run
705 /// use kdb_c_api::*;
706 /// use kdb_c_api::native::*;
707 ///
708 /// #[no_mangle]
709 /// pub extern "C" fn conceal(object: K)->K{
710 /// unsafe{b9(3, object)}
711 /// }
712 /// ```
713 /// ```q
714 /// q)jamming: `libc_api_examples 2: (`conceal; 1);
715 /// q)jamming til 3
716 /// 0x0100000026000000070003000000000000000000000001000000000000000200000000000000
717 /// q)-9!jamming "Look! HE has come!!"
718 /// "Look! HE has come!!"
719 /// ```
720 pub fn b9(mode: I, qobject: K) -> K;
721
722 /// Deserialize a bytes into q object.
723 /// # Example
724 /// ```no_run
725 /// use kdb_c_api::*;
726 /// use kdb_c_api::native::*;
727 ///
728 /// #[no_mangle]
729 /// pub extern "C" fn reveal(bytes: K)->K{
730 /// unsafe{d9(bytes)}
731 /// }
732 /// ```
733 /// ```q
734 /// q)cancelling: `libc_api_examples 2: (`reveal; 1);
735 /// q)cancelling -8!(`contact`from; "space"; 12);
736 /// `contact`from
737 /// "space"
738 /// 12
739 /// ```
740 /// # Note
741 /// On success, returns deserialized `K` object. On error, `(K) 0` is returned; use [`ee`](#fn.ee) to retrieve the error string.
742 ///
743 pub fn d9(bytes: K) -> K;
744
745 /// Remove callback from the associated kdb+ socket and call `kclose`.
746 /// Return null if the socket is invalid or not the one which had been registered by `sd1`.
747 /// # Note
748 /// A function which calls this function must be executed at the exit of the process.
749 pub fn sd0(socket: I) -> V;
750
751 /// Remove callback from the associated kdb+ socket and call `kclose` if the given condition is satisfied.
752 /// Return null if the socket is invalid or not the one which had been registered by `sd1`.
753 /// # Note
754 /// A function which calls this function must be executed at the exit of the process.
755 pub fn sd0x(socket: I, condition: I) -> V;
756
757 /// Register callback to the associated kdb+ socket.
758 /// ```no_run
759 /// use kdb_c_api::*;
760 /// use kdb_c_api::native::*;
761 /// use std::ffi::c_void;
762 ///
763 /// // Send asynchronous query to the q process which sent a query to the caller of this function.
764 /// extern "C" fn counter(socket: I) -> K{
765 /// let extra_query="show `$\"Counter_punch!!\"".as_bytes();
766 /// let query_length=extra_query.len();
767 /// // header (8) + list header (6) + data length
768 /// let total_length=8+6+query_length;
769 /// // Buffer
770 /// let mut message: Vec<u8>=Vec::with_capacity(total_length);
771 /// // Little endian, async, uncompress, reserved
772 /// message.extend_from_slice(&[1_u8, 0, 0, 0]);
773 /// // Total message length
774 /// message.extend_from_slice(&(total_length as i32).to_le_bytes());
775 /// // Data type, attribute
776 /// message.extend_from_slice(&[10_u8, 0]);
777 /// // Length of data
778 /// message.extend_from_slice(&(query_length as i32).to_le_bytes());
779 /// // Data
780 /// message.extend_from_slice(extra_query);
781 /// // Send
782 /// unsafe{libc::send(socket, message.as_slice().as_ptr() as *const c_void, total_length, 0)};
783 /// KNULL
784 /// }
785 ///
786 /// #[no_mangle]
787 /// pub extern "C" fn enable_counter(socket: K) -> K{
788 /// unsafe{
789 /// let result=sd1(socket.get_int().expect("oh no"), counter);
790 /// if result.get_type()== qtype::NULL || result.get_type()== qtype::ERROR{
791 /// return krr(null_terminated_str_to_const_S("Failed to hook\0"));
792 /// }
793 /// else{
794 /// KNULL
795 /// }
796 /// }
797 /// }
798 /// ```
799 /// ```q
800 /// q)// process1
801 /// q)enable_counter: `libc_api_examples 2: (`enable_counter; 1)
802 /// q)\p 5000
803 /// ```
804 /// ```q
805 /// q)// process2
806 /// q)h:hopen `:unix://5000
807 /// ```
808 /// ```q
809 /// q)// process1
810 /// q).z.W
811 /// 5|
812 /// q)enable_counter[5i]
813 /// ```
814 /// ```q
815 /// q)// process2
816 /// q)h "1+2"
817 /// `Counter_punch!!
818 /// 3
819 /// q)neg[h] "1+2"
820 /// `Counter_punch!!
821 /// ```
822 pub fn sd1(socket: I, function: extern fn(I) -> K) -> K;
823
824 //%% Reference Count %%//vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv/
825
826 /// Decrement reference count of the q object. The decrement must be done when `k` function gets an error
827 /// object whose type is `qtype::ERROR` and when you created an object but do not intend to return it to
828 /// q side. See details on [the reference page](https://code.kx.com/q/interfaces/c-client-for-q/#managing-memory-and-reference-counting).
829 /// # Example
830 /// ```no_run
831 /// use kdb_c_api::*;
832 /// use kdb_c_api::native::*;
833 ///
834 /// #[no_mangle]
835 /// pub extern "C" fn idle_man(_: K)->K{
836 /// unsafe{
837 /// // Creare an int object.
838 /// let int=ki(777);
839 /// // Changed the mind. Discard it.
840 /// r0(int);
841 /// }
842 /// // Return null.
843 /// KNULL
844 /// }
845 /// ```
846 /// ```q
847 /// q)idle_man: libc_api_examples 2: (`idle_man; 1);
848 /// q)idle_man[]
849 /// q)
850 /// ```
851 pub fn r0(qobject: K) -> V;
852
853 /// Increment reference count of the q object. Increment must be done when you passed arguments
854 /// to Rust function and intends to return it to q side or when you pass some `K` objects to `k`
855 /// function and intend to use the parameter after the call.
856 /// See details on [the reference page](https://code.kx.com/q/interfaces/c-client-for-q/#managing-memory-and-reference-counting).
857 /// # Example
858 /// ```no_run
859 /// use kdb_c_api::*;
860 /// use kdb_c_api::native::*;
861 ///
862 /// #[no_mangle]
863 /// pub extern "C" fn pass_through_cave(pedestrian: K) -> K{
864 /// let item=unsafe{k(0, str_to_S!("get_item1"), r1(pedestrian), KNULL)};
865 /// println!("What do you see, son of man?: {}", item.get_str().expect("oh no"));
866 /// unsafe{r0(item)};
867 /// let item=unsafe{k(0, str_to_S!("get_item2"), r1(pedestrian), KNULL)};
868 /// println!("What do you see, son of man?: {}", item.get_str().expect("oh no"));
869 /// unsafe{
870 /// r0(item);
871 /// r1(pedestrian)
872 /// }
873 /// }
874 /// ```
875 /// ```q
876 /// q)get_item1:{[man] "a basket of summer fruit"};
877 /// q)get_item2:{[man] "boiling pot, facing away from the north"}
878 /// q).capi.pass_through_cave[`son_of_man]
879 /// What do you see, son of man?: a basket of summer fruit
880 /// What do you see, son of man?: boiling pot, facing away from the north
881 /// `son_of_man
882 /// ```
883 pub fn r1(qobject: K) -> K;
884
885 //%% Miscellaneous %%//vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv/
886
887 /// Apply a function to q list object `.[func; args]`.
888 /// # Example
889 /// ```no_run
890 /// use kdb_c_api::*;
891 /// use kdb_c_api::native::*;
892 ///
893 /// #[no_mangle]
894 /// pub extern "C" fn rust_parse(dollar: K, type_and_text: K) -> K{
895 /// unsafe{
896 /// dot(dollar, type_and_text)
897 /// }
898 /// }
899 /// ```
900 /// ```q
901 /// q)rust_parse:`libc_api_examples 2: (`rust_parse; 2);
902 /// q)rust_parse[$; ("S"; "text")]
903 /// `text
904 /// ```
905 pub fn dot(func: K, args: K) -> K;
906
907 /// Release the memory allocated for the thread's pool.
908 /// Call when the thread is about to complete, releasing the memory allocated for that thread's pool.
909 pub fn m9() -> V;
910
911 /// Set whether interning symbols uses a lock: `lock` is either 0 or 1.
912 /// Returns the previously set value.
913 /// # Example
914 /// ```no_run
915 /// use kdb_c_api::*;
916 /// use kdb_c_api::native::*;
917 ///
918 /// #[no_mangle]
919 /// pub extern "C" fn parallel_sym_change(list: K) -> K{
920 /// unsafe{
921 /// // `K` cannot have `Send` because it is a pointer but `k0` does.
922 /// let mut inner=*list;
923 /// // Lock symbol before creating an internal symbol on another thread.
924 /// setm(1);
925 /// let task=std::thread::spawn(move || {
926 /// inner.as_mut_slice::<S>()[0]=ss(str_to_S!("replaced"));
927 /// inner
928 /// });
929 /// list.as_mut_slice::<S>()[1]=ss(str_to_S!("symbolbol"));
930 /// match task.join(){
931 /// Err(_) => {
932 /// // Unlock.
933 /// setm(0);
934 /// krr(null_terminated_str_to_const_S("oh no"))
935 /// },
936 /// Ok(l) => {
937 /// // Unlock.
938 /// setm(0);
939 /// (*list)=l;
940 /// // Increment reference count for copy.
941 /// r1(list)
942 /// }
943 /// }
944 /// }
945 /// }
946 /// ```
947 /// ```q
948 /// q)alms_with_left_hand: `libc_api_examples 2: (`parallel_sym_change; 2);
949 /// q)alms_with_left_hand[`a`b];
950 /// `replaced`symbolbol
951 /// ```
952 pub fn setm(lock: I) -> I;
953
954 /// Load C function as q function (`K` object).
955 /// # Parameters
956 /// - `func`: A function takes a C function that would take `n` `K` objects as arguments and returns a `K` object.
957 /// - `n`: The number of arguments for the function.
958 pub fn dl(func: *const V, n: J) -> K;
959
960 /// Convert ymd to the number of days from `2000.01.01`.
961 /// # Example
962 /// ```no_run
963 /// use kdb_c_api::*;
964 /// use kdb_c_api::native::*;
965 ///
966 /// fn main(){
967 ///
968 /// let days=unsafe{ymd(2020, 4, 1)};
969 /// assert_eq!(days, 7396);
970 ///
971 /// }
972 /// ```
973 pub fn ymd(year: I, month: I, date:I) -> I;
974
975 /// Convert days from `2000.01.01` to a number expressed as `yyyymmdd`.
976 /// # Example
977 /// ```no_run
978 /// use kdb_c_api::*;
979 /// use kdb_c_api::native::*;
980 ///
981 /// fn main(){
982 ///
983 /// let number=unsafe{dj(7396)};
984 /// assert_eq!(number, 20200401);
985 ///
986 /// }
987 /// ```
988 pub fn dj(days: I) -> I;
989
990 /* Unsupported
991
992 /// Connect with timeout (millisecond) and capability. The value of capability is:
993 /// - 1: 1TB limit
994 /// - 2: use TLS
995 /// Return value is either of:
996 /// - 0 Authentication error
997 /// - -1 Connection error
998 /// - -2 Timeout error
999 /// - -3 OpenSSL initialization failed
1000 /// # Note
1001 /// Standalone application only. Not for a shared library.
1002 pub fn khpunc(host: S, port: I, credential: S, timeout_millis: I, capability: I) -> I;
1003
1004 /// Connect with timeout (millisecond).
1005 /// Return value is either of:
1006 /// - 0 Authentication error
1007 /// - -1 Connection error
1008 /// - -2 Timeout error
1009 /// # Note
1010 /// Standalone application only. Not for a shared library.
1011 pub fn khpun(host: const_S, port: I, credential: const_S, timeout_millis: I) -> I;
1012
1013 /// Connect with no timeout.
1014 pub fn khpu(host: const_S, port: I, credential: const_S) -> I;
1015
1016 /// Connect anonymously.
1017 pub fn khp(host: const_S, port: I) -> I;
1018
1019 /// Close the socket to a q process.
1020 /// # Note
1021 /// Standalone application only. Not for a shared library.
1022 pub fn kclose(socket: I) -> V;
1023
1024 /// Verify that the received bytes is a valid IPC message.
1025 /// The message is not modified.
1026 /// Returns `0` if not valid.
1027 /// # Note
1028 /// Decompressed data only.
1029 pub fn okx(bytes: K) -> I;
1030
1031 /// Return a dictionary of TLS setting. See `-26!`.
1032 /// # Note
1033 /// As this library is purposed to build shared object, this function will not add a value.
1034 pub fn sslInfo(_: K) -> K;
1035
1036 /// Return kdb+ release date.
1037 /// # Note
1038 /// This function seems not exist (`undefined symbol`).
1039 pub fn ver() -> I;
1040
1041 /// Variadic version of `knk`.
1042 fn vaknk(qtype: I, args: va_list) -> K;
1043
1044 /// Variadic version of `k`.
1045 fn vak(qtype: I, query: const_S, args: va_list) -> K;
1046
1047 */
1048}