add ncplane_cursor_y()/ncplane_cursor_x()

NEWS.md

@@ -1,7 +1,10 @@
 This document attempts to list user-visible changes and any major internal
 rearrangements of Notcurses.
 
-* 3.0.1 (not yet released)
+* 3.0.2 (not yet released)
+  * Added `ncplane_cursor_y()` and `ncplane_cursor_x()`.
+
+* 3.0.1 (2021-12-14)
   * Added the `NCPLANE_OPTION_VSCROLL` flag. Creating an `ncplane` with this
     flag is equivalent to immediately calling `ncplane_set_scrolling(true)`.
   * Added the `NCPLANE_OPTION_AUTOGROW` flag and the `ncplane_set_autogrow()`

USAGE.md

@@ -1262,6 +1262,20 @@ int ncplane_cursor_move_rel(struct ncplane* n, int y, int x);
 // Get the current position of the cursor within n. y and/or x may be NULL.
 void ncplane_cursor_yx(const struct ncplane* n, int* restrict y, int* restrict x);
 
+static inline unsigned
+ncplane_cursor_y(const struct ncplane* n){
+  unsigned y;
+  ncplane_cursor_yx(n, &y, NULL);
+  return y;
+}
+
+static inline unsigned
+ncplane_cursor_x(const struct ncplane* n){
+  unsigned x;
+  ncplane_cursor_yx(n, NULL, &x);
+  return x;
+}
+
 // Replace the cell at the specified coordinates with the provided cell 'c',
 // and advance the cursor by the width of the cell (but not past the end of the
 // plane). On success, returns the number of columns the cursor was advanced.

doc/man/man3/notcurses_plane.3.md

@@ -135,6 +135,10 @@ typedef struct ncplane_options {
 
 **void ncplane_cursor_yx(const struct ncplane* ***n***, unsigned* restrict ***y***, unsigned* restrict ***x***);**
 
+**unsigned ncplane_cursor_y(const struct ncplane* ***n***);**
+
+**unsigned ncplane_cursor_x(const struct ncplane* ***n***);**
+
 **void ncplane_translate(const struct ncplane* ***src***, const struct ncplane* ***dst***, int* restrict ***y***, int* restrict ***x***);**
 
 **bool ncplane_translate_abs(const struct ncplane* ***n***, int* restrict ***y***, int* restrict ***x***);**

include/ncpp/Plane.hh

@@ -483,6 +483,16 @@ namespace ncpp
 			get_cursor_yx (&y, &x);
 		}
 
+		unsigned cursor_y() const noexcept
+	  {
+			return ncplane_cursor_y(plane);
+		}
+
+		unsigned cursor_x() const noexcept
+	  {
+			return ncplane_cursor_x(plane);
+		}
+
 		int putc (const Cell &c) const NOEXCEPT_MAYBE
 		{
 			return error_guard<int> (ncplane_putc (plane, c), -1);

include/notcurses/notcurses.h

@@ -1981,6 +1981,20 @@ API void ncplane_home(struct ncplane* n)
 API void ncplane_cursor_yx(const struct ncplane* n, unsigned* RESTRICT y, unsigned* RESTRICT x)
   __attribute__ ((nonnull (1)));
 
+static inline unsigned
+ncplane_cursor_y(const struct ncplane* n){
+  unsigned y;
+  ncplane_cursor_yx(n, &y, NULL);
+  return y;
+}
+
+static inline unsigned
+ncplane_cursor_x(const struct ncplane* n){
+  unsigned x;
+  ncplane_cursor_yx(n, NULL, &x);
+  return x;
+}
+
 // Get the current channels or attribute word for ncplane 'n'.
 API uint64_t ncplane_channels(const struct ncplane* n)
   __attribute__ ((nonnull (1)));