Reject invalid arguments instead of ignoring them

term_feed() returns bool and rejects a NULL terminal, a NULL buffer with
a nonzero length, and any flag bit it does not know. Unknown bits are
rejected now so that later flags can be added without changing what the
old calls mean.

term_new() returns NULL for a negative size component, columns above
TERM_MAX_COLS, a negative scrollback, or a cursor style outside the enum.
Zero still selects the default size and scrollback. It no longer clamps
bad values silently.

term_resize() rejects columns above TERM_MAX_COLS instead of clamping
them, which matches how it already rejects a size below 1.

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

1 files changed, 17 insertions, 6 deletions

diff --git a/include/term/term.h b/include/term/term.h
index dc41114..05afbd9 100644
--- a/include/term/term.h
+++ b/include/term/term.h
@@ -139,9 +139,14 @@ struct term_callbacks {
     void (*trace)(void *ud, const char *line);
 };
 
-/* Options for term_new(). An all-zero value is valid. */
+/*
+ * Options for term_new(). An all-zero value is valid. A size component of 0
+ * selects 80 columns or 24 rows. A negative component, or columns above
+ * TERM_MAX_COLS, makes term_new() fail. A negative scrollback fails too.
+ * cursor_style must be a value of enum term_cursor_style.
+ */
 struct term_options {
-    struct term_vector2i size;  /* columns and rows; each is at least 1 */
+    struct term_vector2i size;  /* columns and rows */
     int scrollback;             /* history lines; 0 selects TERM_SCROLLBACK_DEFAULT */
     struct term_theme theme;
     enum term_cursor_style cursor_style;
@@ -149,7 +154,6 @@ struct term_options {
     struct term_callbacks callbacks;
 };
 
-/* NULL when memory runs out. */
 /* The Unicode version of the width tables, such as "18.0.0". A host can
  * pass it to programs as UNICODE_VERSION. */
 TERM_API const char *term_unicode_version(void);
@@ -165,6 +169,7 @@ TERM_API size_t term_scan_printable_span(const char *buf, size_t len, unsigned c
  * and comparisons. */
 TERM_API const char *term_isa(void);
 
+/* NULL when memory runs out or an option is invalid. */
 TERM_API struct term *term_new(const struct term_options *opt);
 TERM_API void term_free(struct term *t);
 
@@ -175,8 +180,9 @@ TERM_API void term_free(struct term *t);
 TERM_API void term_lock(struct term *t);
 TERM_API void term_unlock(struct term *t);
 
-/* Change the size in cells. Returns false when memory runs out; the terminal
- * is then unchanged. The screen reflows to the new width. */
+/* Change the size in cells. Returns false, and the terminal is unchanged,
+ * when a component is below 1, when cols is above TERM_MAX_COLS, or when
+ * memory runs out. The screen reflows to the new width. */
 TERM_API bool term_resize(struct term *t, struct term_vector2i size);
 
 /* Replace the theme. A different theme also drops the colors that the
@@ -197,7 +203,12 @@ enum term_feed_flags {
     TERM_FEED_ONLCR = 1u << 0,
 };
 
-TERM_API void term_feed(struct term *t, const char *bytes, size_t len, unsigned flags);
+/*
+ * Feed bytes from the program. Returns false, and changes nothing, when t is
+ * NULL, when bytes is NULL and len is not 0, or when flags has a bit that is
+ * not in enum term_feed_flags. A len of 0 is a no-op that returns true.
+ */
+TERM_API bool term_feed(struct term *t, const char *bytes, size_t len, unsigned flags);
 
 /* Report a focus change. The terminal replies only in focus-event mode. */
 TERM_API void term_focus(struct term *t, bool focused);