iOS Developer Library

Developer

Foundation Framework Reference NSMutableString Class Reference

Options
Deployment Target:

On This Page
Language:

NSMutableString

The NSMutableString class declares the programmatic interface to an object that manages a mutable string—that is, a string whose contents can be edited—that conceptually represents an array of Unicode characters. To construct and manage an immutable string—or a string that cannot be changed after it has been created—use an object of the NSString class.

The NSMutableString class adds one primitive method—replaceCharactersInRange:withString:—to the basic string-handling behavior inherited from NSString. All other methods that modify a string work through this method. For example, insertString:atIndex: simply replaces the characters in a range of 0 length, while deleteCharactersInRange: replaces the characters in a given range with no characters.

NSMutableString is “toll-free bridged” with its Core Foundation counterpart, CFMutableStringRef. See Toll-Free Bridging for more information.

  • Returns an empty NSMutableString object with initial storage for a given number of characters.

    Declaration

    Objective-C

    + (NSMutableString *)stringWithCapacity:(NSUInteger)capacity

    Parameters

    capacity

    The number of characters the string is expected to initially contain.

    Return Value

    An empty NSMutableString object with initial storage for capacity characters.

    Discussion

    The number of characters indicated by capacity is simply a hint to increase the efficiency of data storage. The value does not limit the length of the string.

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSMutableString object initialized with initial storage for a given number of characters,

    Declaration

    Swift

    init(capacity capacity: Int)

    Objective-C

    - (NSMutableString *)initWithCapacity:(NSUInteger)capacity

    Parameters

    capacity

    The number of characters the string is expected to initially contain.

    Return Value

    An initialized NSMutableString object with initial storage for capacity characters. The returned object might be different than the original receiver.

    Discussion

    The number of characters indicated by capacity is simply a hint to increase the efficiency of data storage. The value does not limit the length of the string.

    Availability

    Available in iOS 2.0 and later.

  • Adds a constructed string to the receiver.

    Declaration

    Objective-C

    - (void)appendFormat:(NSString *)format, ...

    Parameters

    format

    A format string. See Formatting String Objects for more information. This value must not be nil.

    ...

    A comma-separated list of arguments to substitute into format.

    Availability

    Available in iOS 2.0 and later.

  • Adds to the end of the receiver the characters of a given string.

    Declaration

    Swift

    func appendString(_ aString: String)

    Objective-C

    - (void)appendString:(NSString *)aString

    Parameters

    aString

    The string to append to the receiver. aString must not be nil

    Availability

    Available in iOS 2.0 and later.

  • Transliterates the receiver by applying a specified ICU string transform.

    Declaration

    Swift

    func applyTransform(_ transform: String, reverse reverse: Bool, range range: NSRange, updatedRange resultingRange: NSRangePointer) -> Bool

    Objective-C

    - (BOOL)applyTransform:(NSString *)transform reverse:(BOOL)reverse range:(NSRange)range updatedRange:(NSRangePointer)resultingRange

    Parameters

    transform

    The transformation to apply. For a list of possible values, see String Transformations. If the specified transform does not exist, the receiver is not modified, and this method returns NOfalse.

    reverse

    Whether an inverse transform should be used. If the specified transform does not have an inverse, the receiver is not modified, and this method returns NOfalse.

    range

    The range of the string to transform. range must not exceed the bounds of the receiver.

    resultingRange

    If the transform was successfully applied, upon return contains the range of the transformed string.

    Return Value

    YEStrue if the transform was successfully applied. Otherwise, NOfalse.

    Discussion

    In addition to the provided transformation constants, you may use any valid ICU transform ID as defined in the ICU User Guide. However, arbitrary ICU transform rules are not supported.

    Availability

    Available in iOS 9.0 and later.

  • Removes from the receiver the characters in a given range.

    Declaration

    Swift

    func deleteCharactersInRange(_ range: NSRange)

    Objective-C

    - (void)deleteCharactersInRange:(NSRange)aRange

    Parameters

    aRange

    The range of characters to delete. aRange must not exceed the bounds of the receiver.

    Discussion

    This method treats the length of the string as a valid range value that returns an empty string.

    Availability

    Available in iOS 2.0 and later.

  • Inserts into the receiver the characters of a given string at a given location.

    Declaration

    Swift

    func insertString(_ aString: String, atIndex loc: Int)

    Objective-C

    - (void)insertString:(NSString *)aString atIndex:(NSUInteger)anIndex

    Parameters

    aString

    The string to insert into the receiver. aString must not be nil.

    anIndex

    The location at which aString is inserted. The location must not exceed the bounds of the receiver.

    Discussion

    The new characters begin at anIndex and the existing characters from anIndex to the end are shifted by the length of aString.

    This method treats the length of the string as a valid index value that returns an empty string.

    Availability

    Available in iOS 2.0 and later.

  • Replaces the characters from aRange with those in aString.

    Declaration

    Swift

    func replaceCharactersInRange(_ range: NSRange, withString aString: String)

    Objective-C

    - (void)replaceCharactersInRange:(NSRange)aRange withString:(NSString *)aString

    Parameters

    aRange

    The range of characters to replace. aRange must not exceed the bounds of the receiver.

    aString

    The string with which to replace the characters in aRange. aString must not be nil.

    Discussion

    This method treats the length of the string as a valid range value that returns an empty string.

    Availability

    Available in iOS 2.0 and later.

  • Replaces all occurrences of a given string in a given range with another given string, returning the number of replacements.

    Declaration

    Swift

    func replaceOccurrencesOfString(_ target: String, withString replacement: String, options options: NSStringCompareOptions, range searchRange: NSRange) -> Int

    Objective-C

    - (NSUInteger)replaceOccurrencesOfString:(NSString *)target withString:(NSString *)replacement options:(NSStringCompareOptions)opts range:(NSRange)searchRange

    Parameters

    target

    The string to replace.

    replacement

    The string with which to replace target.

    opts

    A mask specifying search options. See String Programming Guide for details.

    If opts is NSBackwardsSearch, the search is done from the end of the range. If opts is NSAnchoredSearch, only anchored (but potentially multiple) instances are replaced. NSLiteralSearch and NSCaseInsensitiveSearch also apply.

    searchRange

    The range of characters to replace. aRange must not exceed the bounds of the receiver. Specify searchRange as NSMakeRange(0, [receiver length]) to process the entire string.

    Return Value

    The number of replacements made.

    Discussion

    This method treats the length of the string as a valid range value that returns an empty string.

    Availability

    Available in iOS 2.0 and later.

  • Replaces the characters of the receiver with those in a given string.

    Declaration

    Swift

    func setString(_ aString: String)

    Objective-C

    - (void)setString:(NSString *)aString

    Parameters

    aString

    The string with which to replace the receiver's content. aString must not be nil.

    Availability

    Available in iOS 2.0 and later.

  • These constants specify transforms used by the applyTransform:reverse:range:updatedRange: method.

    Declaration

    Swift

    let NSStringTransformLatinToKatakana: String let NSStringTransformLatinToHiragana: String let NSStringTransformLatinToHangul: String let NSStringTransformLatinToArabic: String let NSStringTransformLatinToHebrew: String let NSStringTransformLatinToThai: String let NSStringTransformLatinToCyrillic: String let NSStringTransformToLatin: String let NSStringTransformMandarinToLatin: String let NSStringTransformHiraganaToKatakana: String let NSStringTransformFullwidthToHalfwidth: String let NSStringTransformToXMLHex: String let NSStringTransformToUnicodeName: String let NSStringTransformStripCombiningMarks: String let NSStringTransformStripDiacritics: String

    Objective-C

    NSString * const NSStringTransformLatinToKatakana; NSString * const NSStringTransformLatinToHiragana; NSString * const NSStringTransformLatinToHangul; NSString * const NSStringTransformLatinToArabic; NSString * const NSStringTransformLatinToHebrew; NSString * const NSStringTransformLatinToThai; NSString * const NSStringTransformLatinToCyrillic; NSString * const NSStringTransformLatinToGreek; NSString * const NSStringTransformToLatin; NSString * const NSStringTransformMandarinToLatin; NSString * const NSStringTransformHiraganaToKatakana; NSString * const NSStringTransformFullwidthToHalfwidth; NSString * const NSStringTransformToXMLHex; NSString * const NSStringTransformToUnicodeName; NSString * const NSStringTransformStripCombiningMarks; NSString * const NSStringTransformStripDiacritics;

    Constants

    • NSStringTransformLatinToKatakana

      NSStringTransformLatinToKatakana

      Transliterate Latin script to Katakana script. This transformation is reversible.

      For example, the string “katakana” transliterates to “カタカナ”.

      Equivalent to kCFStringTransformLatinKatakana.

      Available in iOS 9.0 and later.

    • NSStringTransformLatinToHiragana

      NSStringTransformLatinToHiragana

      Transliterate Latin script to Hiragana script. This transformation is reversible.

      For example, the string “hiragana” transliterates to “ひらがな”.

      Equivalent to kCFStringTransformLatinHiragana.

      Available in iOS 9.0 and later.

    • NSStringTransformLatinToHangul

      NSStringTransformLatinToHangul

      Transliterate Latin script to Hangul script. This transformation is reversible.

      For example, the string “hangul” transliterates to “한굴”.

      Equivalent to kCFStringTransformLatinHangul.

      Available in iOS 9.0 and later.

    • NSStringTransformLatinToArabic

      NSStringTransformLatinToArabic

      Transliterate Latin script to Arabic script. This transformation is reversible.

      For example, the string “ạlʿarabīẗ‎” transliterates to “العَرَبِية”.

      Equivalent to kCFStringTransformLatinArabic.

      Available in iOS 9.0 and later.

    • NSStringTransformLatinToHebrew

      NSStringTransformLatinToHebrew

      Transliterate Latin script to Hebrew script. This transformation is reversible.

      For example, the string “ʻbryţ” transliterates to “עברית”.

      Equivalent to kCFStringTransformLatinHebrew.

      Available in iOS 9.0 and later.

    • NSStringTransformLatinToThai

      NSStringTransformLatinToThai

      Transliterate Latin script to Thai script. This transformation is reversible.

      For example, the string “p̣hās̄ʹā thịy” transliterates to “ภาษาไทย”.

      Equivalent to kCFStringTransformLatinThai.

      Available in iOS 9.0 and later.

    • NSStringTransformLatinToCyrillic

      NSStringTransformLatinToCyrillic

      Transliterate Latin script to Cyrillic script. This transformation is reversible.

      For example, the string “kirillica” transliterates to “кириллица”.

      Equivalent to kCFStringTransformLatinCyrillic.

      Available in iOS 9.0 and later.

    • NSStringTransformToLatin

      NSStringTransformToLatin

      Transliterate any script to Latin script.

      Equivalent to kCFStringTransformToLatin.

      Available in iOS 9.0 and later.

    • NSStringTransformMandarinToLatin

      NSStringTransformMandarinToLatin

      Transliterate Han script to Latin.

      For example, the string “hàn zì” transliterates to “汉字”.

      Equivalent to kCFStringTransformMandarinLatin.

      Available in iOS 9.0 and later.

    • NSStringTransformHiraganaToKatakana

      NSStringTransformHiraganaToKatakana

      Transliterate Hiragana script to Katakana script. This transformation is reversible.

      For example, the string “ひらがな” transliterates to “カタカナ”.

      Equivalent to kCFStringTransformHiraganaKatakana.

      Available in iOS 9.0 and later.

    • NSStringTransformFullwidthToHalfwidth

      NSStringTransformFullwidthToHalfwidth

      Transform full-width CJK characters to half-width forms. This transformation is reversible.

      Equivalent to kCFStringTransformFullwidthHalfwidth.

      Available in iOS 9.0 and later.

    • NSStringTransformToXMLHex

      NSStringTransformToXMLHex

      Transform characters to XML hexadecimal escape codes. This transformation is reversible.

      For example, the string “❦” transforms to “❦”.

      Equivalent to kCFStringTransformToXMLHex.

      Available in iOS 9.0 and later.

    • NSStringTransformToUnicodeName

      NSStringTransformToUnicodeName

      Transform characters to Unicode names.

      For example, the string “🐶🐮” transforms to “{DOG FACE}{COW FACE}”.

      Equivalent to kCFStringTransformToUnicodeName.

      Available in iOS 9.0 and later.

    • NSStringTransformStripCombiningMarks

      NSStringTransformStripCombiningMarks

      Transform characters by removing combining marks.

      Equivalent to kCFStringTransformStripCombiningMarks.

      Available in iOS 9.0 and later.

    • NSStringTransformStripDiacritics

      NSStringTransformStripDiacritics

      Transform characters by removing diacritics.

      Equivalent to kCFStringTransformStripDiacritics.

      Available in iOS 9.0 and later.