From ee467d0ae79e05d193ea1b125e697c4429a03c35 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Thu, 15 Feb 2007 11:29:08 +0000
Subject: Patch #1494140: Add documentation for the new struct.Struct object. 
 (backport from rev. 53785)

---
 Doc/lib/libstruct.tex | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++
 Misc/NEWS             |  2 ++
 2 files changed, 57 insertions(+)

diff --git a/Doc/lib/libstruct.tex b/Doc/lib/libstruct.tex
index 026968c..d8e48c7 100644
--- a/Doc/lib/libstruct.tex
+++ b/Doc/lib/libstruct.tex
@@ -29,6 +29,13 @@ The module defines the following exception and functions:
   exactly.
 \end{funcdesc}
 
+\begin{funcdesc}{pack_into}{fmt, buffer, offset, v1, v2, \moreargs}
+  Pack the values \code{\var{v1}, \var{v2}, \textrm{\ldots}} according to the given
+  format, write the packed bytes into the writable \var{buffer} starting at
+  \var{offset}.
+  Note that the offset is not an optional argument.
+\end{funcdesc}
+
 \begin{funcdesc}{unpack}{fmt, string}
   Unpack the string (presumably packed by \code{pack(\var{fmt},
   \textrm{\ldots})}) according to the given format.  The result is a
@@ -37,6 +44,14 @@ The module defines the following exception and functions:
   (\code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
 \end{funcdesc}
 
+\begin{funcdesc}{unpack_from}{fmt, buffer\optional{,offset \code{= 0}}}
+  Unpack the \var{buffer} according to tthe given format.
+  The result is a tuple even if it contains exactly one item. The
+  \var{buffer} must contain at least the amount of data required by the
+  format (\code{len(buffer[offset:])} must be at least
+  \code{calcsize(\var{fmt})}).
+\end{funcdesc}
+
 \begin{funcdesc}{calcsize}{fmt}
   Return the size of the struct (and hence of the string)
   corresponding to the given format.
@@ -195,3 +210,43 @@ in effect; standard size and alignment does not enforce any alignment.
   \seemodule{array}{Packed binary storage of homogeneous data.}
   \seemodule{xdrlib}{Packing and unpacking of XDR data.}
 \end{seealso}
+
+\subsection{Struct Objects \label{struct-objects}}
+
+The \module{struct} module also defines the following type:
+
+\begin{classdesc}{Struct}{format}
+  Return a new Struct object which writes and reads binary data according to
+  the format string \var{format}.  Creating a Struct object once and calling
+  its methods is more efficient than calling the \module{struct} functions
+  with the same format since the format string only needs to be compiled once.
+
+ \versionadded{2.5}
+\end{classdesc}
+
+Compiled Struct objects support the following methods and attributes:
+
+\begin{methoddesc}[Struct]{pack}{v1, v2, \moreargs}
+  Identical to the \function{pack()} function, using the compiled format.
+  (\code{len(result)} will equal \member{self.size}.)
+\end{methoddesc}
+
+\begin{methoddesc}[Struct]{pack_into}{buffer, offset, v1, v2, \moreargs}
+  Identical to the \function{pack_into()} function, using the compiled format.
+\end{methoddesc}
+
+\begin{methoddesc}[Struct]{unpack}{string}
+  Identical to the \function{unpack()} function, using the compiled format.
+  (\code{len(string)} must equal \member{self.size}).
+\end{methoddesc}
+
+\begin{methoddesc}[Struct]{unpack_from}{buffer\optional{,offset
+                                              \code{= 0}}}
+  Identical to the \function{unpack_from()} function, using the compiled format.
+  (\code{len(buffer[offset:])} must be at least \member{self.size}).
+\end{methoddesc}
+
+\begin{memberdesc}[Struct]{format}
+  The format string used to construct this Struct object.
+\end{memberdesc}
+
diff --git a/Misc/NEWS b/Misc/NEWS
index 640bc8d..cd72a0c 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -107,6 +107,8 @@ Core and builtins
 Extension Modules
 -----------------
 
+- Patch #1494140: Add documentation for the new struct.Struct object.
+
 - Patch #1657276: Make NETLINK_DNRTMSG conditional.
 
 - Bug #1653736: Complain about keyword arguments to time.isoformat.
-- 
cgit v0.12

