add ncplane_moverel(), no unit tests though =[ #1881

NEWS.md

@@ -5,6 +5,7 @@ rearrangements of Notcurses.
   * `notcurses_detected_terminal()` and `ncdirect_detected_terminal()` now
     both return a heap-allocated string, which will contain the terminal
     version if Notcurses was able to detect it. This result ought be free()d.
+  * Added `ncplane_moverel()`.
 
 * 2.3.8 (2021-07-04)
   * Marked all capability functions `__attribute__ ((pure))`. If you were

USAGE.md

@@ -917,6 +917,15 @@ ncplane_resize_simple(struct ncplane* n, int ylen, int xlen){
 // standard plane. Specifying a coordinate as -1 will hold it constant.
 int ncplane_move_yx(struct ncplane* n, int y, int x);
 
+// Move this plane relative to its current location. Negative values move up
+// and left, respectively. Pass 0 to hold an axis constant.
+__attribute__ ((nonnull (1))) static inline int
+ncplane_moverel(struct ncplane* n, int y, int x){
+  int oy, ox;
+  ncplane_yx(n, &oy, &ox);
+  return ncplane_move_yx(n, oy + y, ox + x);
+}
+
 // Get the origin of plane 'n' relative to its bound plane, or its pile (if
 // 'n' is a root plane).
 void ncplane_yx(const struct ncplane* n, int* restrict y, int* restrict x);

doc/man/man3/notcurses_plane.3.md

@@ -70,6 +70,8 @@ typedef struct ncplane_options {
 
 **int ncplane_move_yx(struct ncplane* ***n***, int ***y***, int ***x***);**
 
+**int ncplane_moverel(struct ncplane* ***n***, int ***y***, int ***x***);**
+
 **void ncplane_yx(const struct ncplane* ***n***, int* restrict ***y***, int* restrict ***x***);**
 
 **int ncplane_y(const struct ncplane* ***n***);**

include/notcurses/notcurses.h

@@ -1490,11 +1490,6 @@ API int ncplane_set_base(struct ncplane* n, const char* egc,
 // 'ncp' is destroyed.
 API int ncplane_base(struct ncplane* n, nccell* c);
 
-// Move this plane relative to the standard plane, or the plane to which it is
-// bound (if it is bound to a plane). It is an error to attempt to move the
-// standard plane. Specifying a coordinate as -1 will hold it constant.
-API int ncplane_move_yx(struct ncplane* n, int y, int x);
-
 // Get the origin of plane 'n' relative to its bound plane, or pile (if 'n' is
 // a root plane). To get absolute coordinates, use ncplane_abs_yx().
 API void ncplane_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x)
@@ -1502,6 +1497,20 @@ API void ncplane_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x)
 API int ncplane_y(const struct ncplane* n) __attribute__ ((pure));
 API int ncplane_x(const struct ncplane* n) __attribute__ ((pure));
 
+// Move this plane relative to the standard plane, or the plane to which it is
+// bound (if it is bound to a plane). It is an error to attempt to move the
+// standard plane. Specifying a coordinate as -1 will hold it constant.
+API int ncplane_move_yx(struct ncplane* n, int y, int x);
+
+// Move this plane relative to its current location. Negative values move up
+// and left, respectively. Pass 0 to hold an axis constant.
+__attribute__ ((nonnull (1))) static inline int
+ncplane_moverel(struct ncplane* n, int y, int x){
+  int oy, ox;
+  ncplane_yx(n, &oy, &ox);
+  return ncplane_move_yx(n, oy + y, ox + x);
+}
+
 // Get the origin of plane 'n' relative to its pile. Either or both of 'x' and
 // 'y' may be NULL.
 API void ncplane_abs_yx(const struct ncplane* n, int* RESTRICT y, int* RESTRICT x)