NSString

Inherits From: NSObject

Conforms To: NSCoding, NSCopying, NSMutableCopying NSObject (NSObject)

Declared In: Foundation/NSString.h

Foundation/NSPathUtilities.h

Foundation/NSUtilities.h

Class Description

NSString declares the programmatic interface for objects that create and manage immutable character strings in a representation-independent format.

NSString (and NSMutableString) are abstract classes for string manipulation. NSString provides methods for read-only access, while NSMutableString allows for changing the contents of the string. NSString and NSMutableString provide factory methods that return autoreleased instances of unspecified subclasses of strings.

While the actual representation of character strings stored in NSString and NSMutableString is independent of any particular implementation, you can in general think of the contents of NSString and NSMutableString objects as being, canonically, Unicode characters (defined by the unichar data type). Methods that use the terms character, range, and length, refer to strings of unichars and ranges and lengths of unichar stringsthis is important, because conversion between unichars and other character encodings is not necessarily one-to-one. For instance, an ISO Latin1 encoded string of a given length might contain fewer or more characters when encoded as unichars. Another important point is that unichars don't necessarily correspond one-to-one with what is normally thought of as letters in a string; if you need to go through a string in terms of letters, use rangeOfComposedCharacterSequenceAtIndex:.

Methods that take CString arguments deal with the default eight-bit encoding of the environment, which could be, for instance, EUC or ISOLatin1. You can also explicitly convert to and from any encoding by using methods such as initWithData:usingEncoding: and dataUsingEncoding:.

Constant NSStrings can be created with the @"..." optionsuch strings should contain only ASCII characters, and nothing more.

Strings are provided with generic coding behavior when used for storage or distribution. This behavior is to copy the contents and provide a generic NSString implementation, losing class but preserving mutability.

In general, you instantiate NSString objects sending one of the stringWith1/4 methods or the localizedStringWithFormat: method to the NSString class object. For NSString objects that were allocated manually, use any of the initWith1/4 methods to initialize the contents of the string object.

The primitive methods to NSString are length and characterAtIndex:.

UNIX-style file system path names can be manipulated using the collection of stringBy1/4 methods described under Manipulating File System Paths below.

Creating Temporary Strings

• + (NSString *)localizedStringWithFormat:(NSString *)format,... Returns a string created by using format as a printf() style format string, and the following arguments as values to be substituted into the format string. The user's default locale is used for format information.
• + (NSString *)stringWithCString:(const char *)byteString Returns a string containing the characters in byteString, which must be null-terminated. byteString should contain characters in the default C string encoding.
• + (NSString *)stringWithCString:(const char *)byteString length:(unsigned int)length Returns a string containing characters from byteString. byteString should contain characters in the default C string encoding. length bytes are copied into the string, regardless of whether a null byte exists in byteString. Raises NSInvalidArgumentException if byteString is NULL
• + (NSString *)stringWithCharacters:(const unichar *)chars length:(unsigned int)length Returns a string containing chars. length characters are copied into the string, regardless of whether a null character exists in chars.
• + (NSString *)stringWithContentsOfFile:(NSString *)path Returns a string containing the contents of the file specified by path. This method attempts to determine the encoding for the file. The string is assumed to be in Unicode encoding, but if the encoding is determined not to be Unicode, the default C string encoding is used instead.
• + (NSString *)stringWithFormat:(NSString *)format,... Returns a string created by using format as a printf() style format string, and the following arguments as values to be substituted into the format string.

