Struct ion_c_sys::writer::IonCWriterHandle

pub struct IonCWriterHandle<'a> { /* fields omitted */ }

Wrapper over hWRITER to make it easier to writers in IonC correctly.

Specifically supports the Drop trait to make sure ion_writer_close is run. Access to the underlying hWRITER pointer is done by de-referencing the handle.

See also IonCValueWriter for details

Usage

// a buffer to write to
let mut buf = vec![0; 12];

// borrow the buffer and do some writing!
let len = {
    // write in binary
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut(), WriterMode::Binary)?;

    // write something
    writer.write_i64(4)?;

    // finish up the writing
    writer.finish()?

    // handle implements Drop, so we're good to go!
};

assert_eq!(b"\xE0\x01\x00\xEA\x21\x04", &buf[0..len]);

Implementations

impl<'a> IonCWriterHandle<'a>

pub fn new_buf(
    buf: &'a mut [u8],
    options: &mut ION_WRITER_OPTIONS
) -> Result<Self, IonCError>

Construct a writer to a given mutable slice with options.

pub fn new_buf_mode(
    buf: &'a mut [u8],
    mode: WriterMode
) -> Result<Self, IonCError>

Construct a text/binary mode writer with otherwise default options.

pub fn field<'b, 'c>(
    &'b mut self,
    field: &'c str
) -> IonCAnnotationsFieldWriterContext<'a, 'b, 'c>

Returns a lifetime safe writing context for a field.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    writer.start_container(ION_TYPE_STRUCT)?;
    {
        writer.field("name").write_string("kumo")?;
    }
    writer.finish_container()?;
    writer.finish()?
};
assert_eq!(b"\xE0\x01\x00\xEA\xD6\x84\x84kumo", &buf[0..len]);

pub fn annotations<'b, 'c>(
    &'b mut self,
    annotations: &'c [&'c str]
) -> IonCAnnotationsFieldWriterContext<'a, 'b, 'c>

Returns a lifetime safe writing context for annotations.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Text)?;
    writer.annotations(&["a", "b", "c"]).start_container(ION_TYPE_STRUCT)?;
    {
        writer.field("name").annotations(&["def"]).write_string("kumo")?;
        writer.annotations(&["ghi"]).field("type").write_symbol("dog")?;
    }
    writer.finish_container()?;
    writer.finish()?
};
assert_eq!("a::b::c::{name:def::\"kumo\",type:ghi::dog}", str::from_utf8(&buf[0..len])?);

pub fn finish(&mut self) -> IonCResult<usize>

Trait Implementations

impl<'_> Deref for IonCWriterHandle<'_>

type Target = hWRITER

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'_> DerefMut for IonCWriterHandle<'_>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'_> Drop for IonCWriterHandle<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl<'_> IonCValueWriter for IonCWriterHandle<'_>

fn write_null(&mut self, tid: ION_TYPE) -> IonCResult<()>

Writes a null value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    writer.write_null(ION_TYPE_INT)?;
    writer.finish()?
};
assert_eq!(b"\xE0\x01\x00\xEA\x2F", &buf[0..len]);

fn write_bool(&mut self, value: bool) -> IonCResult<()>

Writes a bool value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Text)?;
    writer.write_bool(true)?;
    writer.write_bool(false)?;
    writer.finish()?
};
assert_eq!(b"true false", &buf[0..len]);

fn write_i64(&mut self, value: i64) -> IonCResult<()>

Writes an int value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    writer.write_i64(-16)?;
    writer.finish()?
};
assert_eq!(b"\xE0\x01\x00\xEA\x31\x10", &buf[0..len]);

fn write_bigint(&mut self, value: &BigInt) -> IonCResult<()>

Writes an int value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    let value = BigInt::parse_bytes(b"987654321987654321987654321", 10).unwrap();
    writer.write_bigint(&value)?;
    writer.finish()?
};
assert_eq!(
    b"\xE0\x01\x00\xEA\x2C\x03\x30\xF7\xF0\x14\x03\xF9\x4E\xDB\x18\x12\xB1",
    &buf[0..len]);

fn write_f64(&mut self, value: f64) -> IonCResult<()>

Writes a float value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    writer.write_f64(3.0)?;
    writer.finish()?
};
assert_eq!(b"\xE0\x01\x00\xEA\x48\x40\x08\x00\x00\x00\x00\x00\x00", &buf[0..len]);

fn write_bigdecimal(&mut self, value: &BigDecimal) -> IonCResult<()>

Writes a decimal value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    let value = BigDecimal::parse_bytes(b"1.1", 10).unwrap();
    writer.write_bigdecimal(&value)?;
    writer.finish()?
};
assert_eq!(
    b"\xE0\x01\x00\xEA\x52\xC1\x0B",
    &buf[0..len]);

fn write_datetime(&mut self, value: &IonDateTime) -> IonCResult<()>

Writes a timestamp value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Text)?;
    let dt = DateTime::parse_from_rfc3339("2020-01-02T12:34:00.123Z").unwrap();

    // write the date time with microsecond precision and an unknown offset
    let ion_dt = IonDateTime::try_new(dt, Fractional(Digits(6)), UnknownOffset)?;
    writer.write_datetime(&ion_dt)?;
    writer.finish()?
};
assert_eq!(
    b"2020-01-02T12:34:00.123000-00:00",
    &buf[0..len]);

fn write_symbol(&mut self, value: &str) -> IonCResult<()>

Writes a symbol value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Text)?;
    writer.write_symbol("🍥")?;
    writer.finish()?
};
assert_eq!(b"'\xF0\x9F\x8D\xA5'", &buf[0..len]);

fn write_string(&mut self, value: &str) -> IonCResult<()>

Writes a string value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    writer.write_string("🐡")?;
    writer.finish()?
};
assert_eq!(b"\xE0\x01\x00\xEA\x84\xF0\x9F\x90\xA1", &buf[0..len]);

fn write_clob(&mut self, value: &[u8]) -> IonCResult<()>

Writes a clob value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    writer.write_clob("🐡".as_bytes())?;
    writer.finish()?
};
assert_eq!(b"\xE0\x01\x00\xEA\x94\xF0\x9F\x90\xA1", &buf[0..len]);

fn write_blob(&mut self, value: &[u8]) -> IonCResult<()>

Writes a blob value.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Text)?;
    writer.write_blob("🍥".as_bytes())?;
    writer.finish()?
};
assert_eq!(b"{{8J+NpQ==}}", &buf[0..len]);

fn start_container(&mut self, tid: ION_TYPE) -> IonCResult<()>

Starts a container.

Usage

let mut buf = vec![0; 128];
let len = {
    let mut writer = IonCWriterHandle::new_buf_mode(buf.as_mut_slice(), WriterMode::Binary)?;
    writer.start_container(ION_TYPE_LIST)?;
    writer.finish_container()?;
    writer.finish()?
};
assert_eq!(b"\xE0\x01\x00\xEA\xB0", &buf[0..len]);

fn finish_container(&mut self) -> IonCResult<()>

Finishes a container.