Refactor `assert_debug.h` to add new debug assertion aliases and update include …

…directives across modules to improve clarity and enforce better assertion practices.

Refactor `assert_debug.h` to add new debug assertion aliases and update include …
…directives across modules to improve clarity and enforce better assertion practices.
m-holger
1 parent 2f232e8e
Showing 10 changed files with 29 additions and 19 deletions
README-maintainer.md
libqpdf/Pl_Base64.cc
libqpdf/QPDFObjectHandle.cc
libqpdf/QPDFWriter.cc
libqpdf/QPDF_encryption.cc
libqpdf/QPDF_optimization.cc
libqpdf/qpdf/InputSource_private.hh
libqpdf/qpdf/Pipeline_private.hh
libqpdf/qpdf/Util.hh
libqpdf/qpdf/assert_debug.h
@@ -200,7 +200,15 @@ Building docs from pull requests is also enabled.
   * Test code: #include <qpdf/assert_test.h> first.
   * Debug code: #include <qpdf/assert_debug.h> first and use
-    qpdf_assert_debug instead of assert.
+    qpdf_assert_debug instead of assert. Note that <qpdf/Util.hh>
+    includes assert_debug.h. Include this instead if 'At most one
+    qpdf/assert header ...' errors are encounted, especially when
+    using assert in private header files.
+  * Use 'qpdf_expect', 'qpdf_static_expect', 'qpdf_ensures' and
+    'qpdf_ionvariant' to document pre/post-conditions and ivariants.
+    This requires inclusion of 'assert_debug.h' or 'Util.hh'. Remember
+    that these (except for 'qpdf_static_expect') are only checked in
+    debug builds.
   These rules are enforced by the check-assert test. This practices
   serves to
-#include <qpdf/assert_debug.h>
-
 #include <qpdf/Pl_Base64.hh>
 #include <qpdf/QIntC.hh>
-#include <qpdf/QUtil.hh>
 #include <qpdf/Util.hh>
 #include <cstring>
-#include <qpdf/assert_debug.h>
-
 #include <qpdf/QPDFObjectHandle_private.hh>
 #include <qpdf/JSON_writer.hh>
-#include <qpdf/assert_debug.h>
-
 #include <qpdf/qpdf-config.h> // include early for large file support
 #include <qpdf/QPDFWriter_private.hh>
-// This file implements methods from the QPDF class that involve
-// encryption.
-
-#include <qpdf/assert_debug.h>
+// This file implements methods from the QPDF class that involve encryption.
 #include <qpdf/QPDF_private.hh>
 // See the "Optimization" section of the manual.
-#include <qpdf/assert_debug.h>
-
 #include <qpdf/QPDF_private.hh>
 #include <qpdf/QPDFExc.hh>
@@ -3,6 +3,7 @@
 #include <qpdf/Buffer.hh>
 #include <qpdf/InputSource.hh>
+#include <qpdf/Util.hh>
 #include <limits>
 #include <sstream>
 #ifndef PIPELINE_PRIVATE_HH
 #define PIPELINE_PRIVATE_HH
+#include <qpdf/Types.h>
+
 #include <qpdf/Pipeline.hh>
 #include <qpdf/Pl_Flate.hh>
-#include <qpdf/Types.h>
+#include <qpdf/Util.hh>
 namespace qpdf::pl
 {
 #ifndef UTIL_HH
 #define UTIL_HH
+#include <qpdf/assert_debug.h>
+
 #include <string>
+#include <utility>
 namespace qpdf::util
 {
-    // This is a collection of useful utility functions for qpdf internal use. They include inline
-    // functions, some of which are exposed as regular functions in QUtil. Implementations are in
-    // QUtil.cc.
+    // qpdf::util is a collection of useful utility functions for qpdf internal use. It includes
+    // inline functions, some of which are exposed as regular functions in QUtil. Implementations
+    // are in QUtil.cc.
     inline constexpr char
     hex_decode_char(char digit)
@@ -12,7 +12,15 @@
 #else
 # define QPDF_ASSERT_H
-# include <assert.h>
+# include <cassert>
 # define qpdf_assert_debug assert
+// Alias for assert. Pre-condition is only enforced in debug builds.
+# define qpdf_expect assert
+// Alias for assert. Post-condition is only enforced in debug builds.
+# define qpdf_ensures assert
+// Alias for assert. Invariant is only enforced in debug builds.
+# define qpdf_invariant assert
+// Alias for static_assert.
+# define qpdf_static_expect static_assert
 #endif /* QPDF_ASSERT_H */