Document snapshot pointer lifetimes and make getters NULL-safe

The snapshot getters crashed on a NULL snapshot, unlike the rest of the
API. They now return NULL, an empty span, 0, or write nothing, as the
terminal functions do. term_snapshot_cluster writes nothing when cps is
NULL or cap is 0.

Document that the view and its palette keep their address for the life
of the snapshot, and that a row pointer lasts only until the next update
or free, since an update can realloc the cell array.

Rename the term_input.h include guard to TERM_INPUT_H to match the file.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>

1 files changed, 50 insertions, 0 deletions

diff --git a/tests/term_test.c b/tests/term_test.c
index 66dbd96..b904148 100644
--- a/tests/term_test.c
+++ b/tests/term_test.c
@@ -1440,6 +1440,55 @@ static void test_snapshot_follows_new_terminal(void)
     term_snapshot_free(s);
 }
 
+/* The getters take a NULL snapshot and an out-of-range row like a NULL
+ * terminal: they return the empty value. The view keeps its address. */
+static void test_snapshot_null_and_range(void)
+{
+    uint32_t cps[4] = { 0xAAAA, 0xAAAA, 0xAAAA, 0xAAAA };
+    assert(term_snapshot_view(NULL) == NULL);
+    assert(term_snapshot_row(NULL, 0) == NULL);
+    assert(term_snapshot_row_key(NULL, 0) == 0);
+    struct term_span none = term_snapshot_row_selection(NULL, 0);
+    assert(none.begin == 0 && none.end == 0);
+    assert(term_snapshot_cluster(NULL, 'a', cps, 4) == 0);
+    assert(term_snapshot_cluster(NULL, TERM_TEXT_CLUSTER, cps, 4) == 0);
+    assert(cps[0] == 0xAAAA);
+
+    struct term *t = tt_new(4, 2);
+    tt_write(t, "e\xcc\x81", 3);
+    struct term_snapshot *s = term_snapshot_new();
+    assert(term_snapshot_update(s, t));
+
+    const struct term_view *view = term_snapshot_view(s);
+    const uint32_t *palette = view->palette;
+    assert(term_snapshot_update(s, t));
+    assert(term_snapshot_view(s) == view && view->palette == palette);
+
+    assert(term_snapshot_row(s, -1) == NULL);
+    assert(term_snapshot_row(s, 2) == NULL);
+    assert(term_snapshot_row_key(s, -1) == 0);
+    assert(term_snapshot_row_key(s, 2) == 0);
+    struct term_span off = term_snapshot_row_selection(s, 2);
+    assert(off.begin == 0 && off.end == 0);
+
+    /* A cluster cell gives its count with no buffer, and with cap 0 it
+     * writes nothing. */
+    uint32_t text = term_snapshot_row(s, 0)[0].text;
+    assert(text & TERM_TEXT_CLUSTER);
+    assert(term_snapshot_cluster(s, text, NULL, 0) == 2);
+    assert(term_snapshot_cluster(s, text, cps, 0) == 2);
+    assert(cps[0] == 0xAAAA);
+    assert(term_snapshot_cluster(s, text, NULL, 4) == 2);
+    /* A plain code point is one code point, and cap 0 writes nothing. */
+    assert(term_snapshot_cluster(s, 'a', NULL, 0) == 1);
+    assert(term_snapshot_cluster(s, 'a', cps, 0) == 1);
+    assert(cps[0] == 0xAAAA);
+    assert(term_snapshot_cluster(s, 'a', cps, 4) == 1 && cps[0] == 'a');
+
+    term_snapshot_free(s);
+    term_free(t);
+}
+
 static void test_string_payloads(void)
 {
     static const char *prefixes[] = {"\033]0;", "\033]7;file://host/", "\033P"};
@@ -1859,6 +1908,7 @@ int main(void)
     test_alt_shrink_then_flood();
     test_alt_erase_scrollback();
     test_snapshot_follows_new_terminal();
+    test_snapshot_null_and_range();
     test_bulk_rows_survive_edits();
 
     assert(!strcmp(UNICODE_DATA_VERSION, "18.0.0"));