- Inherits from:
- NSObject
- Package:
- com.apple.yellow.foundation
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 array of Unicode characters (in other words, a text string). To create and manage a string that can be changed after it has been created, use 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). General use of these methods is presented in the section "Working with 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 is 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 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 it 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 3.0. The Unicode Consortium. Addison Wesley Longman, 2000. ISBN 0-201-61633-5.
NSStringReference provides several means for creating instances, most based around the various character encodings it supports. Although string objects always present their own contents as Unicode characters, they can convert their contents to and from many other encodings, such as 7-bit ASCII, ISO Latin 1, EUC, and Shift-JIS. The availableStringEncodings class method returns the encodings supported. You can specify an encoding explicitly when converting a C string to or from a string object, or use the default C string encoding, which varies from platform to platform and is returned by the defaultCStringEncoding class method.
Such an object is created at compile time and exists throughout your program's execution. The compiler makes such object constants unique on a per-module basis, and they're never deallocated (though you can retain and release them as you do any other object).
In format strings, a '%' character announces a placeholder
for a value, with the characters that follow determining the kind
of value expected and how to format it. For example, a format string
of "%d houses" expects an integer value to be substituted for
the format expression "%d". NSStringReference supports the format
characters defined for the ANSI C function printf()
,
plus '@' for any object.
Many compilers perform typecasting of arguments to printf()
,
so printing an integer into a %f (floating-point)
placeholder works as expected. This typecasting doesn't occur
with NSStringReference's formatted methods, so be sure to cast
your values explicitly.
Value formatting is affected by the user's current locale, which is an NSDictionary specifying number, date, and other kinds of formats. NSStringReference uses only the locale's definition for the decimal separator (given by the key named NSDecimalSeparator). If you use a method that doesn't specify a locale, the string assumes the default locale.
The string classes provide methods for finding characters and substrings within strings and for comparing one string to another. These methods conform to the Unicode standard for determining whether two character sequences are equivalent. The string classes provide comparison methods that handle composed character sequences properly, though you do have the option of specifying a literal search when efficiency is important and you can guarantee some canonical form for composed character sequences.
The search and comparison methods each come in three variants. The simplest version of each searches or compares entire strings. Other variants allow you to alter the way comparison of composed character sequences is performed and to specify a specific range of characters within a string to be searched or compared. You can specify these options (not all options are available for every method):
Search Option | Effect |
CaseInsensitiveSearch |
Ignores case distinctions among characters. |
LiteralSearch |
Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically. |
BackwardsSearch |
Performs searching from the end of the range toward the beginning. |
AnchoredSearch |
Performs searching only on characters at the beginning or end of the range. No match at the beginning or end means nothing is found, even if a matching sequence of characters occurs elsewhere in the string. |
Search and comparison are currently performed as if the LiteralSearch
option
were specified. As the Unicode encoding becomes more widely used,
and the need for more flexible comparison increases, the default
behavior will be changed accordingly.
Substrings are only found if completely contained within the
specified range. If you specify a range for a search or comparison
method and don't request LiteralSearch
,
the range must not break composed character sequences on either
end; if it does you could get an incorrect result.
The rangeOfString:... methods search for a substring within the receiver. Several other methods allow you to determine whether two strings are equal or whether one is the prefix or suffix of another, but they don't have variants that allow you to specify search options or ranges.
You can extract substrings from the beginning or end of a string to a particular index, or from a specific range, with substringWithRange . You can also split a string into substrings (based on a separator string) with the componentsSeparatedByString method.
Most of the NSStringReference classes' remaining methods are for conveniences such as changing case, quickly extracting numeric values, and working with encodings. There's also a set of methods for treating strings as file system paths, described below in "Manipulating Paths" . An additional class cluster, NSScanner, allows you to scan a string object for numeric and string values. Both the NSStringReference and the NSScanner classes use the NSCharacterSet class for search operations. See the appropriate class specifications for more information.
In addition to all the basic methods for working with character strings merely as strings, NSStringReference also provides a rich set of methods for manipulating strings as file system paths. A string can extract a path's directory, file name, and extension, expand a tilde expression (such as "~me") or create one for the user's home directory, and clean up paths containing symbolic links, redundant slashes, and references to "." (current directory) and ".." (parent directory). These methods are listed under "Working with paths" (page 658) in the Method Types section.
NSStringReference represents paths generically with '/
'
as the path separator and '.
'
as the extension separator. Methods that accept strings as path
arguments convert these generic representations to the proper system-specific
form as needed. On systems with an implicit root directory, absolute
paths begin with a path separator or with a tilde expression ("~/...
"
or "~user/...
").
The following constants are provided by NSStringReference:
Constant | Type | Description |
ASCIIStringEncoding |
int | ASCII values 0..127 only |
ISO2022JPStringEncoding |
int | ISO 2022 Japanese encoding for e-mail |
ISOLatin1StringEncoding |
int | 5 |
ISOLatin2StringEncoding |
int | 9 |
JapaneseEUCStringEncoding |
int | 3 |
MacOSRomanStringEncoding |
int | 30 |
NEXTSTEPStringEncoding |
int | 2 |
NonLossyASCIIStringEncoding |
int | 7 |
ShiftJISStringEncoding |
int | 8 |
SymbolStringEncoding |
int | 6 |
UTF8StringEncoding |
int | 4 |
UnicodeStringEncoding |
int | 10 |
WindowsCP1250StringEncoding |
int | WinLatin2 |
WindowsCP1251StringEncoding |
int | Cyrillic; same as AdobeStandardCyrillic |
WindowsCP1252StringEncoding |
int | WinLatin1 |
WindowsCP1253StringEncoding |
int | Greek |
WindowsCP1254StringEncoding |
int | Turkish |
- Constructors
- NSStringReference
- Getting a string's length
- length
- Accessing characters
- characterAtIndex
- Dividing strings
- componentsSeparatedByString
- substringWithRange
- Finding characters and substrings
- rangeOfString
- Determining line ranges
- lineRangeForRange
- Identifying and comparing strings
- hasPrefix
- hasSuffix
- string
- Getting a shared prefix
- commonPrefixWithString
- Working with encodings
- availableStringEncodings
- defaultCStringEncoding
- localizedNameOfStringEncoding
- canBeConvertedToEncoding
- dataUsingEncoding
- fastestEncoding
- smallestEncoding
- Writing to an URL
- writeToURL
public NSStringReference()
public NSStringReference(
NSData aData,
int anInt)
public NSStringReference(java.net.URL anURL)
public NSStringReference(
java.net.URL anURL,
int anInt)
public static NSArray availableStringEncodings()
ASCIIStringEncoding
NEXTSTEPStringEncoding
UnicodeStringEncoding
ISOLatin1StringEncoding
ISOLatin2StringEncoding
SymbolStringEncoding
See the "Types and Constants" section of the Foundation Kit documentation for a complete list and descriptions of supported encodings.
See Also: localizedNameOfStringEncoding
public static int defaultCStringEncoding()
public static String localizedNameOfStringEncoding(int encoding)
public boolean canBeConvertedToEncoding(int encoding)
If you plan to actually convert a string, the dataUsingEncoding:... methods return null on failure, so you can avoid the overhead of invoking this method yourself by simply trying to convert the string.
See Also: dataUsingEncoding
public char characterAtIndex(int index)
public String commonPrefixWithString(
String aString,
int mask)
CaseInsensitiveSearch
LiteralSearch
See "Working with String Objects" in the class cluster description for details on these options.
See Also: hasPrefix
public NSArray componentsSeparatedByString(String separator)
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)
public NSData dataUsingEncoding(
int encoding,
boolean flag)
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.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: canBeConvertedToEncoding
public int fastestEncoding()
See Also: smallestEncoding
public boolean hasPrefix(String aString)
AnchoredSearch
option.
See "Working with String Objects" in the class cluster description
for more information.See Also: hasSuffix
public boolean hasSuffix(String aString)
AnchoredSearch
and BackwardsSearch
options.
See "Working with String Objects" in the class cluster description
for more information.See Also: hasPrefix
public int length()
public NSRange lineRangeForRange(NSRange aRange)
See Also: substringWithRange
public NSRange rangeOfString(String aString)
public NSRange rangeOfString(
String aString,
int mask,
NSRange aRange)
CaseInsensitiveSearch
LiteralSearch
BackwardsSearch
AnchoredSearch
See "Working with String Objects" in the class description for details on these options. Throws an NSRangeException if any part of aRange lies beyond the end of the string. Returns a range of {NotFound, 0} if subString is the null string.
public int smallestEncoding()
See Also: fastestEncoding
public String string()
public String substringWithRange(NSRange aRange)
public boolean writeToURL(
java.net.URL anURL,
boolean atomically)
atomically is ignored if anURL is not of a type that can be accessed atomically.
See Also: defaultCStringEncoding
public boolean writeToURL(
java.net.URL anURL,
boolean aBoolean,
int anInt)