Remove and replace ncplane_boundlist()

The function ncplane_boundlist() was poorly-considered,
and ought never have existed. Remove all traces of it.
Add the new functions ncplane_move_family_top() and
ncplane_move_family_bottom(). Replace the
ncplane_boundlist() code in notcurses-demo with a call
to ncplane_move_family_top(). We'll also want
ncplane_move_family_above() and ncplane_move_family_below(),
but they're not yet here. Document all z-axis movement
functions; they were lacking documentation before #2232.

USAGE.md

@@ -871,9 +871,6 @@ int ncplane_resize_realign(struct ncplane* n);
 struct ncplane* ncplane_parent(struct ncplane* n);
 const struct ncplane* ncplane_parent_const(const struct ncplane* n);
 
-// Get the head of the list of planes bound to 'n'.
-struct ncplane* ncplane_boundlist(struct ncplane* n);
-
 // Duplicate an existing ncplane. The new plane will have the same geometry,
 // will duplicate all content, and will start with the same rendering state.
 struct ncplane* ncplane_dup(struct ncplane* n, void* opaque);
@@ -1102,6 +1099,14 @@ int ncplane_base(struct ncplane* ncp, nccell* c);
 void ncplane_move_top(struct ncplane* n);
 void ncplane_move_bottom(struct ncplane* n);
 
+// Splice ncplane 'n' and its bound planes out of the z-buffer, and reinsert
+// them at the top or bottom. Relative order will be maintained between the
+// reinserted planes. For a plane E bound to C, with z-ordering A B C D E,
+// moving the C family to the top results in C E A B D, while moving it to
+// the bottom results in A B D C E.
+void ncplane_move_family_top(struct ncplane* n);
+void ncplane_move_family_bottom(struct ncplane* n);
+
 // Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'.
 // Returns non-zero if 'n' is already in the desired location. 'n' and
 // 'below' must not be the same plane.

doc/man/man3/notcurses_plane.3.md

