Struct Element

Source

pub struct Element { /* private fields */ }

Expand description

An (annotations, value) pair representing an Ion value.

Implementations§

Source §

impl Element

Source

pub fn value(&self) -> &Value

Returns a reference to this Element’s Value.

use ion_rs::{Element, Value};
let element: Element = true.into();
if let Value::Bool(b) = element.value() {
    println!("It was a boolean: {b}");
} else {
    println!("It was something else.");
}

Source

pub fn location(&self) -> &SourceLocation

Returns the source location (row, column) of this element in the original Ion text.

The location metadata is primarily intended for error reporting and debugging purposes, helping applications provide meaningful feedback to users about the source of issues.

§Returns

Some((row, column)) - Position where this element was found in the source text
None - Location information is not available

§Important

Location information is best-effort and may not be available in all cases:

Elements created programmatically won’t have locations
Some parsing scenarios might not preserve location data
Binary Ion data does not contain location information

Do not rely on this metadata for programmatic manipulation of Ion data.

Source

pub fn into_value(self) -> Value

Consumes self and returns this Element’s Value.

Source

pub fn into_annotations(self) -> Annotations

Consumes self and returns this Element’s Annotations.

Source

pub fn into_parts(self) -> (Annotations, Value)

Consumes self and returns this Element’s Annotations and Value.

Source

pub fn try_into_timestamp(self) -> ConversionOperationResult<Element, Timestamp>

Source

pub fn as_text(&self) -> Option<&str>

Source

pub fn expect_text(&self) -> IonResult<&str>

Source

pub fn try_into_text(self) -> ConversionOperationResult<Element, String>

Source

pub fn as_string(&self) -> Option<&str>

Source

pub fn expect_string(&self) -> IonResult<&str>

Source

pub fn try_into_string(self) -> ConversionOperationResult<Element, Str>

Source

pub fn as_symbol(&self) -> Option<&Symbol>

Source

pub fn expect_symbol(&self) -> IonResult<&Symbol>

Source

pub fn try_into_symbol(self) -> ConversionOperationResult<Element, Symbol>

Source

pub fn as_bool(&self) -> Option<bool>

Source

pub fn expect_bool(&self) -> IonResult<bool>

Source

pub fn try_into_bool(self) -> ConversionOperationResult<Element, bool>

Source

pub fn as_lob(&self) -> Option<&[u8]>

Source

pub fn expect_lob(&self) -> IonResult<&[u8]>

Source

pub fn try_into_lob(self) -> ConversionOperationResult<Element, Bytes>

Source

pub fn as_blob(&self) -> Option<&[u8]>

Source

pub fn expect_blob(&self) -> IonResult<&[u8]>

Source

pub fn try_into_blob(self) -> ConversionOperationResult<Element, Bytes>

Source

pub fn as_clob(&self) -> Option<&[u8]>

Source

pub fn expect_clob(&self) -> IonResult<&[u8]>

Source

pub fn try_into_clob(self) -> ConversionOperationResult<Element, Bytes>

Source

pub fn as_sequence(&self) -> Option<&Sequence>

Source

pub fn expect_sequence(&self) -> IonResult<&Sequence>

Source

pub fn try_into_sequence(self) -> ConversionOperationResult<Element, Sequence>

Source

pub fn as_list(&self) -> Option<&Sequence>

Source

pub fn expect_list(&self) -> IonResult<&Sequence>

Source

pub fn try_into_list(self) -> ConversionOperationResult<Element, Sequence>

Source

pub fn as_sexp(&self) -> Option<&Sequence>

Source

pub fn expect_sexp(&self) -> IonResult<&Sequence>

Source

pub fn try_into_sexp(self) -> ConversionOperationResult<Element, Sequence>

Source

pub fn as_struct(&self) -> Option<&Struct>

Source

pub fn expect_struct(&self) -> IonResult<&Struct>

Source

pub fn try_into_struct(self) -> ConversionOperationResult<Element, Struct>

Source

pub fn read_first<A: AsRef<[u8]>>(data: A) -> IonResult<Option<Element>>

Reads a single Ion Element from the provided data source.

If the data source is empty, returns Ok(None). If the data source has at least one value, returns Ok(Some(Element)). If the data source has invalid data, returns Err.

Source

pub fn read_one<A: AsRef<[u8]>>(data: A) -> IonResult<Element>

Reads a single Ion Element from the provided data source. If the input has invalid data or does not contain at exactly one Ion value, returns Err(IonError).

Source

pub fn read_all<A: AsRef<[u8]>>(data: A) -> IonResult<Sequence>

Reads all available Elements from the provided data source.

If the input has valid data, returns Ok(Sequence). If the input has invalid data, returns Err(IonError).

Source

pub fn iter<'a, I: IonInput + 'a>( source: I, ) -> IonResult<impl Iterator<Item = IonResult<Element>> + 'a>

Returns an iterator over the Elements in the provided Ion data source. If the data source cannot be read or contains invalid Ion data, this method will return an Err.

Source

pub fn encode_as<E: Encoding, C: Into<WriteConfig<E>>>( &self, config: C, ) -> IonResult<E::Output>

Encodes this element as an Ion stream with itself as the only top-level value. If the stream’s encoding is binary Ion, returns a Vec<u8> containing the encoded bytes. If the stream’s encoding is text Ion, returns a String containing the UTF-8 encoded text.

use ion_rs::Element;
use ion_rs::v1_0::Binary;

let ion_data = r#"{foo: "hello", bar: quux::5, baz: null, bar: false}"#;
let element_before = Element::read_one(ion_data)?;

// Encode the element as a binary Ion stream
let ion_bytes: Vec<u8> = element_before.encode_as(Binary)?;
// Read the element back from the binary stream
let element_after = Element::read_one(ion_bytes)?;

// Confirm that the value we read back is identical to the one we serialized
assert_eq!(element_before, element_after);

Source

pub fn encode_to<E: Encoding, C: Into<WriteConfig<E>>, W: Write>( &self, output: W, config: C, ) -> IonResult<W>

Encodes this element as an Ion stream with itself as the only top-level value. The encoded bytes are written to the provided io::Write implementation.

use ion_rs::Element;
use ion_rs::v1_0::Binary;

let ion_data = r#"{foo: "hello", bar: quux::5, baz: null, bar: false}"#;
let element_before = Element::read_one(ion_data)?;

// Encode the element as a binary Ion stream. The bytes will be written to the provided
//  Vec<u8>, and the Vec<u8> will be returned when encoding is complete.
let ion_bytes: Vec<u8> = element_before.encode_to(Vec::new(), Binary)?;
// Read the element back from the binary stream
let element_after = Element::read_one(ion_bytes)?;

// Confirm that the value we read back is identical to the one we serialized
assert_eq!(element_before, element_after);