Merge pull request #646 from onevcat/fix/resizing-refactor

Deprecate unclear methods and update docs

Sources/ImageProcessor.swift

@@ -183,7 +183,7 @@ public struct RoundCornerImageProcessor: ImageProcessor {
 }
 
 
-/// Specify how a size adjusts itself to fit a target.
+/// Specify how a size adjusts itself to fit a target size.
 ///
 /// - none: Not scale the content.
 /// - aspectFit: Scale the content to fit the size of the view by maintaining the aspect ratio.
@@ -201,25 +201,40 @@ public struct ResizingImageProcessor: ImageProcessor {
     /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier: String
 
-    /// Target size of output image should be.
-    public let targetSize: CGSize
+    /// The reference size for resizing operation.
+    public let referenceSize: CGSize
 
     /// Target content mode of output image should be.
     /// Default to ContentMode.none
     public let targetContentMode: ContentMode
 
-    /// Initialize a `ResizingImageProcessor`
+    /// Initialize a `ResizingImageProcessor`.
     ///
-    /// - parameter targetSize: Target size of output image should be.
-    /// - parameter contentMode: Target content mode of output image should be.
-    public init(targetSize: CGSize, contentMode: ContentMode = .none) {
-        self.targetSize = targetSize
-        self.targetContentMode = contentMode
+    /// - Parameters:
+    ///   - referenceSize: The reference size for resizing operation.
+    ///   - mode: Target content mode of output image should be.
+    ///
+    /// - Note:
+    ///   The instance of `ResizingImageProcessor` will follow its `mode` property
+    ///   and try to resizing the input images to fit or fill the `referenceSize`.
+    ///   That means if you are using a `mode` besides of `.none`, you may get an
+    ///   image with its size not be the same as the `referenceSize`.
+    ///
+    ///   **Example**: With input image size: {100, 200}, 
+    ///   `referenceSize`: {100, 100}, `mode`: `.aspectFit`,
+    ///   you will get an output image with size of {50, 100}, which "fit"s
+    ///   the `referenceSize`.
+    ///
+    ///   If you need an output image exactly to be a specified size, append or use
+    ///   a `CroppingImageProcessor`.
+    public init(referenceSize: CGSize, mode: ContentMode = .none) {
+        self.referenceSize = referenceSize
+        self.targetContentMode = mode
 
-        if contentMode == .none {
-            self.identifier = "com.onevcat.Kingfisher.ResizingImageProcessor(\(targetSize))"
+        if mode == .none {
+            self.identifier = "com.onevcat.Kingfisher.ResizingImageProcessor(\(referenceSize))"
         } else {
-            self.identifier = "com.onevcat.Kingfisher.ResizingImageProcessor(\(targetSize), \(contentMode))"
+            self.identifier = "com.onevcat.Kingfisher.ResizingImageProcessor(\(referenceSize), \(mode))"
         }
     }
 
@@ -234,7 +249,7 @@ public struct ResizingImageProcessor: ImageProcessor {
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
-            return image.kf.resize(to: targetSize, for: targetContentMode)
+            return image.kf.resize(to: referenceSize, for: targetContentMode)
         case .data(_):
             return (DefaultImageProcessor.default >> self).process(item: item, options: options)
         }
@@ -522,3 +537,25 @@ fileprivate extension Color {
         return String(format:"#%08x", rgba)
     }
 }
+
+// MARK: - Deprecated
+extension ResizingImageProcessor {
+    /// Reference size of output image should follow.
+    @available(*, deprecated,
+    message: "targetSize are renamed. Use `referenceSize` instead",
+    renamed: "referenceSize")
+    public var targetSize: CGSize {
+        return referenceSize
+    }
+
+    /// Initialize a `ResizingImageProcessor`
+    ///
+    /// - parameter targetSize: Reference size of output image should follow.
+    /// - parameter contentMode: Target content mode of output image should be.
+    @available(*, deprecated,
+    message: "targetSize and contentMode are renamed. Use `init(referenceSize:mode:)` instead",
+    renamed: "init(referenceSize:mode:)")
+    public init(targetSize: CGSize, contentMode: ContentMode = .none) {
+        self.init(referenceSize: targetSize, mode: contentMode)
+    }
+}

Tests/KingfisherTests/ImageProcessorTests.swift

@@ -68,17 +68,17 @@ class ImageProcessorTests: XCTestCase {
     }
 
     func testResizingProcessor() {
-        let p = ResizingImageProcessor(targetSize: CGSize(width: 120, height: 120))
+        let p = ResizingImageProcessor(referenceSize: CGSize(width: 120, height: 120))
         XCTAssertEqual(p.identifier, "com.onevcat.Kingfisher.ResizingImageProcessor((120.0, 120.0))")
         checkProcessor(p, with: "resize-120")
     }
 
     func testResizingProcessorWithContentMode() {
-        let p1 = ResizingImageProcessor(targetSize: CGSize(width: 240, height: 60), contentMode: .aspectFill)
+        let p1 = ResizingImageProcessor(referenceSize: CGSize(width: 240, height: 60), mode: .aspectFill)
         XCTAssertEqual(p1.identifier, "com.onevcat.Kingfisher.ResizingImageProcessor((240.0, 60.0), aspectFill)")
         checkProcessor(p1, with: "resize-240-60-aspectFill")
 
-        let p2 = ResizingImageProcessor(targetSize: CGSize(width: 240, height: 60), contentMode: .aspectFit)
+        let p2 = ResizingImageProcessor(referenceSize: CGSize(width: 240, height: 60), mode: .aspectFit)
         XCTAssertEqual(p2.identifier, "com.onevcat.Kingfisher.ResizingImageProcessor((240.0, 60.0), aspectFit)")
         checkProcessor(p2, with: "resize-240-60-aspectFit")
     }