您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 訊息 >> iOS 相關資訊

NSData API 完整整理:位元組操作、檔案讀寫與 Base64 編解碼

編輯:iOS 相關資訊

搜尋 NSData 的資料時,網路上幾乎都是沒有註解的純代碼拷貝,這讓整理 API 文件變得格外吃力。既然現成資料不足,索性自己把這份介面整理出來,補上說明,也省下其他人摸索的時間。

一、Base64 是什麼

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 被終止,原檔案也不會只剩一半內容。

四、不可變 NSData 的核心成員

@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

五、建立 NSData 的方式

@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 在生命週期結束時執行任意清理邏輯。

六、四個 Base64 API 的選擇邏輯

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

七、可變 NSMutableData

@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

最後一個值得知道的類別是 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 依目標載體選擇字串版或位元組版。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved