v1.0.0 Release Candidate 1

This release is the first release candidate for ion-rust v1.0. It stabilizes the Element API for reading, writing, and manipulating Ion data. Please open issues for any API concerns that cannot be addressed in a backwards-compatible manner. We still intend to offer features like serde support and stabilize streaming readers and writers in future releases.

Breaking changes from v0.18

Experimental features

Portions of the API that are not ready to be stabilized have been moved into opt-in crate features.

Warning
Types requiring the experimental- features are still subject to breaking changes between minor versions.

This includes:

• The streaming reader (experimental-reader)
• The streaming writer (experimental-writer)
• Ion hash (experimental-ion-hash).

Most inner modules are now private

Nearly all inner modules are now private. In almost all cases, types that were previously imported from paths like ion_rs::types::, ion_rs::element::, etc have been re-exported at the top level.

// Before
use crate::element::Element;
use crate::result::IonResult;
use crate::types::Int;

// After
use crate::{Element, Int, IonResult};

Int and UInt are now opaque structs, not enums

In order to minimize the number of third-party types exposed in the public API, the Int and UInt types are now opaque structs. This prevents users from encountering version mismatches between their own dependency on num-bigint and ion_rs's dependency on num-bigint.

// Before
let int = Int::from(5);

match int {
  Int::I64(i64_value) => {...},
  Int::BigInt(big_int_value) => {...},
};

// After
let int = Int::from(5);

let value: i64 = int.try_into()?;
// or
let value: BigInt = int.into()?;

Into/TryInto have been added for Int/UInt to and from most Rust integer types, including i128/u128.

Vec<Element> has been replaced by Sequence

In order to make implementation changes in the future, APIs that previously returned Vec<Element> now return Sequence, an opaque wrapper around Vec<Element>.

IonError is now non_exhaustive

We may need to add new error variants to IonError in the future, so it is now marked non_exhaustive.

IonError's variants are now opaque structs

In order to improve error handling and enable future implementation changes, each of the error variants is now an opaque struct.

match Element::read_one(...) {
  Ok(element) => {...},
  Err(Decoding(e)) => {...},
  Err(Encoding(e)) => {...},
  Err(Io(e)) => {...},
  Err(IllegalOperation(e)) = {...}
  // ...
}

Methods referring to 3rd party types have been removed

The streaming reader and writer (both now marked experimental) previously supported chrono DateTimes and BigDecimals, which were holdovers from before we implemented Timestamp and Decimal.

The TimestampBuilder API is now simpler

See #588; most method names have remained the same, but the types they return have changed, potentially leading to breakage.

Pull Requests

• [User]Reader wraps SystemReader, not RawReader by @zslayton in #567
• Makes UInt an opaque struct type by @zslayton in #568
• Signed type impls of Into are now fallible by @zslayton in #570
• Makes Int an opaque struct by @zslayton in #571
• Replaces Vec<Element> with Sequence by @zslayton in #572
• Adds Into, Into impl for all ints by @zslayton in #574
• Adds "experimental-reader" feature by @zslayton in #577
• Adds write_value to ElementWriter by @popematt in #579
• Adds an "experimental-writer" feature by @zslayton in #580
• Makes IonError variants wrap opaque types by @zslayton in #584
• Removes IonDataSource and vestigial read() impls by @zslayton in #591
• Adds From<Int> and From` impls for Decimal by @zslayton in #592
• Adds Decimal methods to access the coefficient and exponent by @zslayton in #593
• Removes vestigial dependency on BigDecimal by @zslayton in #594
• Module cleanup, adds Element::expect_*, removes IntAccess by @zslayton in #595
• Clean up TimestampBuilder by @popematt in #588
• ion-hash cleanup by @zslayton in #597
• Adds traits for the lazy reader API to abstract over format by @zslayton in #596
• Makes element and types private by @zslayton in #598
• Removes Coefficient and Sign from the root by @zslayton in #599
• Adds UInt conversions to Rust unsigned int types by @zslayton in #600
• adds changes for shared symbol table support in reader by @desaikd in #578
• Error types now hold a Cow instead of requiring a String by @zslayton in #601
• Removes SymbolTable and Catalog from the public API by @zslayton in #602
• Adds doc comments, Element::write_all_as method by @zslayton in #604
• Result doc comments by @zslayton in #605
• Update readme by @zslayton in #606
• Version bump to 1.0.0-rc.1 by @zslayton in #608

Full Changelog: v0.18.1...v1.0.0-rc.1