SDImageCache

@interface SDImageCache : NSObject

SDImageCache maintains a memory cache and a disk cache. Disk cache write operations are performed asynchronous so it doesn’t add unnecessary latency to the UI.

Properties

  • Cache Config object - storing all kind of settings. The property is copy so change of current config will not accidentally affect other cache’s config.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nonnull) SDImageCacheConfig *config;

    Swift

    @NSCopying var config: SDImageCacheConfig { get }
  • The memory cache implementation object used for current image cache. By default we use SDMemoryCache class, you can also use this to call your own implementation class method.

    Note

    To customize this class, check SDImageCacheConfig.memoryCacheClass property.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nonnull) id<SDMemoryCache> memoryCache;

    Swift

    var memoryCache: SDMemoryCacheProtocol { get }
  • The disk cache implementation object used for current image cache. By default we use SDMemoryCache class, you can also use this to call your own implementation class method.

    Note

    To customize this class, check SDImageCacheConfig.diskCacheClass property.

    Warning

    When calling method about read/write in disk cache, be sure to either make your disk cache implementation IO-safe or using the same access queue to avoid issues.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nonnull) id<SDDiskCache> diskCache;

    Swift

    var diskCache: SDDiskCacheProtocol { get }
  • The disk cache’s root path

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nonnull) NSString *diskCachePath;

    Swift

    var diskCachePath: String { get }
  • The additional disk cache path to check if the query from disk cache not exist; The key param is the image cache key. The returned file path will be used to load the disk cache. If return nil, ignore it. Useful if you want to bundle pre-loaded images with your app

    Declaration

    Objective-C

    @property (copy, nonatomic, nullable) SDImageCacheAdditionalCachePathBlock additionalCachePathBlock;

    Swift

    var additionalCachePathBlock: SDImageCacheAdditionalCachePathBlock? { get set }

Singleton and initialization

  • Returns global shared cache instance

    Declaration

    Objective-C

    @property (readonly, nonatomic, nonnull, class) SDImageCache *sharedImageCache;

    Swift

    class var shared: SDImageCache { get }
  • Init a new cache store with a specific namespace

    Declaration

    Objective-C

    - (nonnull instancetype)initWithNamespace:(nonnull NSString *)ns;

    Swift

    convenience init(namespace ns: String)

    Parameters

    ns

    The namespace to use for this cache store

  • Init a new cache store with a specific namespace and directory. If you don’t provide the disk cache directory, we will use the User Cache directory with prefix (~/Library/Caches/com.hackemist.SDImageCache/).

    Declaration

    Objective-C

    - (nonnull instancetype)initWithNamespace:(nonnull NSString *)ns
                           diskCacheDirectory:(nullable NSString *)directory;

    Swift

    convenience init(namespace ns: String, diskCacheDirectory directory: String?)

    Parameters

    ns

    The namespace to use for this cache store

    directory

    Directory to cache disk images in

  • Init a new cache store with a specific namespace, directory and file manager The final disk cache directory should looks like ($directory/$namespace). And the default config of shared cache, should result in (~/Library/Caches/com.hackemist.SDImageCache/default/)

    Declaration

    Objective-C

    - (nonnull instancetype)initWithNamespace:(nonnull NSString *)ns
                           diskCacheDirectory:(nullable NSString *)directory
                                       config:(nullable SDImageCacheConfig *)config;

    Swift

    init(namespace ns: String, diskCacheDirectory directory: String?, config: SDImageCacheConfig?)

    Parameters

    ns

    The namespace to use for this cache store

    directory

    Directory to cache disk images in

    config

    The cache config to be used to create the cache. You can provide custom memory cache or disk cache class in the cache config

Cache paths

  • Get the cache path for a certain key

    Declaration

    Objective-C

    - (nullable NSString *)cachePathForKey:(nullable NSString *)key;

    Swift

    func cachePath(forKey key: String?) -> String?

    Parameters

    key

    The unique image cache key

    Return Value

    The cache path. You can check lastPathComponent to grab the file name.

