diff --git a/libluna/include/luna/Bitmap.h b/libluna/include/luna/Bitmap.h index e4990c04..2e0e59a3 100644 --- a/libluna/include/luna/Bitmap.h +++ b/libluna/include/luna/Bitmap.h @@ -1,58 +1,195 @@ +/** + * @file Bitmap.h + * @author apio (cloudapio.eu) + * @brief An interface to an array of bits. + * + * @copyright Copyright (c) 2022-2023, the Luna authors. + * + */ + #pragma once #include #include +/** + * @brief A class providing an interface to an array of bits. + */ class Bitmap { public: + /** + * @brief Construct a new empty Bitmap object. + * + * This object is invalid until initialize() is called on it. + */ Bitmap(); + + /** + * @brief Construct a new Bitmap object. + * + * @param location The memory to use. This memory is not managed by Bitmap; if it is dynamically allocated, you must + * free it after it is no longer used by the bitmap. + * @param size_in_bytes The size (in bytes, the number of bits available will be 8 times more) of the memory used. + */ Bitmap(void* location, usize size_in_bytes); - // Naive initialization functions. + /** + * @brief Initialize a Bitmap object. + * + * If the object was previously initialized, you should call move() instead. + * + * @param location The memory to use. This memory is not managed by Bitmap; if it is dynamically allocated, you must + * free it after it is no longer used by the bitmap. + * @param size_in_bytes The size (in bytes, the number of bits available will be 8 times more) of the memory used. + */ void initialize(void* location, usize size_in_bytes); + + /** + * @brief Initialize a previously initialized Bitmap object and return the memory location it was previously using. + * + * If the object was not previously initialized, you should call initialize() instead. + * + * @param new_location The memory to use. This memory is not managed by Bitmap; if it is dynamically allocated, you + * must free it after it is no longer used by the bitmap. + * @param new_location_size_in_bytes The size (in bytes, the number of bits available will be 8 times more) of the + * memory used. + * @return void* The old memory location previously used by the bitmap. + */ void* move(void* new_location, usize new_location_size_in_bytes); - // Dynamic memory initialization functions. - Result allocate(usize size_in_bytes); - Result resize(usize new_size_in_bytes); - Result deallocate(); - + /** + * @brief Change the value of the bit at a specific index. + * + * @param index The index of the bit to change. + * @param value The value to set. + */ void set(usize index, bool value); + + /** + * @brief Read the value of the bit at a specific index. + * + * @param index The index of the bit to read. + * @return bool The value of the specified bit. + */ bool get(usize index) const; - // size() returns size in bits! If you want the size in bytes, call size_in_bytes(). + /** + * @brief Return the size in bits of the bitmap. + * + * @return usize The size in bits. + */ usize size() const { return m_size_in_bytes * 8; } + /** + * @brief Return the size in bytes of the bitmap. + * + * @return usize The size in bytes. + */ usize size_in_bytes() const { return m_size_in_bytes; } + /** + * @brief Return the memory location used by the bitmap. + * + * @return void* The memory location used. If it is NULL, the bitmap was not initialized. + */ void* location() const { return (void*)m_location; } + /** + * @brief Check whether the bitmap has been initialized. + * + * @return true The bitmap was initialized by a constructor or initialize(). + * @return false The bitmap was not initialized and you should not call other methods on it until initialize() is + * called. + */ bool initialized() const { return m_location; } + /** + * @brief Find the first bit with a specific value. + * + * @param value The value to look for. + * @param begin If different from 0, the bit index to start looking at. + * @return Option If a matching bit was found, the index of said bit, otherwise an empty Option. + */ Option find(bool value, usize begin = 0) const; + /** + * @brief Find the first bit with a specific value and toggle it. + * + * @param value The value to look for. + * @param begin If different from 0, the bit index to start looking at. + * @return Option If a matching bit was found, the index of said bit, otherwise an empty Option. + */ Option find_and_toggle(bool value, usize begin = 0); + /** + * @brief Find the first region of bits all with a specific value. + * + * @param value The value to look for. + * @param count The number of consecutive bits that should all match the value. + * @param begin If different from 0, the bit index to start looking at. + * @return Option If a matching region was found, the index of the first bit in said region, otherwise an + * empty Option. + */ Option find_region(bool value, usize count, usize begin = 0) const; + /** + * @brief Find the first region of bits all with a specific value, and toggle them all. + * + * @param value The value to look for. + * @param count The number of consecutive bits that should all match the value. + * @param begin If different from 0, the bit index to start looking at. + * @return Option If a matching region was found, the index of the first bit in said region, otherwise an + * empty Option. + */ Option find_and_toggle_region(bool value, usize count, usize begin = 0); + /** + * @brief Check whether a region of bits all match a value. + * + * @param start The bit index of the first bit in the region. + * @param bits The number of bits in the region. + * @param value The value to check against. + * @return bool Whether the region matches. + */ bool match_region(usize start, usize bits, bool value); + + /** + * @brief Check whether a region of bits all match a value, returning an error if the region is outside of the + * Bitmap's bounds (instead of crashing). + * + * @param start The bit index of the first bit in the region. + * @param bits The number of bits in the region. + * @param value The value to check against. + * @return Result An error if the region is out of bounds, or whether the region matches. + */ Result try_match_region(usize start, usize bits, bool value); + /** + * @brief Set the entire bitmap to a value. + * + * @param value The value to use. + */ void clear(bool value); + + /** + * @brief Set a region of bits to a value. + * + * @param start The bit index of the first bit in the region. + * @param bits The number of bits in the region. + * @param value The value to set. + */ void clear_region(usize start, usize bits, bool value); private: diff --git a/libluna/src/Bitmap.cpp b/libluna/src/Bitmap.cpp index b32285cc..88eba537 100644 --- a/libluna/src/Bitmap.cpp +++ b/libluna/src/Bitmap.cpp @@ -1,3 +1,12 @@ +/** + * @file Bitmap.cpp + * @author apio (cloudapio.eu) + * @brief An interface to an array of bits. + * + * @copyright Copyright (c) 2022-2023, the Luna authors. + * + */ + #include #include #include @@ -17,24 +26,6 @@ void Bitmap::initialize(void* location, usize size_in_bytes) m_size_in_bytes = size_in_bytes; } -Result Bitmap::allocate(usize size_in_bytes) -{ - initialize(TRY(malloc_impl(size_in_bytes)), size_in_bytes); - return {}; -} - -Result Bitmap::resize(usize new_size_in_bytes) -{ - m_location = (u8*)TRY(realloc_impl(m_location, new_size_in_bytes)); - m_size_in_bytes = new_size_in_bytes; - return (void*)m_location; -} - -Result Bitmap::deallocate() -{ - return free_impl(m_location); -} - void* Bitmap::move(void* new_location, usize new_location_size_in_bytes) { if (new_location_size_in_bytes > m_size_in_bytes) memcpy(new_location, m_location, m_size_in_bytes);