PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSStringReference


Inherits from:
NSObject
Package:
com.apple.yellow.foundation


Class Description


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" .


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.


Creating and Converting String Objects


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.


Working with String Objects


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.


Manipulating Paths


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/...").




Constants


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



Method Types


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


Constructors



NSStringReference

public NSStringReference()

Description forthcoming.

public NSStringReference( NSData aData, int anInt)

Description forthcoming.

public NSStringReference(java.net.URL anURL)

Description forthcoming.

public NSStringReference( java.net.URL anURL, int anInt)

Description forthcoming.


Static Methods



availableStringEncodings

public static NSArray availableStringEncodings()

Returns a zero-terminated list of the encodings string objects support in the application's environment. Among the more commonly used are:

See the "Types and Constants" section of the Foundation Kit documentation for a complete list and descriptions of supported encodings.

See Also: localizedNameOfStringEncoding



defaultCStringEncoding

public static int defaultCStringEncoding()

Returns the C string encoding assumed for any method accepting a C string as an argument. (These methods use ...CString... in the keywords for such arguments; for example, stringWithCString:). The default C string encoding is determined from system information, and can't be changed programmatically for an individual process. See the description of NSStringEncoding in the "Types and Constants" section for a full list of supported encodings.

localizedNameOfStringEncoding

public static String localizedNameOfStringEncoding(int encoding)

Returns a human-readable string giving the name of encoding in the current locale's language.


Instance Methods



canBeConvertedToEncoding

public boolean canBeConvertedToEncoding(int encoding)

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.

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



characterAtIndex

public char characterAtIndex(int index)

Returns the character at the array position given by index. Throws a RangeException if index lies beyond the end of the string.

commonPrefixWithString

public String commonPrefixWithString( String aString, int mask)

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. 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:

See "Working with String Objects" in the class cluster description for details on these options.

See Also: hasPrefix



componentsSeparatedByString

public NSArray componentsSeparatedByString(String separator)

Returns an NSArray containing substrings from the receiver that have been divided by separator. 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

public NSData dataUsingEncoding( int encoding, boolean flag)

Returns an NSData object containing a representation of the receiver in encoding. 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.

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



fastestEncoding

public int fastestEncoding()

Returns the fastest encoding to which the receiver may be converted without loss of information. "Fastest" applies to retrieval of characters from the string. This encoding may not be space efficient.

See Also: smallestEncoding





hasPrefix

public boolean hasPrefix(String aString)

Returns true if aString matches the beginning characters of the receiver, false otherwise. Returns false if aString is the null string. This method is a convenience for comparing strings using the AnchoredSearch option. See "Working with String Objects" in the class cluster description for more information.

See Also: hasSuffix



hasSuffix

public boolean hasSuffix(String aString)

Returns true if aString matches the ending characters of the receiver, false otherwise. Returns false if aString is the null string. This method is a convenience for comparing strings using the AnchoredSearch and BackwardsSearch options. See "Working with String Objects" in the class cluster description for more information.

See Also: hasPrefix



length

public int length()

Returns the number of Unicode characters in the receiver. This 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

public NSRange lineRangeForRange(NSRange aRange)

Returns the smallest range of lines containing aRange, including the characters that terminate the line.

See Also: substringWithRange



rangeOfString

public NSRange rangeOfString(String aString)

public NSRange rangeOfString( String aString, int mask, NSRange aRange)

Returns an NSRange giving the location and length of the first occurrence of subString within aRange in the receiver. If subString isn't found, the length of the returned NSRange is zero. 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:

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.



smallestEncoding

public int smallestEncoding()

Returns the smallest encoding to which the receiver can be converted without loss of information. 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: fastestEncoding



string

public String string()

Description forthcoming.

substringWithRange

public String substringWithRange(NSRange aRange)

Returns a string object containing the characters of the receiver that lie within aRange. Throws a RangeException if any part of aRange lies beyond the end of the string.

writeToURL

public boolean writeToURL( java.net.URL anURL, boolean atomically)

Writes the string's characters to the location named by path, returning true on success and false on failure. If atomically is true, attempts to write the location safely so an existing location named by anURL is not overwritten, nor does a new location at anURL actually get created, unless the write is successful. The string is written in the default C string encoding if possible (that is, if no information would be lost), in the Unicode encoding otherwise.

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)

Description forthcoming.


Table of Contents