# Migration guide

This document helps with migration to newer versions of `tskit-rust`.
This document will not be exhaustive.
Rather, it will focus on highlights or "must know" items.

Regarding breaking changes:

* This document will discuss breaking changes requiring change in client code.
* Other changes listed in the change log as breaking are considered "technically breaking
  but unlikely to affect anyone in practice". Please file an issue if we are wrong!

Acronyms used:

* UB = undefined behavior.

## v0.12.0

### Breaking changes

* Provenance table getters now return `Option<&str>` rather than `Option<String>`.
  These two types are very close to identical in API.
  Breakage is only possible if code relied on the return value owning its data.
* Several member functions of Tree previously accepted `NodeId` as arguments.
  They now take `N: Into<NodeId> + Copy`.
  Thus, code passing in integers will have to drop the `.into()` calls.
* Tree functions returning iterators previously returned `Option<Iterator<...>>`.
  They now return `Iterator<...>`.
  Data leading to `None` being returned in previous versions now return an iterator
  that will end immediately.
* `Deref` to `TableViews` was replaced with delegation because using `Deref`
  to model inheritance is an anti-pattern.
* `usize` to `SizeType` conversions are now fallible (*e.g.*, `TryFrom` replaces `From`).
* The `TskitTypeAccess` trait was removed because it was a bad idea.
  (It makes no sense to be generic over returning pointers to low-level tskit types.)
  The functionality is replaced with `impl fn`s.
* The names of all `Owned` tables are now `Owning`.
* `MetadataError::RoundtripError` now requires `Send + Sync`.

## v0.11.0

### Bug fixes

* Issue [363](https://github.com/tskit-dev/tskit-rust/issues/363), which was introduced in PR [300](https://github.com/tskit-dev/tskit-rust/pull/300).
  The bug resulted in UB when advancing trees for release builds.

### Breaking changes

#### New error variant.

The error enum now includes `LibraryError`.
Any code previously matching on errors will now break because the match is no longer exhaustive.

#### Row getters

This change occurred over several PR.

All "getter" functions for table rows now return [`Option`](https://doc.rust-lang.org/std/option/enum.Option.html) instead of [`Result`](https://doc.rust-lang.org/std/result/enum.Result.html) when a row index is out of bounds.
These functions now return `None` for the out of bounds case.
This behavior change brings the API in line with other rust APIs.

To update:

* If `None` should represent an error for your use case, use [`Option::ok_or_else`](https://doc.rust-lang.org/std/option/enum.Option.html#method.ok_or_else).
  In the case of a previous `Result<Option<_>, _>` that is now an `Option<Result<_, _>>`, use [`transpose`](https://doc.rust-lang.org/std/option/enum.Option.html#method.transpose).

#### Lifetime annotations of table types

PR [#373](https://github.com/tskit-dev/tskit-rust/pull/373).

Previously, a non-owning view of an edge table had a type `EdgeTable<'a>`.
Those lifetimes are no longer necessary, which is a big design win.

Two traits, `TableAccess` and `NodeListRowGenerator`, have been removed.
The `TableCollection` and `TreeSequence` types now contain that functionality as
[`Deref`](https://doc.rust-lang.org/std/ops/trait.Deref.html) targets.

Removing these traits implies:

* Their removal from the crate prelude.
* They can no longer be used as trait bounds.

Some views of a node table that required mutability broke due to these changes.
A new function in the `Deref` target is `nodes_mut(&mut self)` addresses this breakage.