- Fixed Documentation for Consistency

- Added more documentation, predominantly in the Math Library

include/fennec/lang/bits.h

@@ -16,19 +16,31 @@
 //  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 // =====================================================================================================================
 
+///
+/// \file bits.h
+/// \brief bit-wise operations
+///
+///
+/// \details
+/// \author Medusa Slockbower
+///
+/// \copyright Copyright © 2025 Medusa Slockbower ([GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html))
+///
+///
+
 
 #ifndef FENNEC_LANG_BITS_H
 #define FENNEC_LANG_BITS_H
 
 #include <fennec/lang/intrinsics.h>
+#include <fennec/memory/memory.h>
 #include <fennec/lang/detail/__bits.h>
 
 namespace fennec
 {
 
 ///
-/// \fn fennec::bit_cast(const FromT&)
-/// \brief
+/// \brief perform a bitcast of FromT to ToT
 /// \tparam ToT Type to cast to
 /// \tparam FromT Type of the value
 /// \param from Value to bit cast
@@ -41,25 +53,110 @@ constexpr ToT bit_cast(const FromT& from)
 	else
 	{
 		ToT to;
-		memcpy(&to, &from, sizeof(ToT));
+		fennec::memcpy(&to, &from, sizeof(ToT));
 		return to;
 	}
 }
 
-constexpr void* bitmask(void* arr, const void* mask, size_t n)
+
+
+
+
+///
+/// \brief perform a bit-wise and over an array of bytes
+/// \param arr the array of bytes to modify
+/// \param mask the mask to and against arr
+/// \param n the number of bytes
+/// \returns the pointer arr
+constexpr void* bit_and(void* arr, const void* mask, size_t n)
 {
 	if (arr == mask) return arr;
 	uint8_t*       d = static_cast<uint8_t*>(arr);
 	const uint8_t* s = static_cast<const uint8_t*>(mask);
 
-	while (n >= 8) { detail::__bitmask_64(d, s); d += 8; s += 8; n -= 8; }
-	while (n >= 4) { detail::__bitmask_32(d, s); d += 4; s += 4; n -= 4; }
-	while (n >= 2) { detail::__bitmask_16(d, s); d += 2; s += 2; n -= 2; }
-	while (n >= 1) { *d++ = *s++; --n; }
+	while (n > 0)
+	{
+		size_t step = detail::__bit_and(d, s, n);
+		d += step; s += step; n -= step;
+	}
 
 	return arr;
 }
 
+///
+/// \brief safe version of fennec::bit_and
+/// \copydoc fennec::bit_and
+/// \param n0 the size of arr in bytes
+/// \param n1 the size of mask in bytes
+constexpr void* bit_and_s(void* arr, size_t n0, const void* mask, size_t n1)
+	{ return bit_and(arr, mask, n0 < n1 ? n0 : n1); }
+
+
+
+
+
+///
+/// \brief perform a bit-wise or over an array of bytes
+/// \param arr the array of bytes to modify
+/// \param mask the mask to or against arr
+/// \param n the number of bytes
+/// \returns the pointer arr
+constexpr void* bit_or(void* arr, const void* mask, size_t n)
+{
+	if (arr == mask) return arr;
+	uint8_t*       d = static_cast<uint8_t*>(arr);
+	const uint8_t* s = static_cast<const uint8_t*>(mask);
+
+	while (n > 0)
+	{
+		size_t step = detail::__bit_or(d, s, n);
+		d += step; s += step; n -= step;
+	}
+
+	return arr;
+}
+
+///
+/// \brief safe version of fennec::bit_or
+/// \copydoc fennec::bit_or
+/// \param n0 the size of arr in bytes
+/// \param n1 the size of mask in bytes
+constexpr void* bit_or_s(void* arr, size_t n0, const void* mask, size_t n1)
+	{ return bit_or(arr, mask, n0 < n1 ? n0 : n1); }
+
+
+
+
+
+///
+/// \brief perform a bit-wise or over an array of bytes
+/// \param arr the array of bytes to modify
+/// \param mask the mask to or against arr
+/// \param n the number of bytes
+/// \returns the pointer arr
+constexpr void* bit_xor(void* arr, const void* mask, size_t n)
+{
+	if (arr == mask) return arr;
+	uint8_t*       d = static_cast<uint8_t*>(arr);
+	const uint8_t* s = static_cast<const uint8_t*>(mask);
+
+	while (n > 0)
+	{
+		size_t step = detail::__bit_xor(d, s, n);
+		d += step; s += step; n -= step;
+	}
+
+	return arr;
+}
+
+///
+/// \brief safe version of fennec::bit_xor
+/// \copydoc fennec::bit_xor
+/// \param n0 the size of arr in bytes
+/// \param n1 the size of mask in bytes
+constexpr void* bit_xor_s(void* arr, size_t n0, const void* mask, size_t n1)
+	{ return bit_xor(arr, mask, n0 < n1 ? n0 : n1); }
+
 }
 
 #endif // FENNEC_LANG_BITS_H