Store Ops

  • Asynchronously store an image into memory and disk cache at the given key.

    Declaration

    Objective-C

    - (void)storeImage:(nullable UIImage *)image
                forKey:(nullable NSString *)key
            completion:(nullable SDWebImageNoParamsBlock)completionBlock;

    Swift

    func store(_ image: UIImage?, forKey key: String?, completion completionBlock: SDWebImageNoParamsBlock? = nil)

    Parameters

    image

    The image to store

    key

    The unique image cache key, usually it’s image absolute URL

    completionBlock

    A block executed after the operation is finished

  • Asynchronously store an image into memory and disk cache at the given key.

    Note

    If no image data is provided and encode to disk, we will try to detect the image format (using either sd_imageFormat or SDAnimatedImage protocol method) and animation status, to choose the best matched format, including GIF, JPEG or PNG.

    Declaration

    Objective-C

    - (void)storeImage:(nullable UIImage *)image
                forKey:(nullable NSString *)key
                toDisk:(BOOL)toDisk
            completion:(nullable SDWebImageNoParamsBlock)completionBlock;

    Swift

    func store(_ image: UIImage?, forKey key: String?, toDisk: Bool, completion completionBlock: SDWebImageNoParamsBlock? = nil)

    Parameters

    image

    The image to store

    key

    The unique image cache key, usually it’s image absolute URL

    toDisk

    Store the image to disk cache if YES. If NO, the completion block is called synchronously

    completionBlock

    A block executed after the operation is finished

  • Asynchronously store an image into memory and disk cache at the given key.

    Note

    If no image data is provided and encode to disk, we will try to detect the image format (using either sd_imageFormat or SDAnimatedImage protocol method) and animation status, to choose the best matched format, including GIF, JPEG or PNG.

    Declaration

    Objective-C

    - (void)storeImage:(nullable UIImage *)image
             imageData:(nullable NSData *)imageData
                forKey:(nullable NSString *)key
                toDisk:(BOOL)toDisk
            completion:(nullable SDWebImageNoParamsBlock)completionBlock;

    Swift

    func store(_ image: UIImage?, imageData: Data?, forKey key: String?, toDisk: Bool, completion completionBlock: SDWebImageNoParamsBlock? = nil)

    Parameters

    image

    The image to store

    imageData

    The image data as returned by the server, this representation will be used for disk storage instead of converting the given image object into a storable/compressed image format in order to save quality and CPU

    key

    The unique image cache key, usually it’s image absolute URL

    toDisk

    Store the image to disk cache if YES. If NO, the completion block is called synchronously

    completionBlock

    A block executed after the operation is finished

  • Synchronously store image into memory cache at the given key.

    Declaration

    Objective-C

    - (void)storeImageToMemory:(nullable UIImage *)image
                        forKey:(nullable NSString *)key;

    Swift

    func storeImage(toMemory image: UIImage?, forKey key: String?)

    Parameters

    image

    The image to store

    key

    The unique image cache key, usually it’s image absolute URL

  • Synchronously store image data into disk cache at the given key.

    Declaration

    Objective-C

    - (void)storeImageDataToDisk:(nullable NSData *)imageData
                          forKey:(nullable NSString *)key;

    Swift

    func storeImageData(toDisk imageData: Data?, forKey key: String?)

    Parameters

    imageData

    The image data to store

    key

    The unique image cache key, usually it’s image absolute URL

Contains and Check Ops

  • Asynchronously check if image exists in disk cache already (does not load the image)

    Note

    the completion block will be always executed on the main queue

    Declaration

    Objective-C

    - (void)diskImageExistsWithKey:(nullable NSString *)key
                        completion:(nullable SDImageCacheCheckCompletionBlock)
                                       completionBlock;

    Swift

    func diskImageExists(withKey key: String?, completion completionBlock: SDImageCacheCheckCompletionBlock? = nil)

    Parameters

    key

    the key describing the url

    completionBlock

    the block to be executed when the check is done.

  • Synchronously check if image data exists in disk cache already (does not load the image)

    Declaration

    Objective-C

    - (BOOL)diskImageDataExistsWithKey:(nullable NSString *)key;

    Swift

    func diskImageDataExists(withKey key: String?) -> Bool

    Parameters

    key

    the key describing the url

