admin/omath
1
0
Fork 0
mirror of https://github.com/orange-cpp/omath.git synced 2026-02-13 07:03:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documents pattern scanning API

Browse Source 
Adds comprehensive documentation for the pattern scanning API.

Details parsing behavior, complexity, and usage examples.
Includes troubleshooting tips and minimal test sketches.
Clarifies edge-case handling and implementation notes.
This commit is contained in:
Orange
2025-10-31 16:25:56 +03:00
parent 56505cf3e1
commit 9212b1f51f
4 changed files with 600 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
docs/utility/color.md Normal file
View File

@@ -0,0 +1,190 @@
# `omath::Color` — RGBA color with HSV helpers (C++20/23)
> Header: your project’s `color.hpp`
> Namespace: `omath`
> Inherits: `Vector4<float>` (`x=r`, `y=g`, `z=b`, `w=a`)
> Depends on: `<cstdint>`, `Vector4`, optionally ImGui (`OMATH_IMGUI_INTEGRATION`)
> Formatting: provides `std::formatter<omath::Color>`
`Color` is a tiny RGBA utility on top of `Vector4<float>`. It offers sRGB-style channel construction, HSV↔RGB conversion, in-place HSV setters, linear blending, and string/formatter helpers.
---
## Quick start
```cpp
#include "color.hpp"
using omath::Color;
// RGBA in [0,1] (r,g,b clamped to [0,1] on construction)
Color c{0.2f, 0.4f, 0.8f, 0.5f};
// From 8-bit channels
auto red = Color::from_rgba(255, 0, 0, 255);
auto green = Color::from_rgba(0, 255, 0, 160);
// From HSV (h ∈ [0,1], s ∈ [0,1], v ∈ [0,1])
auto cyan = Color::from_hsv(0.5f, 1.0f, 1.0f); // a = 1
// Read/modify via HSV
auto hsv = cyan.to_hsv(); // hue ∈ [0,1], saturation ∈ [0,1], value ∈ [0,1]
cyan.set_value(0.6f); // converts back to RGB (alpha becomes 1)
// Blend linearly (lerp)
auto mid = red.blend(green, 0.5f);
// Printable (0–255 per channel)
std::string s = std::format("{}", mid); // "[r:128, g:128, b:0, a:207]" for example
```
---
## Data model
* Inherits `Vector4<float>`:
* `x` = **red**, `y` = **green**, `z` = **blue**, `w` = **alpha**.
* Construction clamps **RGB** to `[0,1]` (via `Vector4::clamp(0,1)`), **alpha is not clamped** by that call (see notes).
---
## Construction & factories
```cpp
// RGBA in [0,1] (RGB clamped to [0,1]; alpha untouched by clamp)
constexpr Color(float r, float g, float b, float a) noexcept;
// Default
constexpr Color() noexcept;
// From 8-bit RGBA (0–255) → normalized to [0,1]
constexpr static Color from_rgba(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept;
// From HSV where hue ∈ [0,1], saturation ∈ [0,1], value ∈ [0,1]
struct Hsv { float hue{}, saturation{}, value{}; };
constexpr static Color from_hsv(float hue, float saturation, float value) noexcept;
constexpr static Color from_hsv(const Hsv& hsv) noexcept; // delegates to the above
// Construct from a Vector4 (RGB clamped, alpha not clamped)
constexpr explicit Color(const Vector4& vec) noexcept;
```
**HSV details**
* `from_hsv(h, s, v)`: `h` is **normalized** (`[0,1]`); it is clamped, then mapped to the 6 hue sectors; **alpha = 1.0**.
* `to_hsv()`: returns `Hsv{h,s,v}` with **`h ∈ [0,1]`** (internally computes degrees and divides by 360), `s,v ∈ [0,1]`.
---
## Mutators
```cpp
constexpr void set_hue(float h) noexcept; // h ∈ [0,1] recommended
constexpr void set_saturation(float s) noexcept; // s ∈ [0,1]
constexpr void set_value(float v) noexcept; // v ∈ [0,1]
// Linear blend: (1-ratio)*this + ratio*other, ratio clamped to [0,1]
constexpr Color blend(const Color& other, float ratio) const noexcept;
```
> ⚠️ **Alpha reset on HSV setters:** each `set_*` converts HSV→RGB using `from_hsv(...)`, which **sets alpha to 1.0** (overwriting previous `w`). If you need to preserve alpha:
>
> ```cpp
> float a = col.w;
> col.set_value(0.5f);
> col.w = a;
> ```
---
## Constants
```cpp
static constexpr Color red(); // (1,0,0,1)
static constexpr Color green(); // (0,1,0,1)
static constexpr Color blue(); // (0,0,1,1)
```
---
## String & formatting
```cpp
// "[r:R, g:G, b:B, a:A]" with each channel shown as 0–255 integer
std::string to_string() const noexcept;
std::wstring to_wstring() const noexcept;
std::u8string to_u8string() const noexcept;
// Formatter forwards to the above (char/wchar_t/char8_t)
template<> struct std::formatter<omath::Color>;
```
---
## ImGui (optional)
```cpp
#ifdef OMATH_IMGUI_INTEGRATION
ImColor to_im_color() const noexcept; // constructs from Vector4's to_im_vec4()
#endif
```
Ensure `<imgui.h>` is included somewhere before this header when the macro is enabled.
---
## Notes & caveats
* **Alpha clamping:** `Vector4::clamp(min,max)` (called by `Color` ctors) clamps **x,y,z** only in the provided `Vector4` implementation; `w` is **left unchanged**. If you require strict `[0,1]` alpha, clamp it yourself:
```cpp
col.w = std::clamp(col.w, 0.0f, 1.0f);
```
* **HSV range:** The API consistently uses **normalized hue** (`[0,1]`). Convert degrees ↔ normalized as `h_norm = h_deg / 360.f`.
* **Blend space:** `blend` is a **linear** interpolation in RGBA; it is not perceptually uniform.
---
## API summary
```cpp
struct Hsv { float hue{}, saturation{}, value{}; };
class Color final : public Vector4<float> {
public:
constexpr Color(float r, float g, float b, float a) noexcept;
constexpr Color() noexcept;
constexpr explicit Color(const Vector4& vec) noexcept;
static constexpr Color from_rgba(uint8_t r, uint8_t g, uint8_t b, uint8_t a) noexcept;
static constexpr Color from_hsv(float hue, float saturation, float value) noexcept;
static constexpr Color from_hsv(const Hsv& hsv) noexcept;
constexpr Hsv to_hsv() const noexcept;
constexpr void set_hue(float h) noexcept;
constexpr void set_saturation(float s) noexcept;
constexpr void set_value(float v) noexcept;
constexpr Color blend(const Color& other, float ratio) const noexcept;
static constexpr Color red();
static constexpr Color green();
static constexpr Color blue();
#ifdef OMATH_IMGUI_INTEGRATION
ImColor to_im_color() const noexcept;
#endif
std::string to_string() const noexcept;
std::wstring to_wstring() const noexcept;
std::u8string to_u8string() const noexcept;
};
// formatter<omath::Color> provided
```
---
*Last updated: 31 Oct 2025*

