adding more to intro

There should be a devlog entry shortly describing this, but the
code for IsParallel wasn't working on arm64 (Linux or Darwin).
Floating point math is weird.

.idea/codeStyles/Project.xml

@@ -7,6 +7,9 @@
       <option name="FUNCTION_BRACE_PLACEMENT" value="2" />
       <option name="FUNCTION_TOP_AFTER_RETURN_TYPE_WRAP" value="2" />
     </Objective-C>
+    <clangFormatSettings>
+      <option name="ENABLED" value="true" />
+    </clangFormatSettings>
     <files>
       <extensions>
         <pair source="cc" header="h" fileNamingConvention="PASCAL_CASE" />

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.22)
 project(scsl LANGUAGES CXX
-        VERSION 1.0.0
+        VERSION 1.1.4
         DESCRIPTION "Shimmering Clarity Standard Library")
 
 set(CMAKE_CXX_STANDARD 14)
@@ -154,7 +154,7 @@ add_custom_target(deploy-docs
 configure_file(scsl.pc.in scsl.pc @ONLY)
 install(TARGETS scsl LIBRARY DESTINATION lib)
 install(TARGETS phonebook RUNTIME DESTINATION bin)
-install(FILES ${HEADER_FILES} DESTINATION include/scsl)
+install(DIRECTORY include/ DESTINATION include)
 install(FILES scslConfig.cmake DESTINATION share/scsl/cmake)
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/scsl.pc DESTINATION lib/pkgconfig)
 

cmake/packaging.cmake

@@ -20,9 +20,9 @@ set(CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS ON)
 set(CPACK_DEBIAN_FILE_NAME DEB-DEFAULT)
 
 if(LINUX)
-set(CPACK_GENERATOR "DEB;STGZ;TGZ")
+set(CPACK_GENERATOR "DEB;RPM;STGZ;TGZ")
 elseif(APPLE)
-set(CPACK_GENERATOR "productbuild")
+set(CPACK_GENERATOR "STGZ;TGZ")
 elseif(MSVC OR MSYS OR MINGW)
 set(CPACK_GENERATOR "NSIS;ZIP")
 else()

include/scmp/Math.h

@@ -115,6 +115,13 @@ WithinTolerance(T a, T b, T epsilon)
 }
 
 
+/// \brief Integer square-root.
+///
+/// \param n A max-value integer whose square root should be returned.
+/// \return The square root of $n$.
+size_t	ISqrt(size_t n);
+
+
 } // namespace scmp
 
 

include/scmp/geom/Quaternion.h

@@ -42,7 +42,7 @@ namespace geom {
 ///        and rotations in three dimensions.
 ///
 /// Quaternions encode rotations in three-dimensional space. While
-/// technically a MakeQuaternion is comprised of a real element and a
+/// technically a Quaternion is comprised of a real element and a
 /// complex vector<3>, for the purposes of this library, it is modeled
 /// as a floating point 4D vector of the form <w, x, y, z>, where x, y,
 /// and z represent an Axis of rotation in R3 and w the Angle, in

include/scmp/geom/Vector.h

@@ -193,8 +193,8 @@ public:
 	T
 	Angle(const Vector<T, N> &other) const
 	{
-		Vector<T, N> unitA = this->UnitVector();
+		auto unitA = this->UnitVector();
-		Vector<T, N> unitB = other.UnitVector();
+		auto unitB = other.UnitVector();
 
 		// Can't compute angles with a zero vector.
 		assert(!this->IsZero());
@@ -214,12 +214,24 @@ public:
 			return true;
 		}
 
-		T angle = this->Angle(other);
+		// If the two unit vectors are equal, the two vectors
-		if (scmp::WithinTolerance(angle, (T) 0.0, this->epsilon)) {
+		// lie on the same path.
-			return true;
+		//
-		}
+		// Context: this used to use Vector::Angle to check for
+		// a zero angle between the two. However, the vagaries
+		// of floating point math meant that while this worked
+		// fine on Linux amd64 builds, it failed on Linux arm64
+		// and MacOS builds. Parallel float vectors would have
+		// an angle of ~0.0003 radians, while double vectors
+		// would have an angle of +NaN. I suspect this is due to
+		// tiny variations in floating point math, such that a dot
+		// product of unit vectors would be just a hair over 1,
+		// e.g. 1.000000001 - which would still fall outside the
+		// domain of acos.
+		auto unitA = this->UnitVector();
+		auto unitB = other.UnitVector();
 
-		return false;
+		return unitA == unitB;
 	}
 
 

include/scsl/SimpleConfig.h

@@ -110,6 +110,27 @@ public:
 	/// \return The value stored under the key, or an empty string.
 	static std::string	GetGlobal(std::string &key);
 
