First beta of SDWebImage 3.0

This version is a rewrite of the lib using iOS 5.0 as minimum target.
The lib as thus been refactored to use blocks/GCD from the ground up.
As a consequence, all delegate code style has been removed. The result
is a lot less lines of code and more flexibility.

Author: Olivier Poitrey

README.md

@@ -1,3 +1,4 @@
+
 Web Image
 =========
 
@@ -8,9 +9,15 @@ It provides:
 - An UIImageView category adding web image and cache management to the Cocoa Touch framework
 - An asynchronous image downloader
 - An asynchronous memory + disk image caching with automatic cache expiration handling
+- A background image decompression
 - A guarantee that the same URL won't be downloaded several times
 - A guarantee that bogus URLs won't be retried again and again
+- A guarantee that main thread will never be blocked
 - Performances!
+- Use GCD and ARC
+
+NOTE: The version 3.0 of SDWebImage isn't fully backward compatible with 1.0 and requires iOS 5.0
+minimum. If you need iOS < 5.0 support, please use the last 2.0 version.
 
 Motivation
 ----------
@@ -94,15 +101,14 @@ handled for you, from async downloads to caching management.
 
 ### Using blocks
 
-If your project's deployement target is set to iOS 4+, you may want to use the success/failure blocks to be
-notified when image have been retrieved from cache.
+With blocks, you can be notified about the image download progress and whenever the image retrival
+has completed with success or not:
+
 ```objective-c
 // Here we use the new provided setImageWithURL: method to load the web image
 [cell.imageView setImageWithURL:[NSURL URLWithString:@"http://www.domain.com/path/to/image.jpg"]
                placeholderImage:[UIImage imageNamed:@"placeholder.png"]
-                        success:^(UIImage *image, BOOL cached) {... success code here ...}
-                        failure:^(NSError *error) {... failure code here ...}];
-];
+                      completed:^(UIImage *image, NSError *error, BOOL fromCache) {... completion code here ...}];
 ```
 
 Note: neither your success nor failure block will be call if your image request is canceled before completion.
@@ -118,29 +124,43 @@ Here is a simple example of how to use SDWebImageManager:
 ```objective-c
 SDWebImageManager *manager = [SDWebImageManager sharedManager];
 [manager downloadWithURL:imageURL
-                delegate:self
                  options:0
-                 success:^(UIImage *image, BOOL cached)
+                 progress:^(NSUInteger receivedSize, long long expectedSize)
                  {
-                     // do something with image
+                     // progression tracking code
                  }
-                 failure:nil];
+                 completed:^(UIImage *image, NSError *error, BOOL fromCache)
+                 {
+                     if (image)
+                     {
+                         // do something with image
+                     }
+                 }];
 ```
 
 ### Using Asynchronous Image Downloader Independently
 
-It is possible to use the async image downloader independently. You just have to create an instance
-of SDWebImageDownloader using its convenience constructor downloaderWithURL:delegate:.
+It's also possible to use the async image downloader independently:
+
 ```objective-c
-downloader = [SDWebImageDownloader downloaderWithURL:url delegate:self];
+[SDWebImageDownloader.sharedDownloader downloadImageWithURL:imageURL
+                                                    options:0
+                                                   progress:^(NSUInteger receivedSize, long long expectedSize)
+                                                   {
+                                                       // progression tracking code
+                                                   }
+                                                   completed:^(UIImage *image, NSError *error, BOOL finished)
+                                                   {
+                                                       if (image && finished)
+                                                       {
+                                                           // do something with image
+                                                       }
+                                                   }];
 ```
 
-The download will start immediately and the imageDownloader:didFinishWithImage: method from the
-SDWebImageDownloaderDelegate protocol will be called as soon as the download of image is completed.
-
 ### Using Asynchronous Image Caching Independently
 
-It is also possible to use the NSOperation based image cache store independently. SDImageCache
+It is also possible to use the aync based image cache store independently. SDImageCache
 maintains a memory cache and an optional disk cache. Disk cache write operations are performed
 asynchronous so it doesn't add unnecessary latency to the UI.
 
@@ -153,7 +173,11 @@ key is an application unique identifier for the image to cache. It is generally
 the image.
 
 ```objective-c
-UIImage *myCachedImage = [[SDImageCache sharedImageCache] imageFromKey:myCacheKey];
+SDImageCache *imageCache = [SDImageCache.alloc initWithNamespace:@"myNamespace"];
+[imageCache queryDiskCacheForKey:myCacheKey done:^(UIImage *image)
+{
+    // image is not nil if image was found
+}];
 ```
 
 By default SDImageCache will lookup the disk cache if an image can't be found in the memory cache.
@@ -182,11 +206,11 @@ the URL before to use it as a cache key:
 ```objective-c
 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
 {
-    [[SDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url)
+    SDWebImageManager.sharedManager.cacheKeyFilter:^(NSURL *url)
     {
         url = [[[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path] autorelease];
         return [url absoluteString];
-    }];
+    };
 
     // Your app init code...
     return YES;
@@ -205,12 +229,6 @@ The following article gives a way to workaround this issue:
 
 [http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/](http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/)
 
-Automatic Reference Counting (ARC)
-----------------------------------
-
-You can use either style in your Cocoa project. SDWebImage Will figure out which you are using at compile
-time and do the right thing.
-
 
 Installation
 ------------