High-level interface for keep_rows

Author: jeromekelleher

docs/substitutions/table_keep_rows_main.rst

@@ -0,0 +1,14 @@
+Updates this table in-place according to the specified boolean
+array, and returns the resulting mapping from old to new row IDs.
+For each row ``j``, if ``keep[j]`` is True, that row will be
+retained in the output; otherwise, the row will be deleted.
+Rows are retained in their original ordering.
+
+The returned ``id_map`` is an array of the same length as
+this table before the operation, such that ``id_map[j] = -1``
+(:data:`tskit.NULL`) if row ``j`` was deleted, and ``id_map[j]``
+is the new ID of that row, otherwise.
+
+.. todo::
+    This needs some examples to link to. See
+    https://github.com/tskit-dev/tskit/issues/2708

python/CHANGELOG.rst

@@ -7,7 +7,9 @@
 - Add ``__repr__`` for variants to return a string representation of the raw data
   without spewing megabytes of text (:user:`chriscrsmith`, :pr:`2695`, :issue:`2694`)
 
-  
+- Add ``keep_rows`` method to table classes to support efficient in-place
+  table subsetting (:user:`jeromekelleher`, :pr:`2700`)
+
 --------------------
 [0.5.4] - 2023-01-13
 --------------------

python/_tskitmodule.c

@@ -993,12 +993,14 @@ table_keep_rows(
     PyArrayObject *keep = NULL;
     PyArrayObject *id_map = NULL;
     npy_intp n = (npy_intp) num_rows;
+    npy_intp array_len;
     int err;
 
     if (!PyArg_ParseTuple(args, "O&", &bool_array_converter, &keep)) {
         goto out;
     }
-    if (PyArray_DIMS(keep)[0] != n) {
+    array_len = PyArray_DIMS(keep)[0];
+    if (array_len != n) {
         PyErr_SetString(PyExc_ValueError, "keep array must be of length Table.num_rows");
         goto out;
     }