OFObject.h

Go to the documentation of this file.

/*
 * Copyright (c) 2008-2026 Jonathan Schleifer <js@nil.im>
 *
 * All rights reserved.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 3.0 only,
 * as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * version 3.0 for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3.0 along with this program. If not, see
 * <https://www.gnu.org/licenses/>.
 */

#include "objfw-defs.h"

#ifndef __STDC_LIMIT_MACROS
# define __STDC_LIMIT_MACROS
#endif
#ifndef __STDC_CONSTANT_MACROS
# define __STDC_CONSTANT_MACROS
#endif

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <limits.h>
#include <math.h>

#include "macros.h"

#import "OFOnce.h"

/*
 * Some versions of MinGW require <winsock2.h> to be included before
 * <windows.h>. Do this here to make sure this is always done in the correct
 * order, even if another header includes just <windows.h>.
 */
#ifdef __MINGW32__
# include <_mingw.h>
# ifdef __MINGW64_VERSION_MAJOR
#  include <winsock2.h>
#  include <windows.h>
# endif
#endif

OF_ASSUME_NONNULL_BEGIN

static const size_t OFNotFound = SIZE_MAX;

typedef enum {
    OFOrderedAscending = -1,
    OFOrderedSame = 0,
    OFOrderedDescending = 1
} OFComparisonResult;

typedef OFComparisonResult (*OFCompareFunction)(id _Nonnull left,
    id _Nonnull right, void *_Nullable context);

#ifdef OF_HAVE_BLOCKS

typedef OFComparisonResult (^OFComparator)(id _Nonnull left, id _Nonnull right);
#endif

typedef enum {
    OFByteOrderBigEndian,
    OFByteOrderLittleEndian,
#ifdef OF_BIG_ENDIAN
    OFByteOrderNative = OFByteOrderBigEndian
#else
    OFByteOrderNative = OFByteOrderLittleEndian
#endif
} OFByteOrder;

typedef struct OF_BOXABLE OFRange {
    size_t location;
    size_t length;
} OFRange;

static OF_INLINE OFRange OF_CONST_FUNC
OFMakeRange(size_t start, size_t length)
{
    OFRange range = { start, length };

    return range;
}

static OF_INLINE bool
OFEqualRanges(OFRange range1, OFRange range2)
{
    if (range1.location != range2.location)
        return false;

    if (range1.length != range2.length)
        return false;

    return true;
}

static OF_INLINE size_t
OFEndOfRange(OFRange range)
{
    if (range.length > SIZE_MAX - range.location) {
        extern void OF_NO_RETURN_FUNC _OFThrowOutOfRangeException(void);
        _OFThrowOutOfRangeException();
    }

    return range.location + range.length;
}

static OF_INLINE bool
OFLocationInRange(size_t location, OFRange range)
{
    return (location >= range.location &&
        location < OFEndOfRange(range));
}

static OF_INLINE OFRange
OFIntersectionRange(OFRange range1, OFRange range2)
{
    OFRange range;

    if (range1.location >= OFEndOfRange(range2) ||
        range2.location >= OFEndOfRange(range1))
        return OFMakeRange(OFNotFound, 0);

    range.location = (range1.location > range2.location
        ? range1.location : range2.location);
    range.length = (OFEndOfRange(range1) < OFEndOfRange(range2))
        ? OFEndOfRange(range1) - range.location
        : OFEndOfRange(range2) - range.location;

    return range;
}

static OF_INLINE OFRange
OFUnionRange(OFRange range1, OFRange range2)
{
    OFRange range;

    if (range1.location > OFEndOfRange(range2) ||
        range2.location > OFEndOfRange(range1))
        return OFMakeRange(OFNotFound, 0);

    range.location = (range1.location < range2.location
        ? range1.location : range2.location);
    range.length = (OFEndOfRange(range1) > OFEndOfRange(range2))
        ? OFEndOfRange(range1) - range.location
        : OFEndOfRange(range2) - range.location;

    return range;
}

typedef double OFTimeInterval;

typedef struct OF_BOXABLE OFPoint {
    float x;
    float y;
} OFPoint;

