Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSStringReference
| Inherits from | |
| Package | com.apple.cocoa.foundation |
| Companion guide |
Overview
The NSStringReference class declares the programmatic interface for an object that manages immutable strings. (An immutable string is a text string that is defined when it is created and subsequently cannot be changed. An immutable string is implemented as an array of Unicode characters (in other words, a text string).
The mutable subclass of NSStringReference is NSMutableStringReference.
The NSStringReference class has two primitive methods—length and characterAtIndex—that provide the basis for all other methods in its interface. The length method returns the total number of Unicode characters in the string. characterAtIndex gives access to each character in the string by index, with index values starting at 0.
NSStringReference declares methods for finding and comparing strings. It also declares methods for reading numeric values from strings, for combining strings in various ways, and for converting a string to different forms (such as encoding and case changes).
The Application Kit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.
String Objects
NSStringReference objects represent character strings in frameworks. Representing strings as objects allows you to use strings wherever you use other objects. It also provides the benefits of encapsulation, so that string objects can use whatever encoding and storage are needed for efficiency while simply appearing as arrays of characters. The two classes, NSStringReference and NSMutableStringReference, declare the programmatic interface for noneditable and editable strings, respectively.
Note: An immutable string is a text string that is defined when it is created and subsequently cannot be changed. An immutable string is implemented as an array of Unicode characters (in other words, a text string). To create and manage an immutable string, use the NSStringReference class. To construct and manage a string that can be changed after it has been created, use NSMutableStringReference.
The objects you create using NSStringReference and NSMutableStringReference are referred to as string objects (or, when no confusion will result, merely as strings). The term C string refers to the standard char * type.
A string object presents itself as an array of Unicode characters (Unicode is a registered trademark of Unicode, Inc.). You can determine how many characters a string object contains with the length method and can retrieve a specific character with the characterAtIndex method. These two “primitive” methods provide basic access to a string object. Most use of strings, however, is at a higher level, with the strings being treated as single entities: You compare strings against one another, search them for substrings, combine them into new strings, and so on. If you need to access string objects character by character, you must understand the Unicode character encoding, specifically issues related to composed character sequences. For details see The Unicode Standard, Version 4.0 (The Unicode Consortium, Boston: Addison-Wesley, 2003, ISBN 0-321-18578-1) and the Unicode Consortium web site: http://www.unicode.org/.
Over distributed-object connections, mutable string objects are passed by-reference and immutable string objects are passed by-copy.
Subclassing Notes
It is possible to subclass NSString (and NSMutableString), but doing so requires providing storage facilities for the string (which is not inherited by subclasses) and implementing two primitive methods. The abstract NSString and NSMutableString classes are the public interface of a class cluster consisting mostly of private, concrete classes that create and return a string object appropriate for a given situation. Making your own concrete subclass of this cluster imposes certain requirements (discussed in “Methods to Override”).
Make sure your reasons for subclassing NSString so are valid. Instances of your subclass should represent a string and not something else. Thus the only attributes the subclass should have are the length of the character buffer it’s managing and access to individual characters in the buffer. Valid reasons for making a subclass of NSString include providing a different backing store (perhaps for better performance) or implementing some aspect of object behavior differently, such as memory management. If your purpose is to add non-essential attributes or metadata to your subclass of NSString, a better alternative would be object composition (see “Alternatives to Subclassing”). Cocoa already provides an example of this with the NSAttributedString class.
Methods to Override
Any subclass of NSString must override the primitive instance methods length and characterAtIndex. These methods must operate on the backing store that you provide for the characters of the string. For this backing store you can use a static array, a dynamically allocated buffer, a standard NSString object, or some other data type or mechanism. You may also choose to override, partially or fully, any other NSString method for which you want to provide an alternative implementation.
You might want to implement an constructor for your subclass that is suited to the backing store that the subclass is managing. The NSString class adopts the NSCopying, NSMutableCopying, and NSCoding interfaces; if you want instances of your own custom subclass created from copying or coding, override the methods in these interfaces.
Alternatives to Subclassing
Often a better and easier alternative to making a subclass of NSString—or of any other abstract, public class of a class cluster, for that matter—is object composition. This is especially the case when your intent is to add to the subclass metadata or some other attribute that is not essential to a string object. In object composition, you would have an NSString object as one instance variable of your custom class (a subclass of NSObject typically) and one or more instance variables that store the metadata that you want for the custom object. Then just design your subclass interface to include accessor methods for the embedded string object and the metadata.
If the behavior you want to add supplements that of the existing class, you could write a category on NSString. Keep in mind, however, that this category will be in effect for all instances of NSString that you use, and this might have unintended consequences.
Tasks
Constructors
Getting a String’s Length
Accessing Characters
Dividing Strings
Finding Characters and Substrings
Determining Line and Paragraph Ranges
Identifying and Comparing Strings
Getting a Shared Prefix
Getting Strings with Mapping
-
decomposedStringWithCanonicalMapping
-
decomposedStringWithCompatibilityMapping
-
precomposedStringWithCanonicalMapping
-
precomposedStringWithCompatibilityMapping
Working with Encodings
-
availableStringEncodings
-
defaultCStringEncoding
-
localizedNameOfStringEncoding
-
canBeConvertedToEncoding
-
dataUsingEncoding
-
fastestEncoding
-
smallestEncoding
Deprecated
Constructors
NSStringReference
Creates an empty NSStringReference.
public NSStringReference()
Creates a new NSStringReference by converting the bytes in aData into Unicode characters.
public NSStringReference(NSData aData, int encoding)
Discussion
aData must be an NSData object containing bytes in encoding and the default plain text format (that is, pure content with no attributes or other markups) for that encoding.
Creates a new NSStringReference by reading characters from the location named by aURL.
public NSStringReference(java.net.URL aURL)
Discussion
If the contents begin with a byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters; otherwise interprets the contents as characters in the default C-string encoding. Returns null if the location can’t be opened.
Creates a new NSStringReference by converting the bytes at aURL into Unicode characters.
public NSStringReference(java.net.URL aURL, int encoding)
Discussion
aURL must contain bytes in encoding and the default plain text format (that is, pure content with no attributes or other markups) for that encoding.
Static Methods
availableStringEncodings
Returns a zero-terminated list of the encodings string objects support in the application’s environment.
public static NSArray availableStringEncodings()
Discussion
Among the more commonly used are:
-
ASCIIStringEncoding NEXTSTEPStringEncodingUnicodeStringEncodingISOLatin1StringEncodingISOLatin2StringEncodingSymbolStringEncoding
See the “Constants” section for a larger list and descriptions of many supported encodings.
See Also
defaultCStringEncoding
Returns the C-string encoding assumed for any method accepting a C string as an argument
public static int defaultCStringEncoding()
Discussion
. (These methods use ...CString... in the keywords for such arguments.) The default C-string encoding is determined from system information and can’t be changed programmatically for an individual process.
localizedNameOfStringEncoding
Returns a human-readable string giving the name of encoding in the current locale’s language.
public static String localizedNameOfStringEncoding(int encoding)
Instance Methods
canBeConvertedToEncoding
Returns true if the receiver can be converted to encoding without loss of information. Returns false if characters would have to be changed or deleted in the process of changing encodings.
public boolean canBeConvertedToEncoding(int encoding)
Discussion
If you plan to actually convert a string, dataUsingEncoding returns null on failure, so you can avoid the overhead of invoking this method yourself by simply trying to convert the string.
See Also
characterAtIndex
Returns the character at the array position given by index.
public char characterAtIndex(int index)
Discussion
Throws a RangeException if index lies beyond the end of the receiver.
commonPrefixWithString
Returns a string containing characters the receiver and aString have in common, starting from the beginning of each up to the first characters that aren’t equivalent.
public String commonPrefixWithString(String aString, int mask)
Discussion
The returned string is based on the characters of the receiver. For example, if the receiver is “Ma¨dchen” and aString is “Mädchenschule”, the string returned is “Ma¨dchen”, not “Mädchen”. The following search options may be specified in mask by combining them with the C bitwise OR operator:
CaseInsensitiveSearchLiteralSearch
See “Strings” for details on these options.
See Also
componentsSeparatedByString
Returns an NSArray containing substrings from the receiver that have been divided by separator.
public NSArray componentsSeparatedByString(String separator)
Discussion
The substrings in the array appear in the order they did in the receiver. If the string begins or ends with the separator, the first or last substring, respectively, is empty. For example, this code excerpt:
NSStringReference list = "wrenches, hammers, saws"; |
NSArray listItems = [list.componentsSeparatedByString (", ")]; |
produces an array with these contents:
Index |
Substring |
|---|---|
0 |
wrenches |
1 |
hammers |
2 |
saws |
If list begins with a comma and space—for example, “, wrenches, hammers, saws”—the array has these contents:
Index |
Substring |
|---|---|
0 |
(empty string) |
1 |
wrenches |
2 |
hammers |
3 |
saws |
If list has no separators—for example, “wrenches”—the array contains the string itself, in this case “wrenches”.
See Also
-
componentsJoinedByString(NSArray)
dataUsingEncoding
Returns an NSData object containing a representation of the receiver in encoding.
public NSData dataUsingEncoding(int encoding, boolean flag)
Discussion
Returns null if flag is false and the receiver can’t be converted without losing some information (such as accents or case). If flag is true and the receiver can’t be converted without losing some information, some characters may be removed or altered in conversion. For example, in converting a character from UnicodeStringEncoding to ASCIIStringEncoding, the character ‘Á’ becomes ‘A’, losing the accent.
This method creates an external representation (with a byte order marker, if necessary, to indicate endianness) to ensure that the resulting NSData object can be written out to a file safely. The result of this method, when lossless conversion is made, is the default “plain text” format for encoding and is the recommended way to save or transmit a string object.
See Also
decomposedStringWithCanonicalMapping
Returns a string made by normalizing the receiver’s contents.
public String decomposedStringWithCanonicalMapping()
Discussion
This method normalizes the string using the Unicode Normalization Form D.
Availability
- Available in Mac OS X v10.2 and later.
See Also
decomposedStringWithCompatibilityMapping
Returns a string made by normalizing the receiver’s contents.
public String decomposedStringWithCompatibilityMapping()
Discussion
This method normalizes the string using the Unicode Normalization Form KD.
Availability
- Available in Mac OS X v10.2 and later.
See Also
fastestEncoding
Returns the fastest encoding to which the receiver may be converted without loss of information.
public int fastestEncoding()
Discussion
“Fastest” applies to retrieval of characters from the string. This encoding may not be space efficient.
See Also
hasPrefix
Returns true if aString matches the beginning characters of the receiver, false otherwise.
public boolean hasPrefix(String aString)
Discussion
Returns false if aString is empty. This method is a convenience for comparing strings using the AnchoredSearch option. See “Strings” for more information.
See Also
hasSuffix
Returns true if aString matches the ending characters of the receiver, false otherwise.
public boolean hasSuffix(String aString)
Discussion
Returns false if aString is empty. This method is a convenience for comparing strings using the AnchoredSearch and BackwardsSearch options. See “Strings” for more information.
See Also
length
Returns the number of Unicode characters in the receiver.
public int length()
Discussion
This number includes the individual characters of composed character sequences, so you can’t use this method to determine if a string will be visible when printed or how long it will appear.
lineRangeForRange
Returns the smallest range of characters representing the lines containing aRange, including the characters that terminate the lines.
public NSRange lineRangeForRange(NSRange aRange)
See Also
paragraphRangeForRange
Returns the smallest range of characters representing the paragraph containing aRange, including the characters that terminate the paragraph.
public NSRange paragraphRangeForRange(NSRange range)
Availability
- Available in Mac OS X v10.3 and later.
See Also
precomposedStringWithCanonicalMapping
Returns a string made by normalizing the receiver’s contents.
public String precomposedStringWithCanonicalMapping()
Discussion
This method normalizes the string using the Unicode Normalization Form C.
Availability
- Available in Mac OS X v10.2 and later.
See Also
precomposedStringWithCompatibilityMapping
Returns a string made by normalizing the receiver’s contents.
public String precomposedStringWithCompatibilityMapping()
Discussion
This method normalizes the string using the Unicode Normalization Form KC.
Availability
- Available in Mac OS X v10.2 and later.
See Also
rangeOfString
Returns an NSRange giving the location and length of the first occurrence of subString within the receiver.
public NSRange rangeOfString(String subString)
Discussion
If subString isn’t found, returns a range of {NSArray.NotFound, 0}. The length of the returned range and that of subString may differ if equivalent composed character sequences are matched.
Returns a range of {NSArray.NotFound, 0} if subString is the null string or empty.
Returns an NSRange giving the location and length of the first occurrence of subString within aRange in the receiver.
public NSRange rangeOfString(String subString, int mask, NSRange aRange)
Discussion
If subString isn’t found, returns a range of {NSArray.NotFound, 0}. The length of the returned range and that of subString may differ if equivalent composed character sequences are matched. The following options may be specified in mask by combining them with the C bitwise OR operator:
CaseInsensitiveSearchLiteralSearchBackwardsSearchAnchoredSearch
See “Strings” for details on these options. Throws a RangeException if any part of aRange lies beyond the end of the string. Returns a range of {NSArray.NotFound, 0} if subString is the null string or empty.
smallestEncoding
Returns the smallest encoding to which the receiver can be converted without loss of information.
public int smallestEncoding()
Discussion
This encoding may not be the fastest for accessing characters, but is very space-efficient. This method itself may take some time to execute.
See Also
string
Returns a Java String version of the receiver.
public String string()
substringWithRange
Returns a string object containing the characters of the receiver that lie within aRange.
public String substringWithRange(NSRange aRange)
Discussion
Throws a RangeException if any part of aRange lies beyond the end of the receiver. This method treats the length of the string as a valid range value that returns an empty string.
writeToURL
public boolean writeToURL(java.net.URL aURL, boolean atomically)
Discussion
Writes the contents of the receiver to the location specified by aURL.
If atomically is true, the receiver is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If atomically is false, the receiver is written directly to aURL. The true option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing.
This method returns true if the location is written successfully, and false otherwise.
The atomically parameter is ignored if aURL is not of a type that can be accessed atomically.
See Also
This method is deprecated.
public boolean writeToURL(java.net.URL aURL, boolean atomically, int encoding)
Discussion
Writes the contents of the receiver, converted into encoding encoding, to the location specified by aURL, writing atomically if atomically is true and aURL supports it. Returns true if the location is written successfully, and false otherwise.
Availability
- Deprecated.
- Available in Mac OS X v10.0 and later. Deprecated in Mac OS X v10.4.
Constants
The following constants are provided by NSStringReference as possible string encodings. This is an incomplete list.
© 1997, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)