Skip to content

amazon-ion/ion-rust

Folders and files

NameName
Last commit message
Last commit date
Nov 8, 2024
Jan 16, 2025
Dec 2, 2024
Mar 13, 2023
Jan 22, 2025
Jan 22, 2025
Jan 9, 2025
May 1, 2023
Sep 2, 2022
Mar 13, 2023
May 1, 2023
Dec 14, 2018
Jan 25, 2023
Jan 16, 2025
Dec 14, 2018
Apr 15, 2021
May 24, 2024
Apr 29, 2023

Amazon Ion Rust

Crate Docs License CI Build codecov

A Rust implementation of the Amazon Ion data format.

Example

For more information, please see the documentation.

use crate::{ion_seq, Element, IonResult, Timestamp};

fn main() -> IonResult<()> {
    // Read a single value from a string/slice/Vec
    let element = Element::read_one("\"Hello, world!\"")?;
    let text = element.expect_string()?;
    assert_eq!(text, "Hello, world!");

    // Read a series of values from a string/slice/Vec
    let elements = Element::read_all("1 2 3")?;
    let mut sum = 0;
    for element in elements {
        sum += element.expect_i64()?;
    }
    assert_eq!(sum, 6);

    // Iterate over values in a file
    let ion_file = std::fs::File::open("/foo/bar/baz.ion").unwrap();
    for element in Element::iter(ion_file)? {
        println!("{}", element?)
    }

    // Construct a sequence of Ion elements from Rust values
    let values = ion_seq!(
        "foo",
        Timestamp::with_ymd(2016, 5, 11).build()?,
        3.1416f64,
        true
    );

    // Write values to a String using generously-spaced text
    let text_ion: String = values.encode_as(v1_0::Text.with_format(TextFormat::Pretty))?;
    assert_eq!(values, Element::read_all(text_ion)?);

    // Write values to a buffer in compact binary
    let binary_buffer: Vec<u8> = values.encode_as(v1_0::Binary)?;
    assert_eq!(values, Element::read_all(binary_buffer)?);

    Ok(())
}

Experimental features

The ion_rs library has a number of features that users can opt into. While the following features are complete and well-tested, their APIs are not stable and are subject to change without notice between minor versions of the library.

  1. experimental-reader-writer, a streaming reader and writer API.
  2. experimental-tooling-apis, APIs for accessing the encoding-level details of the stream.
  3. experimental-serde, a serde serializer and deserializer.
  4. experimental-ion-hash, an implementation of Ion Hash.

Development

This project uses a submodule to pull in Ion Tests and Ion Hash Tests. The easiest way to pull everything in is to clone the repository recursively:

$ git clone --recursive https://github.com/amazon-ion/ion-rust

You can also initialize the submodules as follows:

$ git submodule update --init --recursive

Building the project:

$ cargo build --all-features

Running all tests for ion-rust:

$ cargo test --all-features

Our continuous integration builds/tests, checks formatting, builds all API docs including private, and clippy linting, you will likely want to check most of these to avoid having to wait until the CI finds it:

$ ./clean-rebuild.sh