+	/// \brief Get the value stored for the key from the config.
+	///
+	/// \note This operates on the global config.
+	///
+	/// \param key The key to look up. See the class documentation
+	///        for information on how this is used.
+	/// \return The value stored under the key, or an empty string.
+	static std::string	GetGlobal(const char *key);
+
+	/// \brief Get the value stored for the key from the config.
+	///
+	/// \note This operates on the global config.
+	///
+	/// \param key The key to look up. See the class documentation
+	///        for information on how this is used.
+	/// \param defaultValue A default value to cache and use if no
+	///        value is stored under the key.
+	/// \return The value stored under the key, or the default
+	///         value.
+	static std::string	GetGlobal(const char *key, const std::string &defaultValue);
+
 	/// \brief Get the value stored for the key from the config.
 	///
 	/// \note This operates on the global config.
@@ -121,6 +142,14 @@ public:
 	/// \return The value stored under the key, or the default
 	///         value.
 	static std::string	GetGlobal(std::string &key, const std::string &defaultValue);
+
+	/// \brief Set a configuration value. This will override any
+	///        value set.
+	static void	 	PutGlobal(std::string &key, const std::string &value);
+
+	/// \brief Set a configuration value. This will override any
+	///        value set.
+	static void	 	PutGlobal(const char *key, const std::string &value);
 #endif
 
 	/// \brief The constructor doesn't need any initialisation.
@@ -163,6 +192,13 @@ public:
 	/// \return The value stored under the key, or an empty string.
 	std::string	Get(std::string &key);
 
+	/// \brief Get the value stored for the key from the config.
+	///
+	/// \param key The key to look up. See the class documentation
+	///        for information on how this is used.
+	/// \return The value stored under the key, or an empty string.
+	std::string	Get(const char *key);
+
 	/// \brief Get the value stored for the key from the config.
 	///
 	/// \param key The key to look up. See the class documentation
@@ -173,6 +209,31 @@ public:
 	///         value.
 	std::string	Get(std::string &key, std::string defaultValue);
 
+	/// \brief Get the value stored for the key from the config.
+	///
+	/// \param key The key to look up. See the class documentation
+	///        for information on how this is used.
+	/// \param defaultValue A default value to cache and use if no
+	///        value is stored under the key.
+	/// \return The value stored under the key, or the default
+	///         value.
+	std::string	Get(const char *key, std::string defaultValue);
+
+	/// \brief Set a configuration value. This will override any
+	///        value set.
+	///
+	/// \param key The key to look up. See the class documentation
+	///        for information on how this is used.
+	/// \param value The value to set.
+	void 	Put(std::string &key, const std::string value);
+
+	/// \brief Set a configuration value. This will override any
+	///        value set.
+	///
+	/// \param key The key to look up. See the class documentation
+	///        for information on how this is used.
+	/// \param value The value to set.
+	void	Put(const char *key, const std::string value);
 private:
 	std::string 				envPrefix;
 	std::map<std::string, std::string>	vars;

include/scsl/scsl.h

@@ -72,6 +72,12 @@ namespace scsl {
 /// working on a graphical editor. For this, I needed some data structures to
 /// manage memory in the editor. Thus, Buffer was born.
 ///
+/// \subsection finally Finally
+///
+/// I'd been writing Go professionally for a while, but C was my first love. I
+/// recently started a job that is mostly in C++, and the best way for me to
+/// learn is to build a bunch of stuff with it. So, I took a bunch of micro-
+/// controller stuff I'd been writing and started building out some other stuff.
 
 
 }

src/scmp/Math.cc

@@ -151,5 +151,37 @@ DefaultEpsilon(int& epsilon)
 }
 
 
+size_t
+ISqrt(size_t n)
+{
+	if (n < 2) {
+		return n;
+	}
+
+	size_t	start = 0;
+	size_t	end = n / 2;
+	size_t	result = 0;
+
+	while (start <= end) {
+		auto middle = (start + end) >> 1;
+		result = middle * middle;
+		if (result == n) {
+			return middle;
+		}
+
+		if (result < n) {
+			start = middle + 1;
+			result = middle;
+		} else {
+			end = middle - 1;
+			result = middle;
+		}
+	}
+
+	return result;
+}
+
+
+
 } // namespace scmp
 

src/sl/Flags.cc

@@ -25,9 +25,9 @@
 #include <regex>
 #include <utility>
 
-#include <vector>
 #include <scsl/Flags.h>
 #include <scsl/StringUtil.h>
+#include <vector>
 
 
 namespace scsl {
@@ -300,7 +300,6 @@ Flags::Parse(int argc, char **argv, bool skipFirst)
 			throw std::runtime_error("unhandled parse state");
 #endif
 		}
-
 	}
 
 	return ParseStatus::OK;
@@ -313,26 +312,44 @@ Flags::Usage(std::ostream &os, int exitCode)
 	os << this->name << ":\t";
 	auto indent = this->name.size() + 7;
 