Query and Retrieve Ops

  • Synchronously query the image data for the given key in disk cache. You can decode the image data to image after loaded.

    Declaration

    Objective-C

    - (nullable NSData *)diskImageDataForKey:(nullable NSString *)key;

    Swift

    func diskImageData(forKey key: String?) -> Data?

    Parameters

    key

    The unique key used to store the wanted image

    Return Value

    The image data for the given key, or nil if not found.

  • Asynchronously query the image data for the given key in disk cache. You can decode the image data to image after loaded.

    Note

    the completion block will be always executed on the main queue

    Declaration

    Objective-C

    - (void)diskImageDataQueryForKey:(nullable NSString *)key
                          completion:(nullable SDImageCacheQueryDataCompletionBlock)
                                         completionBlock;

    Swift

    func diskImageDataQuery(forKey key: String?, completion completionBlock: SDImageCacheQueryDataCompletionBlock? = nil)

    Parameters

    key

    The unique key used to store the wanted image

    completionBlock

    the block to be executed when the query is done.

  • Asynchronously queries the cache with operation and call the completion when done.

    Declaration

    Objective-C

    - (nullable NSOperation *)
        queryCacheOperationForKey:(nullable NSString *)key
                             done:(nullable SDImageCacheQueryCompletionBlock)
                                      doneBlock;

    Swift

    func queryCacheOperation(forKey key: String?, done doneBlock: SDImageCacheQueryCompletionBlock? = nil) -> Operation?

    Parameters

    key

    The unique key used to store the wanted image. If you want transformed or thumbnail image, calculate the key with SDTransformedKeyForKey, SDThumbnailedKeyForKey, or generate the cache key from url with cacheKeyForURL:context:.

    doneBlock

    The completion block. Will not get called if the operation is cancelled

    Return Value

    a NSOperation instance containing the cache op

  • Asynchronously queries the cache with operation and call the completion when done.

    Declaration

    Objective-C

    - (nullable NSOperation *)
        queryCacheOperationForKey:(nullable NSString *)key
                          options:(SDImageCacheOptions)options
                             done:(nullable SDImageCacheQueryCompletionBlock)
                                      doneBlock;

    Swift

    func queryCacheOperation(forKey key: String?, options: SDImageCacheOptions = [], done doneBlock: SDImageCacheQueryCompletionBlock? = nil) -> Operation?

    Parameters

    key

    The unique key used to store the wanted image. If you want transformed or thumbnail image, calculate the key with SDTransformedKeyForKey, SDThumbnailedKeyForKey, or generate the cache key from url with cacheKeyForURL:context:.

    options

    A mask to specify options to use for this cache query

    doneBlock

    The completion block. Will not get called if the operation is cancelled

    Return Value

    a NSOperation instance containing the cache op

  • Asynchronously queries the cache with operation and call the completion when done.

    Declaration

    Objective-C

    - (nullable NSOperation *)
        queryCacheOperationForKey:(nullable NSString *)key
                          options:(SDImageCacheOptions)options
                          context:(nullable SDWebImageContext *)context
                             done:(nullable SDImageCacheQueryCompletionBlock)
                                      doneBlock;

    Swift

    func queryCacheOperation(forKey key: String?, options: SDImageCacheOptions = [], context: [SDWebImageContextOption : Any]?, done doneBlock: SDImageCacheQueryCompletionBlock? = nil) -> Operation?

    Parameters

    key

    The unique key used to store the wanted image. If you want transformed or thumbnail image, calculate the key with SDTransformedKeyForKey, SDThumbnailedKeyForKey, or generate the cache key from url with cacheKeyForURL:context:.

    options

    A mask to specify options to use for this cache query

    context

    A context contains different options to perform specify changes or processes, see SDWebImageContextOption. This hold the extra objects which options enum can not hold.

    doneBlock

    The completion block. Will not get called if the operation is cancelled

    Return Value

    a NSOperation instance containing the cache op

  • Asynchronously queries the cache with operation and call the completion when done.

    Declaration

    Objective-C

    - (nullable NSOperation *)
        queryCacheOperationForKey:(nullable NSString *)key
                          options:(SDImageCacheOptions)options
                          context:(nullable SDWebImageContext *)context
                        cacheType:(SDImageCacheType)queryCacheType
                             done:(nullable SDImageCacheQueryCompletionBlock)
                                      doneBlock;

    Swift

    func queryCacheOperation(forKey key: String?, options: SDImageCacheOptions = [], context: [SDWebImageContextOption : Any]?, cacheType queryCacheType: SDImageCacheType, done doneBlock: SDImageCacheQueryCompletionBlock? = nil) -> Operation?

    Parameters

    key

    The unique key used to store the wanted image. If you want transformed or thumbnail image, calculate the key with SDTransformedKeyForKey, SDThumbnailedKeyForKey, or generate the cache key from url with cacheKeyForURL:context:.

    options

    A mask to specify options to use for this cache query

    context

    A context contains different options to perform specify changes or processes, see SDWebImageContextOption. This hold the extra objects which options enum can not hold.

    queryCacheType

    Specify where to query the cache from. By default we use .all, which means both memory cache and disk cache. You can choose to query memory only or disk only as well. Pass .none is invalid and callback with nil immediately.

    doneBlock

    The completion block. Will not get called if the operation is cancelled

    Return Value

    a NSOperation instance containing the cache op

  • Synchronously query the memory cache.

    Declaration

    Objective-C

    - (nullable UIImage *)imageFromMemoryCacheForKey:(nullable NSString *)key;

    Swift

    func imageFromMemoryCache(forKey key: String?) -> UIImage?

    Parameters

    key

    The unique key used to store the image

    Return Value

    The image for the given key, or nil if not found.

  • Synchronously query the disk cache.

    Declaration

    Objective-C

    - (nullable UIImage *)imageFromDiskCacheForKey:(nullable NSString *)key;

    Swift

    func imageFromDiskCache(forKey key: String?) -> UIImage?

    Parameters

    key

    The unique key used to store the image

    Return Value

    The image for the given key, or nil if not found.

  • Synchronously query the disk cache. With the options and context which may effect the image generation. (Such as transformer, animated image, thumbnail, etc)

    Declaration

    Objective-C

    - (nullable UIImage *)imageFromDiskCacheForKey:(nullable NSString *)key
                                           options:(SDImageCacheOptions)options
                                           context:(nullable SDWebImageContext *)
                                                       context;

    Swift

    func imageFromDiskCache(forKey key: String?, options: SDImageCacheOptions = [], context: [SDWebImageContextOption : Any]?) -> UIImage?

    Parameters

    key

    The unique key used to store the image

    options

    A mask to specify options to use for this cache query

    context

    A context contains different options to perform specify changes or processes, see SDWebImageContextOption. This hold the extra objects which options enum can not hold.

    Return Value

    The image for the given key, or nil if not found.

  • Synchronously query the cache (memory and or disk) after checking the memory cache.

    Declaration

    Objective-C

    - (nullable UIImage *)imageFromCacheForKey:(nullable NSString *)key;

    Swift

    func imageFromCache(forKey key: String?) -> UIImage?

    Parameters

    key

    The unique key used to store the image

    Return Value

    The image for the given key, or nil if not found.

  • Synchronously query the cache (memory and or disk) after checking the memory cache. With the options and context which may effect the image generation. (Such as transformer, animated image, thumbnail, etc)

    Declaration

    Objective-C

    - (nullable UIImage *)imageFromCacheForKey:(nullable NSString *)key
                                       options:(SDImageCacheOptions)options
                                       context:
                                           (nullable SDWebImageContext *)context;

    Swift

    func imageFromCache(forKey key: String?, options: SDImageCacheOptions = [], context: [SDWebImageContextOption : Any]?) -> UIImage?

    Parameters

    key

    The unique key used to store the image

    options

    A mask to specify options to use for this cache query

    context

    A context contains different options to perform specify changes or processes, see SDWebImageContextOption. This hold the extra objects which options enum can not hold.

    Return Value

    The image for the given key, or nil if not found.

