gh-114894: add array.array.clear() method (#114919)

Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: AN Long <aisk@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

diff --git a/Doc/library/array.rst b/Doc/library/array.rst
index a0e8bb20a098fdc49d563aa31ca4bbe01d08070f..043badf05ffc126238bf99130d5b5cbf525c8452 100644 (file)
--- a/Doc/library/array.rst
+++ b/Doc/library/array.rst
@@ -215,6 +215,13 @@ The module defines the following type:
       Remove the first occurrence of *x* from the array.
 
 
+   .. method:: clear()
+
+      Remove all elements from the array.
+
+      .. versionadded:: 3.13
+
+
    .. method:: reverse()
 
       Reverse the order of the items in the array.

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index de79bd979aff80e6a351d814bbc072b6a3453385..aee37737a9990accbc61fb9e73a4c02c6429b45a 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -185,6 +185,9 @@ array
   It can be used instead of ``'u'`` type code, which is deprecated.
   (Contributed by Inada Naoki in :gh:`80480`.)
 
+* Add ``clear()`` method in order to implement ``MutableSequence``.
+  (Contributed by Mike Zimin in :gh:`114894`.)
+
 ast
 ---
 

diff --git a/Lib/test/test_array.py b/Lib/test/test_array.py
index a219fa365e7f20212c5253c2096d92cf19394cb8..95383be9659eb9ed298879121c45d2b7755d2579 100755 (executable)
--- a/Lib/test/test_array.py
+++ b/Lib/test/test_array.py
@@ -1014,6 +1014,29 @@ class BaseTest:
             array.array(self.typecode, self.example[3:]+self.example[:-1])
         )
 
+    def test_clear(self):
+        a = array.array(self.typecode, self.example)
+        with self.assertRaises(TypeError):
+            a.clear(42)
+        a.clear()
+        self.assertEqual(len(a), 0)
+        self.assertEqual(a.typecode, self.typecode)
+
+        a = array.array(self.typecode)
+        a.clear()
+        self.assertEqual(len(a), 0)
+        self.assertEqual(a.typecode, self.typecode)
+
+        a = array.array(self.typecode, self.example)
+        a.clear()
+        a.append(self.example[2])
+        a.append(self.example[3])
+        self.assertEqual(a, array.array(self.typecode, self.example[2:4]))
+
+        with memoryview(a):
+            with self.assertRaises(BufferError):
+                a.clear()
+
     def test_reverse(self):
         a = array.array(self.typecode, self.example)
         self.assertRaises(TypeError, a.reverse, 42)

diff --git a/Lib/test/test_collections.py b/Lib/test/test_collections.py
index 7e6f811e17cfa2d25154f54b1d6891186d5e3696..1fb492ecebd668757a17c1797da610821826cabe 100644 (file)
--- a/Lib/test/test_collections.py
+++ b/Lib/test/test_collections.py
@@ -1,5 +1,6 @@
 """Unit tests for collections.py."""
 
+import array
 import collections
 import copy
 import doctest
@@ -1972,6 +1973,7 @@ class TestCollectionABCs(ABCTestCase):
         for sample in [list, bytearray, deque]:
             self.assertIsInstance(sample(), MutableSequence)
             self.assertTrue(issubclass(sample, MutableSequence))
+        self.assertTrue(issubclass(array.array, MutableSequence))
         self.assertFalse(issubclass(str, MutableSequence))
         self.validate_abstract_methods(MutableSequence, '__contains__', '__iter__',
             '__len__', '__getitem__', '__setitem__', '__delitem__', 'insert')

diff --git a/Misc/NEWS.d/next/Library/2024-02-02-15-50-13.gh-issue-114894.DF-dSd.rst b/Misc/NEWS.d/next/Library/2024-02-02-15-50-13.gh-issue-114894.DF-dSd.rst
new file mode 100644 (file)
index 0000000..ec620f2
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-02-02-15-50-13.gh-issue-114894.DF-dSd.rst
@@ -0,0 +1 @@
+Add :meth:`array.array.clear`.

diff --git a/Modules/arraymodule.c b/Modules/arraymodule.c
index b97ade6126fa08fae2d6be9bfaaabd7bccfbc70b..df09d9d84789f7329adbfd7dfb125efa8618a663 100644 (file)
--- a/Modules/arraymodule.c
+++ b/Modules/arraymodule.c
@@ -868,6 +868,21 @@ array_slice(arrayobject *a, Py_ssize_t ilow, Py_ssize_t ihigh)
     return (PyObject *)np;
 }
 
+/*[clinic input]
+array.array.clear
+
+Remove all items from the array.
+[clinic start generated code]*/
+
+static PyObject *
+array_array_clear_impl(arrayobject *self)
+/*[clinic end generated code: output=5efe0417062210a9 input=5dffa30e94e717a4]*/
+{
+    if (array_resize(self, 0) == -1) {
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
 
 /*[clinic input]
 array.array.__copy__
@@ -2342,6 +2357,7 @@ static PyMethodDef array_methods[] = {
     ARRAY_ARRAY_APPEND_METHODDEF
     ARRAY_ARRAY_BUFFER_INFO_METHODDEF
     ARRAY_ARRAY_BYTESWAP_METHODDEF
+    ARRAY_ARRAY_CLEAR_METHODDEF
     ARRAY_ARRAY___COPY___METHODDEF
     ARRAY_ARRAY_COUNT_METHODDEF
     ARRAY_ARRAY___DEEPCOPY___METHODDEF

diff --git a/Modules/clinic/arraymodule.c.h b/Modules/clinic/arraymodule.c.h
index 0b764e43e1943752ca836b866619928f48d3c974..60a03fe012550eebcfdbe9993eb10825ec986e7c 100644 (file)
--- a/Modules/clinic/arraymodule.c.h
+++ b/Modules/clinic/arraymodule.c.h
@@ -5,6 +5,24 @@ preserve
 #include "pycore_abstract.h"      // _PyNumber_Index()
 #include "pycore_modsupport.h"    // _PyArg_CheckPositional()
 
+PyDoc_STRVAR(array_array_clear__doc__,
+"clear($self, /)\n"
+"--\n"
+"\n"
+"Remove all items from the array.");
+
+#define ARRAY_ARRAY_CLEAR_METHODDEF    \
+    {"clear", (PyCFunction)array_array_clear, METH_NOARGS, array_array_clear__doc__},
+
+static PyObject *
+array_array_clear_impl(arrayobject *self);
+
+static PyObject *
+array_array_clear(arrayobject *self, PyObject *Py_UNUSED(ignored))
+{
+    return array_array_clear_impl(self);
+}
+
 PyDoc_STRVAR(array_array___copy____doc__,
 "__copy__($self, /)\n"
 "--\n"
@@ -667,4 +685,4 @@ PyDoc_STRVAR(array_arrayiterator___setstate____doc__,
 
 #define ARRAY_ARRAYITERATOR___SETSTATE___METHODDEF    \
     {"__setstate__", (PyCFunction)array_arrayiterator___setstate__, METH_O, array_arrayiterator___setstate____doc__},
-/*[clinic end generated code: output=3be987238a4bb431 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=52c55d9b1d026c1c input=a9049054013a1b77]*/