The iOS framework that grows only as fast as its documentation
NIMemoryCache Class Reference

Overview

An in-memory cache for storing objects with expiration support.

The Nimbus in-memory object cache allows you to store objects in memory with an expiration date attached. Objects with expiration dates drop out of the cache when they have expired.

Inheritance diagram for NIMemoryCache:
NIImageMemoryCache

Tasks

Creating an In-Memory Cache
(id) - initWithCapacity:
 
Querying an In-Memory Cache
(NSUInteger) - count
 
Storing Objects in the Cache
(void) - storeObject:withName:
 
(void) - storeObject:withName:expiresAfter:
 
Removing Objects from the Cache
(void) - removeObjectWithName:
 
(void) - removeAllObjectsWithPrefix:
 
(void) - removeAllObjects
 
Accessing Objects in the Cache
(id) - objectWithName:
 
(BOOL) - containsObjectWithName:
 
(NSDate *) - dateOfLastAccessWithName:
 
(NSString *) - nameOfLeastRecentlyUsedObject
 
(NSString *) - nameOfMostRecentlyUsedObject
 
Reducing Memory Usage Explicitly
(void) - reduceMemoryUsage
 
Subclassing

The following methods are provided to aid in subclassing and are not meant to be used externally.

(BOOL) - shouldSetObject:withName:previousObject:
 
(void) - didSetObject:withName:
 
(void) - willRemoveObject:withName:
 
(BOOL) - willSetObject:withName:previousObject:
 

Method Documentation

initWithCapacity:

Initializes a newly allocated cache with the given capacity.

- (id)initWithCapacity:(NSUInteger)capacity;
Discussion
Returns
An in-memory cache initialized with the given capacity.

count

Returns the number of objects currently in the cache.

- (NSUInteger)count;
Discussion
Returns
The number of objects currently in the cache.

storeObject:withName:

Stores an object in the cache.

- (void)storeObject:(id)object withName:(NSString *)name;
Discussion

The object will be stored without an expiration date. The object will stay in the cache until it's bumped out due to the cache's memory limit.

Parameters
objectThe object being stored in the cache.
nameThe name used as a key to store this object.

storeObject:withName:expiresAfter:

Stores an object in the cache with an expiration date.

- (void)storeObject:(id)object withName:(NSString *)name expiresAfter:(NSDate *)expirationDate;
Discussion

If an object is stored with an expiration date that has already passed then the object will not be stored in the cache and any existing object will be removed. The rationale behind this is that the object would be removed from the cache the next time it was accessed anyway.

Parameters
objectThe object being stored in the cache.
nameThe name used as a key to store this object.
expirationDateA date after which this object is no longer valid in the cache.

removeObjectWithName:

Removes an object from the cache with the given name.

- (void)removeObjectWithName:(NSString *)name;
Discussion
Parameters
nameThe name used as a key to store this object.

removeAllObjectsWithPrefix:

Removes all objects from the cache with a given prefix.

- (void)removeAllObjectsWithPrefix:(NSString *)prefix;
Discussion

This method requires a scan of the cache entries.

Parameters
prefixAny object name that has this prefix will be removed from the cache.

removeAllObjects

Removes all objects from the cache, regardless of expiration dates.

- (void)removeAllObjects;
Discussion

This will completely clear out the cache and all objects in the cache will be released.

objectWithName:

Retrieves an object from the cache.

- (id)objectWithName:(NSString *)name;
Discussion

If the object has expired then the object will be removed from the cache and nil will be returned.

Returns
The object stored in the cache. The object is retained and autoreleased to ensure that it survives this run loop if you then remove it from the cache.

containsObjectWithName:

Returns a Boolean value that indicates whether an object with the given name is present in the cache.

- (BOOL)containsObjectWithName:(NSString *)name;
Discussion

Does not update the access time of the object.

If the object has expired then the object will be removed from the cache and NO will be returned.

Returns
YES if an object with the given name is present in the cache and has not expired, otherwise NO.

dateOfLastAccessWithName:

Returns the date that the object with the given name was last accessed.

- (NSDate*)dateOfLastAccessWithName:(NSString *)name;
Discussion

Does not update the access time of the object.

If the object has expired then the object will be removed from the cache and nil will be returned.

Returns
The last access date of the object if it exists and has not expired, nil otherwise.

nameOfLeastRecentlyUsedObject

Retrieve the name of the object that was least recently used.

- (NSString*)nameOfLeastRecentlyUsedObject;
Discussion

This will not update the access time of the object.

If the cache is empty, returns nil.

nameOfMostRecentlyUsedObject

Retrieve the key with the most fresh access.

- (NSString*)nameOfMostRecentlyUsedObject;
Discussion

This will not update the access time of the object.

If the cache is empty, returns nil.

reduceMemoryUsage

Removes all expired objects from the cache.

- (void)reduceMemoryUsage;
Discussion

Subclasses may add additional functionality to this implementation. Subclasses should call super in order to prune expired objects.

This will be called when UIApplicationDidReceiveMemoryWarningNotification is posted.

shouldSetObject:withName:previousObject:

An object is about to be stored in the cache.

- (BOOL)shouldSetObject:(id)object withName:(NSString *)name previousObject:(id)previousObject;
Discussion
Parameters
objectThe object that is about to be stored in the cache.
nameThe cache name for the object.
previousObjectThe object previously stored in the cache. This may be the same as object.
Returns
YES If object is allowed to be stored in the cache.

didSetObject:withName:

An object has been stored in the cache.

- (void)didSetObject:(id)object withName:(NSString *)name;
Discussion
Parameters
objectThe object that was stored in the cache.
nameThe cache name for the object.

willRemoveObject:withName:

An object is about to be removed from the cache.

- (void)willRemoveObject:(id)object withName:(NSString *)name;
Discussion
Parameters
objectThe object about to removed from the cache.
nameThe cache name for the object about to be removed.

willSetObject:withName:previousObject:

This method is deprecated.

- (BOOL)willSetObject:(id)object withName:(NSString *)name previousObject:(id)previousObject;
Discussion

Please use shouldSetObject:withName:previousObject: instead.