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

v0.18.1

What's Changed

• Hotfix v0.18.1: Exposes raw bytes accessors in the SystemReader by @zslayton in #566

Full Changelog: v0.18.0...v0.18.1

v0.18.0

What's Changed

• Fixes incorrect handling of SID 0 as symbol text by @popematt in #515
• Fix rustdoc by @almann in #518
• Reduce 'pretty' indentation 4=>2 by @jobarr-amzn in #523
• Adds Lazy Evaluation Support by @almann in #522
• Adds IonData wrapper that uses Ion equivalence for equality by @popematt in #517
• Refactors Value, TextValue, and IonType enum variants to have consistent order by @popematt in #525
• Refactors Annotations conversion trait implementations by @almann in #528
• Adds CI matrix for crate features by @almann in #533
• Fixes a warning for ion-hash by @almann in #535
• Fixes clippy warnings by @almann in #539
• Updates code coverage CI to stable by @almann in #538
• Updates README by @almann in #537
• Move the Ion value types to the types module by @popematt in #543
• Clean up imports, newlines, and doc code by @popematt in #545
• Disable the "oldtime" feature of chrono by @tommy in #548
• Adds experimental tokens module by @almann in #540
• Adds ReaderTokenStream by @almann in #541
• updates Ord implementation of Timestamp by @desaikd in #553
• Adds TokenStreamReader by @almann in #542
• Fix multiple blocking binary reader issues by @nirosys in #552
• Introduces a lazy binary reader by @zslayton in #546
• Version bump to v0.18.0 by @zslayton in #561
• Fix conversion to Decimal from f64 for values greater than +/- i64::MAX and smaller than +/- 1e-15 by @jpschorr in #562
• Add ElementStreamWriter, an IonWriter that outputs Elements by @jpschorr in #563

New Contributors

• @tommy made their first contribution in #548
• @jpschorr made their first contribution in #562

Full Changelog: v0.17.0...v0.18.0

v0.17.0

What's Changed

• Make Element implement Send by @zslayton in #497
• Implements IntoIterator for container Elements by @zslayton in #499
• Custom string type by @zslayton in #501
• Makes List and SExp thin wrappers around Sequence by @zslayton in #502
• Makes Value::List and Value::SExp wrap Sequence by @zslayton in #505
• Introduces Bytes, Blob, and Clob wrapper types by @zslayton in #506
• Handle incomplete errors when parsing escaped string sequences by @nirosys in #495
• Add BlockingRawReader as a blocking wrapper around non-blocking text and binary readers by @nirosys in #493
• Introduces an Annotations type by @zslayton in #508
• Remove map_ APIs and replace them with read_ by @nirosys in #509
• Adds conversion from byte literals to Bytes by @popematt in #510
• Adds Copy/Clone derivation to StreamItem by @almann in #513
• Version bump to v0.17.0 by @zslayton in #514

Full Changelog: v0.16.0...v0.17.0

v0.16.0

What's Changed

• Introduced builder APIs for List, SExp, and Struct
• Introduced ion_list!, ion_sexp!, and ion_struct! macros for initializing container Elements.
• Into<Element> implementations for Rust types that map intuitively to Ion types.
• Modernized the ElementReader trait so all IonReader implementations can read the current value(s) as an Element.
• Modernized the ElementWriter trait so all IonWriter implementations can write an Element.
• Adds accessor methods for the various time unit fields in a Timestamp
• ion-hash is now a feature of ion-rs instead of an independent crate, eliminating downstream dependency version mismatches
• Removed the ion-c-sys crate
• Removed the little-used value::borrowed module and the IonElement trait
• Bugfixes for the text reader

PRs

• Format Agnostic RawReader Pass by @nirosys in #458
• Removes ion-c-sys by @popematt in #457
• Update all references to the GitHub organization: amzn -> amazon-ion by @popematt in #462
• Fix permissions for clippy-check by @nirosys in #463
• Fix transposed string formats for RawStreamItem by @popematt in #464
• Fix validated span calculation bug which could result in invalid UTF-8 sequences. by @nirosys in #466
• Dependency updates by @zslayton in #469
• Clippy suggestions by @zslayton in #470
• Removes uses of deprecated methods from chrono by @zslayton in #471
• Allows empty one-line comments. by @zslayton in #474
• Fix silent test failures caused by unimplemented features by @popematt in #473
• Removes IonElement trait, ElementRef impl by @zslayton in #475
• Make Display for Decimal more human-friendly by @jobarr-amzn in #477
• Makes ion-hash a feature of ion-rs by @popematt in #478
• Adds builder API and macros for Element by @zslayton in #479
• Suppresses invalid clippy warning by @zslayton in #483
• Update rstest syntax by @jobarr-amzn in #481
• Element reader by @zslayton in #485
• Mass renaming, container Display impls by @zslayton in #486
• Modernizes the ElementWriter trait by @zslayton in #487
• Address boundary handling issues in non-blocking raw text reader, and its blocking wrapper by @nirosys in #488
• adds accessor methods for Timestamp by @desaikd in #482
• Adds basic crate-level documentation by @zslayton in #490
• Remove crate::element::owned module by @zslayton in #491
• Version bump to v0.16.0 by @zslayton in #492

