Skip to content

Commit

Permalink
Adds recommendation to use IonElement
Browse files Browse the repository at this point in the history
  • Loading branch information
popematt committed Mar 13, 2024
1 parent d7f900c commit 55a25c4
Showing 1 changed file with 14 additions and 0 deletions.
14 changes: 14 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,3 +67,17 @@ to the official one.
A great way to get started is to use the [Ion cookbook](https://amazon-ion.github.io/ion-docs/guides/cookbook.html).
The [API documentation](http://www.javadoc.io/doc/com.amazon.ion/ion-java) will give a lot
of detailed information about how to use the library.

### Alternatives

If you are looking for an in-memory Ion data model, this library provides `IonValue`, but you should consider
using `IonElement` from [`ion-element-kotlin`](https://github.com/amazon-ion/ion-element-kotlin) instead.

`IonElement` is a better choice than `IonValue` as long as you can work within its limitations. `IonElement` has
significantly less memory overhead than `IonValue`. It is immutable and does not have references to parent values, so
it is always threadsafe, and unlike `IonValue` there is no need to make deep copies of `IonElement`.
The limitations of `IonElement` are that it does not support symbols with unknown text, it will bring a dependency
on the Kotlin Stdlib, and you may need to change some logic in your application if it relies on being able to access the
parent container of an Ion value.

The Ion maintainers recommend using `IonElement` instead of `IonValue` whenever possible.

0 comments on commit 55a25c4

Please sign in to comment.