• - (id)init Initializes the receiver, a newly allocated NSString, to contain no characters. This is the only initialization method that a subclass of NSString should invoke.
• - (id)initWithCString:(const char *)byteString Initializes the receiver, a newly allocated NSString, by converting the one-byte characters in byteString into Unicode characters. byteString must be a null-terminated C string in the default C string encoding.
• - (id)initWithCString:(const char *)byteString Initializes the receiver, a newly allocated NSString, by length:(unsigned int)length converting length one-byte characters in byteString into Unicode characters. This method doesn't stop at a null byte.
• - (id)initWithCStringNoCopy:(char *)byteString Initializes the receiver, a newly allocated NSString, by length:(unsigned int)length converting length one-byte characters in byteString into freeWhenDone:(BOOL)flag Unicode characters. This method doesn't stop at a null byte. The receiver becomes the owner of byteString; if flag is YES it will free the memory when it no longer needs it, but if flag is NO it won't.
• - (id)initWithCharacters:(const unichar *)chars Initializes the receiver, a newly allocated NSString, by length:(unsigned int)length copying length characters from chars. This method doesn't stop at a null character.
• - (id)initWithCharactersNoCopy:(unichar *)chars Initializes the receiver, a newly allocated NSString, to length:(unsigned int)length contain length characters from chars. This method freeWhenDone:(BOOL)flag doesn't stop at a null character. The receiver becomes the owner of chars; if flag is YES the receiver will free the memory when it no longer needs them, but if flag is NO it won't. Note that the NO case could be dangerous if used with memory that could be freed. The NO flag should be used only when the provided backing store is permanent.
• - (id)initWithContentsOfFile:(NSString *)path Initializes the receiver, a newly allocated NSString, by reading characters from the file whose name is given by path. This method attempts to determine the encoding for the file. The string is assumed to be in Unicode encoding, but if the encoding is determined not to be Unicode, the default C string encoding is used instead. Also see writeToFile:atomically: in Storing the String.
• - (id)initWithData:(NSData *)data Initializes the receiver, a newly allocated NSString, by encoding:(NSStringEncoding)encoding converting the bytes in data into Unicode characters. data must be an NSData object containing bytes in encoding and in the default plain text format for that encoding.
• - (id)initWithFormat:(NSString *)format,... Initializes the receiver, a newly allocated NSString, by constructing a string from format and following string objects in the manner of printf().
• - (id)initWithFormat:(NSString *)format Initializes the receiver, a newly allocated NSString, by arguments:(va_list)argList constructing a string from format and argList in the manner of vprintf().
• - (id)initWithFormat:(NSString *)format Initializes the receiver, a newly allocated NSString, by locale:(NSDictionary *)dictionary,... constructing a string from format and the formatting information in the dictionary in the manner of printf().
• - (id)initWithFormat:(NSString *)format Initializes the receiver, a newly allocated NSString, by locale:(NSDictionary *)dictionary constructing a string from format and format arguments:(va_list)argList information in dictionary and argList in the manner of vprintf().
• - (id)initWithString:(NSString *)string Initializes the receiver, a newly allocated NSString, by copying the characters from string.

• - (unsigned int)length Returns the number of characters in the receiver. This number includes the individual characters of composed character sequences.

• - (unichar)characterAtIndex:(unsigned int)index Returns the character at the array position given by index. This method raises an NSStringBoundsError exception if index lies beyond the end of the string.
• - (void)getCharacters:(unichar *)buffer Invokes getCharacters:range: with the provided buffer and the entire extent of the receiver as the range.
• - (void)getCharacters:(unichar *)buffer Copies characters from aRange in the receiver into buffer, range:(NSRange)aRange which must be large enough to contain them. This method does not add a null character. This method raises an NSStringBoundsError exception if any part of aRange lies beyond the end of the string.

• - (NSString *)stringByAppendingFormat:(NSString *)format,... Returns a string made by using format as a printf() style format string, and the following arguments as values to be substituted into the format string.
• - (NSString *)stringByAppendingString:(NSString *)aString Returns a string made by appending aString and the receiver.

• - (NSArray *)componentsSeparatedByString:(NSString *)separator Finds the substrings in the receiver that are delimited by separator and returns them as the elements of an NSArray. The strings in the array appear in the order they did in the receiver.
• - (NSString *)substringFromIndex:(unsigned int)index Returns a string object containing the characters of the receiver starting from the one at index to the end. This method raises an NSStringBoundsError exception if index lies beyond the end of the string.
• - (NSString *)substringFromRange:(NSRange)aRange Returns a string object containing the characters of the receiver which lie within aRange. This method raises an NSStringBoundsError exception if any part of aRange lies beyond the end of the string.
• - (NSString *)substringToIndex:(unsigned int)index Returns a string object containing the characters of the receiver up to, but not including, the one at index. This method raises an NSStringBoundsError exception if index lies beyond the end of the string.