194
docs/utility/pattern_scan.md Normal file
View File

@@ -0,0 +1,194 @@
# `omath::PatternScanner` — Fast byte-pattern search with wildcards
> Header: your project’s `pattern_scanner.hpp`
> Namespace: `omath`
> Core API: `scan_for_pattern(...)` (span or iterators)
> Errors: `PatternScanError::INVALID_PATTERN_STRING` (from `parse_pattern`)
> C++: uses `std::span`, `std::expected`, `std::byte`
`PatternScanner` scans a contiguous byte range for a **hex pattern** that may include **wildcards**. It returns an iterator to the **first match** or the end iterator if not found (or if the pattern string is invalid).
---
## Quick start
```cpp
#include "pattern_scanner.hpp"
using omath::PatternScanner;
std::vector<std::byte> buf = /* ... bytes ... */;
std::span<std::byte> s{buf.data(), buf.size()};
// Example pattern: "48 8B ?? ?? 89" (hex bytes with '?' as any byte)
auto it = PatternScanner::scan_for_pattern(s, "48 8B ?? ?? 89");
if (it != s.end()) {
// Found at offset:
auto offset = static_cast<std::size_t>(it - s.begin());
}
```
Or with iterators:
```cpp
auto it = PatternScanner::scan_for_pattern(buf.begin(), buf.end(), "DE AD BE EF");
if (it != buf.end()) { /* ... */ }
```
---
## Pattern string grammar
The pattern string is parsed into a sequence of byte **tokens**:
* **Hex byte**: two hexadecimal digits form one byte.
Examples: `90`, `4F`, `00`, `ff`
* **Wildcard byte**: `?` or `??` matches **any single byte**.
* **Separators**: any ASCII whitespace (space, tab, newline) is **ignored** and may be used to group tokens.
> ✔️ Valid: `"48 8B ?? 05 00"`, `"90 90 90"`, `"??"`, `"00??FF"` (no spaces)
> ❌ Invalid: odd number of hex digits in a token, non-hex characters (besides `?` and whitespace)
If the string cannot be parsed into a clean sequence of tokens, `parse_pattern()` returns `std::unexpected(PatternScanError::INVALID_PATTERN_STRING)`, and the public scan function returns **end**.
---
## API
```cpp
namespace omath {
enum class PatternScanError { INVALID_PATTERN_STRING };
class PatternScanner final {
public:
// Contiguous range (span) overload
[[nodiscard]]
static std::span<std::byte>::iterator
scan_for_pattern(const std::span<std::byte>& range,
const std::string_view& pattern);
// Deleted rvalue-span overload (prevents dangling)
static std::span<std::byte>::iterator
scan_for_pattern(std::span<std::byte>&&,
const std::string_view&) = delete;
// Iterator overload
template<class IteratorType>
requires std::input_or_output_iterator<std::remove_cvref_t<IteratorType>>
static IteratorType
scan_for_pattern(const IteratorType& begin,
const IteratorType& end,
const std::string_view& pattern);
private:
[[nodiscard]]
static std::expected<std::vector<std::optional<std::byte>>, PatternScanError>
parse_pattern(const std::string_view& pattern_string);
};
} // namespace omath
```
### Return value
* On success: iterator to the **first** matching position.
* On failure / not found / invalid pattern: **`end`**.
---
## Complexity
Let `N` be the number of bytes in the range and `M` the number of **pattern tokens**.
* Time: **O(N × M)** (simple sliding window with early break).
* Space: **O(M)** for the parsed pattern vector.
---
## Examples
### Find a function prologue
```cpp
// x86-64: push rbp; mov rbp, rsp
auto it = PatternScanner::scan_for_pattern(s, "55 48 89 E5");
if (it != s.end()) {
// ... process
}
```
### Skip variable bytes with wildcards
```cpp
// mov rax, <imm32>; call <rel32>
auto it = PatternScanner::scan_for_pattern(s, "48 B8 ?? ?? ?? ?? ?? ?? ?? ?? E8 ?? ?? ?? ??");
```
### Iterator-based scan (subrange)
```cpp
auto sub_begin = buf.begin() + 1024;
auto sub_end = buf.begin() + 4096;
auto it = PatternScanner::scan_for_pattern(sub_begin, sub_end, "DE AD ?? BE EF");
```
---
## Behavior & edge cases
* **Empty or too-short**: If the effective pattern token count `M` is `0` or `M > N`, the function returns `end`.
* **Wildcards**: Each `?`/`??` token matches **exactly one** byte.
* **No exceptions**: Invalid pattern → parsed as `unexpected`, public API returns `end`.
* **No ownership**: The span overload takes `const std::span<std::byte>&` and returns a **mutable iterator** into that span. You must ensure the underlying memory stays alive. The rvalue-span overload is **deleted** to prevent dangling.
---
## Notes & caveats (implementation-sensitive)
* Although the iterator overload is constrained with `std::input_or_output_iterator`, the implementation uses `*(begin + i + j)` and arithmetic on iterators. In practice this means you should pass **random-access / contiguous iterators** (e.g., from `std::vector<std::byte>` or `std::span<std::byte>`). Using non-random-access iterators would be ill-formed.
* The inner matching loop compares a parsed token (`std::optional<std::byte>`) to the candidate byte; `std::nullopt` is treated as a **wildcard** (always matches).
* **Implementation note:** the outer scan currently derives its scan bound from the **pattern string length**; conceptually it should use the **number of parsed tokens** (hex/wildcard bytes). If you plan to accept spaces (or other non-byte characters) in the pattern string, ensure the scan window uses the parsed token count to avoid false negatives near the end of the buffer.
---
## Testing hooks
The class befriends several unit tests:
```
unit_test_pattern_scan_read_test_Test
unit_test_pattern_scan_corner_case_1_Test
unit_test_pattern_scan_corner_case_2_Test
unit_test_pattern_scan_corner_case_3_Test
unit_test_pattern_scan_corner_case_4_Test
```
Use these to validate parsing correctness, wildcard handling, and boundary conditions.
---
## Troubleshooting
* **Always returns end**: verify the pattern string is valid hex/wildcards and that you’re scanning the intended subrange. Try a simpler pattern (e.g., a single known byte) to sanity-check.
* **Crashes or compile errors with iterator overload**: use iterators that support random access (e.g., from `std::vector`), or prefer the `std::span` overload.
* **Ambiguous wildcards**: this scanner treats `?` and `??` as **byte-wide** wildcards (not per-nibble). If you need nibble-level masks, extend `parse_pattern` to support patterns like `A?`/`?F` with bitmask matching.
---
## Minimal unit test sketch
```cpp
TEST(pattern, basic) {
std::array<std::byte, 8> data{
std::byte{0x48}, std::byte{0x8B}, std::byte{0x01}, std::byte{0x02},
std::byte{0x89}, std::byte{0x50}, std::byte{0x90}, std::byte{0xCC}
};
std::span<std::byte> s{data.data(), data.size()};
auto it = omath::PatternScanner::scan_for_pattern(s, "48 8B ?? ?? 89");
ASSERT_NE(it, s.end());
EXPECT_EQ(static_cast<size_t>(it - s.begin()), 0U);
}
```
---
*Last updated: 31 Oct 2025*