From 3edc6ea17270d9befef95d634d1f0318a9c8d4a7 Mon Sep 17 00:00:00 2001 From: WerWolv Date: Sun, 26 Mar 2023 16:58:39 +0200 Subject: [PATCH] includes: Added documentation for a few more files --- includes/hex/core.pat | 11 +++ includes/std/math.pat | 189 +++++++++++++++++++++++++++++++++++++++- includes/std/string.pat | 102 ++++++++++++++++++++-- 3 files changed, 296 insertions(+), 6 deletions(-) diff --git a/includes/hex/core.pat b/includes/hex/core.pat index 988d38c..80bf0ab 100644 --- a/includes/hex/core.pat +++ b/includes/hex/core.pat @@ -2,13 +2,24 @@ #include +/*! + Core intrinsic functions to interact with the ImHex Hex Editor +*/ + namespace hex::core { + /** + A type representing a selection in the hex editor + */ struct Selection { bool valid; u64 address, size; }; + /** + Returns the current selection in the hex editor + @return The current selection + */ fn get_selection() { u128 result = builtin::hex::core::get_selection(); diff --git a/includes/std/math.pat b/includes/std/math.pat index 8804e9d..e6492c5 100644 --- a/includes/std/math.pat +++ b/includes/std/math.pat @@ -50,6 +50,11 @@ namespace std::math { return x; }; + /** + Returns the absolute value of `x`. + @param x Value + @return `x` if `x` is positive, `-x` otherwise + */ fn abs(auto x) { if (x < 0) return -x; @@ -57,6 +62,11 @@ namespace std::math { return x; }; + /** + Returns the sign of `x`. + @param x Value + @return `1` if `x` is positive, `-1` if `x` is negative, `0` if `x` is zero + */ fn sign(auto x) { if (x > 0) return 1; @@ -66,6 +76,12 @@ namespace std::math { return 0; }; + /** + Copies the sign of `y` to `x`. + @param x Value + @param y Value + @return `x` if `y` is positive, `-x` if `y` is negative + */ fn copy_sign(auto x, auto y) { if (y >= 0) return std::math::abs(x); @@ -73,6 +89,11 @@ namespace std::math { return -std::math::abs(x); }; + /** + Calculates the factorial of `x`. + @param x Value + @return Factorial of `x` + */ fn factorial(u128 x) { u128 result; @@ -85,6 +106,12 @@ namespace std::math { return result; }; + /** + Calculates the binomial coefficient of `n` and `k`. + @param n Value + @param k Value + @return Binomial coefficient of `n` and `k` + */ fn comb(u128 n, u128 k) { if (k > n) return 0; @@ -92,6 +119,12 @@ namespace std::math { return std::math::factorial(n) / (std::math::factorial(k) * std::math::factorial(n - k)); }; + /** + Calculates the permutation of `n` and `k`. + @param n Value + @param k Value + @return Permutation of `n` and `k` + */ fn perm(u128 n, u128 k) { if (k > n) return 0; @@ -99,38 +132,182 @@ namespace std::math { return std::math::factorial(n) / std::math::factorial(n - k); }; - + /** + Floors the value of `value`. + @param value Value + @return `value` floored + */ fn floor(auto value) { return builtin::std::math::floor(value); }; + + /** + Ceils the value of `value`. + @param value Value + @return `value` ceiled + */ fn ceil(auto value) { return builtin::std::math::ceil(value); }; + + /** + Rounds the value of `value`. + @param value Value + @return `value` rounded + */ fn round(auto value) { return builtin::std::math::round(value); }; + + /** + Truncates the value of `value`. + @param value Value + @return `value` truncated + */ fn trunc(auto value) { return builtin::std::math::trunc(value); }; + + /** + Calculates the logarithm of `value` with base 10. + @param value Value + @return Logarithm of `value` with base 10 + */ fn log10(auto value) { return builtin::std::math::log10(value); }; + + /** + Calculates the logarithm of `value` with base 2. + @param value Value + @return Logarithm of `value` with base 2 + */ fn log2(auto value) { return builtin::std::math::log2(value); }; + + /** + Calculates the natural logarithm of `value`. + @param value Value + @param base Base + @return Logarithm of `value` with base `e` + */ fn ln(auto value) { return builtin::std::math::ln(value); }; + /** + Calculates the floating point modulus of `value`. + @param value Value + @return Floating point modulus of `value` + */ fn fmod(auto value) { return builtin::std::math::fmod(value); }; + + /** + Calculates the value of `base` raised to the power of `exp`. + @param base Base + @param exp Exponent + @return `base` raised to the power of `exp` + */ fn pow(auto base, auto exp) { return builtin::std::math::pow(base, exp); }; + + /** + Calculates the square root of `value`. + @param value Value + @return Square root of `value` + */ fn sqrt(auto value) { return builtin::std::math::sqrt(value); }; + + /** + Calculates the cubic root of `value`. + @param value Value + @return Cubic root of `value` + */ fn cbrt(auto value) { return builtin::std::math::cbrt(value); }; + /** + Calculates the sine of `value`. + @param value Angle value in radians + @return Sine of `value` + */ fn sin(auto value) { return builtin::std::math::sin(value); }; + + /** + Calculates the cosine of `value`. + @param value Angle value in radians + @return Cosine of `value` + */ fn cos(auto value) { return builtin::std::math::cos(value); }; + + /** + Calculates the tangent of `value`. + @param value Angle value in radians + @return Tangent of `value` + */ fn tan(auto value) { return builtin::std::math::tan(value); }; + /** + Calculates the arc sine of `value`. + @param value Angle value in radians + @return Arc sine of `value` + */ fn asin(auto value) { return builtin::std::math::asin(value); }; + + /** + Calculates the arc cosine of `value`. + @param value Value + @return Arc cosine of `value` in radians + */ fn acos(auto value) { return builtin::std::math::acos(value); }; + + /** + Calculates the arc tangent of `value`. + @param value Value + @return Arc tangent of `value` in radians between `-pi/2` and `pi/2` + */ fn atan(auto value) { return builtin::std::math::atan(value); }; + + /** + Calculates the arc tangent of `value`. + @param value Value + @return Arc tangent of `value` in radians between `-pi` and `pi` + */ fn atan2(auto value) { return builtin::std::math::atan2(value); }; + /** + Calculates the hyperbolic sine of `value`. + @param value Angle value in radians + @return Hyperbolic sine of `value` + */ fn sinh(auto value) { return builtin::std::math::sinh(value); }; + + /** + Calculates the hyperbolic cosine of `value`. + @param value Angle value in radians + @return Hyperbolic cosine of `value` + */ fn cosh(auto value) { return builtin::std::math::cosh(value); }; + + /** + Calculates the hyperbolic tangent of `value`. + @param value Angle value in radians + @return Hyperbolic tangent of `value` + */ fn tanh(auto value) { return builtin::std::math::tanh(value); }; + + /** + Calculates the arc hyperbolic sine of `value`. + @param value Value + @return Arc hyperbolic sine of `value` + */ fn asinh(auto value) { return builtin::std::math::asinh(value); }; + + /** + Calculates the arc hyperbolic cosine of `value`. + @param value Value + @return Arc hyperbolic cosine of `value` + */ fn acosh(auto value) { return builtin::std::math::acosh(value); }; + + /** + Calculates the arc hyperbolic tangent of `value`. + @param value Value + @return Arc hyperbolic tangent of `value` + */ fn atanh(auto value) { return builtin::std::math::atanh(value); }; + + /** + Options to use with the `std::math::accumulate` function. + */ enum AccumulateOperation : u8 { Add = 0, Multiply = 1, @@ -139,6 +316,16 @@ namespace std::math { Max = 4 }; + /** + Calculates the sum of all values in the specified memory range. + @param start Start address + @param end End address + @param valueSize Size of each value in bytes + @param section Section to use + @param operation Operation to use + @param endian Endianness to use + @return Sum of all values in the specified memory range + */ fn accumulate(u128 start, u128 end, u128 valueSize, std::mem::Section section = 0, AccumulateOperation operation = AccumulateOperation::Add, std::mem::Endian endian = std::mem::Endian::Native) { return builtin::std::math::accumulate(start, end, valueSize, section, u128(operation), u128(endian)); }; diff --git a/includes/std/string.pat b/includes/std/string.pat index 62a3e4c..67af869 100644 --- a/includes/std/string.pat +++ b/includes/std/string.pat @@ -2,14 +2,32 @@ #include +/*! + Libray to interact with strings. +*/ + namespace std::string { + /** + Base type for sized strings. Represents a string with its size preceeding it. + @tparam SizeType The type of the size field. + @tparam DataType The type of the characters. + */ struct SizedStringBase { SizeType size; DataType data[size]; } [[sealed, format("std::string::impl::format_sized_string"), transform("std::string::impl::format_sized_string")]]; + /** + A ASCII string with a prefixed size. + @tparam SizeType The type of the size field. + */ using SizedString = SizedStringBase; + + /** + A UTF-16 string with a prefixed size. + @tparam SizeType The type of the size field. + */ using SizedString16 = SizedStringBase; namespace impl { @@ -20,52 +38,109 @@ namespace std::string { } + /** + Gets the length of a string. + @param string The string to get the length of. + @return The length of the string. + */ fn length(str string) { return builtin::std::string::length(string); }; + /** + Gets the character at a given index. + @param string The string to get the character from. + @param index The index of the character to get. + @return The character at the given index. + */ fn at(str string, u32 index) { return builtin::std::string::at(string, index); }; + /** + Gets a substring of a string. + @param string The string to get the substring from. + @param pos The position of the first character of the substring. + @param count The number of characters to get. + @return The substring. + */ fn substr(str string, u32 pos, u32 count) { return builtin::std::string::substr(string, pos, count); }; + /** + Converts a string to an integer. + @param string The string to convert. + @param base The base of the number. + @return The integer. + */ fn parse_int(str string, u8 base) { return builtin::std::string::parse_int(string, base); }; + /** + Converts a string to a float. + @param string The string to convert. + @return The float. + */ fn parse_float(str string) { return builtin::std::string::parse_float(string); }; + /** + Converts any type to a string. + @param x The value to convert. + @return The string. + */ fn to_string(auto x) { return std::format("{}", x); }; + /** + Checks if a string starts with a given substring. + @param string The string to check. + @param part The substring to check for. + @return True if the string starts with the substring, false otherwise. + */ fn starts_with(str string, str part) { return std::string::substr(string, 0, std::string::length(part)) == part; }; + /** + Checks if a string ends with a given substring. + @param string The string to check. + @param part The substring to check for. + @return True if the string ends with the substring, false otherwise. + */ fn ends_with(str string, str part) { return std::string::substr(string, std::string::length(string) - std::string::length(part), std::string::length(part)) == part; }; - fn contains(str a, str b) { - s32 a_len = std::string::length(a); - s32 b_len = std::string::length(b); + /** + Checks if a string contains a given substring. + @param string The string to check. + @param part The substring to check for. + @return True if the string contains the substring, false otherwise. + */ + fn contains(str string, str part) { + s32 string_len = std::string::length(string); + s32 part_len = std::string::length(part); - for (s32 i = 0, i <= (a_len - b_len), i += 1) { - if (std::string::substr(a, i, b_len) == b) + for (s32 i = 0, i <= (string_len - part_len), i += 1) { + if (std::string::substr(string, i, part_len) == part) return true; } return false; }; + /** + Reverses a string. + @param string The string to reverse. + @return The reversed string. + */ fn reverse(str string) { str result; @@ -79,6 +154,11 @@ namespace std::string { return result; }; + /** + Converts a string to upper case. + @param string The string to convert. + @return The converted string. + */ fn to_upper(str string) { str result; @@ -98,6 +178,11 @@ namespace std::string { return result; }; + /** + Converts a string to lower case. + @param string The string to convert. + @return The converted string. + */ fn to_lower(str string) { str result; @@ -117,6 +202,13 @@ namespace std::string { return result; }; + /** + Replaces all occurrences of a substring with another substring. + @param string The string to replace in. + @param pattern The substring to replace. + @param replace The substring to replace with. + @return The string with the replacements. + */ fn replace(str string, str pattern, str replace) { u32 string_len, pattern_len, replace_len; string_len = std::string::length(string);