From 144c40f3a9081b5097d03286263ea77b4b2e55a0 Mon Sep 17 00:00:00 2001
From: Avinash Maddikonda <45308169+SFM61319@users.noreply.github.com>
Date: Wed, 26 Jul 2023 17:16:52 +0530
Subject: [PATCH] Add `char` type, related constants and functions

---
 .github/ISSUE_TEMPLATE/bug_report.yml |   1 +
 CMakeLists.txt                        |   4 +-
 Doxyfile                              |   2 +-
 cspell.json                           |   2 +-
 include/ds/char.h                     | 109 ++++++++++++++++++++++++++
 src/ds/char.c                         |   8 ++
 tests/CMakeLists.txt                  |   1 +
 tests/test_ds/test_char.cpp           |  18 +++++
 8 files changed, 142 insertions(+), 3 deletions(-)
 create mode 100644 include/ds/char.h
 create mode 100644 src/ds/char.c
 create mode 100644 tests/test_ds/test_char.cpp

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index ec73876..d67e8ac 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -40,6 +40,7 @@ body:
       description: Since what version of `ds` have you been seeing this problem?
       multiple: false
       options:
+        - 0.3.0
         - 0.2.0
         - 0.1.0
     validations:
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 17f000c..4729ebf 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.22.1...3.25.1 FATAL_ERROR)
 project("ds"
-  VERSION 0.2.0
+  VERSION 0.3.0
   DESCRIPTION "A C library to safely yet efficiently work with UTF-8–encoded, growable dynamic strings."
   HOMEPAGE_URL "https://github.com/SFM61319/ds"
   # While `ds` itself is written in C, the tests are written in C++ (as they can not be written in C).
@@ -50,9 +50,11 @@ set(DS_PRIVATE_SOURCES_DIR "${DS_SRC_DIR}")
 # For example, for a new public header file created in `include/ds/foo.h`,
 # the appended file path must be `"${DS_PUBLIC_HEADERS_DIR}/${PROJECT_NAME}/foo.h"`.
 set(DS_PUBLIC_HEADERS
+  "${DS_PUBLIC_HEADERS_DIR}/${PROJECT_NAME}/char.h"
   "${DS_PUBLIC_HEADERS_DIR}/${PROJECT_NAME}/helpers.h"
   "${DS_PUBLIC_HEADERS_DIR}/${PROJECT_NAME}/usize.h")
 set(DS_PRIVATE_SOURCES
+  "${DS_PRIVATE_SOURCES_DIR}/${PROJECT_NAME}/char.c"
   "${DS_PRIVATE_SOURCES_DIR}/${PROJECT_NAME}/helpers.c"
   "${DS_PRIVATE_SOURCES_DIR}/${PROJECT_NAME}/usize.c")
 
diff --git a/Doxyfile b/Doxyfile
index db536b0..5905aca 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -47,7 +47,7 @@ PROJECT_NAME           = "ds"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.2.0"
+PROJECT_NUMBER         = "0.3.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
diff --git a/cspell.json b/cspell.json
index 0c4c082..36de68a 100644
--- a/cspell.json
+++ b/cspell.json
@@ -39,5 +39,5 @@
   "userWords": [],
   "validateDirectives": true,
   "version": "0.2",
-  "words": ["ds", "dyn", "sfm", "str", "streq", "usize", "utf", "zu"]
+  "words": ["ds", "dyn", "nul", "sfm", "str", "streq", "usize", "utf", "zu"]
 }
