Module lv2rs_atom::object

Object- or Map-style atom container.

An object contains a series of atoms which are tagged with a key. This way, one can view an atom in an object either as a property of an object (just like in object-oriented programming) or as an entry in a URID->Atom map.

When initialized, an object does not contain any items. Instead, you have to push them to the end of the object using the ObjectWritingFrame trait. Every writing frame implements this trait via a blanket implementation and the trait is included in the crate's prelude. You can, therefore, act as if the extended methods were normal methods of a writing frame.

Reading an object is accomplished by creating an iterator over the properties with the iter method.

An example:

extern crate lv2rs_atom as atom;
extern crate lv2rs_urid as urid;

use atom::prelude::*;
use atom::ports::*;
use urid::{CachedMap, debug::DebugMap};
use std::ffi::{CString, CStr};

pub struct Plugin {
    in_port: AtomInputPort<Object>,
    out_port: AtomOutputPort<Object>,
    urids: CachedMap,
}

impl Plugin {
    /// Simulated `run` method.
    fn run(&mut self) {
        let my_class_urid = self.urids.map(
            CStr::from_bytes_with_nul(b"https://example.org#MyClass\0").unwrap()
        );
        let a_urid = self.urids.map(
            CStr::from_bytes_with_nul(b"https://example.org#a\0").unwrap()
        );
        let b_urid = self.urids.map(
            CStr::from_bytes_with_nul(b"https://example.org#b\0").unwrap()
        );

        // Writing
        {
            // We are writing an object that is an instance of `MyClass`. This information
            // is expressed by passing the URID of `MyClass` as the second parameter. In
            // real plugins, you would describe `MyClass` in a Turtle document.
            let mut frame =
                unsafe {
                    self.out_port.write_atom_body(
                        &(0, my_class_urid),
                        &mut self.urids
                    )
                }.unwrap();

            // Pushing a property requires a key, a context, the parameter for the atom type
            // and a mut reference to the URID map.
            frame.push_property::<i32>(a_urid, 0, &42, &mut self.urids).unwrap();
            frame.push_property::<f32>(b_urid, 0, &17.0, &mut self.urids).unwrap();
        }

        // Reading
        let object = unsafe { self.in_port.get_atom_body(&mut self.urids) }.unwrap();
        // We're iterating through the properties. If a property matches our known key,
        // We assert that it has the right value.
        for (header, property_atom) in object.iter() {
            if header.key == a_urid {
                let a: &i32 = unsafe { property_atom.get_body(&mut self.urids) }.unwrap();
                assert_eq!(42, *a);
            } else if header.key == b_urid {
                let b: &f32 = unsafe { property_atom.get_body(&mut self.urids) }.unwrap();
                assert_eq!(17.0, *b);
            } else {
                panic!("Unknown property in object!");
            }
        }
    }
}

// Getting a debug URID map.
let mut debug_map = DebugMap::new();
let mut urids = unsafe {debug_map.create_cached_map()};

// Creating the plugin.
let mut plugin = Plugin {
    in_port: AtomInputPort::new(),
    out_port: AtomOutputPort::new(),
    urids: urids,
};

// Creating the atom space.
let mut atom_space = vec![0u8; 256];
let atom = unsafe { (atom_space.as_mut_ptr() as *mut Atom).as_mut() }.unwrap();
*(atom.mut_size()) = 256 - 8;

// Connecting the ports.
plugin.in_port.connect_port(atom as &Atom);
plugin.out_port.connect_port(atom);

// Calling `run`.
plugin.run();

Structs

ObjectHeader	Header of an object.
PropertyHeader	The header of an object's property.

Traits

ObjectWritingFrame

Extension for WritingFrame and WritingFrameExt for vectors.

Type Definitions

Object

Object- or Map-style atom container.