move_family_{below,above}() need return int #2232

USAGE.md

@@ -1121,11 +1121,11 @@ int ncplane_move_above(struct ncplane* RESTRICT n,
 int ncplane_move_below(struct ncplane* RESTRICT n,
                        struct ncplane* RESTRICT below);
 
-void ncplane_move_family_above(struct ncplane* RESTRICT n,
-                               struct ncplane* RESTRICT above);
+int ncplane_move_family_above(struct ncplane* RESTRICT n,
+                              struct ncplane* RESTRICT above);
 
-void ncplane_move_family_below(struct ncplane* RESTRICT n,
-                               struct ncplane* RESTRICT below);
+int ncplane_move_family_below(struct ncplane* RESTRICT n,
+                              struct ncplane* RESTRICT below);
 
 // Return the ncplane below this one, or NULL if this is at the stack's bottom.
 struct ncplane* ncplane_below(struct ncplane* n);

doc/man/man3/notcurses_plane.3.md

@@ -95,9 +95,9 @@ typedef struct ncplane_options {
 
 **int ncplane_base(struct ncplane* ***ncp***, nccell* ***c***);**
 
-**int ncplane_move_top(struct ncplane* ***n***);**
+**void ncplane_move_top(struct ncplane* ***n***);**
 
-**int ncplane_move_bottom(struct ncplane* ***n***);**
+**void ncplane_move_bottom(struct ncplane* ***n***);**
 
 **void ncplane_move_family_top(struct ncplane* ***n***);**
 
@@ -107,9 +107,9 @@ typedef struct ncplane_options {
 
 **int ncplane_move_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
 
-**void ncplane_move_family_above(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
+**int ncplane_move_family_above(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
 
-**void ncplane_move_family_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
+**int ncplane_move_family_below(struct ncplane* restrict ***n***, struct ncplane* restrict ***targ***);**
 
 **struct ncplane* ncplane_below(struct ncplane* ***n***);**
 

include/notcurses/notcurses.h

@@ -1658,10 +1658,10 @@ API void ncplane_move_bottom(struct ncplane* n)
 // 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_above(struct ncplane* n, struct ncplane* targ)
+API int ncplane_move_family_above(struct ncplane* n, struct ncplane* targ)
   __attribute__ ((nonnull (1)));
 
-API void ncplane_move_family_below(struct ncplane* n, struct ncplane* targ)
+API int ncplane_move_family_below(struct ncplane* n, struct ncplane* targ)
   __attribute__ ((nonnull (1)));
 
 __attribute__ ((nonnull (1)))

src/lib/notcurses.c

@@ -1453,10 +1453,12 @@ void ncplane_move_bottom(ncplane* n){
 }
 
 // if above is NULL, we're moving to the bottom
-void ncplane_move_family_above(ncplane* restrict n, ncplane* restrict bpoint){
+int ncplane_move_family_above(ncplane* restrict n, ncplane* restrict bpoint){
   ncplane* above = ncplane_above(n);
   ncplane* below = ncplane_below(n);
-  ncplane_move_above(n, bpoint);
+  if(ncplane_move_above(n, bpoint)){
+    return -1;
+  }
   // traverse the planes above n, until we hit NULL. do the planes above n
   // first, so that we know the topmost element of our new ensplicification.
   // at this point, n is the bottommost plane, and we're inserting above it.
@@ -1481,13 +1483,16 @@ void ncplane_move_family_above(ncplane* restrict n, ncplane* restrict bpoint){
     }
     below = tmp;
   }
+  return 0;
 }
 
 // if below is NULL, we're moving to the top
-void ncplane_move_family_below(ncplane* restrict n, ncplane* restrict bpoint){
+int ncplane_move_family_below(ncplane* restrict n, ncplane* restrict bpoint){
   ncplane* below = ncplane_below(n);
   ncplane* above = ncplane_above(n);
-  ncplane_move_below(n, bpoint);
+  if(ncplane_move_below(n, bpoint)){
+    return -1;
+  }
   // traverse the planes below n, until we hit NULL. do the planes below n
   // first, so that we know the bottommost element of our new ensplicification.
   // we're inserting below n...
@@ -1512,6 +1517,7 @@ void ncplane_move_family_below(ncplane* restrict n, ncplane* restrict bpoint){
     }
     above = tmp;
   }
+  return 0;
 }
 
 void ncplane_cursor_yx(const ncplane* n, int* y, int* x){