static OF_INLINE OFPoint OF_CONST_FUNC
OFMakePoint(float x, float y)
{
    OFPoint point = { x, y };

    return point;
}

static OF_INLINE bool
OFEqualPoints(OFPoint point1, OFPoint point2)
{
    if (point1.x != point2.x)
        return false;

    if (point1.y != point2.y)
        return false;

    return true;
}

typedef struct OF_BOXABLE OFSize {
    float width;
    float height;
} OFSize;

static OF_INLINE OFSize OF_CONST_FUNC
OFMakeSize(float width, float height)
{
    OFSize size = { width, height };

    return size;
}

static OF_INLINE bool
OFEqualSizes(OFSize size1, OFSize size2)
{
    if (size1.width != size2.width)
        return false;

    if (size1.height != size2.height)
        return false;

    return true;
}

typedef struct OF_BOXABLE OFRect {
    OFPoint origin;
    OFSize size;
} OFRect;

static OF_INLINE OFRect OF_CONST_FUNC
OFMakeRect(float x, float y, float width, float height)
{
    OFRect rect = {
        OFMakePoint(x, y),
        OFMakeSize(width, height)
    };

    return rect;
}

static OF_INLINE bool
OFEqualRects(OFRect rect1, OFRect rect2)
{
    if (!OFEqualPoints(rect1.origin, rect2.origin))
        return false;

    if (!OFEqualSizes(rect1.size, rect2.size))
        return false;

    return true;
}

typedef struct OF_BOXABLE OFVector3D {
    float x;
    float y;
    float z;
} OFVector3D;

static OF_INLINE OFVector3D OF_CONST_FUNC
OFMakeVector3D(float x, float y, float z)
{
    OFVector3D vector = { x, y, z };

    return vector;
}

static OF_INLINE bool
OFEqualVectors3D(OFVector3D vector1, OFVector3D vector2)
{
    if (vector1.x != vector2.x)
        return false;

    if (vector1.y != vector2.y)
        return false;

    if (vector1.z != vector2.z)
        return false;

    return true;
}

static OF_INLINE OFVector3D
OFAddVectors3D(OFVector3D vector1, OFVector3D vector2)
{
    return OFMakeVector3D(vector1.x + vector2.x, vector1.y + vector2.y,
        vector1.z + vector2.z);
}

static OF_INLINE OFVector3D
OFSubtractVectors3D(OFVector3D vector1, OFVector3D vector2)
{
    return OFMakeVector3D(vector1.x - vector2.x, vector1.y - vector2.y,
        vector1.z - vector2.z);
}

static OF_INLINE OFVector3D
OFMultiplyVector3D(OFVector3D vector, float scalar)
{
    return OFMakeVector3D(vector.x * scalar, vector.y * scalar,
        vector.z * scalar);
}

static OF_INLINE float
OFDotProductOfVectors3D(OFVector3D vector1, OFVector3D vector2)
{
    return vector1.x * vector2.x + vector1.y * vector2.y +
        vector1.z * vector2.z;
}

static OF_INLINE float
OFDistanceOfVectors3D(OFVector3D vector1, OFVector3D vector2)
{
    OFVector3D difference = OFSubtractVectors3D(vector1, vector2);

    return sqrtf(OFDotProductOfVectors3D(difference, difference));
}

typedef struct OF_BOXABLE OFVector4D {
    float x;
    float y;
    float z;
    float w;
} OFVector4D;

static OF_INLINE OFVector4D OF_CONST_FUNC
OFMakeVector4D(float x, float y, float z, float w)
{
    OFVector4D vector = { x, y, z, w };

    return vector;
}

static OF_INLINE bool
OFEqualVectors4D(OFVector4D vector1, OFVector4D vector2)
{
    if (vector1.x != vector2.x)
        return false;

    if (vector1.y != vector2.y)
        return false;

    if (vector1.z != vector2.z)
        return false;

    if (vector1.w != vector2.w)
        return false;

    return true;
}

static OF_INLINE OFVector4D
OFAddVectors4D(OFVector4D vector1, OFVector4D vector2)
{
    return OFMakeVector4D(vector1.x + vector2.x, vector1.y + vector2.y,
        vector1.z + vector2.z, vector1.w + vector2.w);
}

