kc3-lang/gnulib/doc/string-desc.texi

• Show log

  Commit

• Hash : 5656e32e
  Author :
  Date : 2025-05-10T03:16:52
  

  string-desc: Distinguish writable strings from read-only strings.
  
  * lib/string-desc.h (HAVE_STATEMENT_EXPRESSIONS): New macro.
  (rw_string_desc_t): New type.
  (string_desc_t) [HAVE_STATEMENT_EXPRESSIONS]: Change field _data from
  'char *' to 'const char *'.
  (sd_readonly, sd_readwrite): New inline functions.
  (sd_length): Define through a macro with _Generic.
  (sd_char_at): Define through a macro and an inline function.
  (sd_data, sd_is_empty): Define through a macro with _Generic.
  (sd_equals, sd_startswith, sd_endswith, sd_cmp, sd_c_casecmp, sd_index,
  sd_last_index, sd_contains): Define through a macro.
  (sd_new_addr): Define through a macro with _Generic.
  (sd_substring, sd_write, sd_fwrite): Define through a macro.
  (sd_new, sd_new_filled): Change parameter type.
  (sd_copy): Define through a macro.
  (sd_concat): Change parameter type.
  (sd_c): Define through a macro.
  (sd_set_char_at, sd_fill): Change parameter type.
  (sd_overwrite): Define through a macro.
  (sd_free): Change parameter type.
  * lib/string-desc.c (_sd_equals): Renamed from sd_equals. Take scalar
  parameters.
  (_sd_startswith): Renamed from sd_startswith. Take scalar parameters.
  (_sd_endswith): Renamed from sd_endswith. Take scalar parameters.
  (_sd_cmp): Renamed from sd_cmp. Take scalar parameters.
  (_sd_c_casecmp): Renamed from sd_c_casecmp. Take scalar parameters.
  (_sd_index): Renamed from sd_index. Take scalar parameters.
  (_sd_last_index): Renamed from sd_last_index. Take scalar parameters.
  (_sd_new_addr, _rwsd_new_addr): Renamed from sd_new_addr.
  (sd_substring): Remove function.
  (_sd_write): Renamed from sd_write. Take scalar parameters.
  (_sd_fwrite): Renamed from sd_fwrite. Take scalar parameters.
  (sd_new, sd_new_filled): Change parameter type.
  (_sd_copy): Renamed from sd_copy. Change parameter type. Take scalar
  parameters.
  (sd_concat): Change parameter type.
  (_sd_c): Renamed from sd_c. Take scalar parameters.
  (sd_set_char_at, sd_fill): Change parameter type.
  (_sd_overwrite): Renamed from sd_overwrite. Change parameter type. Take
  scalar parameters.
  (sd_free): Change parameter type.
  * lib/string-desc-contains.c (_sd_contains): Renamed from sd_contains.
  Take scalar parameters.
  * lib/xstring-desc.h (xsd_new, xsd_new_filled, xsd_copy, xsd_concat):
  Change return type to rw_string_desc_t.
  (xsd_c): Define through a macro.
  * lib/xstring-desc.c (xsd_concat): Change return type to
  rw_string_desc_t.
  * doc/string-desc.texi (Handling strings with NUL characters): Mention
  rw_string_desc_t and the sd_readonly() function.
  * lib/string-buffer.h (sb_dupfree, sb_xdupfree): Change return type to
  rw_string_desc_t.
  * lib/string-buffer.c (sb_contents): Add a cast to 'const char *'.
  (sb_dupfree): Change return type to rw_string_desc_t.
  * lib/xstring-buffer.c (sb_xdupfree): Change return type to
  rw_string_desc_t.
  * lib/string-buffer-reversed.h (sbr_dupfree, sbr_xdupfree): Change
  return type to rw_string_desc_t.
  * lib/string-buffer-reversed.c (sbr_contents): Add a cast to
  'const char *'.
  (sbr_dupfree): Change return type to rw_string_desc_t.
  * lib/xstring-buffer-reversed.c (sbr_xdupfree): Change return type to
  rw_string_desc_t.
  * tests/test-string-desc.c (main): Use type rw_string_desc_t as
  appropriate.
  * tests/test-xstring-desc.c (main): Likewise.
  * tests/test-sf-istream.c (main): Remove cast in sd_new_addr argument.
  * tests/test-sfl-istream.c (main): Likewise.
  * NEWS: Mention the change.
  

Download

• doc/string-desc.texi

