本文把 Foundation 框架中 NSString 的龐大 API 依功能重新分區,並標註 iOS 8 時代新增或較少被使用的介面,方便查閱與複習。
// 一個 UTF-16 代碼單元,兩字節,範圍 [0, 65535] typedef unsigned short unichar; // 提前宣告,讓編譯器知道這六個都是類名 @class NSData, NSArray, NSDictionary, NSCharacterSet, NSURL, NSError, NSLocale; // 解析字串發生異常時拋出的例外名稱 FOUNDATION_EXPORT NSString *const NSParseErrorException; // 字串長度上限 #define NSMaximumStringLength (INT_MAX-1) // 字元轉換失敗時拋出的例外 FOUNDATION_EXPORT NSString *const NSCharacterConversionException; // 編碼型別 typedef NSUInteger NSStringEncoding;
幾乎所有 compare 家族與 search 家族的方法,都靠這組位元遮罩控制比較行為,可按位或運算任意組合。
typedef NS_OPTIONS(NSUInteger, NSStringCompareOptions) {
NSCaseInsensitiveSearch = 1, // 忽略大小寫
NSLiteralSearch = 2, // 按字面精確比較
NSBackwardsSearch = 4, // 從尾端向前搜尋
NSAnchoredSearch = 8, // 只比對字串邊界(前綴或後綴)
NSNumericSearch = 64, // 依數字大小排序,如 "a2" 排在 "a10" 前
NSDiacriticInsensitiveSearch = 128, // 忽略變音符號
NSWidthInsensitiveSearch = 256, // 忽略全形半形寬度差異
NSForcedOrderingSearch = 512, // 強制忽略大小寫選項
NSRegularExpressionSearch = 1024 // 以正規表達式比對(iOS 3.2 起)
};
NSStringEncoding 枚舉涵蓋了從 ASCII 到 UTF-32 的完整光譜,日常開發絕大多數場景只需要下面幾個:
NSASCIIStringEncoding = 1, // 0..127 NSNEXTSTEPStringEncoding = 2, NSJapaneseEUCStringEncoding = 3, NSUTF8StringEncoding = 4, // 最常用 NSISOLatin1StringEncoding = 5, NSSymbolStringEncoding = 6, NSNonLossyASCIIStringEncoding = 7, NSShiftJISStringEncoding = 8, NSISOLatin2StringEncoding = 9, NSUnicodeStringEncoding = 10, // 等同 NSUTF16StringEncoding NSWindowsCP1250StringEncoding = 15, // WinLatin2 NSWindowsCP1251StringEncoding = 11, // 西里爾字母 NSWindowsCP1252StringEncoding = 12, // WinLatin1 NSWindowsCP1253StringEncoding = 13, // 希臘文 NSWindowsCP1254StringEncoding = 14, // 土耳其文 NSISO2022JPStringEncoding = 21, // 郵件用的日文編碼 NSMacOSRomanStringEncoding = 30, NSUTF16BigEndianStringEncoding = 0x90000100, NSUTF16LittleEndianStringEncoding = 0x94000100, NSUTF32StringEncoding = 0x8c000100, NSUTF32BigEndianStringEncoding = 0x98000100, NSUTF32LittleEndianStringEncoding = 0x9c000100
編碼轉換時另有兩個選項可搭配緩衝區寫入使用:
typedef NS_OPTIONS(NSUInteger, NSStringEncodingConversionOptions) {
NSStringEncodingConversionAllowLossy = 1, // 允許有損轉換
NSStringEncodingConversionExternalRepresentation = 2 // 使用外部表示法
};
@interface NSString : NSObject <NSCopying, NSMutableCopying, NSSecureCoding> @property (readonly) NSUInteger length; // 字元數 - (unichar)characterAtIndex:(NSUInteger)index; // 取指定位置的 UTF-16 單元 - (instancetype)init NS_DESIGNATED_INITIALIZER; - (instancetype)initWithCoder:(NSCoder *)aDecoder NS_DESIGNATED_INITIALIZER; @end
- (void)getCharacters:(unichar *)buffer range:(NSRange)aRange; // 取指定範圍到緩衝區 - (NSString *)substringFromIndex:(NSUInteger)from; // 從 from 取到尾端 - (NSString *)substringToIndex:(NSUInteger)to; // 從頭取到 to 之前 - (NSString *)substringWithRange:(NSRange)range; // 取任意範圍
- (NSComparisonResult)compare:(NSString *)string;
- (NSComparisonResult)compare:(NSString *)string options:(NSStringCompareOptions)mask;
- (NSComparisonResult)compare:(NSString *)string options:(NSStringCompareOptions)mask
range:(NSRange)compareRange;
- (NSComparisonResult)compare:(NSString *)string options:(NSStringCompareOptions)mask
range:(NSRange)compareRange locale:(id)locale;
- (NSComparisonResult)caseInsensitiveCompare:(NSString *)string;
- (NSComparisonResult)localizedCompare:(NSString *)string;
- (NSComparisonResult)localizedCaseInsensitiveCompare:(NSString *)string;
- (NSComparisonResult)localizedStandardCompare:(NSString *)string; // 依本地排序規則,適合檔案清單
- (BOOL)isEqualToString:(NSString *)aString;
前綴、後綴與包含判斷:
- (BOOL)hasPrefix:(NSString *)aString; - (BOOL)hasSuffix:(NSString *)aString; - (BOOL)containsString:(NSString *)aString; // iOS 8 起 - (BOOL)localizedCaseInsensitiveContainsString:(NSString *)aString; // iOS 8 起,忽略大小寫與本地化
- (NSRange)rangeOfString:(NSString *)aString;
- (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask;
- (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask
range:(NSRange)searchRange;
- (NSRange)rangeOfString:(NSString *)aString options:(NSStringCompareOptions)mask
range:(NSRange)searchRange locale:(NSLocale *)locale;
// 以字元集搜尋
- (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet;
- (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(NSStringCompareOptions)mask;
- (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(NSStringCompareOptions)mask
range:(NSRange)searchRange;
// 以「組合字元序列」(如 emoji、組合附加符號)為單位查找
- (NSRange)rangeOfComposedCharacterSequenceAtIndex:(NSUInteger)index;
- (NSRange)rangeOfComposedCharacterSequencesForRange:(NSRange)range;
若找不到結果,NSRange 的 location 會是 NSNotFound,length 為 0,這是判斷時要注意的慣例。
- (NSString *)stringByAppendingString:(NSString *)aString;
- (NSString *)stringByAppendingFormat:(NSString *)format, ...;
- (NSArray *)componentsSeparatedByString:(NSString *)separator;
- (NSArray *)componentsSeparatedByCharactersInSet:(NSCharacterSet *)separator;
- (NSString *)commonPrefixWithString:(NSString *)aString options:(NSStringCompareOptions)mask;
- (NSString *)stringByPaddingToLength:(NSUInteger)newLength
withString:(NSString *)padString
startingAtIndex:(NSUInteger)padIndex;
@property (readonly) double doubleValue; @property (readonly) float floatValue; @property (readonly) int intValue; @property (readonly) NSInteger integerValue; @property (readonly) long long longLongValue; @property (readonly) BOOL boolValue;
@property (readonly, copy) NSString *uppercaseString; // 全大寫 @property (readonly, copy) NSString *lowercaseString; // 全小寫 @property (readonly, copy) NSString *capitalizedString; // 每個單詞首字母大寫 - (NSString *)uppercaseStringWithLocale:(NSLocale *)locale; - (NSString *)lowercaseStringWithLocale:(NSLocale *)locale; - (NSString *)capitalizedStringWithLocale:(NSLocale *)locale;
土耳其文的 i/İ 問題是經典案例:不指定 locale 時大小寫轉換會出錯,涉及多語言時務必帶上 NSLocale。
// 移除指定字元集中的字元;去除前後空白與換行是最常見用法
- (NSString *)stringByTrimmingCharactersInSet:(NSCharacterSet *)set;
// 用法
NSString *result = [str stringByTrimmingCharactersInSet:
[NSCharacterSet whitespaceAndNewlineCharacterSet]];
// 依本地規則做「摺疊」,常用於忽略發音符號的搜尋比對
- (NSString *)stringByFoldingWithOptions:(NSStringCompareOptions)options
locale:(NSLocale *)locale;
- (void)getLineStart:(NSUInteger *)startPtr end:(NSUInteger *)lineEndPtr
contentsEnd:(NSUInteger *)contentsEndPtr forRange:(NSRange)range;
- (NSRange)lineRangeForRange:(NSRange)range;
- (void)getParagraphStart:(NSUInteger *)startPtr end:(NSUInteger *)parEndPtr
contentsEnd:(NSUInteger *)contentsEndPtr forRange:(NSRange)range;
- (NSRange)paragraphRangeForRange:(NSRange)range;
typedef NS_OPTIONS(NSUInteger, NSStringEnumerationOptions) {
NSStringEnumerationByLines = 0,
NSStringEnumerationByParagraphs = 1,
NSStringEnumerationByComposedCharacterSequences = 2,
NSStringEnumerationByWords = 3,
NSStringEnumerationBySentences = 4,
NSStringEnumerationReverse = 1UL << 8,
NSStringEnumerationSubstringNotRequired = 1UL << 9,
NSStringEnumerationLocalized = 1UL << 10
};
- (void)enumerateSubstringsInRange:(NSRange)range options:(NSStringEnumerationOptions)opts
usingBlock:(void (^)(NSString *substring, NSRange substringRange,
NSRange enclosingRange, BOOL *stop))block;
- (void)enumerateLinesUsingBlock:(void (^)(NSString *line, BOOL *stop))block;
@property (readonly) NSStringEncoding fastestEncoding; // 取得時最快的編碼
@property (readonly) NSStringEncoding smallestEncoding; // 佔用空間最小的編碼
- (NSData *)dataUsingEncoding:(NSStringEncoding)encoding allowLossyConversion:(BOOL)lossy;
- (NSData *)dataUsingEncoding:(NSStringEncoding)encoding;
- (BOOL)canBeConvertedToEncoding:(NSStringEncoding)encoding;
- (__strong const char *)cStringUsingEncoding:(NSStringEncoding)encoding;
- (BOOL)getCString:(char *)buffer maxLength:(NSUInteger)maxBufferCount
encoding:(NSStringEncoding)encoding;
- (BOOL)getBytes:(void *)buffer maxLength:(NSUInteger)maxBufferCount
usedLength:(NSUInteger *)usedBufferCount encoding:(NSStringEncoding)encoding
options:(NSStringEncodingConversionOptions)options range:(NSRange)range
remainingRange:(NSRangePointer)leftover;
- (NSUInteger)maximumLengthOfBytesUsingEncoding:(NSStringEncoding)enc;
- (NSUInteger)lengthOfBytesUsingEncoding:(NSStringEncoding)enc;
@property (readonly, copy) NSString *decomposedStringWithCanonicalMapping;
@property (readonly, copy) NSString *precomposedStringWithCanonicalMapping;
@property (readonly, copy) NSString *decomposedStringWithCompatibilityMapping;
@property (readonly, copy) NSString *precomposedStringWithCompatibilityMapping;
@property (readonly) __strong const char *UTF8String;
+ (NSStringEncoding)defaultCStringEncoding;
+ (const NSStringEncoding *)availableStringEncodings;
+ (NSString *)localizedNameOfStringEncoding:(NSStringEncoding)encoding;
最後四個屬性對應 Unicode 的四種正規化形式(NFD、NFC、NFKD、NFKC)。在 iOS 上處理使用者輸入或檔名比對時,先做正規化能避免大量「看起來一樣卻不相等」的疑難問題。
- (NSString *)stringByReplacingOccurrencesOfString:(NSString *)target
withString:(NSString *)replacement
options:(NSStringCompareOptions)options
range:(NSRange)searchRange;
- (NSString *)stringByReplacingOccurrencesOfString:(NSString *)target
withString:(NSString *)replacement;
- (NSString *)stringByReplacingCharactersInRange:(NSRange)range
withString:(NSString *)replacement;
// 指定初始器
- (instancetype)initWithCharactersNoCopy:(unichar *)characters length:(NSUInteger)length
freeWhenDone:(BOOL)freeBuffer;
- (instancetype)initWithCharacters:(const unichar *)characters length:(NSUInteger)length;
- (instancetype)initWithUTF8String:(const char *)nullTerminatedCString;
- (instancetype)initWithString:(NSString *)aString;
- (instancetype)initWithFormat:(NSString *)format, ...;
- (instancetype)initWithFormat:(NSString *)format arguments:(va_list)argList;
- (instancetype)initWithFormat:(NSString *)format locale:(id)locale, ...;
- (instancetype)initWithFormat:(NSString *)format locale:(id)locale arguments:(va_list)argList;
- (instancetype)initWithData:(NSData *)data encoding:(NSStringEncoding)encoding;
- (instancetype)initWithBytes:(const void *)bytes length:(NSUInteger)len
encoding:(NSStringEncoding)encoding;
- (instancetype)initWithBytesNoCopy:(void *)bytes length:(NSUInteger)len
encoding:(NSStringEncoding)encoding freeWhenDone:(BOOL)freeBuffer;
- (instancetype)initWithCString:(const char *)nullTerminatedCString
encoding:(NSStringEncoding)encoding;
// 便利構造器(autorelease 語境下不需自行管理記憶體)
+ (instancetype)string;
+ (instancetype)stringWithString:(NSString *)string;
+ (instancetype)stringWithCharacters:(const unichar *)characters length:(NSUInteger)length;
+ (instancetype)stringWithUTF8String:(const char *)nullTerminatedCString;
+ (instancetype)stringWithFormat:(NSString *)format, ...;
+ (instancetype)localizedStringWithFormat:(NSString *)format, ...;
+ (instancetype)stringWithCString:(const char *)cString encoding:(NSStringEncoding)enc;
// 已知編碼
- (instancetype)initWithContentsOfURL:(NSURL *)url encoding:(NSStringEncoding)enc
error:(NSError **)error;
- (instancetype)initWithContentsOfFile:(NSString *)path encoding:(NSStringEncoding)enc
error:(NSError **)error;
+ (instancetype)stringWithContentsOfURL:(NSURL *)url encoding:(NSStringEncoding)enc
error:(NSError **)error;
+ (instancetype)stringWithContentsOfFile:(NSString *)path encoding:(NSStringEncoding)enc
error:(NSError **)error;
// 編碼未知,由系統自動偵測
- (instancetype)initWithContentsOfURL:(NSURL *)url usedEncoding:(NSStringEncoding *)enc
error:(NSError **)error;
- (instancetype)initWithContentsOfFile:(NSString *)path usedEncoding:(NSStringEncoding *)enc
error:(NSError **)error;
+ (instancetype)stringWithContentsOfURL:(NSURL *)url usedEncoding:(NSStringEncoding *)enc
error:(NSError **)error;
+ (instancetype)stringWithContentsOfFile:(NSString *)path usedEncoding:(NSStringEncoding *)enc
error:(NSError **)error;
// 寫入
- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)useAuxiliaryFile
encoding:(NSStringEncoding)enc error:(NSError **)error;
- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile
encoding:(NSStringEncoding)enc error:(NSError **)error;
+ (NSStringEncoding)stringEncodingForData:(NSData *)data
encodingOptions:(NSDictionary *)opts
convertedString:(NSString **)string
usedLossyConversion:(BOOL *)usedLossyConversion;
可搭配的字典鍵包含:
NSStringEncodingDetectionSuggestedEncodingsKey // 建議的編碼候選清單 NSStringEncodingDetectionDisallowedEncodingsKey // 排除的編碼 NSStringEncodingDetectionUseOnlySuggestedEncodingsKey NSStringEncodingDetectionAllowLossyKey NSStringEncodingDetectionFromWindowsKey NSStringEncodingDetectionLossySubstitutionKey NSStringEncodingDetectionLikelyLanguageKey
- (id)propertyList;
- (NSDictionary *)propertyListFromStringsFileFormat;
// 範例
NSString *str = [NSString stringWithFormat:@"Name = xulin ; age = 23;"];
NSLog(@"%@", [str propertyListFromStringFileFormat]);
// 輸出:{ Name = xulin ; age = 23; }
@interface NSMutableString : NSString
- (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)aString;
@end
@interface NSMutableString (NSMutableStringExtensionMethods)
- (void)insertString:(NSString *)aString atIndex:(NSUInteger)loc;
- (void)deleteCharactersInRange:(NSRange)range;
- (void)appendString:(NSString *)aString;
- (void)appendFormat:(NSString *)format, ...;
- (void)setString:(NSString *)aString;
- (NSMutableString *)initWithCapacity:(NSUInteger)capacity;
+ (NSMutableString *)stringWithCapacity:(NSUInteger)capacity;
- (NSUInteger)replaceOccurrencesOfString:(NSString *)target withString:(NSString *)replacement
options:(NSStringCompareOptions)options range:(NSRange)searchRange;
@end
capacity 只是預配置容量,屬於記憶體優化提示,實際長度仍可超出,不必擔心溢位。
以下方法在現代 Objective-C 開發中不應再使用,遇到舊專案時建議逐步替換:
- (const char *)cString; - (const char *)lossyCString; - (NSUInteger)cStringLength; - (void)getCString:(char *)bytes; - (void)getCString:(char *)bytes maxLength:(NSUInteger)maxLength; - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile; - (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically; - (id)initWithContentsOfFile:(NSString *)path; - (id)initWithContentsOfURL:(NSURL *)url; + (id)stringWithContentsOfFile:(NSString *)path; + (id)stringWithContentsOfURL:(NSURL *)url; - (id)initWithCString:(const char *)bytes length:(NSUInteger)length; + (id)stringWithCString:(const char *)bytes length:(NSUInteger)length;
另外還有 NSSimpleCString 與 NSConstantString 兩個內部實作類別,編譯器產生的常數字串即屬於後者,一般開發不需直接理會。
掌握以上分類,日常 90% 的字串處理都能快速定位到對應 API。真正需要背誦的其實只有幾個:substringWithRange:、componentsSeparatedByString:、stringByAppendingFormat:、rangeOfString: 與 dataUsingEncoding:。