Merge pull request #2 from saxbophone/josh/to-string

Added Fixed.to_c_str() method

Author: saxbophone

sxpsxfp/include/sxpsxfp/Fixed.hpp

@@ -22,6 +22,8 @@
 #else
 #include <sys/types.h>
 #endif
+#include <stdio.h>  // snprintf
+#include <stdlib.h> // abs
 
 /**
  * @todo Consider shortening the namespace name to its last component
@@ -176,6 +178,34 @@ namespace com::saxbophone::sxpsxfp {
             // can't use a right-shift here due to it not handling negative values properly
             return this->_raw_value / Fixed::SCALE;
         }
+        /**
+         * @brief Stringifies the Fixed-point value to a C-string
+         * @param buffer pointer to array of `char`. Must be non-null and pointing to buffer of size `buffer_size`.
+         * @param[out] buffer_size size of `buffer`. Should be at least `15`.
+         * @returns `false` if buffer could not be written, because buffer_size wasn't big enough
+         * @returns `true` if buffer was written
+         * @note Although conforming C-libraries check if `buffer == nullptr` for you, the implementation of `vsnprintf()`
+         * in libPSn00bSDK, which this project is intended for use with, doesn't seem to check if `buffer == NULL`, hence
+         * the need to check it here.
+         */
+        constexpr bool to_c_str(char* buffer, size_t buffer_size) const {
+            // don't write to a null-pointer!
+            if (buffer == nullptr) { return false; }
+            // need at least 14 characters and 1 for the null-terminator
+            if (buffer_size < 15) { return false; } // refuse if not at least this many in buffer
+            int decimal_part = this->_raw_value / 4096; // floor-divide
+            // decompose the fractional part into an unsigned int to allow us to scale it up for more decimal places
+            unsigned int remainder = ((unsigned int)abs(this->_raw_value)) % 4096;
+            // 1M is the maximum we can scale it up without overflow, since 4096*1M = 4096M, compared to max uint32 = ~4294M
+            unsigned int fractional_part = (remainder * 1'000'000) / 4096; // this gives us 6 decimal places
+            // can't print a negative sign if negative but decimal_part is zero
+            if (this->_raw_value < 0 and decimal_part == 0) {
+                snprintf(buffer, buffer_size, "-0.%06u", fractional_part);
+            } else { // otherwise, we can rely on snprintf() to do it for us
+                snprintf(buffer, buffer_size, "%d.%06u", decimal_part, fractional_part);
+            }
+            return true;
+        }
         /**
          * @brief Prefix increment operator
          */

tests/CMakeLists.txt

@@ -14,6 +14,8 @@ target_sources(
         casting.cpp
         comparisons.cpp
         constructors.cpp
+        conversion_to_string.cpp
+        conversion_to_string_null.cpp
         division.cpp
         equivalences.cpp
         multiplication.cpp
@@ -22,6 +24,16 @@ target_sources(
         unary_operations.cpp
         user_defined_literals.cpp
 )
+# disable check for null buffer to vsnprintf() family functions for one file,
+# which needs to deliberately pass a null-pointer as part of the test case
+check_cxx_compiler_flag("-Wno-format-truncation" flag_supported)
+if(flag_supported)
+    set_source_files_properties(
+        conversion_to_string_null.cpp
+        PROPERTIES COMPILE_FLAGS -Wno-format-truncation
+    )
+endif()
+unset(flag_supported CACHE)
 target_link_libraries(
     tests
     PRIVATE

tests/config.hpp

@@ -4,6 +4,7 @@
 #include <cstddef>
 
 namespace tests_config {
+    // constexpr std::size_t ITERATIONS = 2'500'000'000;
     constexpr std::size_t ITERATIONS = 10'000;
 }
 

tests/conversion_to_string.cpp

@@ -0,0 +1,53 @@
+#include <limits>
+
+#include <cstdlib>
+
+#include <catch2/catch.hpp>
+
+#include <sxpsxfp/Fixed.hpp>
+
+#include "config.hpp"
+
+using namespace com::saxbophone::sxpsxfp;
+
+TEST_CASE("Conversion to String") {
+    SECTION("Fixed.to_c_str() creates a C string with the value's decimal respresentation") {
+        double i = GENERATE(
+            take(
+                tests_config::ITERATIONS,
+                random(
+                    Fixed::FRACTIONAL_MIN,
+                    Fixed::FRACTIONAL_MAX
+                )
+            )
+        );
+        Fixed var = i;
+        char output[15] = {}; // need up to 15 characters for string, including null-terminator
+
+        // we require the function call to return true for successful call
+        CHECK(var.to_c_str(output, sizeof(output)));
+        // now, try and convert that value back to double so we can approximately compare it
+        char* cursor = nullptr;
+        double value = std::strtod(output, &cursor);
+        // strtod sets cursor to output if conversion failed, so check that it isn't
+        REQUIRE(cursor != output);
+
+        // finally, approximately compare this value cast to double --we want them equal to 6 decimal places
+        REQUIRE(value == Approx((double)var).margin(0.000001));
+    }
+
+    SECTION("Fixed.to_c_str() returns false when given buffer_size = zero") {
+        Fixed var;
+        char output = {};
+
+        REQUIRE_FALSE(var.to_c_str(&output, 0));
+    }
+
+    SECTION("Fixed.to_c_str() returns false when 1 ≤ buffer_size < 15") {
+        std::size_t buffer_size = GENERATE(range(1U, 14U));
+        Fixed var;
+        char* output = new char[buffer_size] {0};
+
+        REQUIRE_FALSE(var.to_c_str(output, buffer_size));
+    }
+}

tests/conversion_to_string_null.cpp

@@ -0,0 +1,12 @@
+#include <catch2/catch.hpp>
+
+#include <sxpsxfp/Fixed.hpp>
+
+using namespace com::saxbophone::sxpsxfp;
+
+TEST_CASE("Fixed.to_c_str() returns false when buffer is a null pointer") {
+    Fixed var;
+
+    // should fail because of null pointer and not buffer_size, the latter of which is big enough
+    REQUIRE_FALSE(var.to_c_str(nullptr, 15));
+}