YapBidirectionalCache

@interface YapBidirectionalCache<KeyType, ObjectType> : NSObject

A bidirectional cache has the following features:

  • stores pairs
  • supports a single value per key
  • supports a single key per value
  • efficient mapping from key to value
  • efficient mapping from value to key
  • optional strict cache size
  • eviction based on least-recently-used

The cache maintains two dictionaries internally. One mapping from key to value. And the other mapping from value to key. So a lookup based on the either the key or value can be performed in O(1).

Caching:

When the countLimit is non-zero, this class operates as a cache, enforcing the designed limit, and using eviction when the limit is exceeded. When the countLimit is zero, this class operates as a generic container (with no limit, and no automatic eviction).

Eviction depends entirely on usage. The cache maintains a doubly linked-list of tuples ordered by access. The most recently accessed item is at the front of the linked-list, and the least recently accessed item is at the back. So it’s very quick and efficient to evict items based on recent usage.

  • Initializes a cache. If you don’t define a countLimit, then the default countLimit of 40 is used.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

    Swift

    init()

  • Undocumented

    Declaration

    Objective-C

    - (instancetype)initWithCountLimit:(NSUInteger)countLimit;

    Swift

    init(countLimit: UInt)

  • Advanced init method allows you to define the CallBacks for the keys & objects to be used by the internal CFDictionaries.

    The default value for callbacks is : { version = 0, shouldCopy = NO, equal = CFEqual, hash = CFHash }

    Declaration

    Objective-C

    - (nonnull instancetype)
    initWithCountLimit:(NSUInteger)countLimit
          keyCallbacks:
              (const YapBidirectionalCacheCallBacks *_Nullable)keyCallbacks
       objectCallbacks:
           (const YapBidirectionalCacheCallBacks *_Nullable)objectCallbacks;

    Swift

    init(countLimit: UInt, keyCallbacks: UnsafePointer<YapBidirectionalCacheCallBacks>?, objectCallbacks: UnsafePointer<YapBidirectionalCacheCallBacks>?)

  • The countLimit specifies the maximum number of items to keep in the cache. This limit is strictly enforced.

    The default countLimit is 40.

    You may optionally disable the countLimit by setting it to zero.

    You may change the countLimit at any time. Changes to the countLimit take immediate effect on the cache (before the set method returns). Thus, if needed, you can temporarily increase the cache size for certain operations.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSUInteger countLimit;

    Swift

    var countLimit: UInt { get set }

  • These methods are for debugging.

    They allows you to specify a set of classes that you intend to use for the keys and/or values. If set, the class will check to ensure you’re always using the proper class type when you set or query the cache.

    You can think of this feature as something similar to templates / generic types in C++. Except that it’s run-time enforcement, and not compile-time.

    Since this is for debugging, the checks are ONLY run when assertions are enabled. In general, assertions are disabled when you compile for release. But to be precise, the checks are only run if NS_BLOCK_ASSERTIONS is not defined.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSSet<Class> *allowedKeyClasses;

    Swift

    var allowedKeyClasses: Set<AnyHashable>? { get set }

  • Undocumented

    Declaration

    Objective-C

    @property (nonatomic, copy, readwrite, nullable) NSSet<Class> *allowedObjectClasses

    Swift

    var allowedObjectClasses: Set<AnyHashable>? { get set }

  • Undocumented

    Declaration

    Objective-C

    - (nullable ObjectType)objectForKey:(KeyType)key;

    Swift

    func object(forKey key: KeyType) -> ObjectType?

  • Undocumented

    Declaration

    Objective-C

    - (BOOL)containsKey:(KeyType)key;

    Swift

    func containsKey(_ key: KeyType) -> Bool

  • Undocumented

    Declaration

    Objective-C

    - (nullable KeyType)keyForObject:(ObjectType)object;

    Swift

    func key(for object: ObjectType) -> KeyType?

  • Undocumented

    Declaration

    Objective-C

    - (BOOL)containsObject:(ObjectType)object;

    Swift

    func contains(_ object: ObjectType) -> Bool

  • Undocumented

    Declaration

    Objective-C

    - (NSUInteger)count;

    Swift

    func count() -> UInt

  • Undocumented

    Declaration

    Objective-C

    - (void)setObject:(ObjectType)object forKey:(KeyType)key;

    Swift

    func setObject(_ object: ObjectType, forKey key: KeyType)

  • Undocumented

    Declaration

    Objective-C

    - (void)removeAllObjects;

    Swift

    func removeAllObjects()

  • Undocumented

    Declaration

    Objective-C

    - (void)removeObjectForKey:(KeyType)key;

    Swift

    func removeObject(forKey key: KeyType)

  • Undocumented

    Declaration

    Objective-C

    - (void)removeObjectsForKeys:(id <NSFastEnumeration>)keys;

    Swift

    func removeObjects(forKeys keys: NSFastEnumeration)

  • Undocumented

    Declaration

    Objective-C

    - (void)removeKeyForObject:(ObjectType)object;

    Swift

    func removeKey(for object: ObjectType)

  • Undocumented

    Declaration

    Objective-C

    - (void)removeKeysForObjects:(id <NSFastEnumeration>)objects;

    Swift

    func removeKeys(forObjects objects: NSFastEnumeration)

  • Undocumented

    Declaration

    Objective-C

    - (void)enumerateKeysWithBlock:(void (NS_NOESCAPE^)(KeyType key, BOOL *stop))block;

    Swift

    func enumerateKeys(_ block: (KeyType, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Undocumented

    Declaration

    Objective-C

    - (void)enumerateObjectsWithBlock:(void (NS_NOESCAPE^)(ObjectType object, BOOL *stop))block;

    Swift

    func enumerateObjects(_ block: (ObjectType, UnsafeMutablePointer<ObjCBool>) -> Void)

  • Undocumented

    Declaration

    Objective-C

    - (void)enumerateKeysAndObjectsWithBlock:(void (NS_NOESCAPE^)(KeyType key, ObjectType obj, BOOL *stop))block;

    Swift

    func enumerateKeysAndObjects(_ block: (KeyType, ObjectType, UnsafeMutablePointer<ObjCBool>) -> Void)