Trait KUtility

pub trait KUtility {
    // Required methods
    fn as_mut_slice<'a, T>(self) -> &'a mut [T];
    fn get_bool(&self) -> Result<bool, &'static str>;
    fn get_guid(&self) -> Result<[u8; 16], &'static str>;
    fn get_byte(&self) -> Result<u8, &'static str>;
    fn get_short(&self) -> Result<i16, &'static str>;
    fn get_int(&self) -> Result<i32, &'static str>;
    fn get_long(&self) -> Result<i64, &'static str>;
    fn get_real(&self) -> Result<f32, &'static str>;
    fn get_float(&self) -> Result<f64, &'static str>;
    fn get_char(&self) -> Result<char, &'static str>;
    fn get_symbol(&self) -> Result<&str, &'static str>;
    fn get_str(&self) -> Result<&str, &'static str>;
    fn get_string(&self) -> Result<String, &'static str>;
    fn get_dictionary(&self) -> Result<K, &'static str>;
    fn get_attribute(&self) -> C;
    fn get_refcount(&self) -> I;
    fn append(&mut self, list: K) -> Result<K, &'static str>;
    fn push(&mut self, atom: K) -> Result<K, &'static str>;
    fn push_raw<T>(&mut self, atom: T) -> Result<K, &'static str>;
    fn push_symbol(&mut self, symbol: &str) -> Result<K, &'static str>;
    fn push_symbol_n(&mut self, symbol: &str, n: I) -> Result<K, &'static str>;
    fn len(&self) -> i64;
    fn get_type(&self) -> i8;
    fn set_type(&self, qtype: i8);
    fn q_ipc_encode(&self, mode: I) -> Result<K, &'static str>;
    fn q_ipc_decode(&self) -> Result<K, &'static str>;
}

Required Methods

fn as_mut_slice<'a, T>(self) -> &'a mut [T]

Derefer K as a mutable slice of the specified type. The supported types are:

• G: Equivalent to C API macro kG.
• H: Equivalent to C API macro kH.
• I: Equivalent to C API macro kI.
• J: Equivalent to C API macro kJ.
• E: Equivalent to C API macro kE.
• F: Equivalent to C API macro kF.
• C: Equivalent to C API macro kC.
• S: Equivalent to C API macro kS.
• K: Equivalent to C API macro kK.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn modify_long_list_a_bit(long_list: K) -> K{
  if long_list.len() >= 2{
    // Derefer as a mutable i64 slice.
    long_list.as_mut_slice::<J>()[1]=30000_i64;
    // Increment the counter to reuse on q side.
    increment_reference_count(long_list)
  }
  else{
    new_error("this list is not long enough. how ironic...\0")
  }
}

q)ironic: `libc_api_examples 2: (`modify_long_list_a_bit; 1);
q)list:1 2 3;
q)ironic list
1 30000 3
q)ironic enlist 1

Note

Intuitively the parameter should be &mut self but it restricts a manipulating K objects in the form of slice simultaneously. As copying a pointer is not an expensive operation, using self should be fine.

fn get_bool(&self) -> Result<bool, &'static str>

