Struct KBox

Source

pub struct KBox<T: KObject> { /* private fields */ }

Expand description

Represents a memory managed K pointer. They are the KDB equivalent of a Rust Box, a zero overhead wrapper around a K pointer. It will call r0 to decrement the reference count when it is dropped.

Implementations§

Source §

impl<T: KValue> KBox<Atom<T>>

Source

pub fn new_atom(value: T) -> KBox<Atom<T>>

Creates a new atom with the specified value.

Examples found in repository ?

examples/using_atoms.rs (line 6)

5fn main() {
6    let mut k = KBox::new_atom(42u8);
7    println!("{}", k);
8    assert_eq!(k.value(), 42);
9
10    k.set_value(43);
11
12    assert_eq!(k.value(), 43);
13}

More examples

Hide additional examples

examples/using_any.rs (line 4)

3fn main() {
4    let int = KBox::new_atom(42);
5
6    // convert to an "any" value:
7    let any: KBox<Any> = int.into();
8
9    // convert back to an i32 atom.
10    let int = cast!(any; Atom<i32>);
11    println!("{:?}", int);
12
13    let any: KBox<Any> = int.into();
14    // try to convert to a u8 atom. This will fail!
15    if let Err(e) = try_cast!(any; Atom<u8>) {
16        println!("Error: {}", e);
17    }
18}

examples/fun_with_symbols.rs (line 12)

3fn main() {
4    //Create two identical symbols in different ways, and check that they are equal.
5    let sym = symbol("Hello, World");
6    // Note: converting a string into a symbol is not an infallible operation
7    // rust strings can contain embedded nuls, whereas symbols cannot.
8    let sym_2 = Symbol::new(String::from("Hello") + ", World").unwrap();
9    assert_eq!(sym, sym_2);
10
11    // As an atom:
12    let atom = KBox::new_atom(sym);
13    let atom_2 = KBox::new_atom(Symbol::new(String::from("Hello") + ", World").unwrap());
14
15    assert_eq!(atom.value(), atom_2.value());
16
17    // Note that because rust strings are utf-8, and symbols have no encoding requirement,
18    // this may not display the same way as you will see it in kdb, especially if the string is
19    // not a valid ASCII or utf-8 string.
20    println!("{}", sym);
21}

Source §

impl KBox<KError>

Source

pub fn new_error(msg: &str) -> Self

Create a new KDB error from the specified string.

Source §

impl<T: KObject> KBox<T>

Source

pub fn into_raw(self) -> *mut T

Converts a box into a raw unmanged K pointer. Note that into raw will consume the KBox, and not call r0, so it’s possible to leak memory by doing this.

Source

pub unsafe fn from_raw(k: *mut K) -> Self

Converts a raw K pointer into a boxed K object. This is the reciprocal of into_raw

§Safety

The type of the k pointer must match the type of the KBox being used. The pointer must not be null.

Do not use this to take ownership of a kdb callback function parameter, use from_shared instead.

Source

pub unsafe fn from_shared(t: &mut T) -> Self

Takes a reference and calls r1, incrementing the reference count and “re-boxing” it. Typically this is a bad thing as you have multiple owned references and kdb does not provide equivalent guarantees to rust about what happens to shared references (especially when reallocating a list for example)

However in the embedded case, where you do not own the parameter and you wish to manipulate it without copying the data, then you need this functionality.

§Safety

A reference should not be owned by more than one KBox instance.

Source §

impl<T: KListable> KBox<List<T>>

Source

pub fn new_list() -> Self

Creates a new empty list.

Note that if you are converting a rust collection to a list, collect is a more efficient. If you are creating a list with a set of known elements, use the list! macro.

Examples found in repository ?

examples/creating_a_list.rs (line 8)

3fn main() {
4    //Create a list containing the numbers from 1 to 10.
5    let mut list: KBox<List<u8>> = (1..=10).collect();
6
7    //Create another list by pushing incrementally
8    let mut list_2: KBox<List<u8>> = KBox::new_list();
9    for i in 11..=20 {
10        list_2.push(i);
11    }
12
13    //Append the second list to the first
14    list.join(list_2);
15
16    // Append from an iterator:
17    list.extend(21..=30);
18
19    // write out the contents
20    for i in list.iter() {
21        println!("{}", i);
22    }
23
24    // we can also use it as a slice:
25    for i in &list[..5] {
26        println!("{}", i)
27    }
28}

Source

pub fn join(&mut self, list: KBox<List<T>>)

Appends a list to this one, consuming it and adding it’s elements to the new one.

Examples found in repository ?

examples/creating_a_list.rs (line 14)

3fn main() {
4    //Create a list containing the numbers from 1 to 10.
5    let mut list: KBox<List<u8>> = (1..=10).collect();
6
7    //Create another list by pushing incrementally
8    let mut list_2: KBox<List<u8>> = KBox::new_list();
9    for i in 11..=20 {
10        list_2.push(i);
11    }
12
13    //Append the second list to the first
14    list.join(list_2);
15
16    // Append from an iterator:
17    list.extend(21..=30);
18
19    // write out the contents
20    for i in list.iter() {
21        println!("{}", i);
22    }
23
24    // we can also use it as a slice:
25    for i in &list[..5] {
26        println!("{}", i)
27    }
28}

Source

pub fn push(&mut self, item: T::ListItem)

Appends an element to the end of the list.

Examples found in repository ?

examples/creating_a_list.rs (line 10)

3fn main() {
4    //Create a list containing the numbers from 1 to 10.
5    let mut list: KBox<List<u8>> = (1..=10).collect();
6
7    //Create another list by pushing incrementally
8    let mut list_2: KBox<List<u8>> = KBox::new_list();
9    for i in 11..=20 {
10        list_2.push(i);
11    }
12
13    //Append the second list to the first
14    list.join(list_2);
15
16    // Append from an iterator:
17    list.extend(21..=30);
18
19    // write out the contents
20    for i in list.iter() {
21        println!("{}", i);
22    }
23
24    // we can also use it as a slice:
25    for i in &list[..5] {
26        println!("{}", i)
27    }
28}