Update: f_convesion, add comments and fix problems

Add comments (including correcting some existing ones).

Rename another case where digit should now be decimal.

Make sure the *decimal parameter only gets updated on success.
Be consistent about returning f_no_data.

diff --git a/level_0/f_conversion/c/conversion.c b/level_0/f_conversion/c/conversion.c
index 98434fb55efb2bb30f6f1dd886ffff73ced9c281..bc88d70ccef7f322d32ef57448555c841c4c0012 100644 (file)
--- a/level_0/f_conversion/c/conversion.c
+++ b/level_0/f_conversion/c/conversion.c
@@ -32,72 +32,72 @@ extern "C" {
   }
 #endif // _di_f_is_hexidecimal_
 
-#ifndef _di_f_character_to_digit_
-  f_return_status f_character_to_digit(const char character, unsigned long *digit) {
+#ifndef _di_f_character_to_decimal_
+  f_return_status f_character_to_decimal(const char character, unsigned long *decimal) {
     #ifndef _di_level_0_parameter_checking_
-      if (digit == 0) return f_status_set_error(f_invalid_parameter);
+      if (decimal == 0) return f_status_set_error(f_invalid_parameter);
     #endif // _di_level_0_parameter_checking_
 
     switch (character) {
-      case 0x30: *digit = 0; break;
-      case 0x31: *digit = 1; break;
-      case 0x32: *digit = 2; break;
-      case 0x33: *digit = 3; break;
-      case 0x34: *digit = 4; break;
-      case 0x35: *digit = 5; break;
-      case 0x36: *digit = 6; break;
-      case 0x37: *digit = 7; break;
-      case 0x38: *digit = 8; break;
-      case 0x39: *digit = 9; break;
+      case 0x30: *decimal = 0; break;
+      case 0x31: *decimal = 1; break;
+      case 0x32: *decimal = 2; break;
+      case 0x33: *decimal = 3; break;
+      case 0x34: *decimal = 4; break;
+      case 0x35: *decimal = 5; break;
+      case 0x36: *decimal = 6; break;
+      case 0x37: *decimal = 7; break;
+      case 0x38: *decimal = 8; break;
+      case 0x39: *decimal = 9; break;
       default:
         return f_no_data;
     }
 
     return f_none;
   }
-#endif // _di_f_character_to_digit_
+#endif // _di_f_character_to_decimal_
 
-#ifndef _di_f_character_to_hexdecimal_
-  f_return_status f_character_to_hexdecimal(const char character, unsigned long *digit) {
+#ifndef _di_f_character_to_hexidecimal_
+  f_return_status f_character_to_hexidecimal(const char character, unsigned long *decimal) {
     #ifndef _di_level_0_parameter_checking_
-      if (digit == 0) return f_status_set_error(f_invalid_parameter);
+      if (decimal == 0) return f_status_set_error(f_invalid_parameter);
     #endif // _di_level_0_parameter_checking_
 
     switch (character) {
-      case 0x30: *digit = 0; break;
-      case 0x31: *digit = 1; break;
-      case 0x32: *digit = 2; break;
-      case 0x33: *digit = 3; break;
-      case 0x34: *digit = 4; break;
-      case 0x35: *digit = 5; break;
-      case 0x36: *digit = 6; break;
-      case 0x37: *digit = 7; break;
-      case 0x38: *digit = 8; break;
-      case 0x39: *digit = 9; break;
-      case 0x41: *digit = 10; break;
-      case 0x42: *digit = 11; break;
-      case 0x43: *digit = 12; break;
-      case 0x44: *digit = 13; break;
-      case 0x45: *digit = 14; break;
-      case 0x46: *digit = 15; break;
-      case 0x61: *digit = 10; break;
-      case 0x62: *digit = 11; break;
-      case 0x63: *digit = 12; break;
-      case 0x64: *digit = 13; break;
-      case 0x65: *digit = 14; break;
-      case 0x66: *digit = 15; break;
+      case 0x30: *decimal = 0; break;
+      case 0x31: *decimal = 1; break;
+      case 0x32: *decimal = 2; break;
+      case 0x33: *decimal = 3; break;
+      case 0x34: *decimal = 4; break;
+      case 0x35: *decimal = 5; break;
+      case 0x36: *decimal = 6; break;
+      case 0x37: *decimal = 7; break;
+      case 0x38: *decimal = 8; break;
+      case 0x39: *decimal = 9; break;
+      case 0x41: *decimal = 10; break;
+      case 0x42: *decimal = 11; break;
+      case 0x43: *decimal = 12; break;
+      case 0x44: *decimal = 13; break;
+      case 0x45: *decimal = 14; break;
+      case 0x46: *decimal = 15; break;
+      case 0x61: *decimal = 10; break;
+      case 0x62: *decimal = 11; break;
+      case 0x63: *decimal = 12; break;
+      case 0x64: *decimal = 13; break;
+      case 0x65: *decimal = 14; break;
+      case 0x66: *decimal = 15; break;
       default:
         return f_no_data;
     }
 
     return f_none;
   }
-#endif // _di_f_character_to_hexdecimal_
+#endif // _di_f_character_to_hexidecimal_
 
 #ifndef _di_f_string_to_decimal_
-  f_return_status f_string_to_decimal(const f_string string, unsigned long *digit, const f_string_location location) {
+  f_return_status f_string_to_decimal(const f_string string, unsigned long *decimal, const f_string_location location) {
     #ifndef _di_level_0_parameter_checking_
-      if (digit == 0) return f_status_set_error(f_invalid_parameter);
+      if (decimal == 0) return f_status_set_error(f_invalid_parameter);
       if (location.start < 0) return f_status_set_error(f_invalid_parameter);
       if (location.stop <= location.start) return f_status_set_error(f_invalid_parameter);
       if (string == 0) return f_status_set_error(f_invalid_parameter);
@@ -105,36 +105,39 @@ extern "C" {
 
     f_string_length current_location = location.start;
     unsigned long scale = 0;
-    unsigned long temp_digit = 0;
+    unsigned long digit = 0;
+    unsigned long decimal_value = 0;
 
     while (current_location < location.stop) {
-      if (f_character_to_digit(string[current_location], &temp_digit) == f_none) {
+      if (f_character_to_decimal(string[current_location], &digit) == f_none) {
 
         // when the scale exists, then we need to make the number larger, for this function the scale is base 10
         if (scale > 0) {
-          *digit = 10 * *digit;
-          *digit += temp_digit;
+          decimal_value = 10 * decimal_value;
+          decimal_value += digit;
         }
         else {
           scale = 1;
-          *digit = temp_digit;
+          decimal_value = digit;
         }
       }
       else {
-        break;
+        return f_no_data;
       }
 
       ++current_location;
     } // while
 
+    *decimal = decimal_value;
+
     return f_none;
   }
 #endif // _di_f_string_to_decimal_
 
 #ifndef _di_f_string_to_hexidecimal_
-  f_return_status f_string_to_hexidecimal(const f_string string, unsigned long *digit, const f_string_location location) {
+  f_return_status f_string_to_hexidecimal(const f_string string, unsigned long *decimal, const f_string_location location) {
     #ifndef _di_level_0_parameter_checking_
-      if (digit == 0) return f_status_set_error(f_invalid_parameter);
+      if (decimal == 0) return f_status_set_error(f_invalid_parameter);
       if (location.start < 0) return f_status_set_error(f_invalid_parameter);
       if (location.stop <= location.start) return f_status_set_error(f_invalid_parameter);
       if (string == 0) return f_status_set_error(f_invalid_parameter);
@@ -142,28 +145,31 @@ extern "C" {
 
     f_string_length current_location = location.start;
     unsigned long scale = 0;
-    unsigned long temp_digit = 0;
+    unsigned long digit = 0;
+    unsigned long decimal_value = 0;
 
     while (current_location < location.stop) {
-      if (f_character_to_hexdecimal(string[current_location], &temp_digit) == f_none) {
+      if (f_character_to_hexidecimal(string[current_location], &digit) == f_none) {
 
-        // when the scale exists, then we need to make the number larger, for this function the scale is base 16
+        // when the scale exists, then we need to make the number larger, for this function the scale is base 16.
         if (scale > 0) {
-          *digit <<= 4;
-          *digit += temp_digit;
+          decimal_value <<= 4;
+          decimal_value += digit;
         }
         else {
           scale = 1;
-          *digit = temp_digit;
+          decimal_value = digit;
         }
       }
       else {
-        break;
+        return f_no_data;
       }
 
       ++current_location;
     } // while
 
+    *decimal = decimal_value;
+
     return f_none;
   }
 #endif // _di_f_string_to_hexidecimal_

diff --git a/level_0/f_conversion/c/conversion.h b/level_0/f_conversion/c/conversion.h
index c13bdb77dc812ab912e996763ca619b750fe023f..f05bc6dbffae2b0180cb8309a7ce67d4ec5ac740 100644 (file)
--- a/level_0/f_conversion/c/conversion.h
+++ b/level_0/f_conversion/c/conversion.h
@@ -6,18 +6,6 @@
  * Licenses: lgplv2.1
  *
  * Provide means to convert one data type to another, such as a string to an integer.
- * Provide means to identify a digit or a hexadecimal digit (hexdigit).
- * In the future this will have to link to locale support, due to interpeting strings.
- *
- * Possible error values on return:
- *   f_critical          - an error.
- *   f_invalid_data      - something is wrong with the data sent to this function, error.
- *   f_invalid_parameter - a parameter sent to this function is invalid, error.
- *   f_invalid_syntax    - syntax for data sent to this is invalid, error.
- *   f_no_data           - something is wrong with the data sent to this function, warning.
- *   f_none              - no errors or warnings.
- *   f_unknown           - an unknown error.
- *   f_warn              - a possible problem, but not an error (warning).
  */
 #ifndef _F_conversion_h
 #define _F_conversion_h
@@ -34,51 +22,116 @@
 extern "C" {
 #endif
 
+/**
+ * Convert a single character into the decimal value that it represents.
+ *
+ * @param character
+ *   The character to validate.
+ *
+ * @return
+ *   f_true if character is a decimal.
+ *   f_false if character is not a decimal.
+ */
 #ifndef _di_f_is_decimal_
-  /**
-   * convert a single character into the decimal value that it represents.
-   */
   extern f_return_status f_is_decimal(const char character);
 #endif // _di_f_is_decimal_
 
+/**
+ * Convert a single character into the hexidecimal digit that it represents.
+ *
+ * @param character
+ *   The character to validate.
+ *
+ * @return
+ *   f_true if character is a hexidecimal.
+ *   f_false if character is not a hexidecimal.
+ */
 #ifndef _di_f_is_hexidecimal_
-  /**
-   * convert a single character into the hexidecimal digit that it represents
-   */
   extern f_return_status f_is_hexidecimal(const char character);
 #endif // _di_f_is_hexidecimal_
 
-#ifndef _di_f_character_to_digit_
-  /**
-   * convert a single character into the digit that it represents.
-   */
-  extern f_return_status f_character_to_digit(const char character, unsigned long *digit);
-#endif // _di_f_character_to_digit_
+/**
+ * Convert a single character into the digit that it represents.
+ *
+ * @param character
+ *   The character to convert.
+ * @param decimal
+ *   This will store the value of the converted character.
+ *   This value is not changed when f_no_data is returned.
+ *
+ * @return
+ *   f_none if character was converted to a decimal.
+ *   f_no_data if no conversion was made due to non-decimal values being found.
+ *   f_invalid_parameter (with error bit) if a parameter is invalid.
+ */
+#ifndef _di_f_character_to_decimal_
+  extern f_return_status f_character_to_decimal(const char character, unsigned long *decimal);
+#endif // _di_f_character_to_decimal_
 
-#ifndef _di_f_character_to_hexdecimal_
-  /**
-   *convert a single character into the hexidecimal digit that it represents.
-   */
-  extern f_return_status f_character_to_hexdecimal(const char character, unsigned long *digit);
-#endif // _di_f_character_to_hexdecimal_
+/**
+ * Convert a single character into the hexidecimal digit that it represents.
+ *
+ * @param character
+ *   The character to convert.
+ * @param decimal
+ *   This will store the value of the converted character.
+ *   This value is not changed when f_no_data is returned.
+ *
+ * @return
+ *   f_none if character was converted to a hexidecimal.
+ *   f_no_data if no conversion was made due to non-hexidecimal values being found.
+ *   f_invalid_parameter (with error bit) if a parameter is invalid.
+ */
+#ifndef _di_f_character_to_hexidecimal_
+  extern f_return_status f_character_to_hexidecimal(const char character, unsigned long *decimal);
+#endif // _di_f_character_to_hexidecimal_
 
+/**
+ * Convert a series of positive decimal numbers characters into an unsigned long.
+ *
+ * This will stop at one of the following: EOS, max_length, or a non-digit.
+ * This works like atoi, except there is a start/stop range.
+ * This will not process signed statuses (+/-).
+ *
+ * @param string
+ *   The string to convert.
+ * @param decimal
+ *   This will store the value of the converted string.
+ *   This value is not changed when f_no_data is returned.
+ * @param location
+ *   The start/stop range to convert.
+ *
+ * @return
+ *   f_none if the decimal string was converted to an unsigned long.
+ *   f_no_data if no conversion was made due to non-decimal values being found.
+ *   f_invalid_parameter (with error bit) if a parameter is invalid.
+ */
 #ifndef _di_f_string_to_decimal_
-  /**
-   * works like atoi, except there is a start/stop range.
-   * convert a series of positive numbers into a string, stopping at one of the following: EOS, max_length, or a non-digit.
-   * will not process signed statuses (+/-).
-   */
-  extern f_return_status f_string_to_decimal(const f_string string, unsigned long *digit, const f_string_location location);
+  extern f_return_status f_string_to_decimal(const f_string string, unsigned long *decimal, const f_string_location location);
 #endif // _di_f_string_to_decimal_
 
+/**
+ * Convert a series of positive hexidecimal numbers characters into an unsigned long.
+ *
+ * This will stop at one of the following: EOS, max_length, or a non-digit.
+ * This works like atoi, except there is a start/stop range.
+ * This will not process signed statuses (+/-).
+ *
+ * @param string
+ *   The string to convert.
+ * @param decimal
+ *   This will store the value of the converted string.
+ *   This value is not changed when f_no_data is returned.
+ * @param location
+ *   The start/stop range to convert.
+ *
+ * @return
+ *   f_none if the hexidecimal string was converted to an unsigned long.
+ *   f_no_data if no conversion was made due to non-hexidecimal values being found.
+ *   f_invalid_parameter (with error bit) if a parameter is invalid.
+ */
 #ifndef _di_f_string_to_hexidecimal_
-
-  /**
-   * works like atoi, except there is a start/stop range and that this is for hexidecimal digits.
-   * convert a series of positive  numbers into a string, stopping at one of the following: EOS, max_length, or a non-hexdigit.
-   * will not process signed statuses (+/-).
-   */
-  extern f_return_status f_string_to_hexidecimal(const f_string string, unsigned long *digit, const f_string_location location);
+  extern f_return_status f_string_to_hexidecimal(const f_string string, unsigned long *decimal, const f_string_location location);
 #endif // _di_f_string_to_hexidecimal_
 
 #ifdef __cplusplus