-	scstring::WriteTabIndented(os, description, 72 - indent, indent / 8, false);
+	scstring::WriteTabIndented(os, this->description, 72 - indent,
+				   indent / 8, false);
 	os << "\n\n";
 
 	for (const auto &pair: this->flags) {
+		auto argDesc = pair.second->Description;
+		if (!argDesc.empty()) {
+			argDesc += ' ';
+		}
 		auto argLine = "\t" + pair.first;
 		switch (pair.second->Type) {
 		case FlagType::Boolean:
 			argLine += "\t\t";
+			argDesc += "(default=false)";
 			break;
 		case FlagType::Integer:
 			argLine += " int\t\t";
+			if (pair.second->Value.i != 0) {
+				argDesc += "(default=" + std::to_string(pair.second->Value.i) + ")";
+			}
 			break;
 		case FlagType::UnsignedInteger:
 			argLine += " uint\t\t";
+			if (pair.second->Value.u != 0) {
+				argDesc += "(default=" + std::to_string(pair.second->Value.u) + ")";
+			}
 			break;
 		case FlagType::SizeT:
 			argLine += " size_t\t";
+			if (pair.second->Value.size != 0) {
+				argDesc += "(default=" + std::to_string(pair.second->Value.size) + ")";
+			}
 			break;
 		case FlagType::String:
 			argLine += " string\t";
+			if (pair.second->Value.s != nullptr && !(pair.second->Value.s->empty())) {
+				argDesc += "(default=" + *(pair.second->Value.s) + ")";
+			}
 			break;
 		case FlagType::Unknown:
 			// fallthrough
@@ -347,8 +364,8 @@ Flags::Usage(std::ostream &os, int exitCode)
 
 		os << argLine;
 		indent = argLine.size();
-		scstring::WriteTabIndented(os, pair.second->Description,
+		scstring::WriteTabIndented(os, argDesc, 72 - indent,
-				       72-indent, (indent/8)+2, false);
+					   (indent / 8) + 2, false);
 	}
 
 	os << "\n";
@@ -456,4 +473,3 @@ Flags::GetString(std::string fName, std::string &flagValue)
 
 
 }// namespace scsl
-

src/sl/SimpleConfig.cc

@@ -83,6 +83,13 @@ SimpleConfig::GetGlobal(std::string &key)
 }
 
 
+std::string
+SimpleConfig::GetGlobal(const char *key)
+{
+	return globalConfig.Get(key);
+}
+
+
 std::string
 SimpleConfig::GetGlobal(std::string &key, const std::string &defaultValue)
 {
@@ -90,6 +97,27 @@ SimpleConfig::GetGlobal(std::string &key, const std::string &defaultValue)
 }
 
 
+std::string
+SimpleConfig::GetGlobal(const char *key, const std::string &defaultValue)
+{
+	return globalConfig.Get(key, defaultValue);
+}
+
+
+void
+SimpleConfig::PutGlobal(std::string &key, const std::string &value)
+{
+	return globalConfig.Put(key, value);
+}
+
+
+void
+SimpleConfig::PutGlobal(const char *key, const std::string &value)
+{
+	return globalConfig.Put(key, value);
+}
+
+
 SimpleConfig::SimpleConfig()
 {
 }
@@ -153,6 +181,14 @@ SimpleConfig::Get(std::string &key)
 }
 
 
+std::string
+SimpleConfig::Get(const char *key)
+{
+	auto keyStr = std::string(key);
+	return this->Get(keyStr, "");
+}
+
+
 std::string
 SimpleConfig::Get(std::string &key, std::string defaultValue)
 {
@@ -173,6 +209,29 @@ SimpleConfig::Get(std::string &key, std::string defaultValue)
 }
 
 
+std::string
+SimpleConfig::Get(const char *key, std::string defaultValue)
+{
+	auto keyStr = std::string(key);
+	return this->Get(keyStr, std::move(defaultValue));
+}
+
+
+void
+SimpleConfig::Put(std::string &key, const std::string value)
+{
+	this->vars[key] = std::move(value);
+}
+
+
+void
+SimpleConfig::Put(const char *key, const std::string value)
+{
+	auto keyStr = std::string(key);
+	this->vars[std::move(keyStr)] = std::move(value);
+}
+
+
 std::vector<std::string>
 SimpleConfig::KeyList()
 {

test/math.cc

@@ -116,6 +116,35 @@ RotateRadians()
 }
 
 
+bool
+IntegerSquareRoot()
+{
+	static std::vector<size_t> ns{
+	    // standard integer roots
+	    4, 9, 16, 25, 36, 49, 64, 81, 100, 121, 144,
+
+	    // a few float cases
+	    42, 90, 92
+	};
+	static std::vector<size_t> expected{
+	    // standard integer roots
+	    2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
+
+	    // a few float cases
+	    6, 9, 10
+	};
+
+	SCTEST_CHECK_EQ(ns.size(), expected.size());
+
+	for (size_t i = 0; i < ns.size(); i++) {
+		auto root = scmp::ISqrt(ns.at(i));
+		SCTEST_CHECK_EQ(root, expected.at(i));
+	}
+
+	return true;
+}
+
+
 } // anonymous namespace
 
 
@@ -148,6 +177,7 @@ main(int argc, char *argv[])
 	suite.AddTest("WithinToleranceFloat", WithinToleranceFloat);
 	suite.AddTest("WithinToleranceDouble", WithinToleranceDouble);
 	suite.AddTest("RotateRadians", RotateRadians);
+	suite.AddTest("IntegerSquareRoot", IntegerSquareRoot);
 
 	delete flags;
 	auto result = suite.Run();