static OF_INLINE OFVector4D
OFSubtractVectors4D(OFVector4D vector1, OFVector4D vector2)
{
    return OFMakeVector4D(vector1.x - vector2.x, vector1.y - vector2.y,
        vector1.z - vector2.z, vector1.w - vector2.w);
}

static OF_INLINE OFVector4D
OFMultiplyVector4D(OFVector4D vector, float scalar)
{
    return OFMakeVector4D(vector.x * scalar, vector.y * scalar,
        vector.z * scalar, vector.w * scalar);
}

static OF_INLINE float
OFDotProductOfVectors4D(OFVector4D vector1, OFVector4D vector2)
{
    return vector1.x * vector2.x + vector1.y * vector2.y +
        vector1.z * vector2.z + vector1.w * vector2.w;
}

static OF_INLINE float
OFDistanceOfVectors4D(OFVector4D vector1, OFVector4D vector2)
{
    OFVector4D difference = OFSubtractVectors4D(vector1, vector2);

    return sqrtf(OFDotProductOfVectors4D(difference, difference));
}

static OF_INLINE void
OFHashAddByte(unsigned long *_Nonnull hash, unsigned char byte)
{
    uint32_t tmp = (uint32_t)*hash;

    tmp += byte;
    tmp += tmp << 10;
    tmp ^= tmp >> 6;

    *hash = tmp;
}

static OF_INLINE void
OFHashAddHash(unsigned long *_Nonnull hash, unsigned long otherHash)
{
    OFHashAddByte(hash, (otherHash >> 24) & 0xFF);
    OFHashAddByte(hash, (otherHash >> 16) & 0xFF);
    OFHashAddByte(hash, (otherHash >>  8) & 0xFF);
    OFHashAddByte(hash, otherHash & 0xFF);
}

static OF_INLINE void
OFHashFinalize(unsigned long *_Nonnull hash)
{
    uint32_t tmp = (uint32_t)*hash;

    tmp += tmp << 3;
    tmp ^= tmp >> 11;
    tmp += tmp << 15;

    *hash = tmp;
}

@class OFMethodSignature;
@class OFString;
@class OFThread;

@protocol OFObject
- (Class)class;

- (nullable Class)superclass;

- (unsigned long)hash;

- (unsigned int)retainCount;

- (bool)isProxy;

- (bool)isKindOfClass: (Class)class_;

- (bool)isMemberOfClass: (Class)class_;

- (bool)respondsToSelector: (SEL)selector;

- (bool)conformsToProtocol: (Protocol *)protocol;

- (nullable IMP)methodForSelector: (SEL)selector;

- (nullable id)performSelector: (SEL)selector;

- (nullable id)performSelector: (SEL)selector withObject: (nullable id)object;

- (nullable id)performSelector: (SEL)selector
            withObject: (nullable id)object1
            withObject: (nullable id)object2;

- (nullable id)performSelector: (SEL)selector
            withObject: (nullable id)object1
            withObject: (nullable id)object2
            withObject: (nullable id)object3;

- (nullable id)performSelector: (SEL)selector
            withObject: (nullable id)object1
            withObject: (nullable id)object2
            withObject: (nullable id)object3
            withObject: (nullable id)object4;

- (bool)isEqual: (nullable id)object;

- (instancetype)retain;

- (void)release;

- (instancetype)autorelease;

- (instancetype)self;

- (bool)allowsWeakReference;

- (bool)retainWeakReference;
@end

OF_ROOT_CLASS
@interface OFObject <OFObject>
{
@private
#ifndef __clang_analyzer__
    Class _isa;
#else
    Class _isa __attribute__((__unused__));
#endif
}

#ifdef OF_HAVE_CLASS_PROPERTIES
# ifndef __cplusplus
@property (class, readonly, nonatomic) Class class;
# else
@property (class, readonly, nonatomic, getter=class) Class class_;
# endif
@property (class, readonly, nonatomic) OFString *className;
@property (class, readonly, nullable, nonatomic) Class superclass;
@property (class, readonly, nonatomic) OFString *description;
#endif