Full Changelog: v0.15.0...v0.16.0

v0.15.0

What's Changed

• Enables GATs iteration in the Element API by @zslayton in #442
• Return to stable Rust now that 1.65 is released by @jobarr-amzn in #446
• adds implementation of Catalog by @desaikd in #448
• Stop impl Display for Element from panicking on typed nulls by @popematt in #451
• Implement blocking RawTextReader wrapper by @nirosys in #440
• Fix bugs in timestamp by @popematt in #452
• Completes impl of Ion Hash algorithm and bumps to latest ion-rust version by @popematt in #453
• Cleans up broken links in docs by @popematt in #455
• Version bump to ion-rs v0.15.0; ion-hash v0.1.0 by @popematt in #456

New Contributors

• @popematt made their first contribution in #451

Full Changelog: v0.14.0...v0.15.0

v0.14.0

Note: This release does not include a new version of ion-hash, which depends on ion-rust v0.13.0. A new version of ion-hash will be available with the next release of ion-rust. If you depend on ion-hash, please wait to upgrade.

What's Changed

• Use Reader instead of chrono to parse Timestamp by @PlasmaIntec in #409
• Removes dependency on ion-c-sys by @zslayton in #418
• Prefixes trait names with Ion, renames impls by @zslayton in #419
• Add non-blocking RawTextReader & TextBuffer by @nirosys in #416
• Updates symbol logic in the Element APIs by @zslayton in #426
• changes Struct and StructRef implementations to consider field order by @desaikd in #429
• Collapse Magnitude with UInteger by @rmarrowstone in #431
• Removes the separate no_text_values collection in Struct by @zslayton in #430
• Implement Display for Timestamp by @rmarrowstone in #435
• Add a 'lines' text writer format by @jobarr-amzn in #415
• changes borrowed module to use SymbolRef and simplifies StructRef by @desaikd in #436
• adds implementaion of Display for UInteger and Integer by @desaikd in #439
• adds implementation of ElementStreamReader by @desaikd in #432
• Version bump to v0.14.0 by @zslayton in #445

New Contributors

• @PlasmaIntec made their first contribution in #409
• @nirosys made their first contribution in #416
• @rmarrowstone made their first contribution in #431

Full Changelog: v0.13.0...v0.14.0

v0.13.0

What's Changed

• adds changes for has_annotation method for Element API by @desaikd in #401
• Encoding oversized binary decimals no longer fails quietly by @zslayton in #407
• The IonValueFormatter now uses the correct s-exp delimiter by @zslayton in #408
• Add a ToIonDataSource implementation for std::io::Cursor and references to byte arrays. by @jnicholls in #406
• adds changes for Ord implementation of Timestamp by @desaikd in #410
• bumps ion-rs version to v0.13.0 by @desaikd in #412

New Contributors

• @jnicholls made their first contribution in #406

Full Changelog: v0.12.0...v0.13.0

v0.12.0

What's Changed

• adds text formatter and Display impl for OwnedElement by @desaikd in #391
• adds PartialOrd and Ord implementations for Integer, UInteger and Timestamp by @desaikd in #393
• Adds a non-blocking raw binary reader by @zslayton in #394
• Optimizes reading binary symbol and integer values by @zslayton in #396
• Updates ion-c to latest commit, fixes clippy warnings by @zslayton in #397
• Bumps version for ion-rs, ion-c-sys, ion-hash by @zslayton in #398

Full Changelog: v0.11.0...v0.12.0

v0.11.0

Major changes:

• ion-rust's readers and writers now pass the ion-tests spec conformance suite (minus tests that require shared symbol table imports).
• ion-c-sys integration is now gated behind an optional feature called ion_c. Crates that don't need access to the ion-c readers and writers no longer have to build cmake, clang, ion-c-sys, ion-c-sys-macros, etc.
• Readers and writers now have builder APIs instead of new() methods, allowing us to add more optional configuration settings over time.

What's Changed

• Adds NativeElementWriter, string/clob validation, big DecodedInts by @zslayton in #384
• Writer tests; fixes:symbols, timestamps, big Ints by @zslayton in #386
• Implements IonEq for Timestamp, Decimal by @zslayton in #387
• Reader/Writer builders, pretty text writer by @zslayton in #388
• Makes ion-c-sys an opt-in feature by @zslayton in #389
• Version bump: ion-rs v0.11.0, ion-hash v0.0.8 by @zslayton in #390

Full Changelog: v0.10.0...v0.11.0