--- Begin Message ---
Subject: |
[PATCH] bindat: Improve str, strz documentation |
Date: |
Sun, 5 Jun 2022 22:22:01 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1 |
X-Debbugs-CC: monnier@iro.umontreal.ca
* 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
0001-bindat-Improve-str-strz-documentation.patch
Description: Text Data
--- End Message ---
--- Begin Message ---
Subject: |
Re: bug#55815: [PATCH] bindat: Improve str, strz documentation |
Date: |
Thu, 09 Jun 2022 10:30:34 +0300 |
> Date: Wed, 8 Jun 2022 00:16:51 -0400
> Cc: 55815@debbugs.gnu.org, monnier@iro.umontreal.ca
> From: Richard Hansen <rhansen@rhansen.org>
>
> 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.
--- End Message ---