And these two patches make the .h file more usable to an average developer.
2025-06-26 Bruno Haible <br...@clisp.org>
kwset: Improve header file.
* lib/kwset.h (kwsalloc): Clarify size of trans parameter. Add
_GL_ATTRIBUTE_RETURNS_NONNULL attribute.
(kwswords): Add specification comment.
(kwsincr, kwswords, kwsprep, kwsexec, kwsfree): Add _GL_ARG_NONNULL
attribute.
kwset: Add specification comments in .h file.
* lib/kwset.h (kwsalloc, kwsincr, kwsprep, kwsexec, kwsfree): Move
specification to here...
* lib/kwset.c (kwsalloc, kwsincr, kwsprep, kwsexec, kwsfree): ...from
here.
>From 46ac1afa57f64c0e0c9c266f4e405928f25978fd Mon Sep 17 00:00:00 2001
From: Bruno Haible <br...@clisp.org>
Date: Thu, 26 Jun 2025 22:46:40 +0200
Subject: [PATCH 1/2] kwset: Add specification comments in .h file.
* lib/kwset.h (kwsalloc, kwsincr, kwsprep, kwsexec, kwsfree): Move
specification to here...
* lib/kwset.c (kwsalloc, kwsincr, kwsprep, kwsexec, kwsfree): ...from
here.
---
ChangeLog | 8 ++++++++
lib/kwset.c | 16 ----------------
lib/kwset.h | 35 ++++++++++++++++++++++++++++-------
3 files changed, 36 insertions(+), 23 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 30dabe44e3..a4597155e4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2025-06-26 Bruno Haible <br...@clisp.org>
+
+ kwset: Add specification comments in .h file.
+ * lib/kwset.h (kwsalloc, kwsincr, kwsprep, kwsexec, kwsfree): Move
+ specification to here...
+ * lib/kwset.c (kwsalloc, kwsincr, kwsprep, kwsexec, kwsfree): ...from
+ here.
+
2025-06-26 Paul Eggert <egg...@cs.ucla.edu>
regex: fix parse_bracket_exp double-free
diff --git a/lib/kwset.c b/lib/kwset.c
index 2784ba5371..f90b01dd34 100644
--- a/lib/kwset.c
+++ b/lib/kwset.c
@@ -148,9 +148,6 @@ static ptrdiff_t acexec (kwset_t, char const *, idx_t,
static ptrdiff_t bmexec (kwset_t, char const *, idx_t,
struct kwsmatch *, bool);
-/* Return a newly allocated keyword set. A nonnull TRANS specifies a
- table of character translations to be applied to all pattern and
- search text. */
kwset_t
kwsalloc (char const *trans)
{
@@ -178,7 +175,6 @@ kwsalloc (char const *trans)
exact for CHAR_BIT in { 4..11, 13, 15, 17, 19 }. */
enum { DEPTH_SIZE = CHAR_BIT + CHAR_BIT / 2 };
-/* Add the given string to the contents of the keyword set. */
void
kwsincr (kwset_t kwset, char const *text, idx_t len)
{
@@ -423,7 +419,6 @@ treenext (struct tree const *tree, struct trie *next[])
next[tree->label] = tree->trie;
}
-/* Prepare a built keyword set for use. */
void
kwsprep (kwset_t kwset)
{
@@ -914,16 +909,6 @@ acexec (kwset_t kwset, char const *text, idx_t size,
: acexec_trans (kwset, text, size, kwsmatch, longest)));
}
-/* Find the first instance of a KWSET member in TEXT, which has SIZE bytes.
- Return the offset (into TEXT) of the first byte of the matching substring,
- or -1 if no match is found.
- Upon a match:
- - Store details in *KWSMATCH: index of matched keyword, start offset
- (same as the return value), and length.
- - If LONGEST, find the longest match that starts at this offset;
- otherwise any match that starts at this offset will do.
- NOTE! LONGEST does *not* mean to search for the longest KWSET member
- across the entire string. */
ptrdiff_t
kwsexec (kwset_t kwset, char const *text, idx_t size,
struct kwsmatch *kwsmatch, bool longest)
@@ -931,7 +916,6 @@ kwsexec (kwset_t kwset, char const *text, idx_t size,
return kwset->kwsexec (kwset, text, size, kwsmatch, longest);
}
-/* Free the components of the given keyword set. */
void
kwsfree (kwset_t kwset)
{
diff --git a/lib/kwset.h b/lib/kwset.h
index 204f409808..223e077144 100644
--- a/lib/kwset.h
+++ b/lib/kwset.h
@@ -44,14 +44,35 @@ struct kwsmatch
struct kwset;
typedef struct kwset *kwset_t;
-extern kwset_t kwsalloc (char const *);
-extern void kwsincr (kwset_t, char const *, idx_t);
-extern idx_t kwswords (kwset_t) _GL_ATTRIBUTE_PURE;
-extern void kwsprep (kwset_t);
-extern ptrdiff_t kwsexec (kwset_t, char const *, idx_t,
- struct kwsmatch *, bool)
+/* Return a newly allocated keyword set. A nonnull TRANS specifies a
+ table of character translations to be applied to all pattern and
+ search text. */
+extern kwset_t kwsalloc (char const *trans);
+
+/* Add the given string to the contents of the keyword set. */
+extern void kwsincr (kwset_t kwset, char const *text, idx_t len);
+
+extern idx_t kwswords (kwset_t kwset) _GL_ATTRIBUTE_PURE;
+
+/* Prepare a built keyword set for use. */
+extern void kwsprep (kwset_t kwset);
+
+/* Find the first instance of a KWSET member in TEXT, which has SIZE bytes.
+ Return the offset (into TEXT) of the first byte of the matching substring,
+ or -1 if no match is found.
+ Upon a match:
+ - Store details in *MATCH: index of matched keyword, start offset
+ (same as the return value), and length.
+ - If LONGEST, find the longest match that starts at this offset;
+ otherwise any match that starts at this offset will do.
+ NOTE! LONGEST does *not* mean to search for the longest KWSET member
+ across the entire string. */
+extern ptrdiff_t kwsexec (kwset_t kwset, char const *text, idx_t size,
+ struct kwsmatch *match, bool longest)
_GL_ARG_NONNULL ((4));
-extern void kwsfree (kwset_t);
+
+/* Free the components of the given keyword set. */
+extern void kwsfree (kwset_t kwset);
#ifdef __cplusplus
}
--
2.43.0
>From b82548a7dffb05f6707454ccdaa630fa4484172e Mon Sep 17 00:00:00 2001
From: Bruno Haible <br...@clisp.org>
Date: Thu, 26 Jun 2025 22:59:02 +0200
Subject: [PATCH 2/2] kwset: Improve header file.
* lib/kwset.h (kwsalloc): Clarify size of trans parameter. Add
_GL_ATTRIBUTE_RETURNS_NONNULL attribute.
(kwswords): Add specification comment.
(kwsincr, kwswords, kwsprep, kwsexec, kwsfree): Add _GL_ARG_NONNULL
attribute.
---
ChangeLog | 7 +++++++
lib/kwset.h | 24 +++++++++++++++---------
2 files changed, 22 insertions(+), 9 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index a4597155e4..b83e1a74a8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
2025-06-26 Bruno Haible <br...@clisp.org>
+ kwset: Improve header file.
+ * lib/kwset.h (kwsalloc): Clarify size of trans parameter. Add
+ _GL_ATTRIBUTE_RETURNS_NONNULL attribute.
+ (kwswords): Add specification comment.
+ (kwsincr, kwswords, kwsprep, kwsexec, kwsfree): Add _GL_ARG_NONNULL
+ attribute.
+
kwset: Add specification comments in .h file.
* lib/kwset.h (kwsalloc, kwsincr, kwsprep, kwsexec, kwsfree): Move
specification to here...
diff --git a/lib/kwset.h b/lib/kwset.h
index 223e077144..5eb0a030e8 100644
--- a/lib/kwset.h
+++ b/lib/kwset.h
@@ -20,7 +20,7 @@
#ifndef _KWSET_H
#define _KWSET_H
-/* This file uses _GL_ATTRIBUTE_PURE. */
+/* This file uses _GL_ATTRIBUTE_PURE, _GL_ATTRIBUTE_RETURNS_NONNULL. */
#if !_GL_CONFIG_H_INCLUDED
#error "Please include config.h first."
#endif
@@ -45,17 +45,22 @@ struct kwset;
typedef struct kwset *kwset_t;
/* Return a newly allocated keyword set. A nonnull TRANS specifies a
- table of character translations to be applied to all pattern and
- search text. */
-extern kwset_t kwsalloc (char const *trans);
+ table (indexed by 'unsigned char' values: 0..UCHAR_MAX+1) of character
+ translations to be applied to all pattern and search text. */
+extern kwset_t kwsalloc (char const *trans)
+ _GL_ATTRIBUTE_RETURNS_NONNULL;
/* Add the given string to the contents of the keyword set. */
-extern void kwsincr (kwset_t kwset, char const *text, idx_t len);
+extern void kwsincr (kwset_t kwset, char const *text, idx_t len)
+ _GL_ARG_NONNULL ((1, 2));
-extern idx_t kwswords (kwset_t kwset) _GL_ATTRIBUTE_PURE;
+/* Return the number of keywords in SET. */
+extern idx_t kwswords (kwset_t kwset)
+ _GL_ARG_NONNULL ((1)) _GL_ATTRIBUTE_PURE;
/* Prepare a built keyword set for use. */
-extern void kwsprep (kwset_t kwset);
+extern void kwsprep (kwset_t kwset)
+ _GL_ARG_NONNULL ((1));
/* Find the first instance of a KWSET member in TEXT, which has SIZE bytes.
Return the offset (into TEXT) of the first byte of the matching substring,
@@ -69,10 +74,11 @@ extern void kwsprep (kwset_t kwset);
across the entire string. */
extern ptrdiff_t kwsexec (kwset_t kwset, char const *text, idx_t size,
struct kwsmatch *match, bool longest)
- _GL_ARG_NONNULL ((4));
+ _GL_ARG_NONNULL ((1, 2, 4));
/* Free the components of the given keyword set. */
-extern void kwsfree (kwset_t kwset);
+extern void kwsfree (kwset_t kwset)
+ _GL_ARG_NONNULL ((1));
#ifdef __cplusplus
}
--
2.43.0
