Index: Doxyfile ================================================================== --- Doxyfile +++ Doxyfile @@ -48,5 +48,6 @@ SIGUSR1 \ SIGUSR2 MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES IGNORE_PREFIX = OF OF_ OT OT_ +EXTRACT_STATIC = yes Index: src/OFDate.m ================================================================== --- src/OFDate.m +++ src/OFDate.m @@ -277,12 +277,12 @@ OFOnce(&once, initZeroDate); return (id)zeroDate; } #if defined(OF_OBJFW_RUNTIME) && UINTPTR_MAX == UINT64_MAX - value = OFFromBigEndian64(OFDoubleToRawUInt64(OFToBigEndianDouble( - seconds))); + value = OFFromBigEndian64(OFBitConvertDoubleToUInt64( + OFToBigEndianDouble(seconds))); /* Almost all dates fall into this range. */ if (value & (UINT64_C(4) << 60)) { id ret = [OFTaggedPointerDate dateWithUInt64TimeIntervalSince1970: value]; Index: src/OFMatrix4x4.m ================================================================== --- src/OFMatrix4x4.m +++ src/OFMatrix4x4.m @@ -316,11 +316,12 @@ OFHashInit(&hash); for (uint_fast8_t i = 0; i < 4; i++) for (uint_fast8_t j = 0; j < 4; j++) - OFHashAddHash(&hash, OFFloatToRawUInt32(_values[i][j])); + OFHashAddHash(&hash, + OFBitConvertFloatToUInt32(_values[i][j])); OFHashFinalize(&hash); return hash; } Index: src/OFObject.h ================================================================== --- src/OFObject.h +++ src/OFObject.h @@ -1480,12 +1480,48 @@ extern id _Nullable objc_getAssociatedObject(id _Nonnull object, const void *_Nonnull key); extern void objc_removeAssociatedObjects(id _Nonnull object); # endif #endif + +/** + * @brief Allocates a new object. + * + * This is useful to override @ref OFObject#alloc in a subclass that can then + * allocate extra memory in the same memory allocation. + * + * @param class_ The class of which to allocate an object + * @param extraSize Extra space after the ivars to allocate + * @param extraAlignment Alignment of the extra space after the ivars + * @param extra A pointer to set to a pointer to the extra space + * @return The allocated object + */ extern id OFAllocObject(Class class_, size_t extraSize, size_t extraAlignment, void *_Nullable *_Nullable extra); + +/** + * @brief This function is called when a method is not found. + * + * It can also be called intentionally to indicate that a method is not + * implemetned, for example in an abstract method. However, instead of calling + * OFMethodNotFound directly, it is preferred to do the following: + * + * - (void)abstractMethod + * { + * OF_UNRECOGNIZED_SELECTOR + * } + * + * However, do not use this for init methods. Instead, use the following: + * + * - (instancetype)init + * { + * OF_INVALID_INIT_METHOD + * } + * + * @param self The object which does not have the method + * @param _cmd The selector of the method that does not exist + */ extern void OF_NO_RETURN_FUNC OFMethodNotFound(id self, SEL _cmd); /** * @brief Initializes the specified hash. * Index: src/OFPlainCondition.h ================================================================== --- src/OFPlainCondition.h +++ src/OFPlainCondition.h @@ -27,10 +27,12 @@ #endif /* For OFTimeInterval */ #import "OFObject.h" #import "OFPlainMutex.h" + +/** @file */ #if defined(OF_HAVE_PTHREADS) # include typedef pthread_cond_t OFPlainCondition; #elif defined(OF_WINDOWS) @@ -51,22 +53,92 @@ #endif #ifdef __cplusplus extern "C" { #endif +/** + * @brief Creates a new plain condition. + * + * A plain condition is similar to an @ref OFCondition, but does not use + * exceptions and can be used from pure C code. + * + * @param condition A pointer to the condition to create + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionNew(OFPlainCondition *condition); + +/** + * @brief Signals the specified condition. + * + * @param condition A pointer to the condition to signal + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionSignal(OFPlainCondition *condition); + +/** + * @brief Broadcasts the specified condition, meaning it will be signaled to + * everyone waiting. + * + * @param condition A pointer to the condition to broadcast + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionBroadcast(OFPlainCondition *condition); + +/** + * @brief Waits on the specified condition with the specified mutex. + * + * @param condition A pointer to the condition to wait on + * @param mutex The mutex to wait with + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionWait(OFPlainCondition *condition, OFPlainMutex *mutex); + +/** + * @brief Waits on the specified condition with the specified mutex with a + * timeout. + * + * @param condition A pointer to the condition to wait on + * @param mutex The mutex to wait with + * @param timeout The timeout after which to give up + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionTimedWait(OFPlainCondition *condition, OFPlainMutex *mutex, OFTimeInterval timeout); + #if defined(OF_AMIGAOS) || defined(DOXYGEN) +/** + * @brief Waits on the specified condition with the specified mutex or the + * specified Exec signal. + * + * @param condition A pointer to the condition to wait on + * @param mutex The mutex to wait with + * @param signalMask The Exec signal mask to wait for + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionWaitOrExecSignal(OFPlainCondition *condition, OFPlainMutex *mutex, ULONG *signalMask); + +/** + * @brief Waits on the specified condition with the specified mutex or the + * specified Exec signal, up until the timeout is reached. + * + * @param condition A pointer to the condition to wait on + * @param mutex The mutex to wait with + * @param signalMask The Exec signal mask to wait for + * @param timeout The timeout after which to give up + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionTimedWaitOrExecSignal(OFPlainCondition *condition, OFPlainMutex *mutex, OFTimeInterval timeout, ULONG *signalMask); #endif + +/** + * @brief Destroys the specified plain condition. + * + * @param condition A pointer to the condition to destroy + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainConditionFree(OFPlainCondition *condition); #ifdef __cplusplus } #endif Index: src/OFPlainMutex.h ================================================================== --- src/OFPlainMutex.h +++ src/OFPlainMutex.h @@ -27,10 +27,12 @@ (!defined(OF_HAVE_PTHREADS) && !defined(OF_WINDOWS) && !defined(OF_AMIGAOS)) # error No mutexes available! #endif #import "macros.h" + +/** @file */ #if defined(OF_HAVE_PTHREADS) # include typedef pthread_mutex_t OFPlainMutex; #elif defined(OF_WINDOWS) @@ -66,26 +68,107 @@ #endif #ifdef __cplusplus extern "C" { #endif +/** + * @brief Creates a new plain mutex. + * + * A plain mutex is similar to an @ref OFMutex, but does not use exceptions and + * is just a lightweight wrapper around the system's mutex implementation. + * + * @param mutex A pointer to the mutex to create + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainMutexNew(OFPlainMutex *mutex); + +/** + * @brief Locks the specified mutex. + * + * @param mutex A pointer to the mutex to lock + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainMutexLock(OFPlainMutex *mutex); + +/** + * @brief Tries to lock the specified mutex without blocking. + * + * @param mutex A pointer to the mutex to try to lock + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainMutexTryLock(OFPlainMutex *mutex); + +/** + * @brief Unlocks the specified mutex. + * + * @param mutex A pointer to the mutex to unlock + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainMutexUnlock(OFPlainMutex *mutex); + +/** + * @brief Destroys the specified mutex + * + * @param mutex A pointer to the mutex to destruct + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainMutexFree(OFPlainMutex *mutex); + +/** + * @brief Creates a new plain recursive mutex. + * + * A plain recursive mutex is similar to an @ref OFRecursiveMutex, but does not + * use exceptions and is just a lightweight wrapper around the system's + * recursive mutex implementation (or lacking that, a simple implementation of + * recursive mutexes via regular mutexes). + * + * @param rmutex A pointer to the recursive mutex to create + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainRecursiveMutexNew(OFPlainRecursiveMutex *rmutex); + +/** + * @brief Locks the specified recursive mutex. + * + * @param rmutex A pointer to the recursive mutex to lock + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainRecursiveMutexLock(OFPlainRecursiveMutex *rmutex); + +/** + * @brief Tries to lock the specified recursive mutex without blocking. + * + * @param rmutex A pointer to the recursive mutex to try to lock + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainRecursiveMutexTryLock(OFPlainRecursiveMutex *rmutex); + +/** + * @brief Unlocks the specified recursive mutex. + * + * @param rmutex A pointer to the recursive mutex to unlock + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainRecursiveMutexUnlock(OFPlainRecursiveMutex *rmutex); + +/** + * @brief Destroys the specified recursive mutex + * + * @param rmutex A pointer to the recursive mutex to destruct + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainRecursiveMutexFree(OFPlainRecursiveMutex *rmutex); #ifdef __cplusplus } #endif /* Spinlocks are inlined for performance. */ +/** + * @brief Yield the current thread, indicating to the OS that another thread + * should execute instead. + */ static OF_INLINE void OFYieldThread(void) { #if defined(OF_HAVE_SCHED_YIELD) sched_yield(); @@ -92,10 +175,16 @@ #elif defined(OF_WINDOWS) Sleep(0); #endif } +/** + * @brief Creates a new spinlock. + * + * @param spinlock A pointer to the spinlock to create + * @return 0 on success, or an error number from `` on error + */ static OF_INLINE int OFSpinlockNew(OFSpinlock *spinlock) { #if defined(OF_HAVE_ATOMIC_OPS) *spinlock = 0; @@ -105,10 +194,16 @@ #else return OFPlainMutexNew(spinlock); #endif } +/** + * @brief Tries to lock a spinlock. + * + * @param spinlock A pointer to the spinlock to try to lock + * @return 0 on success, or an error number from `` on error + */ static OF_INLINE int OFSpinlockTryLock(OFSpinlock *spinlock) { #if defined(OF_HAVE_ATOMIC_OPS) if (OFAtomicIntCompareAndSwap(spinlock, 0, 1)) { @@ -122,10 +217,16 @@ #else return OFPlainMutexTryLock(spinlock); #endif } +/** + * @brief Locks a spinlock. + * + * @param spinlock A pointer to the spinlock to lock + * @return 0 on success, or an error number from `` on error + */ static OF_INLINE int OFSpinlockLock(OFSpinlock *spinlock) { #if defined(OF_HAVE_ATOMIC_OPS) size_t i; @@ -143,10 +244,16 @@ #else return OFPlainMutexLock(spinlock); #endif } +/** + * @brief Unlocks a spinlock. + * + * @param spinlock A pointer to the spinlock to unlock + * @return 0 on success, or an error number from `` on error + */ static OF_INLINE int OFSpinlockUnlock(OFSpinlock *spinlock) { #if defined(OF_HAVE_ATOMIC_OPS) bool ret = OFAtomicIntCompareAndSwap(spinlock, 1, 0); @@ -159,10 +266,16 @@ #else return OFPlainMutexUnlock(spinlock); #endif } +/** + * @brief Destroys a spinlock. + * + * @param spinlock A pointer to the spinlock to destroy + * @return 0 on success, or an error number from `` on error + */ static OF_INLINE int OFSpinlockFree(OFSpinlock *spinlock) { #if defined(OF_HAVE_ATOMIC_OPS) return 0; Index: src/OFPlainThread.h ================================================================== --- src/OFPlainThread.h +++ src/OFPlainThread.h @@ -25,10 +25,12 @@ (!defined(OF_HAVE_PTHREADS) && !defined(OF_WINDOWS) && !defined(OF_AMIGAOS)) # error No threads available! #endif #import "OFObject.h" + +/** @file */ #if defined(OF_HAVE_PTHREADS) # include typedef pthread_t OFPlainThread; #elif defined(OF_WINDOWS) @@ -51,17 +53,28 @@ typedef struct { float priority; size_t stackSize; } OFPlainThreadAttributes; -#if defined(OF_HAVE_PTHREADS) +#if defined(OF_HAVE_PTHREADS) || defined(DOXYGEN) +/** + * @brief Returns the current plain thread. + * + * @return The current plain thread + */ static OF_INLINE OFPlainThread OFCurrentPlainThread(void) { return pthread_self(); } +/** + * @brief Returns whether the specified plain thread is the current thread. + * + * @param thread The thread to check + * @return Whether the specified plain thread is the current thread + */ static OF_INLINE bool OFPlainThreadIsCurrent(OFPlainThread thread) { return pthread_equal(thread, pthread_self()); } @@ -83,14 +96,54 @@ #endif #ifdef __cplusplus extern "C" { #endif +/** + * @brief Initializes the specified thread attributes. + * + * @param attr A pointer to the thread attributes to initialize + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainThreadAttributesInit(OFPlainThreadAttributes *attr); + +/** + * @brief Creates a new plain thread. + * + * A plain thread is similar to @ref OFThread, but does not use exceptions and + * is just a lightweight wrapper around the system's thread implementation. + * + * @param thread A pointer to the thread to create + * @param name A name for the thread + * @param function The function the thread should execute + * @param object The object to pass to the thread as an argument + * @param attr Thread attributes + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainThreadNew(OFPlainThread *thread, const char *name, void (*function)(id), id object, const OFPlainThreadAttributes *attr); + +/** + * @brief Sets the name of the current thread. + * + * @param name The name for the current thread + */ extern void OFSetThreadName(const char *name); + +/** + * @brief Joins the specified thread. + * + * @param thread The thread to join + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainThreadJoin(OFPlainThread thread); + +/** + * @brief Detaches the specified thread. + * + * @param thread The thread to detach + * @return 0 on success, or an error number from `` on error + */ extern int OFPlainThreadDetach(OFPlainThread thread); #ifdef __cplusplus } #endif Index: src/OFString.h ================================================================== --- src/OFString.h +++ src/OFString.h @@ -1333,16 +1333,30 @@ * @param encoding The encoding for which to return the name * @return The name of the specified OFStringEncoding */ extern OFString *_Nullable OFStringEncodingName(OFStringEncoding encoding); +/** + * @brief Returns the length of the specified UTF-16 string. + * + * @param string The UTF-16 string + * @return The length of the specified UTF-16 string + */ +extern size_t OFUTF16StringLength(const OFChar16 *string); + +/** + * @brief Returns the length of the specified UTF-32 string. + * + * @param string The UTF-32 string + * @return The length of the specified UTF-32 string + */ +extern size_t OFUTF32StringLength(const OFChar32 *string); + extern char *_Nullable _OFStrDup(const char *_Nonnull) OF_VISIBILITY_HIDDEN; extern size_t _OFUTF8StringEncode(OFUnichar, char *) OF_VISIBILITY_HIDDEN; extern ssize_t _OFUTF8StringDecode(const char *, size_t, OFUnichar *) OF_VISIBILITY_HIDDEN; -extern size_t OFUTF16StringLength(const OFChar16 *); -extern size_t OFUTF32StringLength(const OFChar32 *); #ifdef __cplusplus } #endif OF_ASSUME_NONNULL_END Index: src/OFTLSKey.h ================================================================== --- src/OFTLSKey.h +++ src/OFTLSKey.h @@ -27,10 +27,12 @@ (!defined(OF_HAVE_PTHREADS) && !defined(OF_WINDOWS) && !defined(OF_AMIGAOS)) # error No thread-local storage available! #endif #import "macros.h" + +/** @file */ #if defined(OF_HAVE_PTHREADS) # include typedef pthread_key_t OFTLSKey; #elif defined(OF_WINDOWS) @@ -47,60 +49,85 @@ #endif #ifdef __cplusplus extern "C" { #endif +/** + * @brief Creates a new Thread Local Storage key. + * + * @param key A pointer to the key to create + * @return 0 on success, or an error number from `` on error + */ extern int OFTLSKeyNew(OFTLSKey *key); + +/** + * @brief Destroys the specified Thread Local Storage key. + * + * @param key A pointer to the key to destroy + * @return 0 on success, or an error number from `` on error + */ extern int OFTLSKeyFree(OFTLSKey key); #ifdef __cplusplus } #endif /* TLS keys are inlined for performance. */ -#if defined(OF_HAVE_PTHREADS) +#if defined(OF_HAVE_PTHREADS) || defined(DOXYGEN) +/** + * @brief Returns the current value for the specified Thread Local Storage key. + * + * @param key A pointer to the key whose value to return + * @return The current value for the specified Thread Local Storage key + */ static OF_INLINE void * OFTLSKeyGet(OFTLSKey key) { return pthread_getspecific(key); } +/** + * @brief Sets the current value for the specified Thread Local Storage key. + * + * @param key A pointer to the key whose value to set + * @param value The new value for the key + */ static OF_INLINE int -OFTLSKeySet(OFTLSKey key, void *ptr) +OFTLSKeySet(OFTLSKey key, void *value) { - return pthread_setspecific(key, ptr); + return pthread_setspecific(key, value); } #elif defined(OF_WINDOWS) static OF_INLINE void * OFTLSKeyGet(OFTLSKey key) { return TlsGetValue(key); } static OF_INLINE int -OFTLSKeySet(OFTLSKey key, void *ptr) +OFTLSKeySet(OFTLSKey key, void *value) { - return (TlsSetValue(key, ptr) ? 0 : EINVAL); + return (TlsSetValue(key, value) ? 0 : EINVAL); } #elif defined(OF_MORPHOS) static OF_INLINE void * OFTLSKeyGet(OFTLSKey key) { return (void *)TLSGetValue(key); } static OF_INLINE int -OFTLSKeySet(OFTLSKey key, void *ptr) +OFTLSKeySet(OFTLSKey key, void *value) { - return (TLSSetValue(key, (APTR)ptr) ? 0 : EINVAL); + return (TLSSetValue(key, (APTR)value) ? 0 : EINVAL); } #elif defined(OF_AMIGAOS) /* Those are too big too inline. */ # ifdef __cplusplus extern "C" { # endif extern void *OFTLSKeyGet(OFTLSKey key); -extern int OFTLSKeySet(OFTLSKey key, void *ptr); +extern int OFTLSKeySet(OFTLSKey key, void *value); # ifdef __cplusplus } # endif #endif Index: src/OFTaggedPointerDate.m ================================================================== --- src/OFTaggedPointerDate.m +++ src/OFTaggedPointerDate.m @@ -38,12 +38,12 @@ { uint64_t value = (uint64_t)object_getTaggedPointerValue(self); value |= UINT64_C(4) << 60; - return OFFromBigEndianDouble(OFRawUInt64ToDouble(OFToBigEndian64( + return OFFromBigEndianDouble(OFBitConvertUInt64ToDouble(OFToBigEndian64( value))); } OF_SINGLETON_METHODS @end #endif Index: src/exceptions/OFException.h ================================================================== --- src/exceptions/OFException.h +++ src/exceptions/OFException.h @@ -22,10 +22,12 @@ #ifdef OF_WINDOWS # include #endif OF_ASSUME_NONNULL_BEGIN + +/** @file */ @class OFArray OF_GENERIC(ObjectType); @class OFString; @class OFValue; @@ -190,14 +192,26 @@ @end #ifdef __cplusplus extern "C" { #endif +/** + * @brief Converts the specified error number (from ``) to a string. + * + * Unlike the system function `strerror`, this function is always thread-safe. + * + * As an addition, on Windows, it is also able to convert socket error numbers + * to string. + * + * @param errNo The error number to convert to a string + * @return A string describing the error + */ extern OFString *OFStrError(int errNo); + #ifdef OF_WINDOWS extern OFString *_OFWindowsStatusToString(LSTATUS status) OF_VISIBILITY_HIDDEN; #endif #ifdef __cplusplus } #endif OF_ASSUME_NONNULL_END Index: src/macros.h ================================================================== --- src/macros.h +++ src/macros.h @@ -36,10 +36,12 @@ #include #include #include #include + +/** @file */ #include "platform.h" #ifdef OF_OBJFW_RUNTIME # ifdef OF_COMPILING_OBJFW @@ -587,79 +589,232 @@ _OFByteSwap32NonConst((uint32_t)(i >> 32)); #endif return i; } -#ifdef __GNUC__ +#if defined(__GNUC__) || defined(DOXYGEN) +/** + * @brief Byte swaps the specified 16 bit integer. + * + * @param i The integer to byte swap + * @return The byte swapped integer + */ # define OFByteSwap16(i) \ (__builtin_constant_p(i) ? _OFByteSwap16Const(i) : _OFByteSwap16NonConst(i)) + +/** + * @brief Byte swaps the specified 32 bit integer. + * + * @param i The integer to byte swap + * @return The byte swapped integer + */ # define OFByteSwap32(i) \ (__builtin_constant_p(i) ? _OFByteSwap32Const(i) : _OFByteSwap32NonConst(i)) + +/** + * @brief Byte swaps the specified 64 bit integer. + * + * @param i The integer to byte swap + * @return The byte swapped integer + */ # define OFByteSwap64(i) \ (__builtin_constant_p(i) ? _OFByteSwap64Const(i) : _OFByteSwap64NonConst(i)) #else # define OFByteSwap16(i) _OFByteSwap16Const(i) # define OFByteSwap32(i) _OFByteSwap32Const(i) # define OFByteSwap64(i) _OFByteSwap64Const(i) #endif -static OF_INLINE uint32_t -OFFloatToRawUInt32(float f) +/** + * @brief Bit-converts the specified float to a uint32_t. + * + * @param f The float to bit-convert + * @return The float bit-converted to a uint32_t + */ +static OF_INLINE uint32_t OF_CONST_FUNC +OFBitConvertFloatToUInt32(float f) { uint32_t ret; memcpy(&ret, &f, 4); return ret; } -static OF_INLINE float -OFRawUInt32ToFloat(uint32_t uInt32) +/** + * @brief Bit-converts the specified uint32_t to a float. + * + * @param uInt32 The uint32_t to bit-convert + * @return The uint32_t bit-converted to a float + */ +static OF_INLINE float OF_CONST_FUNC +OFBitConvertUInt32ToFloat(uint32_t uInt32) { float ret; memcpy(&ret, &uInt32, 4); return ret; } -static OF_INLINE uint64_t -OFDoubleToRawUInt64(double d) +/** + * @brief Bit-converts the specified double to a uint64_t. + * + * @param d The double to bit-convert + * @return The double bit-converted to a uint64_t + */ +static OF_INLINE uint64_t OF_CONST_FUNC +OFBitConvertDoubleToUInt64(double d) { uint64_t ret; memcpy(&ret, &d, 8); return ret; } -static OF_INLINE double -OFRawUInt64ToDouble(uint64_t uInt64) +/** + * @brief Bit-converts the specified uint64_t to a double. + * + * @param uInt64 The uint64_t to bit-convert + * @return The uint64_t bit-converted to a double + */ +static OF_INLINE double OF_CONST_FUNC +OFBitConvertUInt64ToDouble(uint64_t uInt64) { double ret; memcpy(&ret, &uInt64, 8); return ret; } +/** + * @brief Byte swaps the specified float. + * + * @param f The float to byte swap + * @return The byte swapped float + */ static OF_INLINE float OF_CONST_FUNC OFByteSwapFloat(float f) { - return OFRawUInt32ToFloat(OFByteSwap32(OFFloatToRawUInt32(f))); + return OFBitConvertUInt32ToFloat(OFByteSwap32( + OFBitConvertFloatToUInt32(f))); } +/** + * @brief Byte swaps the specified double. + * + * @param d The double to byte swap + * @return The byte swapped double + */ static OF_INLINE double OF_CONST_FUNC OFByteSwapDouble(double d) { - return OFRawUInt64ToDouble(OFByteSwap64(OFDoubleToRawUInt64(d))); + return OFBitConvertUInt64ToDouble(OFByteSwap64( + OFBitConvertDoubleToUInt64(d))); } -#ifdef OF_BIG_ENDIAN +#if defined(OF_BIG_ENDIAN) || defined(DOXYGEN) +/** + * @brief Converts the specified 16 bit integer from big endian to native + * endian. + * + * @param i The 16 bit integer to convert + * @return The 16 bit integer converted to native endian + */ # define OFFromBigEndian16(i) (i) + +/** + * @brief Converts the specified 32 bit integer from big endian to native + * endian. + * + * @param i The 32 bit integer to convert + * @return The 32 bit integer converted to native endian + */ # define OFFromBigEndian32(i) (i) + +/** + * @brief Converts the specified 64 bit integer from big endian to native + * endian. + * + * @param i The 64 bit integer to convert + * @return The 64 bit integer converted to native endian + */ # define OFFromBigEndian64(i) (i) + +/** + * @brief Converts the specified 16 bit integer from little endian to native + * endian. + * + * @param i The 16 bit integer to convert + * @return The 16 bit integer converted to native endian + */ # define OFFromLittleEndian16(i) OFByteSwap16(i) + +/** + * @brief Converts the specified 32 bit integer from little endian to native + * endian. + * + * @param i The 32 bit integer to convert + * @return The 32 bit integer converted to native endian + */ # define OFFromLittleEndian32(i) OFByteSwap32(i) + +/** + * @brief Converts the specified 64 bit integer from little endian to native + * endian. + * + * @param i The 64 bit integer to convert + * @return The 64 bit integer converted to native endian + */ # define OFFromLittleEndian64(i) OFByteSwap64(i) + +/** + * @brief Converts the specified 16 bit integer from native endian to big + * endian. + * + * @param i The 16 bit integer to convert + * @return The 16 bit integer converted to big endian + */ # define OFToBigEndian16(i) (i) + +/** + * @brief Converts the specified 32 bit integer from native endian to big + * endian. + * + * @param i The 32 bit integer to convert + * @return The 32 bit integer converted to big endian + */ # define OFToBigEndian32(i) (i) + +/** + * @brief Converts the specified 64 bit integer from native endian to big + * endian. + * + * @param i The 64 bit integer to convert + * @return The 64 bit integer converted to big endian + */ # define OFToBigEndian64(i) (i) + +/** + * @brief Converts the specified 16 bit integer from native endian to little + * endian. + * + * @param i The 16 bit integer to convert + * @return The 16 bit integer converted to little endian + */ # define OFToLittleEndian16(i) OFByteSwap16(i) + +/** + * @brief Converts the specified 32 bit integer from native endian to little + * endian. + * + * @param i The 32 bit integer to convert + * @return The 32 bit integer converted to little endian + */ # define OFToLittleEndian32(i) OFByteSwap32(i) + +/** + * @brief Converts the specified 64 bit integer from native endian to little + * endian. + * + * @param i The 64 bit integer to convert + * @return The 64 bit integer converted to little endian + */ # define OFToLittleEndian64(i) OFByteSwap64(i) #else # define OFFromBigEndian16(i) OFByteSwap16(i) # define OFFromBigEndian32(i) OFByteSwap32(i) # define OFFromBigEndian64(i) OFByteSwap64(i) @@ -672,18 +827,73 @@ # define OFToLittleEndian16(i) (i) # define OFToLittleEndian32(i) (i) # define OFToLittleEndian64(i) (i) #endif -#ifdef OF_FLOAT_BIG_ENDIAN +#if defined(OF_FLOAT_BIG_ENDIAN) || defined(DOXYGEN) +/** + * @brief Converts the specified float from big endian to native endian. + * + * @param f The float to convert + * @return The float converted to native endian + */ # define OFFromBigEndianFloat(f) (f) + +/** + * @brief Converts the specified double from big endian to native endian. + * + * @param d The double to convert + * @return The double converted to native endian + */ # define OFFromBigEndianDouble(d) (d) + +/** + * @brief Converts the specified float from little endian to native endian. + * + * @param f The float to convert + * @return The float converted to native endian + */ # define OFFromLittleEndianFloat(f) OFByteSwapFloat(f) + +/** + * @brief Converts the specified double from little endian to native endian. + * + * @param d The double to convert + * @return The double converted to native endian + */ # define OFFromLittleEndianDouble(d) OFByteSwapDouble(d) + +/** + * @brief Converts the specified float from native endian to big endian. + * + * @param f The float to convert + * @return The float converted to big endian + */ # define OFToBigEndianFloat(f) (f) + +/** + * @brief Converts the specified double from native endian to big endian. + * + * @param d The double to convert + * @return The double converted to big endian + */ # define OFToBigEndianDouble(d) (d) + +/** + * @brief Converts the specified float from native endian to little endian. + * + * @param f The float to convert + * @return The float converted to little endian + */ # define OFToLittleEndianFloat(f) OFByteSwapFloat(f) + +/** + * @brief Converts the specified double from native endian to little endian. + * + * @param d The double to convert + * @return The double converted to little endian + */ # define OFToLittleEndianDouble(d) OFByteSwapDouble(d) #else # define OFFromBigEndianFloat(f) OFByteSwapFloat(f) # define OFFromBigEndianDouble(d) OFByteSwapDouble(d) # define OFFromLittleEndianFloat(f) (f) @@ -692,21 +902,43 @@ # define OFToBigEndianDouble(d) OFByteSwapDouble(d) # define OFToLittleEndianFloat(f) (f) # define OFToLittleEndianDouble(d) (d) #endif +/** + * @brief Rotates the specified value left by the specified amount of bits. + * + * @param value The value to rotate + * @param bits The number of bits to rotate left the value by + * @return The value rotated left by the specified amount of bits + */ #define OFRotateLeft(value, bits) \ (((bits) % (sizeof(value) * 8)) > 0 \ ? ((value) << ((bits) % (sizeof(value) * 8))) | \ ((value) >> (sizeof(value) * 8 - ((bits) % (sizeof(value) * 8)))) \ : (value)) + +/** + * @brief Rotates the specified value right by the specified amount of bits. + * + * @param value The value to rotate + * @param bits The number of bits to rotate right the value by + * @return The value rotated right by the specified amount of bits + */ #define OFRotateRight(value, bits) \ (((bits) % (sizeof(value) * 8)) > 0 \ ? ((value) >> ((bits) % (sizeof(value) * 8))) | \ ((value) << (sizeof(value) * 8 - ((bits) % (sizeof(value) * 8)))) \ : (value)) +/** + * @brief Rounds up the specified value to the specified power of two. + * + * @param pow2 The power of 2 to round up to + * @param value The value to round up to the specified power of two + * @return The specified value rounded up to the specified power of two + */ #define OFRoundUpToPowerOf2(pow2, value) \ (((value) + (pow2) - 1) & ~((pow2) - 1)) static OF_INLINE bool OFBitsetIsSet(unsigned char *_Nonnull storage, size_t idx)