• - (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet Invokes rangeOfCharacterFromSet:options: with no options.
• - (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(unsigned int)mask Invokes rangeOfCharacterFromSet:options:range: with mask and the entire extent of the receiver as the range.
• - (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(unsigned int)mask Returns the range of the first character found from aSet. range:(NSRange)aRange The search is restricted to aRange with mask options. mask can be any combination (using the C bitwise OR operator |) of NSCaseInsensitiveSearch, NSLiteralSearch, and NSBackwardsSearch.
• - (NSRange)rangeOfString:(NSString *)string Invokes rangeOfString:options: with no options.
• - (NSRange)rangeOfString:(NSString *)string Invokes rangeOfString:options:range: with mask options:(unsigned int)mask options and the entire extent of the receiver as the range.
• - (NSRange)rangeOfString:(NSString *)aString Returns the range giving the location and length in the options:(unsigned int)mask receiver of aString. The search is restricted to aRange range:(NSRange)aRange with mask options. mask can be any combination (using the C bitwise OR operator |) of NSCaseInsensitiveSearch, NSLiteralSearch, NSBackwardsSearch, and NSAnchoredSearch.

• - (NSRange)rangeOfComposedCharacterSequenceAtIndex:(unsigned int)anIndex Returns an NSRange giving the location and length in the receiver of the composed character sequence located at anIndex. This method raises an NSStringBoundsError exception if anIndex lies beyond the end of the string.

• - (NSComparisonResult)caseInsensitiveCompare:(NSString *)aString Invokes compare:options: with the option NSCaseInsensitiveSearch.
• - (NSComparisonResult)compare:(NSString *)aString Invokes compare:options: with no options.
• - (NSComparisonResult)compare:(NSString *)aString options:(unsigned int)mask Invokes compare:options:range: with mask as the options and the receiver's full extent as the range.
• - (NSComparisonResult)compare:(NSString *)aString options:(unsigned int)mask Compares aString to the receiver and returns their lexical range:(NSRange)aRange ordering. The comparison is restricted to aRange and uses mask options, which may be NSCaseInsensitiveSearch and NSLiteralSearch.
• - (BOOL)hasPrefix:(NSString *)aString Returns YES if aString matches the beginning characters of the receiver, NO otherwise.
• - (BOOL)hasSuffix:(NSString *)aString Returns YES if aString matches the ending characters of the receiver, NO otherwise.
• - (unsigned int)hash Returns an unsigned integer that can be used as a table address in a hash table structure. If two string objects are equal (as determined by the isEqual: method), they must have the same hash value.

- (BOOL)isEqualToString:(NSString *)aString Returns YES if aString is equivalent to the receiver (if they have the same id or if they compare as NSOrderedSame), NO otherwise.

Storing the String

• - (NSString *)description Returns the string itself.
• - (BOOL)writeToFile:(NSString *)filename Writes a textual description of the receiver to filename. atomically:(BOOL)useAuxiliaryFile If useAuxiliaryFile is YES, the data is written to a backup file and then, assuming no errors occur, the backup file is renamed to the intended file name. The string is written in the default C string encoding if the contents can be converted to that encoding. If not, the string is stored in the Unicode encoding.

• - (NSString *)commonPrefixWithString:(NSString *)aString options:(unsigned int)mask Returns the substring of the receiver containing characters that the receiver and aString have in common. mask can be any combination (using the C bitwise OR operator |) of NSCaseInsensitiveSearch and NSLiteralSearch.

• - (NSString *)capitalizedString Returns a string with the first character of each word changed to its corresponding uppercase value.
• - (NSString *)lowercaseString Returns a string with each character changed to its corresponding lowercase value.
• - (NSString *)uppercaseString Returns a string with each character changed to its corresponding uppercase value.

• - (const char *)cString Returns a representation of the receiver as a C string in the default C string encoding.
• - (unsigned int)cStringLength Returns the length in bytes of the C string representation of the receiver.
• - (void)getCString:(char *)buffer Invokes getCString:maxLength:range:remainingRange: with NSMaximumStringLength as the maximum length, the receiver's entire extent as the range, and NULL for the remaining range. buffer must be large enough to contain the resulting C string plus a terminating null character (which this method adds).
• - (void)getCString:(char *)buffer Invokes maxLength:(unsigned int)maxLength getCString:maxLength:range:remainingRange: with maxLength as the maximum length, the receiver's entire extent as the range, and NULL for the remaining range. buffer must be large enough to contain the resulting C string plus a terminating null character (which this method adds).
• - (void)getCString:(char *)buffer Copies the receiver's characters (in the default C string maxLength:(unsigned int)maxLength encoding) as bytes into buffer. buffer must be range:(NSRange)aRange large enough to contain maxLength bytes plus a remainingRange:(NSRange *)leftoverRange terminating null character (which this method adds). Characters are copied from aRange; if not all characters can be copied, the range of those not copied is put into leftoverRange. This method raises an NSStringBoundsError exception if any part of aRange lies beyond the end of the string.

• - (double)doubleValue Returns the double precision floating point value of the receiver's text. Whitespace at the beginning of the string is skipped. If the receiver begins with a valid text representation of a floating-point number, that number's value is returned, otherwise 0.0 is returned. HUGE_VAL or -HUGE_VAL is returned on overflow. 0.0 is returned on underflow. Characters following the number are ignored.
• - (float)floatValue Returns the floating-point value of the receiver's text. Whitespace at the beginning of the string is skipped. If the receiver begins with a valid text representation of a floating-point number, that number's value is returned, otherwise 0.0 is returned. HUGE_VAL or -HUGE_VAL is returned on overflow. 0.0 is returned on underflow. Characters following the number are ignored.
• - (int)intValue Returns the integer value of the receiver's text. Whitespace at the beginning of the string is skipped. If the receiver begins with a valid representation of an integer, that number's value is returned, otherwise 0 is returned. INT_MAX or INT_MIN is returned on overflow. Characters following the number are ignored.

• + (NSStringEncoding *)availableStringEncodings Returns a null terminated array of available string encodings..
• + (NSStringEncoding)defaultCStringEncoding Returns the C string encoding assumed for any method accepting a C string as an argument.
• + (NSString *)localizedNameOfStringEncoding:(NSStringEncoding)encoding Returns the localized name of the string encoding specified by encoding.
• - (BOOL)canBeConvertedToEncoding:(NSStringEncoding)encoding Returns YES if the receiver can be converted to encoding without loss of information, and NO otherwise.
• - (NSData *)dataUsingEncoding:(NSStringEncoding)encoding Invokes dataUsingEncoding:allowLossyConversion: with NO as the argument to allow lossy conversion.
• - (NSData *)dataUsingEncoding:(NSStringEncoding)encoding allowLossyConversion:(BOOL)flag Returns an NSData object containing a representation of the receiver in encoding. If flag is NO and the receiver can't be converted without losing some information (such as accents or case) this method returns nil. If flag is YES and the receiver can't be converted without losing some information, some characters may be removed or altered in conversion.
• - (NSStringEncoding)fastestEncoding Encoding in which this string can be expressed (with lossless conversion) most quickly.
• - (NSStringEncoding)smallestEncoding Encoding in which this string can be expressed (with lossless conversion) in the most space efficient manner

• - (id)propertyList Depending on the format of the receiver's contents, returns a string, data, array, or dictionary object represention of those contents.
• - (NSDictionary *)propertyListFromStringsFileFormat Returns a dictionary object initialized with the keys and values found in the receiver. The receiver's format must be that used for .string files.

• - (unsigned int)completePathIntoString:(NSString **)outputName caseSensitive:(BOOL)flag Regards the receiver as containing a partial filename and matchesIntoArray:(NSArray **)outputArray returns in outputName the longest matching path name. filterTypes:(NSArray *)filterTypes Case is considered if flag is YES. If outputArray is given, all matching filenames are return in outputArray. If filterTypes is provided, this method considers only those paths that match one of the types. Returns 0 if no matches are found; otherwise, the return value is positive.
• - (NSString *)lastPathComponent Returns the last component of the receiver's path representation. Given the path /Images/Bloggs.tiff, this method returns a string containing Bloggs.tiff.
• - (NSString *)pathExtension Returns the extension of the receiver's path representation. Given the path /Images/Bloggs.tiff, this method returns a string containing tiff.
• - (NSString *)stringByAbbreviatingWithTildeInPath Returns a string in which the user's home directory path is replace by ~.
• - (NSString *)stringByAppendingPathComponent:(NSString *)aString Returns a string representing the receiver's path with the addition of the path component aString.
• - (NSString *)stringByAppendingPathExtension:(NSString *)aString Returns a string representing the receiver's path with the addition of the extension aString.
• - (NSString *)stringByDeletingLastPathComponent Returns the receiver's path representation minus the last component. Given the path /Images/Bloggs.tiff, this method returns a string containing /Images.
• - (NSString *)stringByDeletingPathExtension Returns the receiver's path representation minus the extension on the last component. Given the path /Images/Bloggs.tiff, this method returns a string containing /Images/Bloggs.
• - (NSString *)stringByExpandingTildeInPath Returns a string in which a tilde is expanded to its full path equivalent.
• - (NSString *)stringByResolvingSymlinksInPath Returns a string identical to the receiver's path except that any symbolic links have been resolved.
• - (NSString *)stringByStandardizingPath Returns a string containing a standardized path, one in which tildes are expanded and redundant elements (for example //) eliminated.