29 releases (17 breaking)
1.0.0-rc.7 | Aug 23, 2024 |
---|---|
1.0.0-rc.6 | Jun 6, 2024 |
1.0.0-rc.4 | May 31, 2024 |
1.0.0-rc.3 | Feb 26, 2024 |
0.1.2 | Oct 19, 2020 |
#82 in Encoding
11,811 downloads per month
Used in 16 crates
(14 directly)
2MB
44K
SLoC
Amazon Ion Rust
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.
experimental-reader-writer
, a streaming reader and writer API.experimental-tooling-apis
, APIs for accessing the encoding-level details of the stream.experimental-serde
, aserde
serializer and deserializer.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
Dependencies
~2.9–9MB
~77K SLoC