From: Richard Hansen <rhansen@rhansen.org>
To: Eli Zaretskii <eliz@gnu.org>
Cc: 55815@debbugs.gnu.org, monnier@iro.umontreal.ca
Subject: bug#55815: [PATCH] bindat: Improve str, strz documentation
Date: Wed, 8 Jun 2022 00:16:51 -0400 [thread overview]
Message-ID: <5bcd8ca9-4be6-5aa4-ac63-b65a89c97b39@rhansen.org> (raw)
In-Reply-To: <831qw077xa.fsf@gnu.org>
[-- Attachment #1.1.1: Type: text/plain, Size: 575 bytes --]
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.
> In any case, you say "unibyte input string" too many time, and that's
> unnecessary.
Done, see attached.
[-- Attachment #1.1.2: v3-0001-bindat-Improve-str-strz-documentation.patch --]
[-- Type: text/x-patch, Size: 2645 bytes --]
From 089b0e54e868e0c28b262d6b09a2d6af322ea31e Mon Sep 17 00:00:00 2001
From: Richard Hansen <rhansen@rhansen.org>
Date: Thu, 2 Jun 2022 21:05:40 -0400
Subject: [PATCH v3] 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 | 36 +++++++++++++++++++++++++++++++++---
1 file changed, 33 insertions(+), 3 deletions(-)
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 668a577870..a93a617c8a 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -3479,11 +3479,41 @@ Bindat Types
@var{bitlen} has to be a multiple of 8.
@item str @var{len}
-String of bytes of length @var{len}.
+Unibyte string (@pxref{Text Representations}) 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 will be null (zero) unless a pre-allocated string
+was provided to @code{bindat-pack}, in which case the remaining bytes
+are left unmodified. When unpacking, any null 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 unibyte
+string (@pxref{Text Representations}). When packing, the entire input
+string is copied to the packed output followed by a null byte. The
+length of the packed output is the length of the input string plus one
+(for the added null byte). The input string must not contain any null
+bytes. When unpacking, the resulting string contains all bytes up to
+(but excluding) the null byte.
+
+If @var{len} is provided: @code{strz} behaves the same as @code{str}
+with one difference: When unpacking, the first null byte 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 one of the
+following is true:
+@itemize
+@item
+The input string is shorter than @var{len} and either no pre-allocated
+string was provided to @code{bindat-pack} or the appropriate byte in
+the pre-allocated string was already null.
+@item
+The input string contains a null byte within the first @var{len}
+bytes.
+@end itemize
+@end quotation
@item vec @var{len} [@var{type}]
Vector of @var{len} elements. The type of the elements is given by
--
2.36.1
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2022-06-08 4:16 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-06 2:22 bug#55815: [PATCH] bindat: Improve str, strz documentation Richard Hansen
2022-06-06 10:59 ` Eli Zaretskii
2022-06-06 23:31 ` Richard Hansen
2022-06-07 16:30 ` Eli Zaretskii
2022-06-07 18:17 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-06-08 4:16 ` Richard Hansen [this message]
2022-06-09 7:30 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5bcd8ca9-4be6-5aa4-ac63-b65a89c97b39@rhansen.org \
--to=rhansen@rhansen.org \
--cc=55815@debbugs.gnu.org \
--cc=eliz@gnu.org \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).