From 1fcdc232dbfbd05b92eaed42bf9f779d27c55a92 Mon Sep 17 00:00:00 2001
From: Bob Ippolito <bob@redivi.com>
Date: Sat, 27 May 2006 12:11:36 +0000
Subject: Fix up struct docstrings, add struct.pack_to function for symmetry

---
 Lib/struct.py           | 12 ++++++++++++
 Lib/test/test_struct.py | 22 ++++++++++++++++++++++
 Modules/_struct.c       | 16 ++++++++--------
 3 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/Lib/struct.py b/Lib/struct.py
index b4f56bb..51ee29a 100644
--- a/Lib/struct.py
+++ b/Lib/struct.py
@@ -62,6 +62,18 @@ def pack(fmt, *args):
         o = _compile(fmt)
     return o.pack(*args)
 
+def pack_to(fmt, buf, offset, *args):
+    """
+    Pack the values v2, v2, ... according to fmt, write
+    the packed bytes into the writable buffer buf starting at offset.
+    See struct.__doc__ for more on format strings.
+    """
+    try:
+        o = _cache[fmt]
+    except KeyError:
+        o = _compile(fmt)
+    return o.pack_to(buf, offset, *args)
+
 def unpack(fmt, s):
     """
     Unpack the string, containing packed C structure data, according
diff --git a/Lib/test/test_struct.py b/Lib/test/test_struct.py
index 6bc1f86..7981a52 100644
--- a/Lib/test/test_struct.py
+++ b/Lib/test/test_struct.py
@@ -509,6 +509,28 @@ class PackBufferTestCase(unittest.TestCase):
         self.assertRaises(struct.error, s.pack_to, small_buf, 0, test_string)
         self.assertRaises(struct.error, s.pack_to, small_buf, 2, test_string)
 
+    def test_pack_to_fn( self ):
+        test_string = 'Reykjavik rocks, eow!'
+        writable_buf = array.array('c', ' '*100)
+        fmt = '21s'
+        pack_to = lambda *args: struct.pack_to(fmt, *args)
+
+        # Test without offset
+        pack_to(writable_buf, 0, test_string)
+        from_buf = writable_buf.tostring()[:len(test_string)]
+        self.assertEquals(from_buf, test_string)
+
+        # Test with offset.
+        pack_to(writable_buf, 10, test_string)
+        from_buf = writable_buf.tostring()[:len(test_string)+10]
+        self.assertEquals(from_buf, (test_string[:10] + test_string))
+
+        # Go beyond boundaries.
+        small_buf = array.array('c', ' '*10)
+        self.assertRaises(struct.error, pack_to, small_buf, 0, test_string)
+        self.assertRaises(struct.error, pack_to, small_buf, 2, test_string)
+
+
 def test_main():
     test.test_support.run_unittest(PackBufferTestCase)
 
diff --git a/Modules/_struct.c b/Modules/_struct.c
index 026fec1..4e758a6 100644
--- a/Modules/_struct.c
+++ b/Modules/_struct.c
@@ -1277,7 +1277,7 @@ fail:
 
 
 PyDoc_STRVAR(s_unpack__doc__,
-"unpack(str) -> (v1, v2, ...)\n\
+"S.unpack(str) -> (v1, v2, ...)\n\
 \n\
 Return tuple containing values unpacked according to this Struct's format.\n\
 Requires len(str) == self.size. See struct.__doc__ for more on format\n\
@@ -1299,7 +1299,7 @@ s_unpack(PyObject *self, PyObject *inputstr)
 }
 
 PyDoc_STRVAR(s_unpack_from__doc__,
-"unpack_from(buffer[, offset]) -> (v1, v2, ...)\n\
+"S.unpack_from(buffer[, offset]) -> (v1, v2, ...)\n\
 \n\
 Return tuple containing values unpacked according to this Struct's format.\n\
 Unlike unpack, unpack_from can unpack values from any object supporting\n\
@@ -1407,7 +1407,7 @@ s_pack_internal(PyStructObject *soself, PyObject *args, int offset, char* buf)
 
 
 PyDoc_STRVAR(s_pack__doc__,
-"pack(v1, v2, ...) -> string\n\
+"S.pack(v1, v2, ...) -> string\n\
 \n\
 Return a string containing values v1, v2, ... packed according to this\n\
 Struct's format. See struct.__doc__ for more on format strings.");
@@ -1445,11 +1445,11 @@ s_pack(PyObject *self, PyObject *args)
 }
 
 PyDoc_STRVAR(s_pack_to__doc__,
-"pack_to(buffer, offset, v1, v2, ...)\n\
+"S.pack_to(buffer, offset, v1, v2, ...)\n\
 \n\
 Pack the values v2, v2, ... according to this Struct's format, write \n\
-the packed bytes into the given buffer at the given offset.  Note that \n\
-the offset is not an optional argument.  See struct.__doc__ for \n\
+the packed bytes into the writable buffer buf starting at offset.  Note\n\
+that the offset is not an optional argument.  See struct.__doc__ for \n\
 more on format strings.");
 
 static PyObject *
@@ -1530,8 +1530,8 @@ PyDoc_STRVAR(s__doc__, "Compiled struct object");
 #define OFF(x) offsetof(PyStructObject, x)
 
 static PyGetSetDef s_getsetlist[] = {
-	{"format", (getter)s_get_format, (setter)NULL, "buffer's capacity", NULL},
-	{"size", (getter)s_get_size, (setter)NULL, "buffer's position", NULL},
+	{"format", (getter)s_get_format, (setter)NULL, "struct format string", NULL},
+	{"size", (getter)s_get_size, (setter)NULL, "struct size in bytes", NULL},
 	{NULL} /* sentinel */
 };
 
-- 
cgit v0.12