Remove Ops

  • Asynchronously remove the image from memory and disk cache

    Declaration

    Objective-C

    - (void)removeImageForKey:(nullable NSString *)key
               withCompletion:(nullable SDWebImageNoParamsBlock)completion;

    Swift

    func removeImage(forKey key: String?, withCompletion completion: SDWebImageNoParamsBlock? = nil)

    Parameters

    key

    The unique image cache key

    completion

    A block that should be executed after the image has been removed (optional)

  • Asynchronously remove the image from memory and optionally disk cache

    Declaration

    Objective-C

    - (void)removeImageForKey:(nullable NSString *)key
                     fromDisk:(BOOL)fromDisk
               withCompletion:(nullable SDWebImageNoParamsBlock)completion;

    Swift

    func removeImage(forKey key: String?, fromDisk: Bool, withCompletion completion: SDWebImageNoParamsBlock? = nil)

    Parameters

    key

    The unique image cache key

    fromDisk

    Also remove cache entry from disk if YES. If NO, the completion block is called synchronously

    completion

    A block that should be executed after the image has been removed (optional)

  • Synchronously remove the image from memory cache.

    Declaration

    Objective-C

    - (void)removeImageFromMemoryForKey:(nullable NSString *)key;

    Swift

    func removeImageFromMemory(forKey key: String?)

    Parameters

    key

    The unique image cache key

  • Synchronously remove the image from disk cache.

    Declaration

    Objective-C

    - (void)removeImageFromDiskForKey:(nullable NSString *)key;

    Swift

    func removeImageFromDisk(forKey key: String?)

    Parameters

    key

    The unique image cache key

Cache clean Ops

Cache Info