Struct ion_c_sys::reader::IonCReaderHandle

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

Wrapper over hREADER to make it easier to use readers in IonC correctly.

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

Usage

let mut reader = IonCReaderHandle::try_from(b"\xE0\x01\x00\xEA\x85hello".as_ref())?;
let tid = reader.next()?;
assert_eq!(ION_TYPE_STRING, tid);
// reader_handle implements Drop, so we're good to go!

Implementations

impl<'a> IonCReaderHandle<'a>

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

Constructs a reader handle from a byte slice and given options.

pub fn next(&mut self) -> IonCResult<ION_TYPE>

Advances the reader to the next value and returns the type.

pub fn get_type(&self) -> IonCResult<ION_TYPE>

Returns the type of the current position.

Usage

let mut reader = IonCReaderHandle::try_from("'''hello!'''")?;
assert_eq!(ION_TYPE_NONE, reader.get_type()?);
assert_eq!(ION_TYPE_STRING, reader.next()?);
assert_eq!(ION_TYPE_STRING, reader.get_type()?);
assert_eq!(ION_TYPE_EOF, reader.next()?);
assert_eq!(ION_TYPE_EOF, reader.get_type()?);

pub fn step_in(&mut self) -> IonCResult<()>

Steps in to the current container.

pub fn step_out(&mut self) -> IonCResult<()>

Steps out of the current container.

pub fn depth(&self) -> IonCResult<i32>

Returns the current container depth.

Usage

let mut reader = IonCReaderHandle::try_from("[[]]")?;
assert_eq!(ION_TYPE_LIST, reader.next()?);
reader.step_in()?;
assert_eq!(1, reader.depth()?);
assert_eq!(ION_TYPE_LIST, reader.next()?);
reader.step_in()?;
assert_eq!(2, reader.depth()?);

pub fn is_null(&self) -> IonCResult<bool>

Returns if the reader is positioned on a null value.

Usage

let mut reader = IonCReaderHandle::try_from("null.int 4")?;
assert_eq!(ION_TYPE_INT, reader.next()?);
assert!(reader.is_null()?);
assert_eq!(ION_TYPE_INT, reader.next()?);
assert!(!reader.is_null()?);

pub fn is_in_struct(&self) -> IonCResult<bool>

Returns if the reader is positioned within a struct value.

Usage

let mut reader = IonCReaderHandle::try_from("{}")?;
assert_eq!(ION_TYPE_STRUCT, reader.next()?);
assert!(!reader.is_in_struct()?);
reader.step_in()?;
assert!(reader.is_in_struct()?);

pub fn get_field_name(&mut self) -> IonCResult<StrSliceRef<'_>>

Returns the field name if the reader positioned within a structure.

Usage

let mut reader = IonCReaderHandle::try_from("{a:5}")?;
assert_eq!(ION_TYPE_STRUCT, reader.next()?);
reader.step_in()?;
assert_eq!(ION_TYPE_INT, reader.next()?);
assert_eq!("a", reader.get_field_name()?.as_str());

pub fn get_annotations(&mut self) -> IonCResult<StrSlicesRef<'_>>

Retrieves the annotations associated with the current value.

Note that this allocates a vector on the heap for the IonCStringRef instances. If this is not desired, use the low-level annotation functions.

Usage

let mut reader = IonCReaderHandle::try_from("ab::cde::fghi::5")?;
assert_eq!(ION_TYPE_INT, reader.next()?);
let annotations = reader.get_annotations()?;
assert_eq!(
    vec!["ab", "cde", "fghi"].as_slice(),
    annotations.as_ref()
);

pub fn read_bool(&mut self) -> IonCResult<bool>

Reads a bool value from the reader.

Usage

let mut reader = IonCReaderHandle::try_from("true")?;
assert_eq!(ION_TYPE_BOOL, reader.next()?);
assert!(reader.read_bool()?);

pub fn read_i64(&mut self) -> IonCResult<i64>

Reads an int value from the reader.

Usage

let mut reader = IonCReaderHandle::try_from("42")?;
assert_eq!(ION_TYPE_INT, reader.next()?);
assert_eq!(42, reader.read_i64()?);

