搜尋 NSData 的資料時,網路上幾乎都是沒有註解的純代碼拷貝,這讓整理 API 文件變得格外吃力。既然現成資料不足,索性自己把這份介面整理出來,補上說明,也省下其他人摸索的時間。
Base64 是一組把二進位資料轉為文字表示的編碼方案,以 ASCII 字元呈現任意二進位內容。它的用途是讓多媒體或二進位檔案能以純文字形式儲存與傳輸,同時保證資料在傳輸過程中的完整性。最常見的應用場景是電子郵件附件編碼,或是把小型圖片內嵌進程式碼與 JSON。
在 iOS 7 之前,Base64 編解碼必須自行實作或引入第三方庫;從 iOS 7 開始,蘋果提供了原生 API。
typedef NS_OPTIONS(NSUInteger, NSDataBase64EncodingOptions) {
NSDataBase64Encoding64CharacterLineLength = 1UL << 0, // 每 64 字元換行
NSDataBase64Encoding76CharacterLineLength = 1UL << 1, // 每 76 字元換行
NSDataBase64EncodingEndLineWithCarriageReturn = 1UL << 4,
NSDataBase64EncodingEndLineWithLineFeed = 1UL << 5,
} NS_ENUM_AVAILABLE(10_9, 7_0);
typedef NS_OPTIONS(NSUInteger, NSDataBase64DecodingOptions) {
NSDataBase64DecodingIgnoreUnknownCharacters = 1UL << 0 // 解碼時忽略無法識別的位元組
} NS_ENUM_AVAILABLE(10_9, 7_0);
typedef NS_OPTIONS(NSUInteger, NSDataReadingOptions) {
NSDataReadingMappedIfSafe = 1UL << 0, // 檔案夠大時用記憶體映射,較安全
NSDataReadingUncached = 1UL << 1, // 跳過系統快取
NSDataReadingMappedAlways = 1UL << 3,
NSDataReadingMapped = NSDataReadingMappedIfSafe,
NSMappedRead = NSDataReadingMapped,
NSUncachedRead = NSDataReadingUncached
};
typedef NS_OPTIONS(NSUInteger, NSDataWritingOptions) {
NSDataWritingAtomic = 1UL << 0, // 先寫暫存檔再置換,避免寫入中斷造成檔案損毀
NSDataWritingWithoutOverwriting = 1UL << 1,
NSDataWritingFileProtectionNone = 0x10000000,
NSDataWritingFileProtectionComplete = 0x20000000,
NSDataWritingFileProtectionCompleteUnlessOpen = 0x30000000,
NSDataWritingFileProtectionCompleteUntilFirstUserAuthentication = 0x40000000,
NSDataWritingFileProtectionMask = 0xf0000000,
NSAtomicWrite = NSDataWritingAtomic
};
typedef NS_OPTIONS(NSUInteger, NSDataSearchOptions) {
NSDataSearchBackwards = 1UL << 0, // 從尾端向前搜尋
NSDataSearchAnchored = 1UL << 1 // 只比對起始位置
};
NSDataWritingAtomic 是最值得養成習慣的選項。它確保寫入過程具原子性,即使中途斷電或 App 被終止,原檔案也不會只剩一半內容。
@interface NSData : NSObject <NSCopying, NSMutableCopying, NSSecureCoding>
@property (readonly) NSUInteger length; // 位元組數
@property (readonly) const void *bytes; // 首個位元組的指標
@end
@interface NSData (NSExtendedData)
@property (readonly, copy) NSString *description; // ASCII 格式的說明字串
- (void)getBytes:(void *)buffer length:(NSUInteger)length;
- (void)getBytes:(void *)buffer range:(NSRange)range;
- (BOOL)isEqualToData:(NSData *)other;
- (NSData *)subdataWithRange:(NSRange)range;
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;
- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically;
- (BOOL)writeToFile:(NSString *)path options:(NSDataWritingOptions)writeOptionsMask
error:(NSError **)errorPtr;
- (BOOL)writeToURL:(NSURL *)url options:(NSDataWritingOptions)writeOptionsMask
error:(NSError **)errorPtr;
- (NSRange)rangeOfData:(NSData *)dataToFind options:(NSDataSearchOptions)mask
range:(NSRange)searchRange NS_AVAILABLE(10_6, 4_0);
- (void)enumerateByteRangesUsingBlock:(void (^)(const void *bytes, NSRange byteRange,
BOOL *stop))block NS_AVAILABLE(10_9, 7_0);
@end
@interface NSData (NSDataCreation)
+ (instancetype)data;
+ (instancetype)dataWithBytes:(const void *)bytes length:(NSUInteger)length;
// 不複製資料,只保存指標。使用時必須確保 bytes 在 NSData 存活期間持續有效
+ (instancetype)dataWithBytesNoCopy:(void *)bytes length:(NSUInteger)length;
// freeWhenDone 為 YES 時,NSData 成為 bytes 的所有者,釋放時一併釋放
// 因此 bytes 必須是以 malloc 配置在堆上的記憶體
// 為 NO 時 bytes 不會被釋放,需自行掌握釋放時機,切勿在物件仍在使用時提前釋放
+ (instancetype)dataWithBytesNoCopy:(void *)bytes length:(NSUInteger)length
freeWhenDone:(BOOL)b;
+ (instancetype)dataWithContentsOfFile:(NSString *)path
options:(NSDataReadingOptions)readOptionsMask
error:(NSError **)errorPtr;
+ (instancetype)dataWithContentsOfURL:(NSURL *)url
options:(NSDataReadingOptions)readOptionsMask
error:(NSError **)errorPtr;
+ (instancetype)dataWithContentsOfFile:(NSString *)path;
+ (instancetype)dataWithContentsOfURL:(NSURL *)url;
+ (instancetype)dataWithData:(NSData *)data;
- (instancetype)initWithBytes:(const void *)bytes length:(NSUInteger)length;
- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length;
- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length
freeWhenDone:(BOOL)b;
- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)length
deallocator:(void (^)(void *bytes, NSUInteger length))deallocator
NS_AVAILABLE(10_9, 7_0);
- (instancetype)initWithContentsOfFile:(NSString *)path
options:(NSDataReadingOptions)readOptionsMask
error:(NSError **)errorPtr;
- (instancetype)initWithContentsOfURL:(NSURL *)url
options:(NSDataReadingOptions)readOptionsMask
error:(NSError **)errorPtr;
- (instancetype)initWithContentsOfFile:(NSString *)path;
- (instancetype)initWithContentsOfURL:(NSURL *)url;
- (instancetype)initWithData:(NSData *)data;
@end
deallocator 版本是最靈活的選擇:你可以傳入自訂的釋放區塊,讓 NSData 在生命週期結束時執行任意清理邏輯。
iOS 7 之後蘋果提供四個方法,前兩個處理字串,後兩個處理 UTF-8 編碼的位元組資料。兩組功能等價,但效率場景不同:
若要把 Base64 結果寫入檔案,用位元組版本;若要把 Base64 結果放進 JSON,用字串版本。
@interface NSData (NSDataBase64Encoding)
// 解碼:Base64 字串 → NSData
- (instancetype)initWithBase64EncodedString:(NSString *)base64String
options:(NSDataBase64DecodingOptions)options;
// 編碼:NSData → Base64 字串
- (NSString *)base64EncodedStringWithOptions:(NSDataBase64EncodingOptions)options;
// 解碼:Base64 NSData → NSData
- (instancetype)initWithBase64EncodedData:(NSData *)base64Data
options:(NSDataBase64DecodingOptions)options;
// 編碼:NSData → Base64 NSData
- (NSData *)base64EncodedDataWithOptions:(NSDataBase64EncodingOptions)options;
@end
完整範例:
NSString *stringExample = [NSString stringWithFormat:@"I Love You"];
NSData *data1 = [stringExample dataUsingEncoding:NSUTF8StringEncoding];
NSString *base64String = [data1 base64EncodedStringWithOptions:
NSDataBase64EncodingEndLineWithCarriageReturn];
NSLog(@"Base64-encoded string is %@", base64String);
// 輸出:SSBMb3ZlIFlvdQ==
NSData *dataFromString = [[NSData alloc]
initWithBase64EncodedString:base64String
options:NSDataBase64DecodingIgnoreUnknownCharacters];
NSLog(@"string is %@", [NSString stringWithUTF8String:[dataFromString bytes]]);
// 輸出:I Love You
@interface NSMutableData : NSData
@property (readonly) void *mutableBytes; // 可寫入的位元組指標
@property NSUInteger length; // 可變長度
@end
@interface NSMutableData (NSExtendedMutableData)
- (void)appendBytes:(const void *)bytes length:(NSUInteger)length;
- (void)appendData:(NSData *)other;
- (void)increaseLengthBy:(NSUInteger)extraLength;
- (void)replaceBytesInRange:(NSRange)range withBytes:(const void *)bytes;
- (void)resetBytesInRange:(NSRange)range; // 指定範圍歸零
- (void)setData:(NSData *)data;
- (void)replaceBytesInRange:(NSRange)range withBytes:(const void *)replacementBytes
length:(NSUInteger)replacementLength;
@end
@interface NSMutableData (NSMutableDataCreation)
+ (instancetype)dataWithCapacity:(NSUInteger)aNumItems;
+ (instancetype)dataWithLength:(NSUInteger)length;
- (instancetype)initWithCapacity:(NSUInteger)capacity;
- (instancetype)initWithLength:(NSUInteger)length;
@end
容量示範:
NSMutableData *data = [NSMutableData data]; [data increaseLengthBy:5]; NSLog(@"dataLength———%lu", (unsigned long)data.length);
最後一個值得知道的類別是 NSPurgeableData,它遵循 NSDiscardableContent 協議:
NS_CLASS_AVAILABLE(10_6, 4_0) @interface NSPurgeableData : NSMutableData <NSDiscardableContent> @end
當系統記憶體吃緊時,這類資料可以被自動清除,適合存放可隨時重建的快取內容,例如圖片解碼後的暫存結果。
- (void)getBytes:(void *)buffer; // 不安全,可能緩衝區溢位,請改用 getBytes:length: + (id)dataWithContentsOfMappedFile:(NSString *)path; - (id)initWithContentsOfMappedFile:(NSString *)path; - (id)initWithBase64Encoding:(NSString *)base64String; - (NSString *)base64Encoding;
以上兩點是整理這份 API 時最想強調的實務結論:讀寫檔案一律帶上 options 與 error,Base64 依目標載體選擇字串版或位元組版。