Removed extraneous includes. Documented includes (in code). Unit-testing throws on failed reading/writing SAC-files. Added tests to bring up code coverage on Trace equality (in particular, on specific inequality scenarios). Added to documentation - convenience methods and exceptions. Minor typos fixed.

Author: arbCoding

docs/index.html

@@ -1,7 +1,7 @@
 * Inbox
 ** [2023-11-21 Tue 12:16]
 Running clang-tidy locally prior to GitHub
-~clang-tidy --checks="bugprone-a*,bugprone-b*,bugprone-c*,bugprone-d*,bugprone-em*,bugprone-ex*,bugprone-f*,bugprone-i*,bugprone-l*,bugprone-m*,bugprone-n*,bugprone-o*,bugprone-p*,bugprone-r*,bugprone-s*,bugprone-t*,bugprone-u*,bugprone-v*,performance-*,readability-a*,readability-b*,readability-c*,readability-d*,readability-e*,readability-f*,readability-i*,readability-m*,readability-n*,readability-o*,readability-q*,readability-r*,readability-si*,readability-st*,readability-u*,portability-*,clang-analyzer-*,cppcoreguidelines-avoid-ca*,cpp-coreguidelines-avoid-co*,cpp-coreguidelines-avoid-d*,cpp-coreguidelines-avoid-g*,cpp-coreguidelines-avoid-n*,cpp-coreguidelines-avoid-r*,cpp-coreguidelines-i*,cpp-coreguidelines-m*,cpp-coreguidelines-n*,cpp-coreguidelines-o*,cpp-coreguidelines-pr*,cpp-coreguidelines-pro-bounds-p*,cpp-coreguidelines-pro-t*,cpp-coreguidelines-r*,cpp-coreguidelines-s*,cpp-coreguidelines-v*" --extra-arg="-O0 -Wall -Werror -Wshadow -Wextra -pedantic-errors -std=c++20" -p ./compile_commands.json src/sac_format.cpp~
+~clang-tidy --checks="bugprone-a*,bugprone-b*,bugprone-c*,bugprone-d*,bugprone-em*,bugprone-ex*,bugprone-f*,bugprone-i*,bugprone-l*,bugprone-m*,bugprone-n*,bugprone-o*,bugprone-p*,bugprone-r*,bugprone-s*,bugprone-t*,bugprone-u*,bugprone-v*,performance-*,readability-a*,readability-b*,readability-c*,readability-d*,readability-e*,readability-f*,readability-i*,readability-m*,readability-n*,readability-o*,readability-q*,readability-r*,readability-si*,readability-st*,readability-u*,portability-*,clang-analyzer-*,cppcoreguidelines-avoid-ca*,cpp-coreguidelines-avoid-co*,cpp-coreguidelines-avoid-d*,cpp-coreguidelines-avoid-g*,cpp-coreguidelines-avoid-n*,cpp-coreguidelines-avoid-r*,cpp-coreguidelines-i*,cpp-coreguidelines-m*,cpp-coreguidelines-n*,cpp-coreguidelines-o*,cpp-coreguidelines-pr*,cpp-coreguidelines-pro-bounds-p*,cpp-coreguidelines-pro-t*,cpp-coreguidelines-r*,cpp-coreguidelines-s*,cpp-coreguidelines-v*" --extra-arg="-std=c++20" -p ./compile_commands.json src/sac_format.cpp~
 ** [2023-11-21 Tue 10:16]
 Prior to =git add -A= be sure to run =clang-format= on all *.cpp and *.hpp files!
 

docs/sac-format_manual.pdf

@@ -280,7 +280,15 @@ a [[Lookup Table][lookup table]]. The internal components are below:
 
 *** Convenience Methods
 
-None implemented yet.
+- =degrees_to_radians=
+- =radians_to_degrees=
+- =gcarc=
+- =azimuth=
+
+*** Exceptions
+
+sac-format throws exceptions of type =std::domain_exception= in the event of a
+failure to read/write a SAC-file.
 
 ** Low-Level I/O
 
@@ -306,7 +314,7 @@ Conversion pair for binary representation of two-word (regular) string values.
 
 ***** =long_string_to_binary= and =binary_to_long_string=
 
-Conversion pair for binary representation of four-word (only [[=kstnm=]]) string
+Conversion pair for binary representation of four-word (only [[=kstnm=][=kstnm=]]) string
 values.
 
 **** Reading/Writing

notes.org

@@ -332,26 +332,34 @@ double radians_to_degrees(const double radians) {
   return deg_per_rad * radians;
 }
 
