ImageCache
open class ImageCache
ImageCache
represents both the memory and disk cache system of Kingfisher.
While a default image cache object will be used if you prefer the extension methods of Kingfisher,
you can create your own cache object and configure it as your need. You could use an ImageCache
object to manipulate memory and disk cache for Kingfisher.
-
The largest cache cost of memory cache. The total cost is pixel count of all cached images in memory. Default is unlimited. Memory cache will be purged automatically when a memory warning notification is received.
Declaration
Swift
open var maxMemoryCost: UInt = 0
-
The disk cache location.
Declaration
Swift
open let diskCachePath: String
-
The default file extension appended to cached files.
Declaration
Swift
open var pathExtension: String?
-
The longest time duration in second of the cache being stored in disk. Default is 1 week (60 * 60 * 24 * 7 seconds). Setting this to a negative value will make the disk cache never expiring.
Declaration
Swift
open var maxCachePeriodInSecond: TimeInterval = 60 * 60 * 24 * 7 //Cache exists for 1 week
-
The largest disk size can be taken for the cache. It is the total allocated size of cached files in bytes. Default is no limit.
Declaration
Swift
open var maxDiskCacheSize: UInt = 0
-
The default cache.
Declaration
Swift
public static let `default` = ImageCache(name: "default")
-
Closure that defines the disk cache path from a given path and cacheName.
Declaration
Swift
public typealias DiskCachePathClosure = (String?, String) -> String
-
The default DiskCachePathClosure
Declaration
Swift
public final class func defaultDiskCachePathClosure(path: String?, cacheName: String) -> String
-
Init method. Passing a name for the cache. It represents a cache folder in the memory and disk.
Declaration
Swift
public init(name: String, path: String? = nil, diskCachePathClosure: DiskCachePathClosure = ImageCache.defaultDiskCachePathClosure)
Parameters
name
Name of the cache. It will be used as the memory cache name and the disk cache folder name appending to the cache path. This value should not be an empty string.
path
Optional - Location of cache path on disk. If
nil
is passed in (the default value), the.cachesDirectory
in of your app will be used.diskCachePathClosure
Closure that takes in an optional initial path string and generates the final disk cache path. You could use it to fully customize your cache path.
Return Value
The cache object.
-
Store an image to cache. It will be saved to both memory and disk. It is an async operation.
Declaration
Swift
open func store(_ image: Image, original: Data? = nil, forKey key: String, processorIdentifier identifier: String = "", cacheSerializer serializer: CacheSerializer = DefaultCacheSerializer.default, toDisk: Bool = true, completionHandler: (() -> Void)? = nil)
Parameters
image
The image to be stored.
original
The original data of the image. Kingfisher will use it to check the format of the image and optimize cache size on disk. If
nil
is supplied, the image data will be saved as a normalized PNG file. It is strongly suggested to supply it whenever possible, to get a better performance and disk usage.key
Key for the image.
identifier
The identifier of processor used. If you are using a processor for the image, pass the identifier of processor to it. This identifier will be used to generate a corresponding key for the combination of
key
and processor.toDisk
Whether this image should be cached to disk or not. If false, the image will be only cached in memory.
completionHandler
Called when store operation completes.
-
Remove the image for key for the cache. It will be opted out from both memory and disk. It is an async operation.
Declaration
Swift
open func removeImage(forKey key: String, processorIdentifier identifier: String = "", fromMemory: Bool = true, fromDisk: Bool = true, completionHandler: (() -> Void)? = nil)
Parameters
key
Key for the image.
identifier
The identifier of processor used. If you are using a processor for the image, pass the identifier of processor to it. This identifier will be used to generate a corresponding key for the combination of
key
and processor.fromMemory
Whether this image should be removed from memory or not. If false, the image won’t be removed from memory.
fromDisk
Whether this image should be removed from disk or not. If false, the image won’t be removed from disk.
completionHandler
Called when removal operation completes.
-
Get an image for a key from memory or disk.
Declaration
Swift
open func retrieveImage(forKey key: String, options: KingfisherOptionsInfo?, completionHandler: ((Image?, CacheType) -> Void)?) -> RetrieveImageDiskTask?
Parameters
key
Key for the image.
options
Options of retrieving image. If you need to retrieve an image which was stored with a specified
ImageProcessor
, pass the processor in the option too.completionHandler
Called when getting operation completes with image result and cached type of this image. If there is no such key cached, the image will be
nil
.Return Value
The retrieving task.
-
Get an image for a key from memory.
Declaration
Swift
open func retrieveImageInMemoryCache(forKey key: String, options: KingfisherOptionsInfo? = nil) -> Image?
Parameters
key
Key for the image.
options
Options of retrieving image. If you need to retrieve an image which was stored with a specified
ImageProcessor
, pass the processor in the option too.Return Value
The image object if it is cached, or
nil
if there is no such key in the cache. -
Get an image for a key from disk.
Declaration
Swift
open func retrieveImageInDiskCache(forKey key: String, options: KingfisherOptionsInfo? = nil) -> Image?
Parameters
key
Key for the image.
options
Options of retrieving image. If you need to retrieve an image which was stored with a specified
ImageProcessor
, pass the processor in the option too.Return Value
The image object if it is cached, or
nil
if there is no such key in the cache.
-
Clear memory cache.
Declaration
Swift
@objc public func clearMemoryCache()
-
Clear disk cache. This is an async operation.
Declaration
Swift
open func clearDiskCache(completion handler: (()->())? = nil)
Parameters
completionHander
Called after the operation completes.
-
Clean expired disk cache. This is an async operation.
Declaration
Swift
open func cleanExpiredDiskCache(completion handler: (()->())? = nil)
Parameters
completionHandler
Called after the operation completes.
-
Clean expired disk cache when app in background. This is an async operation. In most cases, you should not call this method explicitly. It will be called automatically when
UIApplicationDidEnterBackgroundNotification
received.Declaration
Swift
@objc public func backgroundCleanExpiredDiskCache()
-
Cache type for checking whether an image is cached for a key in current cache.
Declaration
Swift
open func imageCachedType(forKey key: String, processorIdentifier identifier: String = "") -> CacheType
Parameters
key
Key for the image.
identifier
Processor identifier which used for this image. Default is empty string.
Return Value
A
CacheType
instance which indicates the cache status..none
means the image is not in cache yet. -
Get the hash for the key. This could be used for matching files.
Declaration
Swift
open func hash(forKey key: String, processorIdentifier identifier: String = "") -> String
Parameters
key
The key which is used for caching.
identifier
The identifier of processor used. If you are using a processor for the image, pass the identifier of processor to it.
Return Value
Corresponding hash.
-
Calculate the disk size taken by cache. It is the total allocated size of the cached files in bytes.
Declaration
Swift
open func calculateDiskCacheSize(completion handler: @escaping ((_ size: UInt) -> Void))
Parameters
completionHandler
Called with the calculated size when finishes.
-
Get the cache path for the key. It is useful for projects with UIWebView or anyone that needs access to the local file path.
i.e. Replace the
<img src='path_for_key'>
tag in your HTML.Note
This method does not guarantee there is an image already cached in the path. It just returns the path that the image should be. You could useisImageCached(forKey:)
method to check whether the image is cached under that key.Declaration
Swift
open func cachePath(forKey key: String, processorIdentifier identifier: String = "") -> String
-
Undocumented
Declaration
Swift
open class ImageCache
-
Cache result for checking whether an image is cached for a key.
See moreDeclaration
Swift
public struct CacheCheckResult
-
Check whether an image is cached for a key.
Declaration
Swift
open func isImageCached(forKey key: String, processorIdentifier identifier: String = "") -> CacheCheckResult
Parameters
key
Key for the image.
Return Value
The check result.