declate nctree_add() and nctree_del() #2458

NEWS.md

@@ -10,6 +10,7 @@ rearrangements of Notcurses.
     or bottom (scrolling enabled) boundaries.
   * Added `notcurses_default_background()` and `notcurses_default_foreground()`.
   * Added `nccell_load_ucs32()`.
+  * Added `nctree_add()` and `nctree_del()`.
 
 * 3.0.0 (2021-12-01) **"In the A"**
   * Made the ABI/API changes that have been planned/collected during 2.x

doc/man/man3/notcurses_tree.3.md

@@ -44,16 +44,19 @@ typedef struct nctree_options {
 
 **void* nctree_prev(struct nctree* ***n***);**
 
-**void* nctree_goto(struct nctree* ***n***, const int* ***spec***, size_t ***specdepth***, int* ***failspec***);**
+**void* nctree_goto(struct nctree* ***n***, const int* ***path***, int* ***failpath***);**
+
+**int nctree_add(struct nctree* ***n***, const unsigned* ***path***, const nctree_item* ***add***);**
+
+**int nctree_del(struct nctree* ***n***, const unsigned* ***path***);**
 
 **void nctree_destroy(struct nctree* ***n***);**
 
 # DESCRIPTION
 
-**nctree**s organize static hierarchical items, and allow them to be browsed.
-Each item can have arbitrary subitems. Items can be collapsed and expanded.
-The display supports scrolling and searching. Items cannot be added or removed,
-however; they must be provided in their entirety at creation time.
+**nctree**s organize hierarchical items, and allow them to be browsed. Each
+item can have arbitrary subitems. Items can be collapsed and expanded.
+The display supports scrolling and searching.
 
 An **nctree** cannot be empty. **count** must be non-zero, and **items** must
 not be **NULL**. The callback function **nctreecb** must also be non-**NULL**.
@@ -72,6 +75,12 @@ is expanded in the callback, it will be shrunk back down by the widget. The
 is negative, the item is before the focused item; a positive parameter implies
 that the item follows the focused item; the focused item itself is passed zero.
 
+**nctree_goto**, **nctree_add**, and **nctree_del** all use the concept of a
+***path***. A path is an array of **unsigned** values, terminated by
+**UINT_MAX**, with each successive value indexing into the hierarchy thus far.
+The root node of the **nctree** thus always has a 2-element path of
+[0, **UINT_MAX**].
+
 # RETURN VALUES
 
 **nctree_create** returns **NULL** for invalid options. This includes a **NULL**
@@ -81,11 +90,23 @@ that the item follows the focused item; the focused item itself is passed zero.
 newly-focused item. **nctree_focused** returns the **curry** pointer from the
 already-focused item.
 
+**nctree_goto** returns the **curry** pointer from the newly-focused item. If
+***path*** is invalid, the first invalid hierarchy level is written to
+***failpath***, and **NULL** is returned. If ***path*** is valid, the value -1
+is written to ***failpath***. Since it is possible for a ***curry***
+pointer to be **NULL**, one should check ***failpath*** before assuming the
+operation failed.
+
+**nctree_add** and **nctree_del** both return -1 for an invalid ***path***, and
+0 otherwise.
+
 # NOTES
 
 **nctree** shares many properties with **notcurses_reel**. Unlike the latter,
-**nctree**s support arbitrary hierarchical levels, but they do not allow
-elements to come and go across the lifetime of the widget.
+**nctree**s support arbitrary hierarchical levels.
+
+**nctree** used to only handle static data, but **nctree_add** and
+**nctree_del** were added in Notcurses 3.0.1.
 
 # SEE ALSO
 

include/notcurses/notcurses.h

@@ -3877,13 +3877,24 @@ API void* nctree_next(struct nctree* n) __attribute__ ((nonnull (1)));
 // Change focus to the previous item.
 API void* nctree_prev(struct nctree* n) __attribute__ ((nonnull (1)));
 
-// Go to the item specified by the array |spec|, terminated by UINT_MAX. If
-// the spec is invalid, NULL is returned, and the depth of the first invalid
-// spec is written to *|failspec|. Otherwise, the true depth is written to
-// *|failspec|, and the curry is returned (|failspec| is necessary because the
-// curry could itself be NULL).
+// Go to the item specified by the array |spec| (a spec is a series of unsigned
+// values, each identifying a subelement in the hierarchy thus far, terminated
+// by UINT_MAX). If the spec is invalid, NULL is returned, and the depth of the
+// first invalid spec is written to *|failspec|. Otherwise, the true depth is
+// written to *|failspec|, and the curry is returned (|failspec| is necessary
+// because the curry could itself be NULL).
 API void* nctree_goto(struct nctree* n, const unsigned* spec, int* failspec);
 
+// Insert |add| into the nctree |n| at |spec|. The path up to the last element
+// must already exist. If an item already exists at the path, it will be moved
+// to make room for |add|.
+API int nctree_add(struct nctree* n, const unsigned* spec, const nctree_item* add)
+  __attribute__ ((nonnull (1, 2, 3)));
+
+// Delete the item at |spec|, including any subitems.
+API int nctree_del(struct nctree* n, const unsigned* spec)
+  __attribute__ ((nonnull (1, 2)));
+
 // Destroy the nctree.
 API void nctree_destroy(struct nctree* n);