-double gcarc(const double latitude1, const double longitude1, const double latitude2, const double longitude2) {
+double gcarc(const double latitude1, const double longitude1,
+             const double latitude2, const double longitude2) {
   const double lat1{degrees_to_radians(latitude1)};
   const double lon1{degrees_to_radians(longitude1)};
   const double lat2{degrees_to_radians(latitude2)};
   const double lon2{degrees_to_radians(longitude2)};
-  return radians_to_degrees(std::acos(std::sin(lat1)*std::sin(lat2) + std::cos(lat1)*std::cos(lat2)*std::cos(lon2-lon1)));
+  return radians_to_degrees(
+      std::acos(std::sin(lat1) * std::sin(lat2) +
+                std::cos(lat1) * std::cos(lat2) * std::cos(lon2 - lon1)));
 }
 
 // I wonder if there is a way to do this with n-vectors
-double azimuth(const double latitude1, const double longitude1, const double latitude2, const double longitude2) {
+double azimuth(const double latitude1, const double longitude1,
+               const double latitude2, const double longitude2) {
   const double lat1{degrees_to_radians(latitude1)};
   const double lon1{degrees_to_radians(longitude1)};
   const double lat2{degrees_to_radians(latitude2)};
   const double lon2{degrees_to_radians(longitude2)};
   const double dlon{lon2 - lon1};
   const double numerator{std::sin(dlon) * std::cos(lat2)};
-  const double denominator{(std::cos(lat1) * std::sin(lat2)) - (std::sin(lat1) * std::cos(lat2) * std::cos(dlon))};
+  const double denominator{(std::cos(lat1) * std::sin(lat2)) -
+                           (std::sin(lat1) * std::cos(lat2) * std::cos(dlon))};
   double result{radians_to_degrees(std::atan2(numerator, denominator))};
-  if (result < 0.0) { result += 360.0; }
-  else if (result > 360.0) { result -= 360.0; }
+  if (result < 0.0) {
+    result += circle_deg;
+  } else if (result > circle_deg) {
+    result -= circle_deg;
+  }
   return result;
 }
 //------------------------------------------------------------------------------

src/docs/index.org

@@ -5,24 +5,34 @@
 #pragma once
 /* Standard library
    https://en.cppreference.com/w/cpp/standard_library */
+// std::ranges::fill
 #include <algorithm>
+// std::array
 #include <array>
 // std::endian
 #include <bit>
+// std::bitset
 #include <bitset>
-#include <cctype>
+// std::abs, std::acos, std::sin, std::cos, std::atan2, std::pow
 #include <cmath>
+// std::memcopy
 #include <cstring>
+// std::filesystem::path
 #include <filesystem>
+// std::ifstream, std::ifstream::binary, std::ofstream, std::ios::binary,
+// std::ios::out, std::ios::trunc
 #include <fstream>
-#include <iostream>
-#include <limits>
+// std::numbers::pi_v<double>
 #include <numbers>
 // std::domain_error
 #include <stdexcept>
+// std::string
 #include <string>
+// std::string_view (used only once...)
 #include <string_view>
+// std::unordered_map
 #include <unordered_map>
+// std::vector
 #include <vector>
 
 namespace sacfmt {
@@ -43,6 +53,7 @@ constexpr bool unset_bool{false};
 // Accuracy precision expected from SAC floats
 constexpr float f_eps{2.75e-6F};
 // This should work for two and four word string headers
+// This is the only instance of a string_view.
 constexpr std::string_view unset_word{"-12345"};
 using word_one = std::bitset<binary_word_size>;
 using word_two = std::bitset<static_cast<size_t>(2) * binary_word_size>;
@@ -61,6 +72,7 @@ constexpr int old_hdr_version{6};
 constexpr int common_skip_num{7};
 constexpr double rad_per_deg{std::numbers::pi_v<double> / 180.0};
 constexpr double deg_per_rad{1.0 / rad_per_deg};
+constexpr double circle_deg{360.0};
 //--------------------------------------------------------------------------
 // Conversions
 //--------------------------------------------------------------------------
@@ -140,9 +152,11 @@ bool equal_within_tolerance(double val1, double val2, double tolerance = f_eps);
 double degrees_to_radians(double degrees);
 double radians_to_degrees(double radians);
 // gcarc
-double gcarc(double latitude1, double longitude1, double latitude2, double longitude2);
+double gcarc(double latitude1, double longitude1, double latitude2,
+             double longitude2);
 // azimuth
-double azimuth(double latitude1, double longitude1, double latitude2, double longitude2);
+double azimuth(double latitude1, double longitude1, double latitude2,
+               double longitude2);
 
 enum class name {
   // Floats
@@ -395,6 +409,7 @@ const std::unordered_map<name, const int> sac_map = {
 class Trace {
 public:
   Trace();
+  // Parametric constructor (read file)
   explicit Trace(const std::filesystem::path &path);
   void write(const std::filesystem::path &path, bool legacy = false) const;
   void legacy_write(const std::filesystem::path &path) const;

src/sac_format.cpp

@@ -1,24 +1,28 @@
 // Copyright 2023 Alexander R. Blanchette
 
 /* Standard Library */
+// std::filesystem::path, std::filesystem::temp_directory_path()
 #include <filesystem>
-#include <fstream>
-#include <iomanip>
-#include <limits>
 /* Catch2 */
 #define CATCH_CONFIG_FAST_COMPILE
 #define CATCH_CONFIG_MAIN
 // testing macros
+// TEST_CASE, SECTION, REQUIRE, CAPTURE, REQUIRE_THROWS
 #include <catch2/catch_test_macros.hpp>
-// Floating-point matcher
+// from catch_matchers.hpp (any matcher includes it)
+// REQUIRE_THAT
+// Catch::Matchers::WithinAbs
 #include <catch2/matchers/catch_matchers_floating_point.hpp>
+// Catch::Matchers::EndsWith
+#include <catch2/matchers/catch_matchers_string.hpp>
 /* My stuff */
 #include <sac_format.hpp>
 #include <util.hpp>
 
 using namespace sacfmt;
 namespace fs = std::filesystem;
 using Catch::Matchers::WithinAbs;
+using Catch::Matchers::EndsWith;
 
 //==============================================================================
 // Basic I/O tests (file writing/reading goes with Trace)
@@ -1139,6 +1143,28 @@ TEST_CASE("Trace Read/Write") {
       REQUIRE(equal_within_tolerance(trace.data2(), in.data2()));
     }
     SECTION("Everything") { REQUIRE(trace == in); }
+    SECTION("Resize data") {
+      Trace in2{};
+      in2 = in;
+      std::vector<double> tmp{in2.data1()};
+      tmp.resize(10);
+      in2.data1(tmp);
+      REQUIRE(!equal_within_tolerance(trace.data1(), in2.data1()));
+    }
+    SECTION("Change a float") {
+      Trace in2{};
+      in2 = in;
+      in2.evdp(in.evdp() - 1.0f);
+      REQUIRE(trace != in2);
+    }
+    SECTION("Change a vector value") {
+      Trace in2{};
+      in2 = in;
+      std::vector<double> tmp{in2.data1()};
+      tmp[0] -= 1.0;
+      in2.data1(tmp);
+      REQUIRE(trace != in2);
+    }
   }
   SECTION("Legacy Read/Write") {
     trace.nvhdr(6);
@@ -1321,6 +1347,16 @@ TEST_CASE("Trace Read/Write") {
       REQUIRE(trace != in);
     }
   }
+  SECTION("Read Throw") {
+    fs::path tmp_dir{fs::temp_directory_path() / "not_a_dir"};
+    fs::path tmp_file{tmp_dir / "not_real.sac"};
+    REQUIRE_THROWS_WITH(Trace(tmp_file), EndsWith("cannot be opened to read."));
+  }
+  SECTION("Write Throw") {
+    fs::path tmp_dir{fs::temp_directory_path() / "not_a_dir"};
+    fs::path tmp_file{tmp_dir / "not_real.sac"};
+    REQUIRE_THROWS_WITH(trace.write(tmp_file), EndsWith("cannot be opened to write."));
+  }
 }
 
 TEST_CASE("Geometric operations") {

src/sac_format.hpp

@@ -6,13 +6,23 @@
 #pragma once
 
 /* Standard library */
-#include <random>
+// std::chrono::steady_clock::now()
+#include <chrono>
+// std::setprecision
+#include <iomanip>
+// std::cout
+#include <iostream>
+// std::numeric_limits
+#include <limits>
 // INT_MIN and INT_MAX
 #include <limits.h>
-#include <limits>
-#include <string>
+// std::random_device, std::uniform_real_distribution
+#include <random>
 // ostringstream
 #include <sstream>
+// std::string
+#include <string>
+// std::vector
 #include <vector>
 /* Xoshiro Random Number generator */
 #include <XoshiroCpp.hpp>
@@ -73,9 +83,8 @@ inline double get(double min, double max) {
 
 void random_vector(std::vector<double> *data, const double minimum = -1.0,
                    const double maximum = 1.0) {
-  std::uniform_real_distribution<> die{minimum, maximum};
   for (std::size_t i{0}; i < data->size(); ++i) {
-    (*data)[i] = die(xos);
+    (*data)[i] = get(minimum, maximum);
   }
 }