pub fn read_bigint(&mut self) -> IonCResult<BigInt>

Reads an int value from the reader as a BigInt.

Usage

let mut reader = IonCReaderHandle::try_from("0x5195a4b154400e07dee3a7378c403b2d5dd6dd58735")?;
assert_eq!(ION_TYPE_INT, reader.next()?);
assert_eq!(
  BigInt::parse_bytes(b"1907775120294590714755986204580814176547217067050805", 10).unwrap(),
  reader.read_bigint()?
);

pub fn read_f64(&mut self) -> IonCResult<f64>

Reads a float value from the reader.

Usage

let mut reader = IonCReaderHandle::try_from("3.0e0")?;
assert_eq!(ION_TYPE_FLOAT, reader.next()?);
assert_eq!(3.0, reader.read_f64()?);

pub fn read_bigdecimal(&mut self) -> IonCResult<BigDecimal>

Reads a bigdecimal value from the reader.

Usage

let mut reader = IonCReaderHandle::try_from("3.0")?;
assert_eq!(ION_TYPE_DECIMAL, reader.next()?);
let value = BigDecimal::parse_bytes(b"30E-1", 10).unwrap();
assert_eq!(value, reader.read_bigdecimal()?);

pub fn read_datetime(&mut self) -> IonCResult<IonDateTime>

Reads a timestamp value from the reader.

Usage

let mut reader = IonCReaderHandle::try_from("2020-10-10T12:34:45.123-00:00")?;
assert_eq!(ION_TYPE_TIMESTAMP, reader.next()?);
let ion_dt = reader.read_datetime()?;

// the point in time should be the same
let expected_dt = DateTime::parse_from_rfc3339("2020-10-10T12:34:45.123Z").unwrap();
assert_eq!(&expected_dt, ion_dt.as_datetime());

// precision should be millisecond level
if let Fractional(Digits(digits)) = ion_dt.precision() {
    assert_eq!(3, *digits);
} else {
    assert!(false, "Expected digits precision!");
}

// we should have an unknown offset
assert_eq!(UnknownOffset, ion_dt.offset_kind());

pub fn read_string(&mut self) -> IonCResult<StrSliceRef<'_>>

Reads a string/symbol value from the reader.

Usage

let mut reader = IonCReaderHandle::try_from("\"🦄\" '✨'")?;
assert_eq!(ION_TYPE_STRING, reader.next()?);
assert_eq!("🦄", reader.read_string()?.as_str());
assert_eq!(ION_TYPE_SYMBOL, reader.next()?);
assert_eq!("✨", reader.read_string()?.as_str());

pub fn read_bytes(&mut self) -> IonCResult<Vec<u8>>

Reads a clob/blob value from the reader.

This method implements a vector on the heap to store a copy of the LOB. If this is not desired, use the low-level length and read methods directly.

Usage

let mut reader = IonCReaderHandle::try_from("{{\"hello\"}} {{d29ybGQ=}}")?;
assert_eq!(ION_TYPE_CLOB, reader.next()?);
assert_eq!(b"hello", reader.read_bytes()?.as_slice());
assert_eq!(ION_TYPE_BLOB, reader.next()?);
assert_eq!(b"world", reader.read_bytes()?.as_slice());

Trait Implementations

impl<'_> Deref for IonCReaderHandle<'_>

type Target = hREADER

The resulting type after dereferencing.

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

Dereferences the value.

impl<'_> DerefMut for IonCReaderHandle<'_>

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

Mutably dereferences the value.

impl<'_> Drop for IonCReaderHandle<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a> TryFrom<&'a [u8]> for IonCReaderHandle<'a>

type Error = IonCError

The type returned in the event of a conversion error.

fn try_from(src: &'a [u8]) -> Result<Self, Self::Error>

Constructs a reader from a byte slice with the default options.

impl<'a> TryFrom<&'a str> for IonCReaderHandle<'a>

type Error = IonCError

The type returned in the event of a conversion error.

fn try_from(src: &'a str) -> Result<Self, Self::Error>

Constructs a reader from a str slice with the default options.