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.


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 fns.
  • The names of all Owned tables are now Owning.
  • MetadataError::RoundtripError now requires Send + Sync.


Bug fixes

  • Issue 363, which was introduced in PR 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 instead of Result 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. In the case of a previous Result<Option<_>, _> that is now an Option<Result<_, _>>, use transpose.

Lifetime annotations of table types

PR #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 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.