add an example object

diff --git a/example.c b/example.c
new file mode 100644 (file)
index 0000000..05b1036
--- /dev/null
+++ b/example.c
@@ -0,0 +1,50 @@
+/*
+ * ProjectName: something small
+ *
+ * Copyright (C) 2025 Niki Roo
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#include <string.h>
+#include <stdlib.h>
+
+#include "example.h"
+
+example_t *new_example() {
+        example_t *self = malloc(sizeof(example_t));
+        if (!init_example(self)) {
+                free(self);
+                self = NULL;
+        }
+
+        return self;
+}
+
+int init_example(example_t *self) {
+        strcpy(self->CNAME, "[example ]");
+       return 1;
+}
+
+void free_example(example_t *self) {
+        if (self)
+                uninit_example(self);
+
+        free(self);
+}
+
+void uninit_example(example_t *self) {
+        self->CNAME[0] = '!';
+}
+

diff --git a/example.h b/example.h
new file mode 100644 (file)
index 0000000..49c47c7
--- /dev/null
+++ b/example.h
@@ -0,0 +1,64 @@
+/** 
+ * @file example.h
+ * @author Niki
+ * @date 2025
+ * 
+ * @brief bla
+ *
+ * blablabla
+ *
+ */
+
+#ifndef EXAMPLE_H
+#define EXAMPLE_H
+
+/**
+ * @brief bla
+ *
+ * blablabla
+ */
+typedef struct {
+        char CNAME[10];
+        size_t count;
+        void *priv;
+} example_t;
+
+/**
+ * Create a new example.
+ *
+ * @note always identical to <tt>malloc</tt> + <tt>init_example</tt>
+ *
+ * @see malloc()
+ * @see init_example(example_t *self)
+ *
+ * @return a new example (you must later call `free_example()`)
+ */
+example_t *new_example();
+
+/**
+ * Initialise a new example.
+ */
+int init_example(example_t *self);
+
+/** 
+ * Free the resources held for the given example: you must not use it any more.
+ *
+ * @note always equivalent to <tt>uninit_example</tt> + <tt>free</tt>
+ *
+ * @see uninit_example(example_t *self)
+ * @see free(void *data)
+ */
+void free_example(example_t *self);
+
+/**
+ * Free the resources held for the given example: you must not use it any more
+ * unless you call <tt>init_example</tt> on it again.
+ *
+ * The memory pointed to by <tt>self</tt> is <i>not</i> free'd.
+ *
+ *
+ * @see init_example(example_t *self)
+ */
+void uninit_example(example_t *self);
+
+#endif /* EXAMPLE_H */