From b3e9e62599532050fc776c5e8f076915b56c2235 Mon Sep 17 00:00:00 2001
From: David Faulkner <d@davo.co>
Date: Fri, 7 Aug 2026 23:40:47 -0500
Subject: Import official C23 code examples for Modern C (Jens Gustedt, 2024)

- Add official C source files, Makefile, c23-fallback.h, and LICENSE
- Update README.md with study mirror notice
---
 circular.h | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 circular.h

(limited to 'circular.h')

diff --git a/circular.h b/circular.h
new file mode 100644
index 0000000..9631ed3
--- /dev/null
+++ b/circular.h
@@ -0,0 +1,123 @@
+#ifndef CIRCULAR_H
+# define CIRCULAR_H 1
+
+# include "c23-fallback.h"
+# include <stdio.h>
+
+typedef struct circular circular;
+
+/** @brief a type for a circular buffer for @c double values
+ **
+ ** This data structure allows to add @c double values in rear and to
+ ** take them out in front. Each such structure has a maximal amount
+ ** of elements that can be stored in it.
+ **
+ **/
+/*
+ *
+ * Direct access to all the elements is deprecated.
+ */
+struct circular {
+  size_t  start [[deprecated("privat")]]; /* First element     */
+  size_t  len   [[deprecated("privat")]]; /* Number of elements*/
+  size_t  cap   [[deprecated("privat")]]; /* Maximum capacity  */
+  double* tab   [[deprecated("privat")]]; /* Data array        */
+};
+
+/**
+ ** @name Initialization and destruction
+ ** @{
+ **/
+
+/** @brief Initialize a circular buffer @a c with maximally @a
+ ** cap elements.
+ **
+ ** Only use this function on an uninitialized buffer.
+ **
+ ** Each buffer that is initialized with this function must be
+ ** destroyed with a call to ::circular_destroy.
+ **/
+circular* circular_init(circular* c, size_t cap);
+
+/** @brief Destroy circular buffer @a c
+ **
+ ** @a c must have been initialized with a call to ::circular_init
+ **/
+void circular_destroy(circular* c);
+
+/** @brief Delete circular buffer @a c
+ **
+ ** @a c must have been allocated with a call to ::circular_new
+ **/
+inline
+void circular_delete(circular* c) {
+  circular_destroy(c);
+  free(c);
+}
+/**
+ ** @}
+ **/
+
+/** @brief Allocate and initialize a circular buffer with maximally
+ ** @a len elements.
+ **
+ ** Each buffer that is allocated with this function must be deleted
+ ** with a call to ::circular_delete.
+ **/
+[[nodiscard("pointer to allocated data dropped")]]
+[[__gnu__::__malloc__, __gnu_free__(circular_delete)]]
+inline
+circular* circular_new(size_t len) {
+  return circular_init(malloc(sizeof(circular)), len);
+}
+
+/**
+ ** @name Using elements of a circular
+ ** @{
+ **/
+
+/** @brief Append a new element with value @a value to the buffer @a c
+ **
+ ** @return c if the new element could be appended, null otherwise.
+ **/
+circular* circular_append(circular* c, double value);
+
+/** @brief Remove the oldest element from @a c and return its value
+ **
+ ** @return the removed element if it exists, @c 0.0 otherwise.
+ **/
+double circular_pop(circular* c);
+
+/** @brief Return a pointer to position @a pos in buffer @a c
+ **
+ ** @return a pointer to element @a pos of the buffer, null otherwise.
+ **/
+double* circular_element(circular const* c, size_t pos);
+
+
+/**
+ ** @}
+ **/
+
+/**
+ ** @name Maintain a circular
+ ** @{
+ **/
+
+/** @brief Return the number of elements stored. */
+size_t circular_getlength(circular const* c);
+
+/** @brief Resize to capacity @a cap. */
+[[nodiscard("returned pointer replaces function argument")]]
+circular* circular_resize(circular* c, size_t cap);
+
+/** @brief Print the buffer values to stream @a s. */
+void circular_fput(circular* c, FILE* s);
+
+/**
+ ** @}
+ **/
+
+
+
+#endif
-- 
cgit v1.2.3