Initial commit

2026-09-12 10:47:02 -05:00
commit 4b3ad9b6f8
6 changed files with 1039 additions and 0 deletions
@@ -0,0 +1,94 @@
+/**
+ * @file version.h
+ * @brief Contains the structure and functions for a semantic version.
+ * @author John Christman (sorakatadzuma@gmail.com)
+ * @copyright Malunal Studios, LLC.
+ */
+#include "malunal/strview.h"
+#include "malunal/types/error.h"
+
+#ifndef MALUNAL_VERSION_HEADER
+#define MALUNAL_VERSION_HEADER
+
+
+/**
+ * @brief   Imports the @c version_t error domain for error checking.
+ * @details The @c version_t error domain is specific for versions to indicate
+ *          an issue with the parsing of a semantic version string into the
+ *          @c version_t object.
+ */
+extern
+const error_domain_t
+ERROR_DOMAIN_VERSION_T;
+
+
+/**
+ * @brief   Contains information for a semantic version.
+ * @details Allows a semantic version to be parsed from some string and its
+ *          content stored in this structure.
+ */
+define_struct(version) {
+  malunal_size_t major;
+  malunal_size_t minor;
+  malunal_size_t patch;
+  strview_t      preview;
+  strview_t      build;
+};
+
+
+/**
+ * @brief   Defines a set of error codes for @c version_t.
+ * @details
+ */
+typedef enum {
+  VERSION_ERROR_NULL_INPUT,
+  VERSION_ERROR_INVALID_NUMBER,
+  VERSION_ERROR_UNEXPECTED_CHAR,
+  VERSION_ERROR_MISSING_PART,
+  VERSION_ERROR_LEADING_ZERO,
+  VERSION_ERROR_VALUE_OVERFLOW,
+} version_error_t;
+
+
+/**
+ * @brief   Parses a version string into a @c version_t object.
+ * @param   verstr The string containing the semantic version to be parsed.
+ * @param   outver A pointer to the version to populate with the result.
+ * @returns An error if the semantic version string could not be parsed into the
+ *          @c version_t object.
+ */
+error_t
+parse_version(
+  strview_iptr_t verstr,
+  version_mptr_t outver
+);
+
+/**
+ * @brief  Compares one @c version_t to another.
+ * @param  self  The @c version_t to compare against.
+ * @param  other The @c version_t to compare with.
+ * @retval -1 if self is less than other.
+ * @retval  0 if self is equal to other.
+ * @retval  1 if self is more than other.
+ */
+malunal_int32_t
+version_compare(
+  version_iptr_t self,
+  version_iptr_t other
+);
+
+/**
+ * @brief   Converts the provided @c version_t to a string.
+ * @param   self   A pointer to the version object to convert to a string.
+ * @param   buffer A pointer to where to write the semantic version string.
+ * @param   length The length of the buffer which will receive the string.
+ * @returns The length of the version written or -1 if the buffer was too small.
+ */
+malunal_int32_t
+version_string(
+  version_iptr_t self,
+  malunal_str_t  buffer,
+  malunal_size_t length
+);
+
+#endif /* MALUNAL_VERSION_HEADER */