Add char type, related constants and functions

.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:

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")
 

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

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"]
 }

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 ([email protected])
+//! @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 */

src/ds/char.c

@@ -0,0 +1,8 @@
+//! @file ds/char.c
+//! @author Avinash Maddikonda ([email protected])
+//! @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"

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")
 

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"); }