Crate ion_rs

Reading and writing Elements

The Element API offers a convenient way to read and write Ion data when its exact shape is not known ahead of time.

Each Element represents an (annotations, value) pair. If the value is a container (an Ion list, sexp, or struct), then it will contain its own collection of Elements. Elements can be nested to arbitrary depth.

Constructing an Element

From text Ion

The Element::read_one method will parse the provided data and requires that it contain exactly one Ion value.

use ion_rs::element::Element;
use ion_rs::IonType;
let ion_data = "[1, 2, 3]";
let element = Element::read_one(ion_data)?;
assert_eq!(element.ion_type(), IonType::List);

Element::read_all will read any number of Ion values and return them as a Vec<Element>.

Element::read_first will read the first Ion value without requiring that the stream have exactly one value.

From a Rust value

Most Rust primitives implement Into<Element>, allowing them to be converted to an Ion Element directly.

use ion_rs::element::Element;

let int: Element = 5.into();
assert_eq!(Element::read_one("5")?, int);

let boolean: Element = true.into();
assert_eq!(Element::read_one("true")?, boolean);

let string: Element = "hello".into();
assert_eq!(Element::read_one("\"hello\"")?, string);

let ion_version_marker: &[u8] = &[0xE0, 0x01, 0x00, 0xEA]; // Ion 1.0 version marker
let blob: Element = ion_version_marker.into();
assert_eq!(Element::read_one("{{4AEA6g==}}")?, blob);

Using macros

When constructing a container Element, you can use the ion_list!, ion_sexp!, and ion_struct! macros.

use ion_rs::element::Element;
use ion_rs::{ion_list, ion_sexp, ion_struct};

// Variable names are allowed
let six = 6i64;
let list: Element = ion_list! [true, six, "foo"].into();
assert_eq!(Element::read_one("[true, 6, \"foo\"]")?, list);

// Nested use of macros is allowed
// Notice that ion_sexp! uses ()s without commas
let sexp: Element = ion_sexp! (true six ion_list!["foo", "bar"]).into();
assert_eq!(Element::read_one("(true 6 [\"foo\", \"bar\"])")?, sexp);

let field_name = "bar";
let struct_: Element = ion_struct! {
  "foo": six,
  field_name: false
}.into();
assert_eq!(Element::read_one("{foo: 6, bar: false}")?, struct_);

From a stream

use ion_rs::element::reader::ElementReader;
use ion_rs::element::Element;
use ion_rs::ReaderBuilder;
use std::fs::File;
let ion_file = File::open("/foo/bar/baz.ion").unwrap();
let mut reader = ReaderBuilder::default().build(ion_file)?;
// A simple pretty-printer
for element in reader.elements() {
    println!("{}", element?)
}

Traversing an Element

use ion_rs::IonResult;
use ion_rs::element::{Element, IntoAnnotatedElement, Value};
use ion_rs::{ion_list, ion_struct};
let element: Element = ion_struct! {
  "foo": "hello",
  "bar": true,
  "baz": ion_list! [4, 5, 6]
}
.into();

if let Value::Struct(s) = element.value() {
    if let Some(Value::List(l)) = s.get("baz").map(|b| b.value()) {
        for (index, element) in l.elements().enumerate() {
            println!("{}. {}", index + 1, element);
            // 1) 4
            // 2) 5
            // 3) 6
        }
    }
}

Writing an Element to an io::Write

use ion_rs::IonResult;
use ion_rs::element::writer::ElementWriter;
use ion_rs::element::{Element, IntoAnnotatedElement, Value};
use ion_rs::{ion_list, ion_struct, IonWriter, TextWriterBuilder};
let element: Element = ion_struct! {
  "foo": "hello",
  "bar": true,
  "baz": ion_list! [4, 5, 6]
}
.into();

let mut buffer: Vec<u8> = Vec::new();
let mut writer = TextWriterBuilder::default().build(&mut buffer)?;
writer.write_element(&element)?;
writer.flush()?;
assert_eq!(
    "{foo: \"hello\", bar: true, baz: [4, 5, 6]}".as_bytes(),
    writer.output().as_slice()
);

Re-exports

pub use types::Decimal;

pub use types::Int;

pub use types::IonType;

pub use types::Str;

pub use types::Symbol;

pub use types::Timestamp;

pub use binary::binary_writer::BinaryWriter;

pub use binary::binary_writer::BinaryWriterBuilder;

pub use binary::raw_binary_writer::RawBinaryWriter;

pub use raw_reader::RawReader;

pub use raw_reader::RawStreamItem;

pub use reader::Reader;

pub use reader::ReaderBuilder;

pub use reader::StreamItem;

pub use reader::UserReader;

pub use text::raw_text_writer::RawTextWriter;

pub use text::raw_text_writer::RawTextWriterBuilder;

pub use result::IonError;

pub use result::IonResult;

Modules

binary

This module provides the necessary structures and logic to read values from a binary Ion data stream.

constants

data_source

element

Provides a dynamically typed, materialized representation of an Ion value.

external

Re-exports of third party dependencies that are part of our public API.

raw_reader

reader

result

text

types

This module provides an implementation of the data types described by the Ion Data Model section of the Ion 1.0 spec.

Macros

ion_list

Constructs a list Element with the specified child values.

ion_sexp

Constructs an s-expression Element with the specified child values.

ion_struct

Constructs an struct Element with the specified fields.

Structs

BlockingRawReader

The BlockingRawReader wraps a non-blocking RawReader that implements the BufferedReader trait, providing a blocking RawReader.

IonData

A wrapper for lifting Ion compatible data into using Ion-oriented comparisons (versus the Rust value semantics). This enables the default semantics to be what a Rust user expects for native values, but allows a user to opt-in to Ion’s structural equivalence/order.

SymbolRef

A reference to a fully resolved symbol. Like Symbol (a fully resolved symbol with a static lifetime), a SymbolRef may have known or undefined text (i.e. $0).

SymbolTable

Stores mappings from Symbol IDs to text and vice-versa.

SystemReader

A streaming Ion reader that:

TextWriter

An application-level text Ion writer. This writer manages a symbol table and so can convert symbol IDs to their corresponding text. However, unlike the BinaryWriter, it is capable of writing text to the output stream without first adding it to the symbol table.

TextWriterBuilder

Enums

RawSymbolToken

A symbol token encountered in a text or binary Ion stream. RawSymbolTokens do not store import source information for the token encountered. Similarly, a RawSymbolToken cannot store both a symbol ID and text, which means that it is not suitable for representing a resolved symbol.

RawSymbolTokenRef

Like RawSymbolToken, but the Text variant holds a borrowed reference instead of a String.

SystemStreamItem

Raw stream elements that a SystemReader may encounter.

Traits

IonDataSource

Optimized read operations for parsing Ion.

IonReader

This trait captures the format-agnostic parser functionality needed to navigate within an Ion stream and read the values encountered into native Rust data types.

IonWriter

This trait captures the format-agnostic encoding functionality needed to write native Rust types to a stream as Ion values.

Type Aliases

BlockingRawBinaryReader

BlockingRawTextReader