diff --git a/include/ds/char.h b/include/ds/char.h
new file mode 100644
index 0000000..0f185a0
--- /dev/null
+++ b/include/ds/char.h
@@ -0,0 +1,109 @@
+#pragma once
+
+#ifndef DS_CHAR_H
+#define DS_CHAR_H 1
+
+//! @file ds/char.h
+//! @author Avinash Maddikonda (svasssakavi@gmail.com)
+//! @brief Declaration of the @ref ds_char_t "char" type, related constants and
+//! functions.
+//! @since 0.3.0
+//! @date 2023-07-26
+
+#include <limits.h>
+
+#include "ds/usize.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif /* __cplusplus */
+
+  /// @brief A character type.
+  ///
+  /// The @ref ds_char_t "char" type represents a single character.
+  ///
+  /// More specifically, since ‘character’ isn’t a well-defined concept in
+  /// Unicode, @ref ds_char_t "char" will be a ‘Unicode scalar value’ in the
+  /// future, when UTF-8 validation is fully supported.
+  typedef char ds_char_t;
+
+/// @brief The size of @ref ds_char_t "char" in bytes.
+///
+/// ### Examples
+///
+/// Basic usage:
+///
+/// ```c
+/// assert (DS_CHAR_BYTES == 1);
+/// ```
+#define DS_CHAR_BYTES ((ds_usize_t)sizeof (ds_char_t))
+
+/// @brief The smallest value that can be represented by @ref ds_char_t "char".
+///
+/// ### Examples
+///
+/// Basic usage:
+///
+/// ```c
+/// assert (DS_CHAR_MIN == CHAR_MIN);
+/// ```
+#define DS_CHAR_MIN ((ds_char_t)CHAR_MIN)
+
+/// @brief The largest value that can be represented by @ref ds_char_t "char".
+///
+/// ### Examples
+///
+/// Basic usage:
+///
+/// ```c
+/// assert (DS_CHAR_MAX == CHAR_MAX);
+/// ```
+#define DS_CHAR_MAX ((ds_char_t)CHAR_MAX)
+
+/// @brief The null-terminator character.
+///
+/// ### Examples
+///
+/// Basic usage:
+///
+/// ```c
+/// assert (DS_CHAR_NUL == '\0');
+/// ```
+#define DS_CHAR_NUL ((ds_char_t)0)
+
+/// @brief @ref ds_char_t "char" notation. Can be used in `scanf` to parse and
+/// read @ref ds_char_t "char" values.
+///
+/// @warning It is strongly advised to use
+/// [`fgets`](https://en.cppreference.com/w/c/io/fgets "fgets -
+/// cppreference.com") instead of `scanf` to read input.
+///
+/// ### Examples
+///
+/// Basic usage:
+///
+/// ```c
+/// ds_char_t x;
+/// scanf ("%" DS_SCN_CHAR, &x);
+/// ```
+#define DS_SCN_CHAR "c"
+
+/// @brief @ref ds_char_t "char" notation. Can be used in `printf` to format
+/// and write @ref ds_char_t "char" values.
+///
+/// ### Examples
+///
+/// Basic usage:
+///
+/// ```c
+/// ds_char_t x = DS_CHAR_MAX;
+/// printf ("%" DS_PRI_CHAR, x);
+/// ```
+#define DS_PRI_CHAR "c"
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* DS_CHAR_H */
diff --git a/src/ds/char.c b/src/ds/char.c
new file mode 100644
index 0000000..c071869
--- /dev/null
+++ b/src/ds/char.c
@@ -0,0 +1,8 @@
+//! @file ds/char.c
+//! @author Avinash Maddikonda (svasssakavi@gmail.com)
+//! @brief Implementation of the @ref ds_char_t "char" type, related constants
+//! and functions.
+//! @since 0.3.0
+//! @date 2023-07-26
+
+#include "ds/char.h"
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 64a2f27..aebca78 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -32,6 +32,7 @@ set(DS_TESTS "test_${PROJECT_NAME}")
 # For example, for a new test file created in `tests/test_ds/test_foo.cpp`, the
 # appended file path must be `"${DS_TESTS_DIR}/${DS_TESTS}/test_foo.cpp"`.
 set(DS_TEST_PRIVATE_SOURCES
+  "${DS_TESTS_DIR}/${DS_TESTS}/test_char.cpp"
   "${DS_TESTS_DIR}/${DS_TESTS}/test_helpers.cpp"
   "${DS_TESTS_DIR}/${DS_TESTS}/test_usize.cpp")
 
diff --git a/tests/test_ds/test_char.cpp b/tests/test_ds/test_char.cpp
new file mode 100644
index 0000000..eb84410
--- /dev/null
+++ b/tests/test_ds/test_char.cpp
@@ -0,0 +1,18 @@
+#include <climits>
+
+#include "gtest/gtest.h"
+
+#include "ds/char.h"
+#include "ds/usize.h"
+
+TEST (CharBytes, CorrectValue)
+{
+  EXPECT_EQ (DS_CHAR_BYTES, (ds_usize_t)sizeof (ds_char_t));
+}
+
+TEST (CharMin, CorrectValue) { EXPECT_EQ (DS_CHAR_MIN, (ds_char_t)CHAR_MIN); }
+TEST (CharMax, CorrectValue) { EXPECT_EQ (DS_CHAR_MAX, (ds_char_t)CHAR_MAX); }
+TEST (CharNul, CorrectValue) { EXPECT_EQ (DS_CHAR_NUL, (ds_char_t)0); }
+
+TEST (CharScn, CorrectValue) { EXPECT_STREQ (DS_SCN_CHAR, "c"); }
+TEST (CharPri, CorrectValue) { EXPECT_STREQ (DS_PRI_CHAR, "c"); }