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>

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.

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
 ---
 

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)

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')

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`.

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

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]*/