Get an underlying q byte.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_bool(atom: K) -> K{
  match atom.get_bool(){
    Ok(boolean) => {
      println!("bool: {}", boolean);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_boole: `libc_api_examples 2: (`print_bool; 1);
q)print_bool[1b]
bool: true

fn get_guid(&self) -> Result<[u8; 16], &'static str>

Get an underlying q byte.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_guid(atom: K) -> K{
  match atom.get_guid(){
    Ok(guid) => {
      let strguid=guid.iter().map(|b| format!("{:02x}", b)).collect::<String>();
      println!("GUID: {}-{}-{}-{}-{}", &strguid[0..4], &strguid[4..6], &strguid[6..8], &strguid[8..10], &strguid[10..16]);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_guid: `libc_api_examples 2: (`print_guid; 1);
q)guid: first 1?0Ng;
q)print_guid[guid]
GUID: 8c6b-8b-64-68-156084

fn get_byte(&self) -> Result<u8, &'static str>

Get an underlying q byte.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_byte(atom: K) -> K{
  match atom.get_byte(){
    Ok(byte) => {
      println!("byte: {:#4x}", byte);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_byte: `libc_api_examples 2: (`print_byte; 1);
q)print_byte[0xc4]
byte: 0xc4

fn get_short(&self) -> Result<i16, &'static str>

Get an underlying q short.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_short(atom: K) -> K{
  match atom.get_short(){
    Ok(short) => {
      println!("short: {}", short);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_short: `libc_api_examples 2: (`print_short; 1);
q)print_short[10h]
short: 10

fn get_int(&self) -> Result<i32, &'static str>

Get an underlying q int.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_int(atom: K) -> K{
  match atom.get_int(){
    Ok(int) => {
      println!("int: {}", int);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_int: `libc_api_examples 2: (`print_int; 1);
q)print_int[03:57:20]
int: 14240

fn get_long(&self) -> Result<i64, &'static str>

Get an underlying q long.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_long(atom: K) -> K{
  match atom.get_long(){
    Ok(long) => {
      println!("long: {}", long);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_long: `libc_api_examples 2: (`print_long; 1);
q)print_long[2000.01.01D12:00:00.123456789]
long: 43200123456789

fn get_real(&self) -> Result<f32, &'static str>

Get an underlying q real.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_real(atom: K) -> K{
  match atom.get_real(){
    Ok(real) => {
      println!("real: {}", real);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_real: `libc_api_examples 2: (`print_real; 1);
q)print_real[193810.32e]
real: 193810.31

fn get_float(&self) -> Result<f64, &'static str>

Get an underlying q float.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_float(atom: K) -> K{
  match atom.get_float(){
    Ok(float) => {
      println!("float: {:.8}", float);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_float: `libc_api_examples 2: (`print_float; 1);
q)print_float[2002.01.12T10:03:45.332]
float: 742.41927468

fn get_char(&self) -> Result<char, &'static str>

Get an underlying q char.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_char(atom: K) -> K{
  match atom.get_char(){
    Ok(character) => {
      println!("char: \"{}\"", character);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_char: `libc_api_examples 2: (`print_char; 1);
q)print_char["k"]
char: "k"

fn get_symbol(&self) -> Result<&str, &'static str>

Get an underlying q symbol.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_symbol2(atom: K) -> K{
  match atom.get_symbol(){
    Ok(symbol) => {
      println!("symbol: `{}", symbol);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_symbol2: `libc_api_examples 2: (`print_symbol2; 1);
q)print_symbol2[`locust]
symbol: `locust

fn get_str(&self) -> Result<&str, &'static str>

Get an underlying q string as &str.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_string(string: K) -> K{
  match string.get_str(){
    Ok(string_) => {
      println!("string: \"{}\"", string_);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_string: `libc_api_examples 2: (`print_string; 1);
q)print_string["gnat"]
string: "gnat"

fn get_string(&self) -> Result<String, &'static str>

Get an underlying q string as String.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn print_string2(string: K) -> K{
  match string.get_string(){
    Ok(string_) => {
      println!("string: \"{}\"", string_);
      KNULL
    },
    Err(error) => new_error(error)
  }
}

q)print_string: `libc_api_examples 2: (`print_string; 1);
q)print_string["grasshopper"]
string: "grasshopper"

fn get_dictionary(&self) -> Result<K, &'static str>

Get a flipped underlying q table as K (dictionary).

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn hidden_key(table: K) -> K{
  match table.get_dictionary(){
    Ok(dictionary) => dictionary.as_mut_slice::<K>()[0].q_ipc_encode(3).unwrap(),
    Err(error) => new_error(error)
  }
}

q)perceive_the_man: `libc_api_examples 2: (`hidden_key; 1);
q)perceive_the_man ([] t: `timestamp$.z.p+1e9*til 9; chr:"ljppkgfgs"; is: 7 8 12 14 21 316 400 1000 6000i)
0x01000000170000000b0003000000740063687200697300

Note

This method is provided because the ony way to examine the value of table type is to access the underlying dictionary (flipped table). Also when some serialization is necessary for a table, you can reuse a serializer for a dictionary if it is already provided. Actually when q serialize a table object with -8! (q function) or b9 (C code), it just serializes the underlying dictionary with an additional marker indicating a table type.

fn get_attribute(&self) -> C

Get an attribute of a q object.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn murmur(list: K) -> K{
  match list.get_attribute(){
    qattribute::SORTED => {
      new_string("Clean")
    },
    qattribute::UNIQUE => {
      new_symbol("Alone")
    },
    _ => KNULL
  }
}

fn get_refcount(&self) -> I

Get a reference count of a q object.

fn append(&mut self, list: K) -> Result<K, &'static str>

Append a q list object to a q list. Returns a pointer to the (potentially reallocated) K object.

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn concat_list2(mut list1: K, list2: K) -> K{
  if let Err(err) = list1.append(list2){
    new_error(err)
  }
  else{
    increment_reference_count(list1)
  }
}

q)plunder: `libc_api_examples 2: (`concat_list2; 2);
q)plunder[(::; `metals; `fire); ("clay"; 316)]
::
`metals
`fire
"clay"
316
q)plunder[1 2 3; 4 5]
1 2 3 4 5
q)plunder[`a`b`c; `d`e]
`a`b`c`d`e

fn push(&mut self, atom: K) -> Result<K, &'static str>

Add a q object to a q compound list. Returns a pointer to the (potentially reallocated) K object.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn create_compound_list(int: K) -> K{
  let mut list=new_simple_list(qtype::COMPOUND, 0);
  for i in 0..5{
    list.push(new_long(i)).unwrap();
  }
  list.push(increment_reference_count(int)).unwrap();
  list
}

q)nums: `libc_api_examples 2: (`create_compound_list2; 1);
q)nums[5i]
0
1
2
3
4
5i

Note

In this example we did not allocate an array as new_simple_list(qtype::COMPOUND, 0) to use push. As new_simple_list initializes the internal list size n with its argument, preallocating memory with new_simple_list and then using push will crash. If you want to allocate a memory in advance, you can substitute a value after converting the q list object into a slice with as_mut_slice.

fn push_raw<T>(&mut self, atom: T) -> Result<K, &'static str>

Add a raw value to a q simple list and returns a pointer to the (potentially reallocated) K object.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn create_simple_list2(_: K) -> K{
  let mut list=new_simple_list(qtype::DATE, 0);
  for i in 0..5{
    list.push_raw(i).unwrap();
  }
  list
}

q)simple_is_the_best: `lic_api_example 2: (`create_simple_list2; 1);
q)simple_is_the_best[]
2000.01.01 2000.01.02 2000.01.03 2000.01.04 2000.01.05

Note

• Concrete type of T is not checked. Its type must be either of I, J and F and it must be compatible with the list type. For example, timestamp list requires J type atom.
• For symbol list, use push_symbol or push_symbol_n.

fn push_symbol(&mut self, symbol: &str) -> Result<K, &'static str>

Add an internalized char array to symbol list. Returns a pointer to the (potentially reallocated) K object.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn create_symbol_list2(_: K) -> K{
  let mut list=new_simple_list(qtype::SYMBOL, 0);
  list.push_symbol("Abraham").unwrap();
  list.push_symbol("Isaac").unwrap();
  list.push_symbol("Jacob").unwrap();
  list.push_symbol_n("Josephine", 6).unwrap();
  list
}

q)summon:`libc_api_examples 2: (`create_symbol_list2; 1)
q)summon[]
`Abraham`Isaac`Jacob`Joseph
q)`Abraham`Isaac`Jacob`Joseph ~ summon[]
1b

Note

In this example we did not allocate an array as new_simple_list(qtype::SYMBOL as I, 0) to use push_symbol. As new_simple_list initializes the internal list size n with its argument, preallocating memory with new_simple_list and then using push_symbol will crash. If you want to allocate a memory in advance, you can substitute a value after converting the q list object into a slice with as_mut_slice.

fn push_symbol_n(&mut self, symbol: &str, n: I) -> Result<K, &'static str>

Add an internalized char array to symbol list. Returns a pointer to the (potentially reallocated) K object.

Example

See the example of push_symbol.

fn len(&self) -> i64

Get a length of the list. More specifically, a value of k0.value.list.n for list types. Otherwise 2 for table and 1 for atom and null.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn numbers(obj: K) -> K{
  let count=format!("{} people are in numbers", obj.len());
  new_string(&count)
}

q)census: `libc_api_examples 2: (`numbers; 1);
q)census[(::)]
"1 people are in numbers"
q)census[til 4]
"4 people are in numbers"
q)census[`a`b!("many"; `split`asunder)]
"2 people are in numbers"
q)census[([] id: til 1000)]
"1000 people are in numbers"

fn get_type(&self) -> i8

Get a type of K object.

fn set_type(&self, qtype: i8)

Set a type of K object.

Example

See the example of `load_as_q_function.

fn q_ipc_encode(&self, mode: I) -> Result<K, &'static str>

Serialize q object and return serialized q byte list object on success: otherwise null. Mode is either of:

• -1: Serialize within the same process.
• 1: retain enumerations, allow serialization of timespan and timestamp: Useful for passing data between threads
• 2: unenumerate, allow serialization of timespan and timestamp
• 3: unenumerate, compress, allow serialization of timespan and timestamp

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn encrypt(object: K)->K{
  match object.q_ipc_encode(3){
    Ok(bytes) => bytes,
    Err(error) => new_error(error)
  }
}

q)disguise: `libc_api_examples 2: (`encrypt; 1);
q)list: (til 3; "abc"; 2018.02.18D04:30:00.000000000; `revive);
q)disguise list
0x010000004600000000000400000007000300000000000000000000000100000000000000020..

fn q_ipc_decode(&self) -> Result<K, &'static str>

Deserialize a bytes into q object.

Example

use kdb_c_api::*;
 
#[no_mangle]
pub extern "C" fn decrypt(bytes: K)->K{
  match bytes.q_ipc_decode(){
    Ok(object) => object,
    Err(error) => new_error(error)
  }
}

q)uncover: `libc_api_examples 2: (`decrypt; 1);
q)uncover -8!"What is the purpose of CREATION?"
"What is the purpose of CREATION?"

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl KUtility for K