Function tskit::bindings::tsk_table_collection_sort [−][src]
pub unsafe extern "C" fn tsk_table_collection_sort(
self_: *mut tsk_table_collection_t,
start: *const tsk_bookmark_t,
options: tsk_flags_t
) -> c_int
Expand description
@brief Sorts the tables in this collection.
@rst
Some of the tables in a table collection must satisfy specific sortedness requirements
in order to define a :ref:valid tree sequence <sec_valid_tree_sequence_requirements>
.
This method sorts the edge
, site
and mutation
tables such that
these requirements are guaranteed to be fulfilled. The individual
,
node
, population
and provenance
tables do not have any sortedness
requirements, and are therefore ignored by this method.
.. note:: The current implementation may sort in such a way that exceeds these requirements, but this behaviour should not be relied upon and later versions may weaken the level of sortedness. However, the method does guarantee that the resulting tables describes a valid tree sequence.
.. warning:: Sorting migrations is currently not supported and an error will be raised if a table collection containing a non-empty migration table is specified.
The specified :c:type:tsk_bookmark_t
allows us to specify a start position
for sorting in each of the tables; rows before this value are assumed to already be
in sorted order and this information is used to make sorting more efficient.
Positions in tables that are not sorted (individual
, node
, population
and provenance
) are ignored and can be set to arbitrary values.
.. warning:: The current implementation only supports specifying a start
position for the edge
table and in a limited form for the
site
and mutation
tables. Specifying a non-zero migration
,
start position results in an error. The start positions for the
site
and mutation
tables can either be 0 or the length of the
respective tables, allowing these tables to either be fully sorted, or
not sorted at all.
The table collection will always be unindexed after sort successfully completes.
See the :ref:table sorting <sec_table_sorting>
section for more details.
For more control over the sorting process, see the
:ref:sec_c_api_low_level_sorting
section.
Options**
Options can be specified by providing one or more of the following bitwise flags:
TSK_NO_CHECK_INTEGRITY
Do not run integrity checks using
:c:func:tsk_table_collection_check_integrity
before sorting,
potentially leading to a small reduction in execution time. This
performance optimisation should not be used unless the calling code can
guarantee reference integrity within the table collection. References
to rows not in the table or bad offsets will result in undefined
behaviour.
@endrst
@param self A pointer to a tsk_individual_table_t object. @param start The position to begin sorting in each table; all rows less than this position must fulfill the tree sequence sortedness requirements. If this is NULL, sort all rows. @param options Sort options. Currently unused; should be set to zero to ensure compatibility with later versions of tskit. @return Return 0 on success or a negative value on failure.