Fix up struct docstrings, add struct.pack_to function for symmetry

diff --git a/Lib/struct.py b/Lib/struct.py
index b4f56bbbd1db8a129bae1779403f13ba7a260f19..51ee29af8f6ece4007968350c81a54035904fe62 100644 (file)
--- 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 6bc1f8663759f1d764c51b1d75c4b0f2f65adc81..7981a5245a7b576ca129e4852a65efe499ba8e70 100644 (file)
--- 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 026fec1c1bfe9d817482dfde9d6e9b3c986a51b4..4e758a6e0286c249d7d11e2cfb5c033da33cf011 100644 (file)
--- 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 */
 };