Add a construction note on why QBitArray has a +1 everywhere

It took me several minutes reading the code to figure out why it was
there. It wasn't immediately obvious.

Change-Id: Ic36b3fd24ce84a1b08c73986d3b7ab8a5bfff133
Reviewed-by: Olivier Goffart <ogoffart@woboq.com>
Reviewed-by: Stephen Kelly <stephen.kelly@kdab.com>

1 files changed, 14 insertions, 0 deletions

diff --git a/src/corelib/tools/qbitarray.cpp b/src/corelib/tools/qbitarray.cpp
index e432322aeb..cae8267772 100644
--- a/src/corelib/tools/qbitarray.cpp
+++ b/src/corelib/tools/qbitarray.cpp
@@ -117,6 +117,20 @@ QT_BEGIN_NAMESPACE
     \sa isEmpty()
 */
 
+/*
+ * QBitArray construction note:
+ *
+ * We overallocate the byte array by 1 byte. The first user bit is at
+ * d.data()[1]. On the extra first byte, we store the difference between the
+ * number of bits in the byte array (including this byte) and the number of
+ * bits in the bit array. Therefore, it's always a number between 8 and 15.
+ *
+ * This allows for fast calculation of the bit array size:
+ *    inline int size() const { return (d.size() << 3) - *d.constData(); }
+ *
+ * Note: for an array of zero size, *d.constData() is the QByteArray implicit NUL.
+ */
+
 /*!
     Constructs a bit array containing \a size bits. The bits are
     initialized with \a value, which defaults to false (0).