From a9a7f0b186162a20e5e585b68492048869921f0e Mon Sep 17 00:00:00 2001 From: WerWolv Date: Sun, 26 Mar 2023 16:34:06 +0200 Subject: [PATCH] includes: Added documentation to the rest of the std and hex library --- includes/hex/dec.pat | 9 +++ includes/hex/http.pat | 9 +++ includes/hex/type/mangled.pat | 7 +++ includes/std/core.pat | 10 +++ includes/std/fxpt.pat | 54 ++++++++++++++++ includes/std/math.pat | 23 +++++++ includes/std/mem.pat | 112 +++++++++++++++++++++++++++++++++- includes/std/time.pat | 70 +++++++++++++++++++++ 8 files changed, 293 insertions(+), 1 deletion(-) diff --git a/includes/hex/dec.pat b/includes/hex/dec.pat index ba33fb3..4559557 100644 --- a/includes/hex/dec.pat +++ b/includes/hex/dec.pat @@ -2,8 +2,17 @@ #include +/*! + Library to allow decoding of more complex values +*/ + namespace hex::dec { + /** + Demangles a mangled name into a human readable name + @param mangled_name The mangled name + @return The demangled name + */ fn demangle(str mangled_name) { return builtin::hex::dec::demangle(mangled_name); }; diff --git a/includes/hex/http.pat b/includes/hex/http.pat index e99cd31..8d0ec5b 100644 --- a/includes/hex/http.pat +++ b/includes/hex/http.pat @@ -2,8 +2,17 @@ #include +/*! + Library to do HTTP requests +*/ + namespace hex::http { + /** + Performs a HTTP GET request to the given URL and returns the response body + @param url URL to perform the request to + @return Response body + */ fn get(str url) { return builtin::hex::http::get(url); }; diff --git a/includes/hex/type/mangled.pat b/includes/hex/type/mangled.pat index a80ebd1..c42e72d 100644 --- a/includes/hex/type/mangled.pat +++ b/includes/hex/type/mangled.pat @@ -6,8 +6,15 @@ #include #include +/*! + Types to automatically decode mangled names +*/ + namespace hex::type { + /** + A mangled name string that gets demangled when displayed + */ struct MangledName { char value[]; } [[sealed, format("hex::type::impl::format_mangled_name")]]; diff --git a/includes/std/core.pat b/includes/std/core.pat index c8cb3df..a579f1a 100644 --- a/includes/std/core.pat +++ b/includes/std/core.pat @@ -121,10 +121,20 @@ namespace std::core { }; + /** + Changes the color of the given pattern to a new color + @param pattern The pattern to modify + @param color The RGBA8 color + */ fn set_pattern_color(ref auto pattern, u32 color) { builtin::std::core::set_pattern_color(pattern, color); }; + /** + Changes the display name of a given pattern + @param pattern The pattern to modify + @param name The new display name of the pattern + */ fn set_display_name(ref auto pattern, str name) { builtin::std::core::set_display_name(pattern, name); }; diff --git a/includes/std/fxpt.pat b/includes/std/fxpt.pat index 4fa7105..90b5233 100644 --- a/includes/std/fxpt.pat +++ b/includes/std/fxpt.pat @@ -1,33 +1,87 @@ #pragma once +/*! + Library for doing arithmetic with fixed point numbers and converting them from/to floating point numbers. +*/ + namespace std::fxpt { + /** + A fixed point value + */ using fixed = s128; + /** + Converts a fixed point value into a floating point value + @param fxt The fixed point value to convert + @param precision The bits of precision the new value should have + @return The floating point representation of fxt + */ fn to_float(fixed fxt, u32 precision) { return double(fxt) / double((1 << precision)); }; + /** + Converts a floating point value into a fixed point value + @param flt The floating point value to convert + @param precision The bits of precision the new value should have + @return The fixed point representation of flt + */ fn to_fixed(double flt, u32 precision) { return fixed((flt * (1 << precision))); }; + /** + Changes the number of bits used to represent the decimal part of the given fixed point number + @param value The fixed point value to convert + @param start_precision The current number of bits used + @param end_precision The new number of bits used + @return `value` as a new fixed point number with `end_precision` bits of precision + */ fn change_precision(fixed value, u32 start_precision, u32 end_precision) { return std::fxpt::to_fixed(std::fxpt::to_float(value, start_precision), end_precision); }; + /** + Adds two fixed point numbers with a given precision together + @param a First fixed point number + @param b Second fixed point number + @param precision The precision of `a` and `b` + @return Result of the addition of `a` and `b` + */ fn add(fixed a, fixed b, u32 precision) { return a + b; }; + /** + Subtracts two fixed point numbers with a given precision together + @param a First fixed point number + @param b Second fixed point number + @param precision The precision of `a` and `b` + @return Result of the subtraction of `a` and `b` + */ fn subtract(fixed a, fixed b, u32 precision) { return a - b; }; + /** + Multiplies two fixed point numbers with a given precision together + @param a First fixed point number + @param b Second fixed point number + @param precision The precision of `a` and `b` + @return Result of the multiplication of `a` and `b` + */ fn multiply(fixed a, fixed b, u32 precision) { return (a * b) / (1 << precision); }; + /** + Divides two fixed point numbers with a given precision together + @param a First fixed point number + @param b Second fixed point number + @param precision The precision of `a` and `b` + @return Result of the division of `a` and `b` + */ fn divide(fixed a, fixed b, u32 precision) { return (a << precision) / b; }; diff --git a/includes/std/math.pat b/includes/std/math.pat index 6922404..8804e9d 100644 --- a/includes/std/math.pat +++ b/includes/std/math.pat @@ -2,8 +2,18 @@ #include +/*! + Library containing more advanced mathematical operations. +*/ + namespace std::math { + /** + Compares the values `a` and `b` with each other and returns the smaller of the two + @param a First value + @param b Second value + @return `a` if `a` is smaller than `b`, otherwise `b` + */ fn min(auto a, auto b) { if (a < b) return a; @@ -11,6 +21,12 @@ namespace std::math { return b; }; + /** + Compares the values `a` and `b` with each other and returns the bigger of the two + @param a First value + @param b Second value + @return `a` if `a` is bigger than `b`, otherwise `b` + */ fn max(auto a, auto b) { if (a > b) return a; @@ -18,6 +34,13 @@ namespace std::math { return b; }; + /** + Clamps the value of `x` between `min` and `max`. + @param x Value + @param min Minimum value + @param max Maximum value + @return `min` if `x` is smaller than `min`, `max` if `x` is bigger than `max`, `x` otherwise + */ fn clamp(auto x, auto min, auto max) { if (x < min) return min; diff --git a/includes/std/mem.pat b/includes/std/mem.pat index 979339a..9abbac7 100644 --- a/includes/std/mem.pat +++ b/includes/std/mem.pat @@ -1,19 +1,40 @@ #pragma once +/*! + Library for doing raw memory accesses and other low-level operations. +*/ + namespace std::mem { + /** + A Handle for a custom Section + */ using Section = u128; + /** + The Endianess of a value + */ enum Endian : u8 { Native = 0, Big = 1, Little = 2 }; + /** + Function that returns true if the cursor position is at the end of the memory + This is usually used in while-sized arrays in the form of `u8 array[while(!std::mem::eof())]` + @return True if the cursor is at the end of the memory + */ fn eof() { return $ >= std::mem::size(); }; + /** + Aligns the given value to the given alignment + @param alignment The alignment to align to + @param value The value to align + @return The aligned value + */ fn align_to(u128 alignment, u128 value) { u128 remainder = value % alignment; @@ -21,57 +42,132 @@ namespace std::mem { }; + /** + Gets the base address of the memory + @return The base address of the memory + */ fn base_address() { return builtin::std::mem::base_address(); }; + /** + Gets the size of the memory + @return The size of the memory + */ fn size() { return builtin::std::mem::size(); }; + /** + Finds a sequence of bytes in the memory + @param occurrence_index The index of the occurrence to find + @param bytes The bytes to find + @return The address of the sequence + */ fn find_sequence(u128 occurrence_index, auto ... bytes) { return builtin::std::mem::find_sequence_in_range(occurrence_index, builtin::std::mem::base_address(), builtin::std::mem::size(), bytes); }; + /** + Finds a sequence of bytes in a specific region of the memory + @param occurrence_index The index of the occurrence to find + @param offsetFrom The offset from which to start searching + @param offsetTo The offset to which to search + @param bytes The bytes to find + @return The address of the sequence + */ fn find_sequence_in_range(u128 occurrence_index, u128 offsetFrom, u128 offsetTo, auto ... bytes) { return builtin::std::mem::find_sequence_in_range(occurrence_index, offsetFrom, offsetTo, bytes); }; + /** + Reads a unsigned value from the memory + @param address The address to read from + @param size The size of the value to read + @param endian The endianess of the value to read + @return The value read + */ fn read_unsigned(u128 address, u8 size, Endian endian = Endian::Native) { return builtin::std::mem::read_unsigned(address, size, u32(endian)); }; + /** + Reads a signed value from the memory + @param address The address to read from + @param size The size of the value to read + @param endian The endianess of the value to read + @return The value read + */ fn read_signed(u128 address, u8 size, Endian endian = Endian::Native) { return builtin::std::mem::read_signed(address, size, u32(endian)); }; + /** + Reads a string value from the memory + @param address The address to read from + @param size The size of the value to read + @return The value read + */ fn read_string(u128 address, u8 size) { return builtin::std::mem::read_string(address, size); }; + /** + Creates a new custom section with the given name + @param name The name of the section + @return The handle to the section + */ fn create_section(str name) { return builtin::std::mem::create_section(name); }; + /** + Deletes a custom section + @param section The handle to the section + */ fn delete_section(Section section) { builtin::std::mem::delete_section(section); }; + /** + Gets the size of a custom section + @param section The handle to the section + @return The size of the section + */ fn get_section_size(Section section) { return builtin::std::mem::get_section_size(section); }; + /** + Copies a range of bytes from one section into another + @param from_section The section to copy from + @param from_address The address to copy from + @param to_section The section to copy to + @param to_address The address to copy to + @param size The size of the range to copy + */ fn copy_section_to_section(Section from_section, u64 from_address, Section to_section, u64 to_address, u64 size) { builtin::std::mem::copy_to_section(from_section, from_address, to_section, to_address, size); }; + /** + Copies a range of bytes from the main section into a custom section + @param from_section The section to copy from + @param from_address The address to copy from + @param to_address The address to copy to + @param size The size of the range to copy + */ fn copy_value_to_section(ref auto value, Section to_section, u64 to_address) { builtin::std::mem::copy_value_to_section(value, to_section, to_address); }; - + /** + Searches for a sequence of bytes and places the given type at that address + @tparam Magic The magic sequence to search for + @tparam T The type to place at the address + */ struct MagicSearch { if ($ < (std::mem::size() - std::string::length(Magic) - 1)) { char __potentialMagic__[std::string::length(Magic)] [[hidden, no_unique_address]]; @@ -88,15 +184,29 @@ namespace std::mem { } }; + /** + Reinterprets a value as a different one + @tparam From The type to reinterpret from + @tparam To The type to reinterpret to + */ union Reinterpreter { From from; To to; }; + + /** + Aligns the cursor to the given alignment + @tparam alignment The alignment to align to + */ struct AlignTo { padding[Alignment - ((($ - 1) % Alignment) + 1)]; } [[hidden, sealed]]; + /** + A type representing a sequence of bytes without any specific meaning + @tparam Size The size of the sequence + */ struct Bytes { u8 bytes[Size]; } [[sealed, format("std::mem::impl::format_bytes")]]; diff --git a/includes/std/time.pat b/includes/std/time.pat index 7a61750..388192e 100644 --- a/includes/std/time.pat +++ b/includes/std/time.pat @@ -2,8 +2,15 @@ #include +/*! + Library to handle time and date related operations. +*/ + namespace std::time { + /** + A structured representation of a time and date. + */ struct Time { u8 sec; u8 min; @@ -16,24 +23,39 @@ namespace std::time { bool isdst; } [[sealed]]; + /** + A helper type to convert between Time and u128. + */ union TimeConverter { Time time; u128 value; }; + /** + A type to represent a time in seconds since the epoch. + */ using EpochTime = u128; + /** + A type to represent a time zone. + */ enum TimeZone : u8 { Local, UTC }; + /** + A type to represent a DOS date. + */ bitfield DOSDate { day: 5; month: 4; year: 7; } [[sealed]]; + /** + A type to represent a DOS time. + */ bitfield DOSTime { seconds: 5; minutes: 6; @@ -54,10 +76,20 @@ namespace std::time { } + + /** + Returns the current time in seconds since the epoch. + @return The current time in seconds since the epoch. + */ fn epoch() { return builtin::std::time::epoch(); }; + /** + Converts a time in seconds since the epoch to a local time. + @param epoch_time The time in seconds since the epoch. + @return The local time. + */ fn to_local(EpochTime epoch_time) { TimeConverter converter; @@ -66,6 +98,11 @@ namespace std::time { return converter.time; }; + /** + Converts a time in seconds since the epoch to a UTC time. + @param epoch_time The time in seconds since the epoch. + @return The UTC time. + */ fn to_utc(EpochTime epoch_time) { TimeConverter converter; @@ -74,6 +111,11 @@ namespace std::time { return converter.time; }; + /** + Queries the current time in the specified time zone. + @param time_zone The time zone to query. + @return The current time in the specified time zone. + */ fn now(TimeZone time_zone = TimeZone::Local) { TimeConverter converter; @@ -87,6 +129,11 @@ namespace std::time { return converter.time; }; + /** + Converts a value to a DOS date. + @param value The value to convert. + @return The DOS date. + */ fn to_dos_date(u16 value) { impl::DOSDateConverter converter; @@ -95,6 +142,11 @@ namespace std::time { return converter.date; }; + /** + Converts a value to a DOS time. + @param value The value to convert. + @return The DOS time. + */ fn to_dos_time(u16 value) { impl::DOSTimeConverter converter; @@ -103,6 +155,12 @@ namespace std::time { return converter.time; }; + /** + Formats a time according to the specified format string. + @param time The time to format. + @param format_string The format string to use. + @return The formatted time. + */ fn format(Time time, str format_string = "%c") { TimeConverter converter; converter.time = time; @@ -110,10 +168,22 @@ namespace std::time { return builtin::std::time::format(format_string, converter.value); }; + /** + Formats a DOS date according to the specified format string. + @param date The DOS date to format. + @param format_string The format string to use. + @return The formatted DOS date. + */ fn format_dos_date(DOSDate date, str format_string = "{}/{}/{}") { return std::format(format_string, date.day, date.month, date.year + 1980); }; + /** + Formats a DOS time according to the specified format string. + @param time The DOS time to format. + @param format_string The format string to use. + @return The formatted DOS time. + */ fn format_dos_time(DOSTime time, str format_string = "{:02}:{:02}:{:02}") { return std::format(format_string, time.hours, time.minutes, time.seconds * 2); };