Trait KUtility

Source
pub trait KUtility {
Show 26 methods // 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§

Source

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.

Source

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
Source

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
Source

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
Source

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
Source

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
Source

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
Source

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
Source

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
Source

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"
Source

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
Source

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"
Source

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"
Source

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.

Source

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
  }
}
Source

fn get_refcount(&self) -> I

Get a reference count of a q object.

Source

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
Source

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.

Source

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.
Source

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.

Source

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.

Source

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"
Source

fn get_type(&self) -> i8

Get a type of K object.

Source

fn set_type(&self, qtype: i8)

Set a type of K object.

§Example

See the example of `load_as_q_function.

Source

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..
Source

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§