Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.

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

Initializing Newly Allocated Strings

Getting a String's Length

Accessing Characters

Combining Strings

Dividing Strings into Substrings

Finding Ranges of Characters and Substrings

Determining Composed Character Sequences

Identifying and Comparing Strings

- (BOOL)isEqual:(id)anObject Returns YES if both the receiver and anObject have the same id or if they're both NSStrings that compare as NSOrderedSame, NO otherwise.

- (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

Getting a Shared Prefix

Changing Case

Getting C Strings

Getting Numeric Values

Working With Encodings

Converting String Contents into a Property List

Manipulating File System Paths