SBSDKImageStorage


@interface SBSDKImageStorage : NSObject

A thread-safe mutable ordered collection of disk-backed UIImage objects. When it comes to image processing with large images it is impossible to hold all the of a collection images in memory. The images have to be backed on disk and reloaded from the file when demanded. This class is a simple wrapper around the described technique. You can add/remove images from the storage, access the storage via an index and retrieve images or image URLs. There is also support for (automatically) creating and caching thumbnails from the storages images. Conforms to NSCopying. When copying the disk-backing-storage is also copied to a different physical location. Accessing the storage and changing properties is implemented with thread-safety using a single-writer/multiple-reader pattern.

The deallocation of this object removes all images from disk.

Deprecated! Use SBSDKIndexedImageStorage instead!

  • The number of images contained in the receiver.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger imageCount;

    Swift

    var imageCount: UInt { get }
  • An array of file URLs of all images the receiver holds.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nonnull) NSArray<NSURL *> *imageURLs;

    Swift

    var imageURLs: [URL] { get }
  • Enables or disables the automatic thumbnail creation. Disabled by default.

    Declaration

    Objective-C

    @property (getter=isAutomaticThumbnailCreationEnabled, assign, readwrite, atomic)
        BOOL enableAutomaticThumbnailCreation;

    Swift

    var isAutomaticThumbnailCreationEnabled: Bool { get set }
  • The size of the thumbnails generated by the automatic thumbnail creation. Defaults to the size of the main screen.

    Declaration

    Objective-C

    @property (assign, readwrite, atomic) CGSize automaticThumbnailSize;

    Swift

    var automaticThumbnailSize: CGSize { get set }
  • The JPEG compression quality factor of the stored images. Ranges from 0.0 (small files, bad quality) to 1.0 (huge files, great quality). Defaults to 0.9.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat imageQuality;

    Swift

    var imageQuality: CGFloat { get set }
  • Returns the URL of the applications ‘Documents’ folder.

    Declaration

    Objective-C

    + (nonnull NSURL *)applicationDocumentsFolderURL;

    Swift

    class func applicationDocumentsFolderURL() -> URL
  • Returns the URL of the applications support folder.

    Declaration

    Objective-C

    + (nonnull NSURL *)applicationSupportFolderURL;

    Swift

    class func applicationSupportFolderURL() -> URL
  • Convenience initializer. Creates a temporary image storage at a temporary folder.

    Declaration

    Objective-C

    + (nonnull instancetype)temporaryStorageWithImages:
        (nonnull NSArray<UIImage *> *)images;

    Swift

    class func temporaryStorage(with images: [UIImage]) -> Self

    Parameters

    images

    An array of UIImage objects that should be added to the newly create instance image storage. Can be nil or empty.

    Return Value

    Initialized image storage.

  • Designated initializer. Creates an image storage in the folder specified by folderURL.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithFolderURL:(nullable NSURL *)folderURL;

    Swift

    init(folderURL: URL?)

    Parameters

    folderURL

    An NSURL describing the location of the image storage folder on the disk, if it’s nil temp path will be used

    Return Value

    Initialized image storage.

  • Appends a single UIImage to the receiver.

    Declaration

    Objective-C

    - (BOOL)addImage:(nullable UIImage *)image;

    Swift

    func add(_ image: UIImage?) -> Bool

    Parameters

    image

    The UIImage object to be added.

    Return Value

    YES if the operation was successful, NO otherwise.

  • Appends a single image from the URL to the receiver.

    Declaration

    Objective-C

    - (BOOL)addImageFromURL:(nullable NSURL *)url;

    Swift

    func addImage(from url: URL?) -> Bool

    Parameters

    url

    The URL to the image to be added.

    Return Value

    YES if the operation was successful, NO otherwise.

  • Removes the image at the given index from the receiver and deletes the image file.

    Declaration

    Objective-C

    - (void)removeImageAtIndex:(NSUInteger)index;

    Swift

    func removeImage(at index: UInt)

    Parameters

    index

    The index of the image to be deleted from the receiver. Does nothing if the index is not valid.

  • Loads the UIImage at the given index from the receiver and returns it.

    Declaration

    Objective-C

    - (nullable UIImage *)imageAtIndex:(NSUInteger)index;

    Swift

    func image(at index: UInt) -> UIImage?

    Parameters

    index

    The index of the image to be loaded from the receiver.

    Return Value

    The loaded image or nil if the index was not valid.

  • Returns the images file URL at the given index. Use with caution: if the receiver is deallocated the URL will be invalid.

    Declaration

    Objective-C

    - (nullable NSURL *)imageURLAtIndex:(NSUInteger)index;

    Swift

    func imageURL(at index: UInt) -> URL?

    Parameters

    index

    The index of the image in the receiver.

    Return Value

    The file URL the image is physically located at. Or nil if index is invalid.

  • Empties the receiver by removing all images from it, including the image files.

    Declaration

    Objective-C

    - (void)removeAllImages;

    Swift

    func removeAllImages()
  • Generates a thumbnail of the image at the specified index with given size. The thumbnail is cached.

    Declaration

    Objective-C

    - (nullable UIImage *)thumbnailForImageAtIndex:(NSUInteger)index
                                            ofSize:(CGSize)size;

    Swift

    func thumbnailForImage(at index: UInt, of size: CGSize) -> UIImage?

    Parameters

    index

    The index of the image in the receiver.

    size

    The size of the thumbnail. If size has a different aspect ratio than the image the thumbnail is fitted-in the requested size.

    Return Value

    An UIImage object representing the thumbnail.

  • Loads the UIImage at the given key from the receiver and returns it.

    Declaration

    Objective-C

    - (nullable UIImage *)imageForKey:(nonnull NSString *)key;

    Swift

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

    Parameters

    key

    The dictionary key of the image to be loaded from the receiver.

    Return Value

    The loaded image or nil if for the key no image is available.

  • Adds an UIImage to the receiver.

    Declaration

    Objective-C

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

    Swift

    func setImage(_ image: UIImage?, forKey key: String)

    Parameters

    image

    The UIImage object to be added. Passing nil removes the existing image for the given key.

    key

    The dictionary key of the image to be added to the receiver.

  • Sets a single image from the URL to the receiver.

    Declaration

    Objective-C

    - (void)setImageFromURL:(nullable NSURL *)url
                     forKey:(nonnull NSString *)key
                   moveFile:(BOOL)move;

    Swift

    func setImageFrom(_ url: URL?, forKey key: String, moveFile move: Bool)

    Parameters

    url

    The URL to the image to be added.

    key

    The dictionary key of the image to be added to the receiver.

    move

    If YES, the file is moved from the source location, otherwise copied.

  • Returns the images file URL at the given key. Use with caution: if the receiver is deallocated the URL will be invalid.

    Declaration

    Objective-C

    - (nullable NSURL *)imageURLForKey:(nonnull NSString *)key;

    Swift

    func imageURL(forKey key: String) -> URL?

    Parameters

    key

    The key of the image in the receivers image dictionary.

    Return Value

    The file URL the image is physically located at. Or nil if index is invalid.

  • Generates a thumbnail of the image at the specified key with given size. The thumbnail is cached.

    Declaration

    Objective-C

    - (nullable UIImage *)thumbnailOfImageForKey:(nonnull NSString *)key
                                          ofSize:(CGSize)size;

    Swift

    func thumbnailOfImage(forKey key: String, of size: CGSize) -> UIImage?

    Parameters

    key

    The key of the image in the receivers image dictionary.

    size

    The size of the thumbnail. If size has a different aspect ratio than the image the thumbnail is fitted-in the requested size.

    Return Value

    An UIImage object representing the thumbnail or nil if no image is present for the given key.

  • Removes the image at the given key from the receiver and deletes the image file.

    Declaration

    Objective-C

    - (void)removeImageForKey:(nonnull NSString *)key;

    Swift

    func removeImage(forKey key: String)

    Parameters

    key

    The key of the image in the receivers image dictionary.

  • Waits, until all changes to written to disk.

    Declaration

    Objective-C

    - (void)waitUntilWritingCompleted;

    Swift

    func waitUntilWritingCompleted()
  • Takes an NSIndexSet of indices into the receiver and returns a validated NSIndexSet by removing all invalid indices.

    Declaration

    Objective-C

    - (nonnull NSIndexSet *)validatedIndexSetForIndexSet:
        (nonnull NSIndexSet *)indexSet;

    Swift

    func validatedIndexSet(for indexSet: IndexSet) -> IndexSet

    Parameters

    indexSet

    The NSIndexSet to validate. If nil or empty all valid indices are added to the result.

    Return Value

    The validated index set.