#ifndef __cplusplus
@property (readonly, nonatomic) Class class;
#else
@property (readonly, nonatomic, getter=class) Class class_;
#endif
@property OF_NULLABLE_PROPERTY (readonly, nonatomic) Class superclass;
@property (readonly, nonatomic) unsigned long hash;
@property (readonly, nonatomic) unsigned int retainCount;
@property (readonly, nonatomic) bool isProxy;
@property (readonly, nonatomic) bool allowsWeakReference;

@property (readonly, nonatomic) OFString *className;

@property (readonly, nonatomic) OFString *description;

+ (void)load;

+ (void)unload;

+ (void)initialize;

+ (instancetype)alloc;

+ (Class)class;

+ (OFString *)className;

+ (bool)isSubclassOfClass: (Class)class_;

+ (nullable Class)superclass;

+ (bool)instancesRespondToSelector: (SEL)selector;

+ (bool)conformsToProtocol: (Protocol *)protocol;

+ (nullable IMP)instanceMethodForSelector: (SEL)selector;

+ (nullable OFMethodSignature *)
    instanceMethodSignatureForSelector: (SEL)selector;

+ (OFString *)description;

+ (nullable IMP)replaceClassMethod: (SEL)selector
           withMethodFromClass: (Class)class_;

+ (nullable IMP)replaceInstanceMethod: (SEL)selector
          withMethodFromClass: (Class)class_;

+ (void)inheritMethodsFromClass: (Class)class_;

+ (bool)resolveClassMethod: (SEL)selector;

+ (bool)resolveInstanceMethod: (SEL)selector;

+ (id)copy;

- (instancetype)init;

- (nullable OFMethodSignature *)methodSignatureForSelector: (SEL)selector;

- (void)dealloc;

- (void)performSelector: (SEL)selector afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
         withObject: (nullable id)object
         afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         withObject: (nullable id)object3
         afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         withObject: (nullable id)object3
         withObject: (nullable id)object4
         afterDelay: (OFTimeInterval)delay;

#ifdef OF_HAVE_THREADS

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
      waitUntilDone: (bool)waitUntilDone;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object
      waitUntilDone: (bool)waitUntilDone;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object1
         withObject: (nullable id)object2
      waitUntilDone: (bool)waitUntilDone;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         withObject: (nullable id)object3
      waitUntilDone: (bool)waitUntilDone;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         withObject: (nullable id)object3
         withObject: (nullable id)object4
      waitUntilDone: (bool)waitUntilDone;

- (void)performSelectorOnMainThread: (SEL)selector
              waitUntilDone: (bool)waitUntilDone;

- (void)performSelectorOnMainThread: (SEL)selector
             withObject: (nullable id)object
              waitUntilDone: (bool)waitUntilDone;

- (void)performSelectorOnMainThread: (SEL)selector
             withObject: (nullable id)object1
             withObject: (nullable id)object2
              waitUntilDone: (bool)waitUntilDone;

- (void)performSelectorOnMainThread: (SEL)selector
             withObject: (nullable id)object1
             withObject: (nullable id)object2
             withObject: (nullable id)object3
              waitUntilDone: (bool)waitUntilDone;

- (void)performSelectorOnMainThread: (SEL)selector
             withObject: (nullable id)object1
             withObject: (nullable id)object2
             withObject: (nullable id)object3
             withObject: (nullable id)object4
              waitUntilDone: (bool)waitUntilDone;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object
         afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         withObject: (nullable id)object3
         afterDelay: (OFTimeInterval)delay;

- (void)performSelector: (SEL)selector
           onThread: (OFThread *)thread
         withObject: (nullable id)object1
         withObject: (nullable id)object2
         withObject: (nullable id)object3
         withObject: (nullable id)object4
         afterDelay: (OFTimeInterval)delay;
#endif

- (nullable id)forwardingTargetForSelector: (SEL)selector;

- (void)doesNotRecognizeSelector: (SEL)selector OF_NO_RETURN;
@end

@protocol OFCopying
- (id)copy;
@end

@protocol OFMutableCopying
- (id)mutableCopy;
@end