@@ -99,9 +99,13 @@ typedef struct ncplane_options {
 
 **int ncplane_move_bottom(struct ncplane* ***n***);**
 
-**int ncplane_move_above(struct ncplane* restrict ***n***, struct ncplane* restrict ***above***);**
+**void ncplane_move_family_top(struct ncplane* ***n***);**
 
-**int ncplane_move_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***below***);**
+**void ncplane_move_family_bottom(struct ncplane* ***n***);**
+
+**int ncplane_move_above(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
+
+**int ncplane_move_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
 
 **struct ncplane* ncplane_below(struct ncplane* ***n***);**
 
@@ -333,6 +337,22 @@ invoked following resizing of its parent's plane. If it returns non-zero, the
 resizing cascade terminates, returning non-zero. Otherwise, resizing proceeds
 recursively.
 
+**ncplane_move_top** and **ncplane_move_bottom** extract their argument
+***n*** from the z-axis, and reinsert it at the top or bottom, respectively,
+of its pile. These functions are both O(1). **ncplane_move_family_top** and
+**ncplane_move_family_bottom** do the same, and move any bound descendants
+along with the plane. Ordering among the plane and its descendants will be
+maintained. For example, assume a pile with A at the top of its z-axis,
+followed by B, C, D, and E, where E is bound to C. Calling
+**ncplane_move_family_top** on C will result in the order CEABD. Calling
+**ncplane_move_family_bottom** on C will result in the order ABDCE. Calling
+**ncplane_move_family_top** or **ncplane_move_top** on E will result in EABCD.
+Calling **ncplane_move_family_bottom** on E is a no-op. These two functions
+are O(N) on the number of planes in the pile.
+
+**ncplane_move_above** and **ncplane_move_below** move the argument ***n***
+above or below, respectively, the argument ***targ***. Both operate in O(1).
+
 ## Base cells
 
 Each plane has a base cell, initialized to all zeroes. When rendering, the

include/notcurses/notcurses.h

@@ -1618,10 +1618,6 @@ API struct ncplane* ncplane_parent(struct ncplane* n)
 API const struct ncplane* ncplane_parent_const(const struct ncplane* n)
   __attribute__ ((nonnull (1)));
 
-// Get the head of the list of planes bound to 'n'.
-API struct ncplane* ncplane_boundlist(struct ncplane* n)
-  __attribute__ ((nonnull (1)));
-
 // Return non-zero iff 'n' is a proper descendent of 'ancestor'.
 static inline int
 ncplane_descendant_p(const struct ncplane* n, const struct ncplane* ancestor){
@@ -1634,20 +1630,34 @@ ncplane_descendant_p(const struct ncplane* n, const struct ncplane* ancestor){
 }
 
 // Splice ncplane 'n' out of the z-buffer, and reinsert it at the top or bottom.
-API void ncplane_move_top(struct ncplane* n);
-API void ncplane_move_bottom(struct ncplane* n);
+API void ncplane_move_top(struct ncplane* n)
+  __attribute__ ((nonnull (1)));
+API void ncplane_move_bottom(struct ncplane* n)
+  __attribute__ ((nonnull (1)));
+
+// Splice ncplane 'n' and its bound planes out of the z-buffer, and reinsert
+// them at the top or bottom. Relative order will be maintained between the
+// reinserted planes. For a plane E bound to C, with z-ordering A B C D E,
+// moving the C family to the top results in C E A B D, while moving it to
+// the bottom results in A B D C E.
+API void ncplane_move_family_top(struct ncplane* n)
+  __attribute__ ((nonnull (1)));
+API void ncplane_move_family_bottom(struct ncplane* n)
+  __attribute__ ((nonnull (1)));
 
 // Splice ncplane 'n' out of the z-buffer, and reinsert it above 'above'.
 // Returns non-zero if 'n' is already in the desired location. 'n' and
 // 'above' must not be the same plane.
 API int ncplane_move_above(struct ncplane* RESTRICT n,
-                           struct ncplane* RESTRICT above);
+                           struct ncplane* RESTRICT above)
+  __attribute__ ((nonnull (1, 2)));
 
 // Splice ncplane 'n' out of the z-buffer, and reinsert it below 'below'.
 // Returns non-zero if 'n' is already in the desired location. 'n' and
 // 'below' must not be the same plane.
 API int ncplane_move_below(struct ncplane* RESTRICT n,
-                           struct ncplane* RESTRICT below);
+                           struct ncplane* RESTRICT below)
+  __attribute__ ((nonnull (1, 2)));
 
 // Return the plane below this one, or NULL if this is at the bottom.
 API struct ncplane* ncplane_below(struct ncplane* n)

src/demo/hud.c

@@ -582,11 +582,7 @@ int demo_render(struct notcurses* nc){
   clock_gettime(CLOCK_MONOTONIC, &ts);
   if(plot){
     if(!plot_hidden){
-      struct ncplane* pixelp = ncplane_boundlist(ncuplot_plane(plot));
-      if(pixelp){
-        ncplane_move_top(pixelp);
-      }
-      ncplane_move_top(ncuplot_plane(plot));
+      ncplane_move_family_top(ncuplot_plane(plot));
     }
     uint64_t ns = (timespec_to_ns(&ts) - plottimestart) / (NANOSECS_IN_SEC / FPSHZ);
     ncuplot_add_sample(plot, ns, 1);

src/lib/notcurses.c

@@ -1444,6 +1444,16 @@ void ncplane_move_bottom(ncplane* n){
   }
 }
 
+void ncplane_move_family_top(ncplane* n){
+  ncplane_move_top(n);
+  // FIXME walk above and below, moving descendants
+}
+
+void ncplane_move_family_bottom(ncplane* n){
+  ncplane_move_bottom(n);
+  // FIXME walk above and below, moving descendants
+}
+
 void ncplane_cursor_yx(const ncplane* n, int* y, int* x){
   if(y){
     *y = n->y;
@@ -2356,10 +2366,6 @@ const ncplane* ncplane_parent_const(const ncplane* n){
   return n->boundto;
 }
 
-ncplane* ncplane_boundlist(ncplane* n){
-  return n->blist;
-}
-
 void ncplane_set_resizecb(ncplane* n, int(*resizecb)(ncplane*)){
   n->resizecb = resizecb;
 }