Name
	n3616, alx-0023r1 - add stpspn(), stpcspn(), wcpspn(), wcpcspn()

Principles
	-  Codify existing practice to address evident deficiencies.
	-  Enable secure programming

Category
	Standardize common APIs

Author
	Alejandro Colomar <alx@kernel.org>

	Cc: Yair Lenga <yair.lenga@gmail.com>
	Cc: Joseph Myers <josmyers@redhat.com>
	Cc: Christopher Bazley <chris.bazley.wg14@gmail.com>

History
	<https://www.alejandro-colomar.es/src/alx/alx/wg14/alx-0023.git/>

	r0 (2025-06-13):
	-  Initial draft.

	r1 (2025-06-26; n3616):
	-  s/Description/Rationale/

Rationale
	The strspn() family of functions is normally used to obtain an
	address, and not just an offset.  Thus, in most cases, it's
	useful to use a variant that returns the address directly.

	In shadow-utils, we call these as stpspn(), with the obvious
	difference being that it returns a pointer to the first non-
	matching character, instead of returning its offset.

	See how frequent these APIs are used in a project like
	shadow-utils:

	$ grep -rn 'strspn *(' | grep -v -e lib/string/strspn/ | wc -l
	11
	$ grep -rn 'stpspn *(' | grep -v -e lib/string/strspn/ | wc -l
	10
	$ grep -rn 'strcspn *(' | grep -v -e lib/string/strspn/ | wc -l
	0
	$ grep -rn 'stpcspn *(' | grep -v -e lib/string/strspn/ | wc -l
	0
	$ grep -rn 'strrspn_ *(' | grep -v -e lib/string/strspn/ | wc -l
	0
	$ grep -rn 'stprspn *(' | grep -v -e lib/string/strspn/ | wc -l
	4
	$ grep -rn 'strrcspn *(' | grep -v -e lib/string/strspn/ | wc -l
	0
	$ grep -rn 'stprcspn *(' | grep -v -e lib/string/strspn/ | wc -l
	1

Prior art
	shadow-utils defines stpspn() as

		$ grepc -h stpspn .
		#define stpspn(s, accept)                             \
		({                                                    \
			__auto_type  s_ = s;                          \
		                                                      \
			s_ + strspn(s_, accept);                      \
		})

	Solaris defines strrspn(3) as returning a pointer (what would
	more appropriately be called stprspn(3)).  This is, BTW, why I
	called the variant returning an offset as strrspn_() in
	shadow-utils.  We should avoid standardizing strrspn() to avoid
	an inconsistency.  Anyway, that shows that variants returning a
	pointer are deemed valuable.

Design decisions
	This paper will only add stp*() variants of the APIs that are
	already in ISO C.  Another paper will propose addition of the
	*r* variants, which search from the end, like strrchr(3).

	Of course, we include wide string equivalents.

Proposed wording
	Based on N3550.

    7.28.5.1 String handling <string.h> :: Search functions :: Introduction
	@@ p1
	 The stateless search functions in this subclause
	-(memchr, strchr, strpbrk, strrchr, strstr)
	+(memchr, strchr, stpcspn, strpbrk, strrchr, stpspn, strstr)
	 are generic functions.
	...

    7.28.5  String handling <string.h> :: Search functions
	## New section after 7.28.5.4 ("The strcspn function"):

	+7.28.5.4+1  The <b>stpcspn</b> generic function
	+
	+Synopsis
	+1	#include <string.h>
	+	QChar *stpcspn(QChar *s, const char *reject);
	+
	+Description
	+2	The <b>stpcspn</b> generic function
	+	is equivalent to <b>strcspn</b>,
	+	except that it returns a pointer instead of an offset.
	+
	+Returns
	+3	The <b>stpcspn</b> generic function returns
	+	<tt>s + strcspn(s, reject)</tt>.

	## New section after 7.28.5.7 ("The strspn function"):

	+7.28.5.7+1  The <b>stpspn</b> generic function
	+
	+Synopsis
	+1	#include <string.h>
	+	QChar *stpspn(QChar *s, const char *accept);
	+
	+Description
	+2	The <b>stpspn</b> generic function
	+	is equivalent to <b>strspn</b>,
	+	except that it returns a pointer instead of an offset.
	+
	+Returns
	+3	The <b>stpspn</b> generic function returns
	+	<tt>s + strspn(s, accept)</tt>.

    7.33.4.6.1 Wide string search functions :: Introduction
	@@ p1
	 The stateless search functions in this subclause
	-(wcschr, wcspbrk, wcsrchr, wmemchr, wcsstr)
	+(wcschr, wcpcspn, wcspbrk, wcsrchr, wmemchr, wcpspn, wcsstr)
	 are generic functions.
	...

    7.33.4.6  Wide string search functions
	## New section after 7.33.4.6.3 ("The wcscspn function"):

	+7.33.4.6.3+1  The <b>wcpcspn</b> function
	+
	+Synopsis
	+1	#include <wchar.h>
	+	QWchar_t *wcpcspn(QWchar_t *s, const wchar_t *reject);
	+
	+Description
	+2	The <b>wcpcspn</b> generic function
	+	is equivalent to <b>stpcspn</b>,
	+	except that it handles wide strings.

	## New section after 7.33.4.6.6 ("The wcsspn function"):

	+7.33.4.6.6+1  The <b>wcpspn</b> function
	+
	+Synopsis
	+1	#include <string.h>
	+	QWchar_t *wcpspn(QWchar_t *s, const wchar_t *reject);
	+
	+Description
	+2	The <b>wcpspn</b> generic function
	+	is equivalent to <b>stpspn</b>,
	+	except that it handles wide strings.

    7.35.18  String handling <string.h>
	@@ p2
	 Suppressing the macro definitions of
	 memchr, strchr,
	+stpcspn,
	 strpbrk, strrchr,
	+stpspn,
	 or strstr
	 to access the corresponding actual definition
	 is an obsolescent feature.

    7.35.21  Extended multibyte and wide character utilities <wchar.h>
	@@ p3
	 Suppressing the macro definitions of
	 wcschr,
	+wcpcspn,
	 wcspbrk, wcsrchr, wmemchr,
	+wcpspn,
	 or wcsstr
	 to access the corresponding actual function
	 is an obsolescent feature.