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