v1.0.0

What's Changed

This release marks the first stable API. See the API documentation for the full public surface.

The list of changes compared to prior releases is extensive and includes breaking changes; these release notes attempt to summarize significant new features and breaking changes. Please refer to the full changelogs if you need an exhaustive list of changes.

New Features (since 0.18.x)

• Reading and writing Ion no longer requires constructing reader/writer objects; Element::read_one, Element::iter, and Element::encode_as handle the common cases directly.
• Element now provides typed accessors (expect_i64(), expect_string(), etc.) and From/Into conversions for building values without intermediate types.
• Element::location() reports byte offsets and line/column positions for values parsed from text Ion, useful for error reporting and debugging.
• IonData now implements Hash, allowing Element and other Ion data model types to be hashed in a way that is consistent with Ion equivalence.
• The experimental-serde feature adds Serialize/Deserialize implementations that map Rust types to and from Ion, with support for enums, annotations, and symbol-as-string deserialization.

Breaking – Clean up public API for v1.0.0 release (#1024)

• Sign and Coefficient are now in ion_rs::decimal
• TextKind was renamed and moved to ion_rs::TextFormat
• SymbolId, ElementWriter, ElementReader are now behind the experimental-reader-writer feature flag
• All other public types are exported through the crate root ion_rs

Breaking – Remove Eq from Element and fix Struct equality (#1028)

Element and some related types no longer implement Eq (see #1025, #1026). If you need map/set key semantics for Ion data model values, wrap values in IonData (e.g. HashMap<IonData<Element>, V>) which provides Eq and Hash using Ion structural equivalence and provides a total Ord. See IonData documentation for details and warnings.

Additional breaking changes from RC versions

If you adopted an earlier RC, these additional changes may affect you:

• Some experimental writer traits were split or simplified (#732)
• Closure-based container writers were dropped (#741)
• Serde serialization no longer emits type-identifier annotations by default (#751)
• Ion 1.1 support now requires the experimental-ion-1-1 feature flag (#842); warning: the Ion 1.1 implementation is not complete or correct at the time of this release

Additional breaking changes since 0.18.x

• All APIs that previously accepted or returned Vec<Element> now use the Sequence type (#572)
• UInt and Int are now opaque structs with no public fields, conversions from signed types to UInt are fallible, and the crate no longer depends on or exposes BigInt/BigUint although arbitrary precision is still supported (#568, #570, #571, #767)
• The IntAccess trait (as_i64(), as_big_int()) was removed; use Element::expect_i64(), Element::expect_int(), and similar typed accessor methods instead (#595)
• The IonReader and IonWriter traits, ReaderBuilder, TextWriterBuilder, BinaryWriterBuilder, IonDataSource, SymbolTable, Catalog, and all related raw/user/system reader types have been removed from the public API (#591, #602, #727, #729, #749, #752)
• IonError variants now wrap opaque inner types rather than exposing fields directly (#584)
• BigDecimal is no longer re-exported; for BigDecimal interop, enable the bigdecimal feature (#990) or use the components of Decimal to convert to any big decimal representation

Upgrading from 0.18.x

1. Bump your toolchain to Rust 1.82 or newer.
2. Update your Cargo features (see table below).
3. Switch imports from deep module paths (e.g., ion_rs::element::Element) to the root ion_rs::* re-exports (e.g., use ion_rs::Element).
4. Replace Vec<Element> assumptions with Sequence.
5. If you used the old reader/writer APIs, migrate to the stable Element helpers or the experimental Reader/Writer APIs.
6. If you relied on direct numeric internals or infallible signed-to-UInt conversions, update that code.

Feature flag renames

0.18.x	1.0.0
experimental-streaming	experimental-reader-writer
experimental-lazy-reader	experimental-reader-writer
ion-hash	experimental-ion-hash

Migrating read/write code

The main entry points for reading and writing Ion have changed.

• If you used ReaderBuilder or reader.elements(), prefer the stable Element helpers:
  Element::read_one(...), Element::read_all(...), and Element::iter(...).
• If you used TextWriterBuilder or BinaryWriterBuilder to serialize Elements or top-level values, prefer encode_as(...) or encode_to(...) on Element or Sequence.
• If you need streaming or lazy reading/writing, enable experimental-reader-writer and use Reader::new(...) and Writer::new(...) with encoding markers like v1_0::Binary and v1_0::Text.

// 0.18.x – Read values
let mut reader = ReaderBuilder::default().build(input)?;
for element in reader.elements() {
    let element = element?;
    // ...
}

// 0.18.x – Write values
let mut writer = TextWriterBuilder::default().build(&mut output)?;
writer.write_element(&element)?;
writer.flush()?;

// 1.0.0 – Iterate all values
for element in Element::iter(input)? {
    let element = element?;
    // ...
}

// 1.0.0 – Read a single value
let element = Element::read_one(input)?;

// 1.0.0 – Encode to text or binary
let text: String = element.encode_as(v1_0::Text.with_format(TextFormat::Pretty))?;
let bytes: Vec<u8> = element.encode_as(v1_0::Binary)?;

There is no direct one-for-one replacement for ReaderBuilder, IonReader, IonWriter, TextWriterBuilder, or BinaryWriterBuilder. Code using those APIs should move to the stable Element helpers or to the experimental Reader/Writer APIs.

Full Changelogs

• v0.18.1 → v1.0.0
• v1.0.0-rc.12 → v1.0.0