From 384b073bdad676bd3e1e39b527321e9a67bfa491 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sat, 22 Jun 2024 20:12:50 -0400
Subject: Add ZIX_NODISCARD attribute to allocating, accessor, and pure API

---
 include/zix/allocator.h  | 1 +
 include/zix/attributes.h | 9 ++++++---
 include/zix/btree.h      | 3 +++
 include/zix/filesystem.h | 1 +
 include/zix/hash.h       | 1 +
 include/zix/path.h       | 4 ++++
 include/zix/ring.h       | 2 ++
 include/zix/tree.h       | 1 +
 8 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/include/zix/allocator.h b/include/zix/allocator.h
index e4d813d..bace039 100644
--- a/include/zix/allocator.h
+++ b/include/zix/allocator.h
@@ -130,6 +130,7 @@ zix_calloc(ZixAllocator* const ZIX_NULLABLE allocator,
 }
 
 /// Convenience wrapper that defers to realloc() if allocator is null
+ZIX_NODISCARD
 static inline void* ZIX_ALLOCATED
 zix_realloc(ZixAllocator* const ZIX_NULLABLE allocator,
             void* const ZIX_NULLABLE         ptr,
diff --git a/include/zix/attributes.h b/include/zix/attributes.h
index a0ed276..249e6a6 100644
--- a/include/zix/attributes.h
+++ b/include/zix/attributes.h
@@ -50,17 +50,20 @@
 /// A pure function in the public API that only reads memory
 #define ZIX_PURE_API \
   ZIX_API            \
-  ZIX_PURE_FUNC
+  ZIX_PURE_FUNC      \
+  ZIX_NODISCARD
 
 /// A const function in the public API that is pure and only reads parameters
 #define ZIX_CONST_API \
   ZIX_API             \
-  ZIX_CONST_FUNC
+  ZIX_CONST_FUNC      \
+  ZIX_NODISCARD
 
 /// A malloc function in the public API that returns allocated memory
 #define ZIX_MALLOC_API \
   ZIX_API              \
-  ZIX_MALLOC_FUNC
+  ZIX_MALLOC_FUNC      \
+  ZIX_NODISCARD
 
 // Printf-like format functions
 #ifdef __GNUC__
diff --git a/include/zix/btree.h b/include/zix/btree.h
index 3161817..ddade81 100644
--- a/include/zix/btree.h
+++ b/include/zix/btree.h
@@ -60,6 +60,7 @@ typedef void (*ZixBTreeDestroyFunc)(void* ZIX_UNSPECIFIED       ptr,
    zix_btree_lower_bound() for details.
 */
 ZIX_API
+ZIX_NODISCARD
 ZixBTree* ZIX_ALLOCATED
 zix_btree_new(ZixAllocator* ZIX_NULLABLE      allocator,
               ZixBTreeCompareFunc ZIX_NONNULL cmp,
@@ -154,6 +155,7 @@ bool
 zix_btree_iter_equals(ZixBTreeIter lhs, ZixBTreeIter rhs);
 
 /// Return true iff `i` is an iterator at the end of a tree
+ZIX_NODISCARD
 static inline bool
 zix_btree_iter_is_end(const ZixBTreeIter i)
 {
@@ -167,6 +169,7 @@ zix_btree_iter_increment(ZixBTreeIter* ZIX_NONNULL i);
 
 /// Return an iterator one past `iter`
 ZIX_API
+ZIX_NODISCARD
 ZixBTreeIter
 zix_btree_iter_next(ZixBTreeIter iter);
 
diff --git a/include/zix/filesystem.h b/include/zix/filesystem.h
index 34f7bcb..221e165 100644
--- a/include/zix/filesystem.h
+++ b/include/zix/filesystem.h
@@ -194,6 +194,7 @@ zix_dir_for_each(const char* ZIX_NONNULL path,
    @return True if the two files have byte-for-byte identical contents.
 */
 ZIX_API
+ZIX_NODISCARD
 bool
 zix_file_equals(ZixAllocator* ZIX_NULLABLE allocator,
                 const char* ZIX_NONNULL    a_path,
diff --git a/include/zix/hash.h b/include/zix/hash.h
index 2bde652..6cd2271 100644
--- a/include/zix/hash.h
+++ b/include/zix/hash.h
@@ -103,6 +103,7 @@ typedef bool (*ZixKeyEqualFunc)(const ZixHashKey* ZIX_NONNULL a,
    @param equal_func A function to test keys for equality.
 */
 ZIX_API
+ZIX_NODISCARD
 ZixHash* ZIX_ALLOCATED
 zix_hash_new(ZixAllocator* ZIX_NULLABLE  allocator,
              ZixKeyFunc ZIX_NONNULL      key_func,
diff --git a/include/zix/path.h b/include/zix/path.h
index 13225e6..22c8202 100644
--- a/include/zix/path.h
+++ b/include/zix/path.h
@@ -36,6 +36,7 @@ ZIX_BEGIN_DECLS
 
 /// Join path `a` and path `b` with a single directory separator between them
 ZIX_API
+ZIX_NODISCARD
 char* ZIX_ALLOCATED
 zix_path_join(ZixAllocator* ZIX_NULLABLE allocator,
               const char* ZIX_NULLABLE   a,
@@ -55,6 +56,7 @@ zix_path_join(ZixAllocator* ZIX_NULLABLE allocator,
    else).
 */
 ZIX_API
+ZIX_NODISCARD
 char* ZIX_ALLOCATED
 zix_path_preferred(ZixAllocator* ZIX_NULLABLE allocator,
                    const char* ZIX_NONNULL    path);
@@ -71,6 +73,7 @@ zix_path_preferred(ZixAllocator* ZIX_NULLABLE allocator,
    zix_canonical_path().
 */
 ZIX_API
+ZIX_NODISCARD
 char* ZIX_ALLOCATED
 zix_path_lexically_normal(ZixAllocator* ZIX_NULLABLE allocator,
                           const char* ZIX_NONNULL    path);
@@ -83,6 +86,7 @@ zix_path_lexically_normal(ZixAllocator* ZIX_NULLABLE allocator,
    up-references).
 */
 ZIX_API
+ZIX_NODISCARD
 char* ZIX_ALLOCATED
 zix_path_lexically_relative(ZixAllocator* ZIX_NULLABLE allocator,
                             const char* ZIX_NONNULL    path,
diff --git a/include/zix/ring.h b/include/zix/ring.h
index a18a50b..db72f41 100644
--- a/include/zix/ring.h
+++ b/include/zix/ring.h
@@ -41,6 +41,7 @@ typedef struct ZixRingImpl ZixRing;
    At most `size` - 1 bytes may be stored in the ring at once.
 */
 ZIX_API
+ZIX_NODISCARD
 ZixRing* ZIX_ALLOCATED
 zix_ring_new(ZixAllocator* ZIX_NULLABLE allocator, uint32_t size);
 
@@ -155,6 +156,7 @@ zix_ring_write(ZixRing* ZIX_NONNULL    ring,
    @return A new empty transaction.
 */
 ZIX_API
+ZIX_NODISCARD
 ZixRingTransaction
 zix_ring_begin_write(ZixRing* ZIX_NONNULL ring);
 
diff --git a/include/zix/tree.h b/include/zix/tree.h
index 0ad37f2..b51fa72 100644
--- a/include/zix/tree.h
+++ b/include/zix/tree.h
@@ -38,6 +38,7 @@ typedef void (*ZixTreeDestroyFunc)(void* ZIX_UNSPECIFIED       ptr,
 
 /// Create a new (empty) tree
 ZIX_API
+ZIX_NODISCARD
 ZixTree* ZIX_ALLOCATED
 zix_tree_new(ZixAllocator* ZIX_NULLABLE      allocator,
              bool                            allow_duplicates,
-- 
cgit v1.2.1