carray doc tweaks, format detection, parameter validation

explicit test code still required

Author: rogerbinns

src/apsw.c

@@ -291,7 +291,9 @@ static int allow_missing_dict_bindings = 0;
 /** .. method:: carray(object: Buffer, *, start: int = 0, stop: int = -1, flags: int = -1)
 
   Indicates a Python object is being provided as a runtime array for the
-  `Carray extension <https://sqlite.org/carray.html>`__.
+  `Carray extension <https://sqlite.org/carray.html>`__.  This is useful if you
+  need a large number of int or float available during a query, as they will
+  be used without calling back into Python code or acquiring the GIL.
 
   .. code-block:: python
 
@@ -301,19 +303,20 @@ static int allow_missing_dict_bindings = 0;
     ids = array.array("l", [1, 73, 94567, 62])
 
     # get records matching those ids
-    for row in con.execute("SELECT * FROM record WHERE record.id in CARRAY(?)",
+    for row in con.execute("SELECT * FROM record WHERE record.id IN CARRAY(?)",
       apsw.carray(ids)):
       print(row)
 
   :param object: Any object that implements the buffer protocol as
      a single contiguous binary data like :class:`bytes`, :class:`bytearray`,
-     :class:`array.array`, numpy etc.
+     :class:`array.array`, numpy.array etc.
   :param start: Index of the first entry to bind
   :param stop: Index to stop at - ie one beyond the last entry bound.  Default
-      is all remaining members.  There is a limit of 2 billion.
+      is all remaining members.  There is a limit of 2 billion, and a minimum
+      of 1.
   :param flags: Indicates if the data is 32/64 bit int, or 64 bit double (floating point).
-      If not supplied then the buffer format is examined and accepted if native byte order.
-      You can see the `format string <https://docs.python.org/3/library/struct.html#byte-order-size-and-alignment>`
+      If not supplied then the buffer format is detected.
+      You can see the `format string <https://docs.python.org/3/library/struct.html#byte-order-size-and-alignment>`__
       with :code:`memoryview(object).format`.  Alternately provide a :data:`constant <apsw.mapping_carray>`
       like :code:`apsw.SQLITE_CARRAY_INT32`
 

src/carray.c

@@ -55,8 +55,76 @@ CArrayBind_init(PyObject *self_, PyObject *args, PyObject *kwargs)
     goto error;
   }
 
-  self->aData = self->view.buf;
-  self->nData = self->view.len / 8;
+  if (flags == -1)
+  {
+    /* try to auto-detect format */
+    if (0 == strcmp(self->view.format, "i"))
+      flags = SQLITE_CARRAY_INT32;
+    else if (0 == strcmp(self->view.format, "l"))
+      flags = SQLITE_CARRAY_INT64;
+    else if (0 == strcmp(self->view.format, "d"))
+      flags = SQLITE_CARRAY_DOUBLE;
+    else
+    {
+      PyErr_Format(PyExc_ValueError, "unable to detect array type from format \"%s\"", self->view.format);
+      goto error;
+    }
+  }
+
+  switch (flags)
+  {
+  case SQLITE_CARRAY_INT32:
+  case SQLITE_CARRAY_INT64:
+  case SQLITE_CARRAY_DOUBLE:
+    break;
+  default:
+    PyErr_Format(PyExc_ValueError, "Unsupported flags value %d", flags);
+    goto error;
+  }
+
+  const unsigned item_size = (flags == SQLITE_CARRAY_INT32) ? 4 : 8;
+  if (self->view.len % item_size)
+  {
+    PyErr_Format(PyExc_ValueError, "Array size %lld bytes is not a multiple of item size %u bytes", self->view.len,
+                 item_size);
+    goto error;
+  }
+
+  size_t nitems = self->view.len / item_size;
+  if (start > nitems)
+  {
+    PyErr_Format(PyExc_ValueError, "Start %lld is beyond end of %lld item array", start, nitems);
+    goto error;
+  }
+  if (stop < 0)
+    stop = nitems;
+  if (stop > nitems)
+  {
+    PyErr_Format(PyExc_ValueError, "Stop %lld is beyond end of %lld item array", stop, nitems);
+    goto error;
+  }
+
+  if (stop < start)
+  {
+    PyErr_Format(PyExc_ValueError, "Stop %lld is before start %lld", stop, start);
+    goto error;
+  }
+
+  nitems = stop - start;
+  if (!nitems)
+  {
+    PyErr_Format(PyExc_ValueError, "CARRAY can't work with a zero item array");
+    goto error;
+  }
+
+  if (nitems >= INT32_MAX)
+  {
+    PyErr_Format(PyExc_ValueError, "CARRAY supports a maximum of 2 billion items");
+    goto error;
+  }
+
+  self->aData = ((uint8_t *)self->view.buf) + (start * item_size);
+  self->nData = nitems;
   self->mFlags = flags;
   return 0;