Function tskit::bindings::tsk_table_collection_sort

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

@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.