Subject: bug#55815: closed (Re: bug#55815: [PATCH] bindat: Improve str, strz documentation)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 09 Jun 2022 07:31:02 +0000

Your bug report

#55815: [PATCH] bindat: Improve str, strz documentation

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
55815: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=55815
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#55815: [PATCH] bindat: Improve str, strz documentation
From: Eli Zaretskii <[email-masked]>
To: Richard Hansen <[email-masked]>
Cc: [email-masked], [email-masked]
Date: Thu, 09 Jun 2022 10:30:34 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> Date: Wed, 8 Jun 2022 00:16:51 -0400
> Cc: [email-masked], [email-masked]
> From: Richard Hansen <[email-masked]>
> 
> On 6/7/22 12:30, Eli Zaretskii wrote:
> >> Right now all three of those are unibyte, but in a future patch I 
> >> plan on changing the first to accept unibyte-convertible multibyte 
> >> input strings.
> > 
> > Not sure I understand: what do you mean by "unibyte-convertible 
> > multibyte input strings", and how do they differ from the other kinds?
> 
> I mean multibyte strings that do not contain characters that will cause string-to-unibyte to signal an error.

IOW, multibyte strings that contain only ASCII characters and
characters of the 'eight-bit' charset.

> > In any case, you say "unibyte input string" too many time, and that's 
> > unnecessary.
> 
> Done, see attached.

Thanks, installed.

Subject: [PATCH] bindat: Improve str, strz documentation
From: Richard Hansen <[email-masked]>
To: [email-masked]
Date: Sun, 5 Jun 2022 22:22:01 -0400
List-Id: <debbugs-submit.debbugs.gnu.org>

X-Debbugs-CC: [email-masked]

* doc/lispref/processes.texi (Bindat Types): Expand the documentation
for the `str' and `strz' types to clarify expectations and explain
edge case behavior.
---
  doc/lispref/processes.texi | 26 +++++++++++++++++++++++---
  1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 668a577870..68621d32a8 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -3479,11 +3479,31 @@ Bindat Types
  @var{bitlen} has to be a multiple of 8.
  
  @item str @var{len}
-String of bytes of length @var{len}.
+String of length @var{len}.  When packing, the first @var{len} bytes
+of the input string are copied to the packed output.  If the input
+string is shorter than @var{len}, the remaining bytes are set to zero.
+The input string must be unibyte (@pxref{Text Representations}).  When
+unpacking, any zero bytes in the packed input string will appear in
+the unpacked output.
  
  @item strz &optional @var{len}
-Zero-terminated string of bytes, can be of arbitrary length or in a fixed-size
-field with length @var{len}.
+If @var{len} is not provided: Variable-length null-terminated string.
+When packing, the entire input string is copied to the packed output
+followed by a zero byte (null terminator).  The input string must be
+unibyte (@pxref{Text Representations}) and must not contain any zero
+bytes.  When unpacking, the resulting string contains all bytes up to
+(but excluding) the null terminator.
+
+If @var{len} is provided: @code{strz} behaves the same as @code{str}
+with one difference. When unpacking, the first zero byte (null
+terminator) encountered in the packed string and all subsequent bytes
+are excluded from the unpacked result.
+
+@quotation Caution
+The packed output will not be null-terminated unless the input string
+is shorter than @var{len} or it contains a zero byte within the first
+@var{len} bytes.
+@end quotation
  
  @item vec @var{len} [@var{type}]
  Vector of @var{len} elements.  The type of the elements is given by
-- 
2.36.1

From 329ec3650c0ccc8a01bd6196805d5136218ef391 Mon Sep 17 00:00:00 2001
From: Richard Hansen <[email-masked]>
Date: Thu, 2 Jun 2022 21:05:40 -0400
Subject: [PATCH] bindat: Improve str, strz documentation

* doc/lispref/processes.texi (Bindat Types): Expand the documentation
for the `str' and `strz' types to clarify expectations and explain
edge case behavior.
---
 doc/lispref/processes.texi | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 668a577870..68621d32a8 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -3479,11 +3479,31 @@ Bindat Types
 @var{bitlen} has to be a multiple of 8.
 
 @item str @var{len}
-String of bytes of length @var{len}.
+String of length @var{len}.  When packing, the first @var{len} bytes
+of the input string are copied to the packed output.  If the input
+string is shorter than @var{len}, the remaining bytes are set to zero.
+The input string must be unibyte (@pxref{Text Representations}).  When
+unpacking, any zero bytes in the packed input string will appear in
+the unpacked output.
 
 @item strz &optional @var{len}
-Zero-terminated string of bytes, can be of arbitrary length or in a fixed-size
-field with length @var{len}.
+If @var{len} is not provided: Variable-length null-terminated string.
+When packing, the entire input string is copied to the packed output
+followed by a zero byte (null terminator).  The input string must be
+unibyte (@pxref{Text Representations}) and must not contain any zero
+bytes.  When unpacking, the resulting string contains all bytes up to
+(but excluding) the null terminator.
+
+If @var{len} is provided: @code{strz} behaves the same as @code{str}
+with one difference. When unpacking, the first zero byte (null
+terminator) encountered in the packed string and all subsequent bytes
+are excluded from the unpacked result.
+
+@quotation Caution
+The packed output will not be null-terminated unless the input string
+is shorter than @var{len} or it contains a zero byte within the first
+@var{len} bytes.
+@end quotation
 
 @item vec @var{len} [@var{type}]
 Vector of @var{len} elements.  The type of the elements is given by
-- 
2.36.1