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, 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 Sequence.

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;

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, 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;
use std::fs::File;
let ion_file = File::open("/foo/bar/baz.ion").unwrap();
// A simple pretty-printer
for element in Element::iter(ion_file)? {
    println!("{}", element?)
}

Traversing an Element

use ion_rs::{Element, Value, 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
        }
    }
}

Modules

decimal

Types for working with Ion decimal coefficients.

v1_0

Macros

ion_list

Constructs a list Element with the specified child values.

ion_seq

Constructs a Sequence 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

Annotations

An ordered sequence of symbols that convey additional, application-specific information about their associated Ion value.

Blob

An in-memory representation of an Ion blob.

Bytes

An owned, immutable byte array.

Clob

An in-memory representation of an Ion clob.

ConversionOperationError

Represents a mismatch during conversion between the expected type and the actual value’s type; Holds the original value that was not able to be converted.

Decimal

An arbitrary-precision Decimal type with a distinct representation of negative zero (-0).

Element

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

Int

A signed integer of arbitrary size.

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.

List

An in-memory representation of an Ion list.

Null

An in-memory representation of a typed null.

SExp

An in-memory representation of an Ion s-expression

Sequence

An iterable, addressable series of Ion Elements.

SequenceBuilder

Constructs Sequence, List, and SExp values incrementally.

SourceLocation

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

Str

An owned, immutable in-memory representation of an Ion string.

Struct

An in-memory representation of an Ion Struct

StructBuilder

Constructs Struct values incrementally.

Symbol

The text of a fully resolved field name, annotation, or symbol value. If the symbol has known text (that is: the symbol is not $0), it will be stored as either a String or a shared reference to text in a symbol table.

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).

Timestamp

Represents a point in time to a specified degree of precision. Unlike chrono’s NaiveDateTime and DateTime, a Timestamp has variable precision ranging from a year to fractional seconds of an arbitrary unit.

UInt

Represents an unsigned integer of any size.

WriteConfig

Writer configuration to provide format and Ion version details to writer through encoding This will be used to create a writer without specifying which writer methods to use

Enums

IonError

Represents the different types of high-level failures that might occur when reading Ion data.

IonType

Represents the Ion data type of a given value. To learn more about each data type, read the Ion Data Model section of the spec.

TextFormat

Whether or not the text spacing is generous/human-friendly or something more compact.

TimestampPrecision

Indicates the most precise time unit that has been specified in the accompanying Timestamp.

Value

Variants for all values within an Element.

Traits

IntoAnnotatedElement

Allows types that can be converted into an Ion Value to also specify annotations, producing an Element.

IntoAnnotations

Defines conversion into Annotations.

IonInput

Types that can be used as a source of Ion data.

Type Aliases

ConversionOperationResult

IonResult

A unified Result type representing the outcome of method calls that may fail.