@protocol OFComparing
- (OFComparisonResult)compare: (id <OFComparing>)object;
@end

#ifdef __cplusplus
extern "C" {
#endif

extern void *_Nullable OFAllocMemory(size_t count, size_t size)
    OF_MALLOC_FUNC OF_WARN_UNUSED_RESULT;

extern void *_Nullable OFAllocZeroedMemory(size_t count, size_t size)
    OF_MALLOC_FUNC OF_WARN_UNUSED_RESULT;

extern void *_Nullable OFResizeMemory(void *_Nullable pointer, size_t count,
    size_t size) OF_WARN_UNUSED_RESULT;

extern void OFFreeMemory(void *_Nullable pointer);

#ifdef OF_APPLE_RUNTIME
extern void *_Null_unspecified objc_autoreleasePoolPush(void);
extern void objc_autoreleasePoolPop(void *_Null_unspecified pool);
extern id _Nullable objc_retain(id _Nullable object);
extern id _Nullable objc_retainBlock(id _Nullable block);
extern id _Nullable objc_retainAutorelease(id _Nullable object);
extern void objc_release(id _Nullable object);
extern id _Nullable objc_autorelease(id _Nullable object);
extern id _Nullable objc_autoreleaseReturnValue(id _Nullable object);
extern id _Nullable objc_retainAutoreleaseReturnValue(id _Nullable object);
extern id _Nullable objc_retainAutoreleasedReturnValue(id _Nullable object);
extern id _Nullable objc_storeStrong(id _Nullable *_Nonnull object,
    id _Nullable value);
extern id _Nullable objc_storeWeak(id _Nullable *_Nonnull object,
    id _Nullable value);
extern id _Nullable objc_loadWeakRetained(id _Nullable *_Nonnull object);
extern _Nullable id objc_initWeak(id _Nullable *_Nonnull object,
    id _Nullable value);
extern void objc_destroyWeak(id _Nullable *_Nonnull object);
extern id _Nullable objc_loadWeak(id _Nullable *_Nonnull object);
extern void objc_copyWeak(id _Nullable *_Nonnull dest,
    id _Nullable *_Nonnull src);
extern void objc_moveWeak(id _Nullable *_Nonnull dest,
    id _Nullable *_Nonnull src);
# ifdef OF_DECLARE_CONSTRUCT_INSTANCE
extern id _Nullable objc_constructInstance(Class _Nullable class_,
    void *_Nullable bytes);
extern void *_Nullable objc_destructInstance(id _Nullable object);
# endif
# ifdef OF_DECLARE_SET_ASSOCIATED_OBJECT
typedef enum objc_associationPolicy {
    OBJC_ASSOCIATION_ASSIGN = 0,
    OBJC_ASSOCIATION_RETAIN_NONATOMIC = 1,
    OBJC_ASSOCIATION_RETAIN = OBJC_ASSOCIATION_RETAIN_NONATOMIC | 0x300,
    OBJC_ASSOCIATION_COPY_NONATOMIC = 3,
    OBJC_ASSOCIATION_COPY = OBJC_ASSOCIATION_COPY_NONATOMIC | 0x300
} objc_associationPolicy;
extern void objc_setAssociatedObject(id _Nonnull object,
    const void *_Nonnull key, id _Nullable value,
    objc_associationPolicy policy);
extern id _Nullable objc_getAssociatedObject(id _Nonnull object,
    const void *_Nonnull key);
extern void objc_removeAssociatedObjects(id _Nonnull object);
# endif
#endif

extern id OFAllocObject(Class class_, size_t extraSize, size_t extraAlignment,
    void *_Nullable *_Nullable extra);

extern void OF_NO_RETURN_FUNC OFMethodNotFound(id self, SEL _cmd);

extern void OFHashInit(unsigned long *_Nonnull hash);

extern uint16_t OFRandom16(void);

extern uint32_t OFRandom32(void);

extern uint64_t OFRandom64(void);
#ifdef __cplusplus
}
#endif

OF_ASSUME_NONNULL_END

#import "OFBlock.h"
#import "OFObject+KeyValueCoding.h"