Merge branch 'main' into dataset-loader

trabalho-pratico/include/types/account_status.h

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2023 Humberto Gomes, José Lopes, José Matos
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file     account_status.h
+ * @brief    Account status of a ::user_t.
+ */
+
+#ifndef ACCOUNT_STATUS_H
+#define ACCOUNT_STATUS_H
+
+/** @brief The account status of a ::user_t. */
+typedef enum {
+    ACCOUNT_STATUS_INACTIVE, /**< @brief Inactive account */
+    ACCOUNT_STATUS_ACTIVE    /**< @brief Active account */
+} account_status_t;
+
+/**
+ * @brief Parses a user's account status.
+ *
+ * @param output Where the parsed status will be placed (only on success).
+ * @param input  Input (`"active"` or `"inactive"`, case-insensitive).
+ *
+ * @retval 0 Parsing success
+ * @retval 1 Parsing failure
+ */
+int account_status_from_string(account_status_t *output, const char *input);
+
+#endif

trabalho-pratico/include/types/airport_code.h

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2023 Humberto Gomes, José Lopes, José Matos
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file     airport_code.h
+ * @brief    Airport code in a ::flight_t.
+ *
+ * @anchor airport_examples
+ * ### Examples
+ *
+ * The following example shows how to validate airport codes and how to print them back to strings.
+ * It's also shown that all airport codes are stored in upper-case.
+ *
+ * ```c
+ * const char *string_codes[6] = {
+ *     "",     // Too short
+ *     "O",    // Too short
+ *     "OP",   // Too short
+ *     "OPO",  // Just right
+ *     "oPo",  // Everything should be converted to upper-case
+ *     "OPOR", // Too long
+ * };
+ *
+ * for (int i = 0; i < 6; ++i) {
+ *     airport_code_t parsed;
+ *
+ *     if (!airport_code_from_string(&parsed, string_codes[i])) {
+ *         char back_to_string[AIRPORT_CODE_SPRINTF_MIN_BUFFER_SIZE];
+ *         airport_code_sprintf(back_to_string, parsed);
+ *         printf("Parsed code: \"%s\"\n", back_to_string);
+ *
+ *     } else {
+ *         fprintf(stderr, "Failed to parse airport code \"%s\"!\n", string_codes[i]);
+ *     }
+ * }
+ * ```
+ */
+
+#ifndef AIRPORT_CODE_H
+#define AIRPORT_CODE_H
+
+#include <stdint.h>
+
+/**
+ * @brief An airport code of a ::flight_t.
+ */
+typedef uint32_t airport_code_t;
+
+/**
+ * @brief Creates (and validates) a airport code from a string.
+ *
+ * @param output Where to place the parsed airport code (not modified on failure).
+ * @param input  String to parse.
+ *
+ * @retval 0 Valid airport code
+ * @retval 1 Invalid airport code
+ */
+int airport_code_from_string(airport_code_t *output, const char *input);
+
+/**
+ * @brief The minimum number of characters (including null terminator) needed to write an airport
+ *        code to a buffer using ::airport_code_sprintf.
+ * @details
+ *
+ * | O | P | O | \0 |
+ * | - | - | - | -- |
+ * | 1 | 2 | 3 | 4  |
+ */
+#define AIRPORT_CODE_SPRINTF_MIN_BUFFER_SIZE 4
+
+/**
+ * @brief Prints a airport code using `sprintf`.
+ *
+ * @param output  Where to print the airport code to. Must be at least
+ *                ::AIRPORT_CODE_SPRINTF_MIN_BUFFER_SIZE long.
+ * @param airport Country code to be printed.
+ */
+void airport_code_sprintf(char *output, airport_code_t airport);
+
+#endif

trabalho-pratico/include/types/country_code.h

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2023 Humberto Gomes, José Lopes, José Matos
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file     country_code.h
+ * @brief    Country code in a ::user_t.
+ *
+ * @anchor country_code_examples
+ * ### Examples
+ *
+ * The following example shows how to validate country codes and how to print them back to strings.
+ *
+ * ```c
+ * const char *string_codes[4] = {
+ *     "",    // Too short
+ *     "P",   // Too short
+ *     "PT",  // Just right
+ *     "POR", // Too long
+ * };
+ *
+ * for (int i = 0; i < 4; ++i) {
+ *     country_code_t parsed;
+ *
+ *     if (!country_code_from_string(&parsed, string_codes[i])) {
+ *         char back_to_string[COUNTRY_CODE_SPRINTF_MIN_BUFFER_SIZE];
+ *         country_code_sprintf(back_to_string, parsed);
+ *         printf("Parsed code: \"%s\"\n", back_to_string);
+ *
+ *     } else {
+ *         fprintf(stderr, "Failed to parse country code \"%s\"!\n", string_codes[i]);
+ *     }
+ * }
+ * ```
+ */
+
+#ifndef COUNTRY_CODE_H
+#define COUNTRY_CODE_H
+
+#include <stdint.h>
+
+/**
+ * @brief A country code of a ::user_t.
+ */
+typedef uint16_t country_code_t;
+
+/**
+ * @brief Creates (and validates) a country code from a string.
+ *
+ * @param output Where to place the parsed country code (not modified on failure).
+ * @param input  String to parse.
+ *
+ * @retval 0 Valid country code
+ * @retval 1 Invalid country code
+ *
+ *
+ * #### Examples
+ * See [the header file's documentation](@ref country_code_examples).
+ */
+int country_code_from_string(country_code_t *output, const char *input);
+
+/**
+ * @brief The minimum number of characters (including null terminator) needed to write a country
+ *        code to a buffer using ::country_code_sprintf.
+ * @details
+ *
+ * | P | T | \0 |
+ * | - | - | -- |
+ * | 1 | 2 | 3  |
+ */
+#define COUNTRY_CODE_SPRINTF_MIN_BUFFER_SIZE 3
+
+/**
+ * @brief Prints a country code using `sprintf`.
+ *
+ * @param output  Where to print the country code to. Must be at least
+ *                ::COUNTRY_CODE_SPRINTF_MIN_BUFFER_SIZE long.
+ * @param country Country code to be printed.
+ *
+ * #### Examples
+ * See [the header file's documentation](@ref country_code_examples).
+ */
+void country_code_sprintf(char *output, country_code_t country);
+
+#endif