From cf0fb8bfeef0cbbf00b99c272f6de8c3d48573e8 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Thu, 23 Jul 1998 21:18:25 +0000
Subject: [PATCH] Document the 'p' format character.

Clean up some of the markup.
---
 Doc/lib/libstruct.tex | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
index 22595cb41b8..08b930c0dfe 100644
--- a/Doc/lib/libstruct.tex
+++ b/Doc/lib/libstruct.tex
@@ -55,6 +55,7 @@ and Python values should be obvious given their types:
   \lineiii{f}{float}{float}
   \lineiii{d}{double}{float}
   \lineiii{s}{char[]}{string}
+  \lineiii{p}{char[]}{string}
 \end{tableiii}
 
 A format character may be preceded by an integral repeat count; e.g.\
@@ -63,7 +64,7 @@ the format string \code{'4h'} means exactly the same as \code{'hhhh'}.
 Whitespace characters between formats are ignored; a count and its
 format must not contain whitespace though.
 
-For the \code{'s'} format character, the count is interpreted as the
+For the \character{s} format character, the count is interpreted as the
 size of the string, not a repeat count like for the other format
 characters; e.g. \code{'10s'} means a single 10-byte string, while
 \code{'10c'} means 10 characters.  For packing, the string is
@@ -72,7 +73,15 @@ For unpacking, the resulting string always has exactly the specified
 number of bytes.  As a special case, \code{'0s'} means a single, empty
 string (while \code{'0c'} means 0 characters).
 
-For the \code{'I'} and \code{'L'} format characters, the return
+The \character{p} format character can be used to encode a Pascal
+string.  The first byte is the length of the stored string, with the
+bytes of the string following.  If count is given, it is used as the
+total number of bytes used, including the length byte.  If the string
+passed in to \function{pack()} is too long, the stored representation
+is truncated.  If the string is too short, padding is used to ensure
+that exactly enough bytes are used to satisfy the count.
+
+For the \character{I} and \character{L} format characters, the return
 value is a Python long integer.
 
 By default, C numbers are represented in the machine's native format
@@ -91,7 +100,7 @@ according to the following table:
   \lineiii{!}{network (= big-endian)}{standard}
 \end{tableiii}
 
-If the first character is not one of these, \code{'@'} is assumed.
+If the first character is not one of these, \character{@} is assumed.
 
 Native byte order is big-endian or little-endian, depending on the
 host system (e.g. Motorola and Sun are big-endian; Intel and DEC are
@@ -105,16 +114,16 @@ for any type (so you have to use pad bytes); short is 2 bytes; int and
 long are 4 bytes.  Float and double are 32-bit and 64-bit IEEE floating
 point numbers, respectively.
 
-Note the difference between \code{'@'} and \code{'='}: both use native
+Note the difference between \character{@} and \character{=}: both use native
 byte order, but the size and alignment of the latter is standardized.
 
-The form \code{'!'} is available for those poor souls who claim they
+The form \character{!} is available for those poor souls who claim they
 can't remember whether network byte order is big-endian or
 little-endian.
 
 There is no way to indicate non-native byte order (i.e. force
-byte-swapping); use the appropriate choice of \code{'<'} or
-\code{'>'}.
+byte-swapping); use the appropriate choice of \character{<} or
+\character{>}.
 
 Examples (all using native byte order, size and alignment, on a
 big-endian machine):