• @node Handling strings with NUL characters
  @section Handling strings with NUL characters
  
  @c Copyright (C) 2023--2025 Free Software Foundation, Inc.
  
  @c Permission is granted to copy, distribute and/or modify this document
  @c under the terms of the GNU Free Documentation License, Version 1.3 or
  @c any later version published by the Free Software Foundation; with no
  @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
  
  @c Written by Bruno Haible.
  
  Strings in C are usually represented by a character sequence with a
  terminating NUL character.  A @samp{char *}, pointer to the first byte
  of this character sequence, is what gets passed around as function
  argument or return value.
  
  The major restriction of this string representation is that it cannot
  handle strings that contain NUL characters: such strings will appear
  shorter than they were meant to be.  In most application areas, this is
  not a problem, and the @code{char *} type is well usable.
  
  A second problem of this string representation is that
  taking a substring is not cheap:
  it either requires a memory allocation
  or a destructive modification of the string.
  The former has a runtime cost;
  the latter complicates the logic of the program.
  This matters for application areas that analyze text, such as parsers.
  
  In areas where strings with embedded NUL characters need to be handled
  or where taking substrings is a recurrent operation,
  the common approach is to use a @code{char *ptr} pointer variable
  together with a @code{size_t nbytes} variable (or an @code{idx_t nbytes}
  variable, if you want to avoid problems due to integer overflow).  This
  works fine in code that constructs or manipulates strings with embedded
  NUL characters.  But when it comes to @emph{storing} them, for example
  in an array or as key or value of a hash table, one needs a type that
  combines these two fields.
  
  @mindex string-desc
  @mindex xstring-desc
  @mindex string-desc-quotearg
  The Gnulib modules @code{string-desc}, @code{xstring-desc}, and
  @code{string-desc-quotearg} provide such a type.  We call it a
  ``string descriptor'' and name it @code{string_desc_t}.
  
  The type @code{string_desc_t} is a struct that contains a pointer to the
  first byte and the number of bytes of the memory region that make up the
  string.  An additional terminating NUL byte, that may be present in
  memory, is not included in this byte count.  This type implements the
  same concept as @code{std::string_view} in C++, or the @code{String}
  type in Java.
  
  @code{string_desc_t} is a string descriptor to a string that cannot
  be written to.  There is also a type @code{rw_string_desc_t}, that is
  a descriptor for a writable string.
  @code{rw_string_desc_t} compares to @code{string_desc_t}, like the
  pointer type @samp{char *} compares to the pointer type
  @samp{const char *}.
  
  A @code{string_desc_t} or @code{rw_string_desc_t}
  can be passed to a function as an argument, or
  can be the return value of a function.  This is type-safe: If, by
  mistake, a programmer passes a @code{string_desc_t} to a function that
  expects a @code{char *} argument, or vice versa, or assigns a
  @code{string_desc_t} value to a variable of type @code{char *}, or
  vice versa, the compiler will report an error.
  
  Unfortunately, @code{string_desc_t} and @code{rw_string_desc_t}
  being different types, there is no implicit conversion from
  @code{rw_string_desc_t} to @code{string_desc_t}.  In places
  where such a conversion is desired, the (inline) function
  @code{sd_readonly} needs to be called.
  
  Functions related to string descriptors are provided:
  @itemize
  @item
  Side-effect-free operations in @code{"string-desc.h"},
  @item
  Memory-allocating operations in @code{"string-desc.h"},
  @item
  Memory-allocating operations with out-of-memory checking in
  @code{"xstring-desc.h"},
  @item
  Operations with side effects in @code{"string-desc.h"}.
  @end itemize
  
  For outputting a string descriptor, the @code{*printf} family of
  functions cannot be used directly.  A format string directive such as
  @code{"%.*s"} would not work:
  @itemize
  @item
  it would stop the output at the first encountered NUL character,
  @item
  it would require to cast the number of bytes to @code{int}, and thus
  would not work for strings longer than @code{INT_MAX} bytes.
  @end itemize
  @c @noindent Other format string directives don't work either, because
  @c the only way to produce a NUL character in @code{*printf}'s output
  @c is through a dedicated @code{%c} or @code{%lc} directive.
  
  Therefore Gnulib offers
  @itemize
  @item
  a function @code{sd_fwrite} that outputs a string descriptor to
  a @code{FILE} stream,
  @item
  a function @code{sd_write} that outputs a string descriptor to
  a file descriptor,
  @item
  and for those applications where the NUL characters should become
  visible as @samp{\0}, a family of @code{quotearg} based functions, that
  allow to specify the escaping rules in detail.
  @end itemize
  
  The functionality is thus split across three modules as follows:
  @itemize
  @item
  The module @code{string-desc}, under LGPL, defines the type and
  elementary functions.
  @item
  The module @code{xstring-desc}, under GPL, defines the memory-allocating
  functions with out-of-memory checking.
  @item
  The module @code{string-desc-quotearg}, under GPL, defines the
  @code{quotearg} based functions.
  @end itemize
  

Download