Up

# NSString class reference

### Authors

Andrew Kachites McCallum (`mccallum@gnu.ai.mit.edu`)

Copyright: (C) 1995-2012 Free Software Foundation, Inc.

### Contents -

1. Portable path handling
2. Software documentation for the NSMutableString class
3. Software documentation for the NSString class
4. Software documentation for the NXConstantString class

# Portable path handling

Portable path handling (across both unix-like and mswindows operating systems) requires some care. A modern operating system uses the concept of a single root to the filesystem, but mswindows has multiple filesystems with no common root, so code must be aware of this. There is also the more minor issue that windows often uses a backslash as a separator between the components of a path and unix-like systems always use forward slash.
On windows there is also the issue that two styles of path are used, most commonly with a drive letter and a path on that drive (eg. 'C:\directory\file') but also UNC paths (eg. '//host/share/directory/file') so path handling functions must deal with both formats.

GNUstep has three path handling modes, 'gnustep', 'unix', and 'windows'. The mode defaults to 'gnustep' but may be set using the GSPathHandling() function.
You should probably stick to using the default 'gnustep' mode in which the path handling methods cope with both 'unix' and 'windows' style paths in portable and tolerant manner:
Paths are read in literally so they can be in the native format provided by the operating system or in a non-native format. See [NSFileManager -stringWithFileSystemRepresentation:length:] .
Paths are written out using the native format of the system the application is running on (eg on windows slashes are converted to backslashes). See [NSFileManager -fileSystemRepresentationWithPath:] .
The path handling methods accept either a forward or backward slash as a path separator when parsing any path.
Unless operating in 'unix' mode, a leading letter followed by a colon is considered the start of a windows style path (the drive specifier), and a path beginning with something of the form '//host/share/' is considered the start of a UNC style path.
The path handling methods add forward slashes when building new paths internally or when standardising paths, so those path strings provide a portable representation (as long as they are relative paths, not including system specific roots).
An important case to note is that on windows a path which looks at first glance like an absolute path may actually be a relative one.
'C:file' is a relative path because it specifies a file on the C drive but does not say what directory it is in.
Similarly, '/dir/file' is a relative path because it specifies the full location fo a file on a drive, but does not specify which drive it is on.

As a consequence of this path handling, you are able to work completely portably using relative paths (adding components, extensions and relative paths to a pth, or removing components, extensions and relative paths from a path etc), and when you save paths as strings in files which may be transferred to another platform, you should save a relative path.
When you need to know absolute paths of various points in the filesystem, you can use various path utility functions to obtain those absolute paths. For instance, instead of saving an absolute path to a file, you might want to save a path relative to a user's home directory. You could do that by calling NSHomeDirectory() to get the home directory, and only saving the part of the full path after that prefix.

# Software documentation for the NSMutableString class

## NSMutableString : NSString

> Declared in:
>   Foundation/NSString.h

Availability: OpenStep
This is the mutable form of the NSString class.
Method summary

- +string
- +stringWithCString:
- +stringWithCString:length:
- +stringWithCapacity:
- +stringWithCharacters:length:
- +stringWithContentsOfFile:
- +stringWithFormat:,...
- -appendFormat:,...
- -appendString:
- -deleteCharactersInRange:
- -initWithCapacity:
- -insertString:atIndex:
- -replaceCharactersInRange:withString:
- -replaceOccurrencesOfString:withString:options:range:
- -setString:

### string

+ (id) string;
Availability: OpenStep
Constructs an empty string.

### stringWithCString:

+ (id) stringWithCString: (const char*)byteString;
Availability: OpenStep
Create a string based on the given C (char[]) string, which should be null-terminated and encoded in the default C string encoding. (Characters will be converted to unicode representation internally.)

### stringWithCString: length:

+ (id) stringWithCString: (const char*)byteString length: (NSUInteger)length;
Availability: OpenStep
Create a string based on the given C (char[]) string, which may contain null bytes and should be encoded in the default C string encoding. (Characters will be converted to unicode representation internally.)

### stringWithCapacity:

+ (NSMutableString*) stringWithCapacity: (NSUInteger)capacity;
Availability: OpenStep
Constructs an empty string with initial buffer size of capacity.

### stringWithCharacters: length:

+ (id) stringWithCharacters: (const unichar*)characters length: (NSUInteger)length;
Availability: OpenStep
Create a string of unicode characters.

### stringWithContentsOfFile:

+ (id) stringWithContentsOfFile: (NSString*)path;
Availability: OpenStep
Load contents of file at path into a new string. Will interpret file as containing direct unicode if it begins with the unicode byte order mark, else converts to unicode using default C string encoding.

### stringWithFormat: ,...

+ (id) stringWithFormat: (NSString*)format,...;
Availability: OpenStep
Creates a new string using C printf-style formatting. First argument should be a constant format string, like ' `@"float val = %f"` ', remaining arguments should be the variables to print the values of, comma-separated.

### appendFormat: ,...

- (void) appendFormat: (NSString*)format,...;
Availability: OpenStep
Modifies this string by appending string described by given format.

### appendString:

- (void) appendString: (NSString*)aString;
Availability: OpenStep
Modifies this string by appending aString.

### deleteCharactersInRange:

- (void) deleteCharactersInRange: (NSRange)range;
Availability: OpenStep
Modifies this instance by deleting specified range of characters.

### initWithCapacity:

- (id) initWithCapacity: (NSUInteger)capacity;
Availability: OpenStep
This is a designated initialiser for the class.
Subclasses must override this method.
Constructs an empty string with initial buffer size of capacity.
Calls -init (which does nothing but maintain MacOS-X compatibility), and needs to be re-implemented in subclasses in order to have all other initialisers work.

### insertString: atIndex:

- (void) insertString: (NSString*)aString atIndex: (NSUInteger)loc;
Availability: OpenStep
Modifies this instance by inserting aString at loc.

### replaceCharactersInRange: withString:

- (void) replaceCharactersInRange: (NSRange)range withString: (NSString*)aString;
Availability: OpenStep
Modifies this instance by deleting characters in range and then inserting aString at its beginning.

### replaceOccurrencesOfString: withString: options: range:

- (NSUInteger) replaceOccurrencesOfString: (NSString*)replace withString: (NSString*)by options: (NSUInteger)opts range: (NSRange)searchRange;
Availability: OpenStep
Replaces all occurrences of the replace string with the by string, for those cases where the entire replace string lies within the specified searchRange value.
The value of opts determines the direction of the search is and whether only leading/trailing occurrences (anchored search) of replace are substituted.
Raises NSInvalidArgumentException if either string argument is `nil`.
Raises NSRangeException if part of searchRange is beyond the end of the receiver.

### setString:

- (void) setString: (NSString*)aString;
Availability: OpenStep
Modifies this instance by replacing contents with those of aString.

# Software documentation for the NSString class

## NSString : NSObject

> Declared in:
>   Foundation/NSString.h

> Conforms to:
>   NSCoding
>   NSCopying
>   NSMutableCopying

Availability: OpenStep

`NSString` objects represent an immutable string of Unicode 3.0 characters. These may be accessed individually as type `unichar`, an unsigned short.
The NSMutableString subclass represents a modifiable string. Both are implemented as part of a class cluster and the instances you receive may actually be of unspecified concrete subclasses.

A constant `NSString` can be created using the following syntax: `@"..."`, where the contents of the quotes are the string, using only ASCII characters.

A variable string can be created using a C printf-like format, as in `[NSString stringWithFormat: @"Total is %f", t]` .

To create a concrete subclass of `NSString` , you must have your class inherit from `NSString` and override at least the two primitive methods - -length and -characterAtIndex:

In general the rule is that your subclass must override any initialiser that you want to use with it. The GNUstep implementation relaxes that to say that, you may override only the designated initialiser and the other initialisation methods should work.

Where an NSString instance method returns an NSString object, the class of the actual object returned may be any subclass of NSString. The actual value returned may be a new autoreleased object, an autoreleased copy of the receiver, or the receiver itsself. While the abstract base class implementations of methods (other than initialisers) will avoid returning mutable strings by returning an autoreleased copy of a mutable receiver, concrete subclasses may behave differently, so code should not rely upon the mutability of returned strings nor upon their lifetime being greater than that of the receiver which returned them.

Method summary

- +availableStringEncodings
- +constantStringClass
- +defaultCStringEncoding
- +localizedNameOfStringEncoding:
- +localizedStringWithFormat:,...
- +pathWithComponents:
- +string
- +stringWithCString:
- +stringWithCString:encoding:
- +stringWithCString:length:
- +stringWithCharacters:length:
- +stringWithContentsOfFile:
- +stringWithContentsOfFile:encoding:error:
- +stringWithContentsOfFile:usedEncoding:error:
- +stringWithContentsOfURL:
- +stringWithContentsOfURL:encoding:error:
- +stringWithContentsOfURL:usedEncoding:error:
- +stringWithFormat:,...
- +stringWithString:
- +stringWithUTF8String:
- -UTF8String
- -_baseLength
- -boolValue
- -cString
- -cStringLength
- -cStringUsingEncoding:
- -canBeConvertedToEncoding:
- -capitalizedString
- -caseInsensitiveCompare:
- -characterAtIndex:
- -commonPrefixWithString:options:
- -compare:
- -compare:options:
- -compare:options:range:
- -compare:options:range:locale:
- -completePathIntoString:caseSensitive:matchesIntoArray:filterTypes:
- -componentsSeparatedByCharactersInSet:
- -componentsSeparatedByString:
- -containsString:
- -dataUsingEncoding:
- -dataUsingEncoding:allowLossyConversion:
- -decomposedStringWithCanonicalMapping
- -decomposedStringWithCompatibilityMapping
- -description
- -doubleValue
- -fastestEncoding
- -fileSystemRepresentation
- -floatValue
- -getCString:
- -getCString:maxLength:
- -getCString:maxLength:encoding:
- -getCString:maxLength:range:remainingRange:
- -getCharacters:
- -getCharacters:range:
- -getFileSystemRepresentation:maxLength:
- -getLineStart:end:contentsEnd:forRange:
- -getParagraphStart:end:contentsEnd:forRange:
- -hasPrefix:
- -hasSuffix:
- -hash
- -init
- -initWithBytes:length:encoding:
- -initWithBytesNoCopy:length:encoding:freeWhenDone:
- -initWithCString:
- -initWithCString:encoding:
- -initWithCString:length:
- -initWithCStringNoCopy:length:freeWhenDone:
- -initWithCharacters:length:
- -initWithCharactersNoCopy:length:freeWhenDone:
- -initWithContentsOfFile:
- -initWithContentsOfFile:encoding:error:
- -initWithContentsOfFile:usedEncoding:error:
- -initWithContentsOfURL:
- -initWithContentsOfURL:encoding:error:
- -initWithContentsOfURL:usedEncoding:error:
- -initWithData:encoding:
- -initWithFormat:,...
- -initWithFormat:arguments:
- -initWithFormat:locale:,...
- -initWithFormat:locale:arguments:
- -initWithString:
- -initWithUTF8String:
- -intValue
- -integerValue
- -isAbsolutePath
- -isEqual:
- -isEqualToString:
- -lastPathComponent
- -length
- -lengthOfBytesUsingEncoding:
- -lineRangeForRange:
- -localizedCaseInsensitiveCompare:
- -localizedCompare:
- -longLongValue
- -lossyCString
- -lowercaseString
- -maximumLengthOfBytesUsingEncoding:
- -paragraphRangeForRange:
- -pathComponents
- -pathExtension
- -precomposedStringWithCanonicalMapping
- -precomposedStringWithCompatibilityMapping
- -propertyList
- -propertyListFromStringsFileFormat
- -rangeOfCharacterFromSet:
- -rangeOfCharacterFromSet:options:
- -rangeOfCharacterFromSet:options:range:
- -rangeOfComposedCharacterSequenceAtIndex:
- -rangeOfComposedCharacterSequencesForRange:
- -rangeOfString:
- -rangeOfString:options:
- -rangeOfString:options:range:
- -rangeOfString:options:range:locale:
- -smallestEncoding
- -stringByAbbreviatingWithTildeInPath
- -stringByAddingPercentEscapesUsingEncoding:
- -stringByAppendingFormat:,...
- -stringByAppendingPathComponent:
- -stringByAppendingPathExtension:
- -stringByAppendingString:
- -stringByDeletingLastPathComponent
- -stringByDeletingPathExtension
- -stringByExpandingTildeInPath
- -stringByPaddingToLength:withString:startingAtIndex:
- -stringByReplacingCharactersInRange:withString:
- -stringByReplacingOccurrencesOfString:withString:
- -stringByReplacingOccurrencesOfString:withString:options:range:
- -stringByReplacingPercentEscapesUsingEncoding:
- -stringByResolvingSymlinksInPath
- -stringByStandardizingPath
- -stringByTrimmingCharactersInSet:
- -stringsByAppendingPaths:
- -substringFromIndex:
- -substringToIndex:
- -substringWithRange:
- -uppercaseString
- -writeToFile:atomically:
- -writeToFile:atomically:encoding:error:
- -writeToURL:atomically:
- -writeToURL:atomically:encoding:error:

### availableStringEncodings

+ (NSStringEncoding*) availableStringEncodings;
Availability: MacOS-X 10.0.0
Returns an array of all available string encodings, terminated by a null value.

### constantStringClass

+ (Class) constantStringClass;
Availability: Not in OpenStep/MacOS-X
Return the class used to store constant strings (those ascii strings placed in the source code using the @"this is a string" syntax).
Use this method to obtain the constant string class rather than using the obsolete name NXConstantString in your code... with more recent compiler versions the name of this class is variable (and will automatically be changed by GNUstep to avoid conflicts with the default implementation in the Objective-C runtime library).

### defaultCStringEncoding

+ (NSStringEncoding) defaultCStringEncoding;
Availability: OpenStep

Returns the encoding used for any method accepting a C string. This value is determined automatically from the program's environment and cannot be changed programmatically.

You should NOT override this method in an attempt to change the encoding being used... it won't work.

In GNUstep, this encoding is determined by the initial value of the `GNUSTEP_STRING_ENCODING` environment variable. If this is not defined, `NSISOLatin1StringEncoding` is assumed.

### localizedNameOfStringEncoding:

+ (NSString*) localizedNameOfStringEncoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.0.0
Returns the localized name of the encoding specified.

### localizedStringWithFormat: ,...

+ (NSString*) localizedStringWithFormat: (NSString*)format,...;
Availability: MacOS-X 10.0.0
Returns an autoreleased string with given format using the default locale.

### pathWithComponents:

+ (NSString*) pathWithComponents: (NSArray*)components;
Availability: MacOS-X 10.0.0
Concatenates the path components in the array and returns the result.
This method does not remove empty path components, but does recognize an empty initial component as a special case meaning that the string returned will begin with a slash.

### string

+ (id) string;
Availability: OpenStep
Create an empty string.

### stringWithCString:

+ (id) stringWithCString: (const char*)byteString;
Availability: OpenStep
Create a string based on the given C (char[]) string, which should be null-terminated and encoded in the default C string encoding. (Characters will be converted to unicode representation internally.)

### stringWithCString: encoding:

+ (id) stringWithCString: (const char*)byteString encoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.4.0, Base 1.2.0
Create a string based on the given C (char[]) string, which should be null-terminated and encoded in the specified C string encoding. Characters may be converted to unicode representation internally.

### stringWithCString: length:

+ (id) stringWithCString: (const char*)byteString length: (NSUInteger)length;
Availability: OpenStep
Create a string based on the given C (char[]) string, which may contain null bytes and should be encoded in the default C string encoding. (Characters will be converted to unicode representation internally.)

### stringWithCharacters: length:

+ (id) stringWithCharacters: (const unichar*)chars length: (NSUInteger)length;
Availability: OpenStep
Create a string of unicode characters.

### stringWithContentsOfFile:

+ (id) stringWithContentsOfFile: (NSString*)path;
Availability: OpenStep
Load contents of file at path into a new string. Will interpret file as containing direct unicode if it begins with the unicode byte order mark, else converts to unicode using default C string encoding.

### stringWithContentsOfFile: encoding: error:

+ (id) stringWithContentsOfFile: (NSString*)path encoding: (NSStringEncoding)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Load contents of file at path into a new string using the -initWithContentsOfFile:encoding:error: method.

### stringWithContentsOfFile: usedEncoding: error:

+ (id) stringWithContentsOfFile: (NSString*)path usedEncoding: (NSStringEncoding*)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Load contents of file at path into a new string using the -initWithContentsOfFile:usedEncoding:error: method.

### stringWithContentsOfURL:

+ (id) stringWithContentsOfURL: (NSURL*)url;
Availability: MacOS-X 10.0.0
Load contents of given URL into a new string. Will interpret contents as containing direct unicode if it begins with the unicode byte order mark, else converts to unicode using default C string encoding.

### stringWithContentsOfURL: encoding: error:

+ (id) stringWithContentsOfURL: (NSURL*)url encoding: (NSStringEncoding)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Description forthcoming.

### stringWithContentsOfURL: usedEncoding: error:

+ (id) stringWithContentsOfURL: (NSURL*)url usedEncoding: (NSStringEncoding*)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Description forthcoming.

### stringWithFormat: ,...

+ (id) stringWithFormat: (NSString*)format,...;
Availability: OpenStep
Creates a new string using C printf-style formatting. First argument should be a constant format string, like ' `@"float val = %f"` ', remaining arguments should be the variables to print the values of, comma-separated.

### stringWithString:

+ (id) stringWithString: (NSString*)aString;
Availability: MacOS-X 10.0.0
Create a copy of aString.

### stringWithUTF8String:

+ (id) stringWithUTF8String: (const char*)bytes;
Availability: MacOS-X 10.0.0
Create a string based on the given UTF-8 string, null-terminated.
Raises NSInvalidArgumentException if given NULL pointer.

### UTF8String

- (const char*) UTF8String;
Availability: MacOS-X 10.0.0
Returns null-terminated UTF-8 version of this unicode string. The char[] memory comes from an autoreleased object, so it will eventually go out of scope.

### _baseLength

- (int) _baseLength;
Availability: OpenStep
Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.

### boolValue

- (BOOL) boolValue;
Availability: MacOS-X 10.5.0
Returns `YES` when scanning the receiver's text from left to right finds an initial digit in the range 1-9 or a letter in the set ('Y', 'y', 'T', 't').
Any trailing characters are ignored.
Any leading whitespace or zeros or signs are also ignored.
Returns `NO` if the above conditions are not met.

### cString

- (const char*) cString;
Availability: OpenStep
Returns a pointer to a null terminated string of 8-bit characters in the default encoding. The memory pointed to is not owned by the caller, so the caller must copy its contents to keep it. Raises an `NSCharacterConversionException` if loss of information would occur during conversion. (See -canBeConvertedToEncoding: .)

### cStringLength

- (NSUInteger) cStringLength;
Availability: OpenStep
Returns length of a version of this unicode string converted to bytes using the default C string encoding. If the conversion would result in information loss, the results are unpredictable. Check -canBeConvertedToEncoding: first.

### cStringUsingEncoding:

- (const char*) cStringUsingEncoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.4.0, Base 1.2.0
Returns a pointer to a null terminated string of characters in the specified encoding.
NB. under GNUstep you can used this to obtain a nul terminated utf-16 string (sixteen bit characters) as well as eight bit strings.
The memory pointed to is not owned by the caller, so the caller must copy its contents to keep it.
Raises an `NSCharacterConversionException` if loss of information would occur during conversion.

### canBeConvertedToEncoding:

- (BOOL) canBeConvertedToEncoding: (NSStringEncoding)encoding;
Availability: OpenStep
Returns whether this string can be converted to the given string encoding without information loss.

### capitalizedString

- (NSString*) capitalizedString;
Availability: OpenStep
Returns version of string in which each whitespace-delimited word is capitalized (not every letter). Conversion to capitals is done in a unicode-compliant manner but there may be exceptional cases where behavior is not what is desired.

### caseInsensitiveCompare:

- (NSComparisonResult) caseInsensitiveCompare: (NSString*)aString;
Availability: MacOS-X 10.0.0
Compares this string with aString ignoring case. Convenience for -compare:options:range: with the `NSCaseInsensitiveSearch` option, in the default locale.

### characterAtIndex:

- (unichar) characterAtIndex: (NSUInteger)index;
Availability: OpenStep
Returns unicode character at index. `unichar` is an unsigned short. Thus, a 16-bit character is returned.

### commonPrefixWithString: options:

- (NSString*) commonPrefixWithString: (NSString*)aString options: (NSUInteger)mask;
Availability: OpenStep
Returns the largest initial portion of this instance shared with aString. mask may be either `NSCaseInsensitiveSearch` or `NSLiteralSearch`. The latter requests a literal byte-by-byte comparison, which is fastest but may return inaccurate results in cases where two different composed character sequences may be used to express the same character.

### compare:

- (NSComparisonResult) compare: (NSString*)aString;
Availability: OpenStep

Compares this instance with aString. Returns `NSOrderedAscending`, `NSOrderedDescending`, or `NSOrderedSame`, depending on whether this instance occurs before or after string in lexical order, or is equal to it.

### compare: options:

- (NSComparisonResult) compare: (NSString*)aString options: (NSUInteger)mask;
Availability: OpenStep

Compares this instance with aString. mask may be either `NSCaseInsensitiveSearch` or `NSLiteralSearch`. The latter requests a literal byte-by-byte comparison, which is fastest but may return inaccurate results in cases where two different composed character sequences may be used to express the same character.

### compare: options: range:

- (NSComparisonResult) compare: (NSString*)aString options: (NSUInteger)mask range: (NSRange)aRange;
Availability: OpenStep

Compares this instance with string. mask may be either `NSCaseInsensitiveSearch` or `NSLiteralSearch`. The latter requests a literal byte-by-byte comparison, which is fastest but may return inaccurate results in cases where two different composed character sequences may be used to express the same character. aRange refers to this instance, and should be set to 0..length to compare the whole string.

### compare: options: range: locale:

- (NSComparisonResult) compare: (NSString*)string options: (NSUInteger)mask range: (NSRange)compareRange locale: (id)locale;
Availability: MacOS-X 10.0.0

Compares this instance with string. If locale is an NSLocale instance and ICU is available, performs a comparison using the ICU collator for that locale. If locale is an instance of a class other than NSLocale, perform a comparison using +[NSLocale currentLocale]. If locale is `nil`, or ICU is not available, use a POSIX-style collation (for example, latin capital letters A-Z are ordered before all of the lowercase letter, a-z.)

mask may be `NSLiteralSearch` , which requests a literal byte-by-byte comparison, which is fastest but may return inaccurate results in cases where two different composed character sequences may be used to express the same character; `NSCaseInsensitiveSearch`, which ignores case differences; `NSDiacriticInsensitiveSearch` which ignores accent differences; `NSNumericSearch`, which sorts groups of digits as numbers, so "abc2" sorts before "abc100".

compareRange refers to this instance, and should be set to 0..length to compare the whole string.

Returns `NSOrderedAscending`, `NSOrderedDescending`, or `NSOrderedSame`, depending on whether this instance occurs before or after string in lexical order, or is equal to it.

### completePathIntoString: caseSensitive: matchesIntoArray: filterTypes:

- (NSUInteger) completePathIntoString: (NSString**)outputName caseSensitive: (BOOL)flag matchesIntoArray: (NSArray**)outputArray filterTypes: (NSArray*)filterTypes;
Availability: OpenStep
Attempts to complete this string as a path in the filesystem by finding a unique completion if one exists and returning it by reference in outputName (which must be a non-nil pointer), or if it finds a set of completions they are returned by reference in outputArray, if it is non-nil. filterTypes can be an array of strings specifying extensions to consider; files without these extensions will be ignored and will not constitute completions. Returns 0 if no match found, else a positive number that is only accurate if outputArray was non-nil.

### componentsSeparatedByCharactersInSet:

- (NSArray*) componentsSeparatedByCharactersInSet: (NSCharacterSet*)separator;
Availability: MacOS-X 10.5.0

Returns an array of NSString s representing substrings of this string that are separated by characters in the set (which must not be `nil`). If there are no occurrences of separator, the whole string is returned. If string begins or ends with separator, empty strings will be returned for those positions.

### componentsSeparatedByString:

- (NSArray*) componentsSeparatedByString: (NSString*)separator;
Availability: OpenStep

Returns an array of NSString s representing substrings of this string that are separated by separator (which itself is never returned in the array). If there are no occurrences of separator, the whole string is returned. If string begins or ends with separator, empty strings will be returned for those positions.

Note, use an NSScanner if you need more sophisticated parsing.

### containsString:

- (BOOL) containsString: (NSString*)string;
Availability: Not in OpenStep/MacOS-X
Returns `YES` if the receiver contains string, otherwise, `NO`.

### dataUsingEncoding:

- (NSData*) dataUsingEncoding: (NSStringEncoding)encoding;
Availability: OpenStep
Converts string to a byte array in the given encoding, returning `nil` if this would result in information loss.

### dataUsingEncoding: allowLossyConversion:

- (NSData*) dataUsingEncoding: (NSStringEncoding)encoding allowLossyConversion: (BOOL)flag;
Availability: OpenStep
Converts string to a byte array in the given encoding. If flag is `NO`, `nil` would be returned if this would result in information loss.

### decomposedStringWithCanonicalMapping

- (NSString*) decomposedStringWithCanonicalMapping;
Availability: MacOS-X 10.2.0
Returns a copy of the receiver normalised using the D form.

### decomposedStringWithCompatibilityMapping

- (NSString*) decomposedStringWithCompatibilityMapping;
Availability: MacOS-X 10.2.0
Returns a copy of the receiver normalised using the KD form.

### description

- (NSString*) description;
Availability: OpenStep
Returns `self`.

### doubleValue

- (double) doubleValue;
Availability: MacOS-X 10.0.0
Returns the string's content as a double. Skips leading whitespace.
Conversion is not localised (i.e. uses '.' as the decimal separator).
Returns 0.0 on underflow or if the string does not contain a number.

### fastestEncoding

- (NSStringEncoding) fastestEncoding;
Availability: OpenStep
Returns the encoding with which this string can be converted without information loss that would result in most efficient character access.

### fileSystemRepresentation

- (const GSNativeChar*) fileSystemRepresentation;
Availability: OpenStep
Converts the receiver to a C string path expressed in the character encoding appropriate for the local host file system. This string will be automatically freed soon after it is returned, so copy it if you need it for long.
NB. On mingw32 systems the filesystem representation of a path is a 16-bit unicode character string, so you should only pass the value returned by this method to functions expecting wide characters.
This method uses [NSFileManager -fileSystemRepresentationWithPath:] to perform the conversion.

### floatValue

- (float) floatValue;
Availability: OpenStep
Returns the string's content as a float. Skips leading whitespace.
Conversion is not localised (i.e. uses '.' as the decimal separator).
Returns 0.0 on underflow or if the string does not contain a number.

### getCString:

- (void) getCString: (char*)buffer;
Availability: OpenStep
Deprecated... do not use.
. Use -getCString:maxLength:encoding: instead.

### getCString: maxLength:

- (void) getCString: (char*)buffer maxLength: (NSUInteger)maxLength;
Availability: OpenStep
Deprecated... do not use.
. Use -getCString:maxLength:encoding: instead.

### getCString: maxLength: encoding:

- (BOOL) getCString: (char*)buffer maxLength: (NSUInteger)maxLength encoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.4.0, Base 1.2.0
Retrieve up to maxLength bytes from the receiver into the buffer.
In GNUstep, this method implements the actual behavior of the MacOS-X method rather than it's documented behavior...
The maxLength argument must be the size (in bytes) of the area of memory pointed to by the buffer argument.
Returns `YES` on success.
Returns `NO` if maxLength is too small to hold the entire string including a terminating nul character.
If it returns `NO`, the terminating nul will not have been written to the buffer.
Raises an exception if the string can not be converted to the specified encoding without loss of information.
eg. If the receiver is @"hello" then the provided buffer must be at least six bytes long and the value of maxLength must be at least six if NSASCIIStringEncoding is requested, but they must be at least twelve if NSUnicodeStringEncoding is requested.

### getCString: maxLength: range: remainingRange:

- (void) getCString: (char*)buffer maxLength: (NSUInteger)maxLength range: (NSRange)aRange remainingRange: (NSRange*)leftoverRange;
Availability: OpenStep
Deprecated... do not use.
. Use -getCString:maxLength:encoding: instead.

### getCharacters:

- (void) getCharacters: (unichar*)buffer;
Availability: OpenStep
Returns this string as an array of 16-bit `unichar` ( unsigned short) values. buffer must be preallocated and should be capable of holding -length shorts.

### getCharacters: range:

- (void) getCharacters: (unichar*)buffer range: (NSRange)aRange;
Availability: OpenStep
Returns aRange of string as an array of 16-bit `unichar` ( unsigned short) values. buffer must be preallocated and should be capable of holding a sufficient number of shorts.

### getFileSystemRepresentation: maxLength:

- (BOOL) getFileSystemRepresentation: (GSNativeChar*)buffer maxLength: (NSUInteger)size;
Availability: OpenStep
Converts the receiver to a C string path using the character encoding appropriate to the local file system. This string will be stored into buffer if it is shorter (number of characters) than size, otherwise `NO` is returned.
NB. On mingw32 systems the filesystem representation of a path is a 16-bit unicode character string, so the buffer you pass to this method must be twice as many bytes as the size (number of characters) you expect to receive.
This method uses [NSFileManager -fileSystemRepresentationWithPath:] to perform the conversion.

### getLineStart: end: contentsEnd: forRange:

- (void) getLineStart: (NSUInteger*)startIndex end: (NSUInteger*)lineEndIndex contentsEnd: (NSUInteger*)contentsEndIndex forRange: (NSRange)aRange;
Availability: MacOS-X 10.0.0
Determines the smallest range of lines containing aRange and returns the locations in that range.
Lines are delimited by any of these character sequences, the longest (CRLF) sequence preferred.

- U+000A (linefeed)
- U+000D (carriage return)
- U+2028 (Unicode line separator)
- U+2029 (Unicode paragraph separator)
- U+000D U+000A (CRLF)

The index of the first character of the line at or before aRange is returned in startIndex.
The index of the first character of the next line after the line terminator is returned in endIndex.
The index of the last character before the line terminator is returned contentsEndIndex.
Raises an NSRangeException if the range is invalid, but permits the index arguments to be null pointers (in which case no value is returned in that argument).

### getParagraphStart: end: contentsEnd: forRange:

- (void) getParagraphStart: (NSUInteger*)startIndex end: (NSUInteger*)parEndIndex contentsEnd: (NSUInteger*)contentsEndIndex forRange: (NSRange)range;
Availability: MacOS-X 10.3.0
Not implemented

### hasPrefix:

- (BOOL) hasPrefix: (NSString*)aString;
Availability: OpenStep
Returns whether this string starts with aString.

### hasSuffix:

- (BOOL) hasSuffix: (NSString*)aString;
Availability: OpenStep
Returns whether this string ends with aString.

### hash

- (NSUInteger) hash;
Availability: OpenStep
Return 28-bit hash value (in 32-bit integer). The top few bits are used for other purposes in a bitfield in the concrete string subclasses, so we must not use the full unsigned integer.

### init

- (id) init;
Availability: OpenStep

In MacOS-X class clusters do not have designated initialisers, and there is a general rule that -init is treated as the designated initialiser of the class cluster, but that other intitialisers may not work as expected and would need to be individually overridden in any subclass.

GNUstep tries to make it easier to subclass a class cluster, by making class clusters follow the same convention as normal classes, so the designated initialiser is the richest initialiser. This means that all other initialisers call the documented designated initialiser (which calls -init only for MacOS-X compatibility), and anyone writing a subclass only needs to override that one initialiser in order to have all the other ones work.

For MacOS-X compatibility, you may also need to override various other initialisers. Exactly which ones, you will need to determine by trial on a MacOS-X system... and may vary between releases of MacOS-X. So to be safe, on MacOS-X you probably need to re-implement all the class cluster initialisers you might use in conjunction with your subclass.

NB. The GNUstep designated initialiser for the NSString class cluster has changed to -initWithBytesNoCopy:length:encoding:freeWhenDone: from -initWithCharactersNoCopy:length:freeWhenDone: and older code subclassing NSString will need to be updated.

### initWithBytes: length: encoding:

- (id) initWithBytes: (const void*)bytes length: (NSUInteger)length encoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.4.0, Base 1.2.0
Initialises the receiver with a copy of the supplied length of bytes, using the specified encoding.
For NSUnicodeStringEncoding and NSUTF8String encoding, a Byte Order Marker (if present at the start of the data) is removed automatically.
If the data can not be interpreted using the encoding, the receiver is released and `nil` is returned.

### initWithBytesNoCopy: length: encoding: freeWhenDone:

- (id) initWithBytesNoCopy: (void*)bytes length: (NSUInteger)length encoding: (NSStringEncoding)encoding freeWhenDone: (BOOL)flag;
Availability: MacOS-X 10.4.0, Base 1.2.0
This is a designated initialiser for the class.
Subclasses must override this method.
Initialises the receiver with the supplied length of bytes, using the specified encoding.
For NSUnicodeStringEncoding and NSUTF8String encoding, a Byte Order Marker (if present at the start of the data) is removed automatically.
If the data is not in a format which can be used internally unmodified, it is copied, otherwise it is used as is. If the data is not copied the flag determines whether the string will free it when it is no longer needed (ie whether the new NSString instance 'owns' the memory).
In the case of non-owned memory, it is the caller's responsibility to ensure that the data continues to exist and is not modified until the receiver is deallocated.
If the data can not be interpreted using the encoding, the receiver is released and `nil` is returned.

Note, this is the most basic initialiser for strings. In the GNUstep implementation, your subclasses may override this initialiser in order to have all other functionality.

### initWithCString:

- (id) initWithCString: (const char*)byteString;
Availability: OpenStep

Initialize with given C string byteString, which should be null-terminated. Characters are converted to unicode based on the default C encoding. Copies the string.

### initWithCString: encoding:

- (id) initWithCString: (const char*)byteString encoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.4.0, Base 1.2.0

Initialize with given C string byteString up to first nul byte. Characters converted to unicode based on the specified C encoding. Copies the string.

### initWithCString: length:

- (id) initWithCString: (const char*)byteString length: (NSUInteger)length;
Availability: OpenStep

Initialize with given C string byteString up to length, regardless of presence of null bytes. Characters converted to unicode based on the default C encoding. Copies the string.

### initWithCStringNoCopy: length: freeWhenDone:

- (id) initWithCStringNoCopy: (char*)byteString length: (NSUInteger)length freeWhenDone: (BOOL)flag;
Availability: OpenStep

Initialize with given C string byteString up to length, regardless of presence of null bytes. Characters converted to unicode based on the default C encoding. Does not copy the string. If flag, frees its storage when this instance is deallocated.

See -initWithBytesNoCopy:length:encoding:freeWhenDone: for more details.

### initWithCharacters: length:

- (id) initWithCharacters: (const unichar*)chars length: (NSUInteger)length;
Availability: OpenStep

Initialize with given unicode chars up to length, regardless of presence of null bytes. Copies the string and frees copy when deallocated.

### initWithCharactersNoCopy: length: freeWhenDone:

- (id) initWithCharactersNoCopy: (unichar*)chars length: (NSUInteger)length freeWhenDone: (BOOL)flag;
Availability: OpenStep

Initialize with given unicode chars up to length, regardless of presence of null bytes. Does not copy the string. If flag, frees its storage when this instance is deallocated.

See -initWithBytesNoCopy:length:encoding:freeWhenDone: for more details.

### initWithContentsOfFile:

- (id) initWithContentsOfFile: (NSString*)path;
Availability: OpenStep

Initialises the receiver with the contents of the file at path.

Invokes [NSData -initWithContentsOfFile:] to read the file, then examines the data to infer its encoding type, and converts the data to a string using -initWithData:encoding:

The encoding to use is determined as follows... if the data begins with the 16-bit unicode Byte Order Marker, then it is assumed to be unicode data in the appropriate ordering and converted as such.
If it begins with a UTF8 representation of the BOM, the UTF8 encoding is used.
Otherwise, the default C String encoding is used.

Releases the receiver and returns `nil` if the file could not be read and converted to a string.

### initWithContentsOfFile: encoding: error:

- (id) initWithContentsOfFile: (NSString*)path encoding: (NSStringEncoding)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Description forthcoming.

### initWithContentsOfFile: usedEncoding: error:

- (id) initWithContentsOfFile: (NSString*)path usedEncoding: (NSStringEncoding*)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0

Initialises the receiver with the contents of the file at path.

Invokes [NSData -initWithContentsOfFile:] to read the file, then examines the data to infer its encoding type, and converts the data to a string using -initWithData:encoding:

The encoding to use is determined as follows... if the data begins with the 16-bit unicode Byte Order Marker, then it is assumed to be unicode data in the appropriate ordering and converted as such.
If it begins with a UTF8 representation of the BOM, the UTF8 encoding is used.
Otherwise, the default C String encoding is used.

Releases the receiver and returns `nil` if the file could not be read and converted to a string.

### initWithContentsOfURL:

- (id) initWithContentsOfURL: (NSURL*)url;
Availability: MacOS-X 10.0.0

Initialises the receiver with the contents of the given URL.

Invokes [NSData +dataWithContentsOfURL:] to read the contents, then examines the data to infer its encoding type, and converts the data to a string using -initWithData:encoding:

The encoding to use is determined as follows... if the data begins with the 16-bit unicode Byte Order Marker, then it is assumed to be unicode data in the appropriate ordering and converted as such.
If it begins with a UTF8 representation of the BOM, the UTF8 encoding is used.
Otherwise, the default C String encoding is used.

Releases the receiver and returns `nil` if the URL contents could not be read and converted to a string.

### initWithContentsOfURL: encoding: error:

- (id) initWithContentsOfURL: (NSURL*)url encoding: (NSStringEncoding)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Description forthcoming.

### initWithContentsOfURL: usedEncoding: error:

- (id) initWithContentsOfURL: (NSURL*)url usedEncoding: (NSStringEncoding*)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Description forthcoming.

### initWithData: encoding:

- (id) initWithData: (NSData*)data encoding: (NSStringEncoding)encoding;
Availability: OpenStep
Initialises the receiver with the supplied data, using the specified encoding.
For NSUnicodeStringEncoding and NSUTF8String encoding, a Byte Order Marker (if present at the start of the data) is removed automatically.
If the data can not be interpreted using the encoding, the receiver is released and `nil` is returned.

### initWithFormat: ,...

- (id) initWithFormat: (NSString*)format,...;
Availability: OpenStep
Invokes -initWithFormat:locale:arguments: with a `nil` locale.

### initWithFormat: arguments:

- (id) initWithFormat: (NSString*)format arguments: (va_list)argList;
Availability: OpenStep
Invokes -initWithFormat:locale:arguments: with a `nil` locale.

### initWithFormat: locale: ,...

- (id) initWithFormat: (NSString*)format locale: (NSDictionary*)locale,...;
Availability: MacOS-X 10.0.0
Invokes -initWithFormat:locale:arguments:

### initWithFormat: locale: arguments:

- (id) initWithFormat: (NSString*)format locale: (NSDictionary*)locale arguments: (va_list)argList;
Availability: MacOS-X 10.0.0
Initialises the string using the specified format and locale to format the following arguments.

### initWithString:

- (id) initWithString: (NSString*)string;
Availability: OpenStep
Initialize to be a copy of the given string.

### initWithUTF8String:

- (id) initWithUTF8String: (const char*)bytes;
Availability: MacOS-X 10.0.0
Initialize based on given null-terminated UTF-8 string bytes.

### intValue

- (int) intValue;
Availability: OpenStep

Returns the string's content as an int.
Current implementation uses a C runtime library function, which does not detect conversion errors -- use with care!

### integerValue

- (NSInteger) integerValue;
Availability: MacOS-X 10.5.0
Description forthcoming.

### isAbsolutePath

- (BOOL) isAbsolutePath;
Availability: MacOS-X 10.0.0
Returns `YES` if the receiver represents an absolute path...
Returns `NO` otherwise.
An absolute path in unix mode is one which begins with a slash or tilde.
In windows mode a drive specification (eg C:) followed by a slash or backslash, is an absolute path, as is any path beginning with a tilde.
In any mode a UNC path (//host/share...) is always absolute.
In the default gnustep path handling mode, the rules are the same as for windows, except that a path whose root is a slash denotes an absolute path when running on unix and a relative path when running under windows.

### isEqual:

- (BOOL) isEqual: (id)anObject;
Availability: OpenStep
Returns whether the receiver and an anObject are equals as strings. If anObject isn't an NSString, returns `NO`.

### isEqualToString:

- (BOOL) isEqualToString: (NSString*)aString;
Availability: OpenStep
Returns whether this instance is equal as a string to aString. See also -compare: and related methods.

### lastPathComponent

- (NSString*) lastPathComponent;
Availability: OpenStep
Returns a string containing the last path component of the receiver.
The path component is the last non-empty substring delimited by the ends of the string, or by path separator characters.
If the receiver only contains a root part, this method returns it.
If there are no non-empty substrings, this returns an empty string.
NB. In a windows UNC path, the host and share specification is treated as a single path component, even though it contains separators. So a string of the form '//host/share' may be returned.
Other special cases are apply when the string is the root.

       @"foo/bar" produces @"bar"
       @"foo/bar/" produces @"bar"
       @"/foo/bar" produces @"bar"
       @"/foo" produces @"foo"
       @"/" produces @"/" (root is a special case)
       @"" produces @""
       @"C:/" produces @"C:/" (root is a special case)
       @"C:" produces @"C:"
       @"//host/share/" produces @"//host/share/" (root is a special case)
       @"//host/share" produces @"//host/share"

### length

- (NSUInteger) length;
Availability: OpenStep
Returns the number of Unicode characters in this string, including the individual characters of composed character sequences,

### lengthOfBytesUsingEncoding:

- (NSUInteger) lengthOfBytesUsingEncoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.4.0, Base 1.2.0
Returns the number of bytes needed to encode the receiver in the specified encoding (without adding a nul character terminator).
Returns 0 if the conversion is not possible.

### lineRangeForRange:

- (NSRange) lineRangeForRange: (NSRange)aRange;
Availability: MacOS-X 10.0.0
Determines the smallest range of lines containing aRange and returns the information as a range.
Calls -getLineStart:end:contentsEnd:forRange: to do the work.

### localizedCaseInsensitiveCompare:

- (NSComparisonResult) localizedCaseInsensitiveCompare: (NSString*)string;
Availability: MacOS-X 10.0.0
Compares this instance with string, using +[NSLocale currentLocale], ignoring case.

### localizedCompare:

- (NSComparisonResult) localizedCompare: (NSString*)string;
Availability: MacOS-X 10.0.0
Compares this instance with string, using +[NSLocale currentLocale].

### longLongValue

- (long long) longLongValue;
Availability: MacOS-X 10.5.0
Description forthcoming.

### lossyCString

- (const char*) lossyCString;
Availability: MacOS-X 10.0.0
Returns a C string converted using the default C string encoding, which may result in information loss. The memory pointed to is not owned by the caller, so the caller must copy its contents to keep it.

### lowercaseString

- (NSString*) lowercaseString;
Availability: OpenStep
Returns a copy of the receiver with all characters converted to lowercase.

### maximumLengthOfBytesUsingEncoding:

- (NSUInteger) maximumLengthOfBytesUsingEncoding: (NSStringEncoding)encoding;
Availability: MacOS-X 10.4.0, Base 1.2.0
Returns a size guaranteed to be large enough to encode the receiver in the specified encoding (without adding a nul character terminator). This may be larger than the actual number of bytes needed.

### paragraphRangeForRange:

- (NSRange) paragraphRangeForRange: (NSRange)range;
Availability: MacOS-X 10.3.0
Not implemented

### pathComponents

- (NSArray*) pathComponents;
Availability: MacOS-X 10.0.0
Returns the path components of the receiver separated into an array.
If the receiver begins with a root sequence such as the path separator character (or a drive specification in windows) then that is used as the first element in the array.
Empty components are removed.
If a trailing path separator (which was not part of the root) was present, it is added as the last element in the array.

### pathExtension

- (NSString*) pathExtension;
Availability: OpenStep
Returns a new string containing the path extension of the receiver.
The path extension is a suffix on the last path component which starts with the extension separator (a '.') (for example.tiff is the pathExtension for /foo/bar.tiff).
Returns an empty string if no such extension exists.

       @"a.b" produces @"b"
       @"a.b/" produces @"b"
       @"/path/a.ext" produces @"ext"
       @"/path/a." produces @""
       @"/path/.a" produces @"" (.a is not an extension to a file)
       @".a" produces @"" (.a is not an extension to a file)

### precomposedStringWithCanonicalMapping

- (NSString*) precomposedStringWithCanonicalMapping;
Availability: MacOS-X 10.2.0
Returns a copy of the receiver normalised using the C form.

### precomposedStringWithCompatibilityMapping

- (NSString*) precomposedStringWithCompatibilityMapping;
Availability: MacOS-X 10.2.0
Returns a copy of the receiver normalised using the KC form.

### propertyList

- (id) propertyList;
Availability: OpenStep

Attempts to interpret the receiver as a property list and returns the result. If the receiver does not contain a string representation of a property list then the method returns `nil`.

Containers (arrays and dictionaries) are decoded as mutable objects.

There are three readable property list storage formats - The binary format used by NSSerializer does not concern us here, but there are two 'human readable' formats, the traditional OpenStep format (which is extended in GNUstep) and the XML format.

The [NSArray -descriptionWithLocale:indent:] and [NSDictionary -descriptionWithLocale:indent:] methods both generate strings containing traditional style property lists, but [NSArray -writeToFile:atomically:] and [NSDictionary -writeToFile:atomically:] generate either traditional or XML style property lists depending on the value of the GSMacOSXCompatible and NSWriteOldStylePropertyLists user defaults.
If GSMacOSXCompatible is `YES` then XML property lists are written unless NSWriteOldStylePropertyLists is also `YES`.
By default GNUstep writes old style data and always supports reading of either style.

The traditional format is more compact and more easily readable by people, but (without the GNUstep extensions) cannot represent date and number objects (except as strings). The XML format is more verbose and less readable, but can be fed into modern XML tools and thus used to pass data to non-OpenStep applications more readily.

The traditional format is strictly ascii encoded, with any unicode characters represented by escape sequences. The XML format is encoded as UTF8 data.

Both the traditional format and the XML format permit comments to be placed in property list documents. In traditional format the comment notations used in Objective-C programming are supported, while in XML format, the standard SGML comment sequences are used.

See the documentation for NSPropertyListSerialization for more information on what a property list is.

If the string cannot be parsed as a normal property list format, this method also tries to parse it as 'strings file' format (see the -propertyListFromStringsFileFormat method).

### propertyListFromStringsFileFormat

- (NSDictionary*) propertyListFromStringsFileFormat;
Availability: OpenStep

Reads a property list (see -propertyList) from a simplified file format. This format is a traditional style property list file containing a single dictionary, but with the leading '{' and trailing '}' characters omitted.

That is to say, the file contains only semicolon separated key/value pairs (and optionally comments). As a convenience, it is possible to omit the equals sign and the value, so an entry consists of a key string followed by a semicolon. In this case, the value for that key is assumed to be an empty string.

       // Strings file entries follow -
       key1 = " a string value";
       key2;	// This key has an empty string as a value.
       "Another key" = "a longer string value for th third key";

### rangeOfCharacterFromSet:

- (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet;
Availability: OpenStep
Returns position of first character in this string that is in aSet. Positions start at 0. If the character is a composed character sequence, the range returned will contain the whole sequence, else just the character itself.

### rangeOfCharacterFromSet: options:

- (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet options: (NSUInteger)mask;
Availability: OpenStep
Returns position of first character in this string that is in aSet. Positions start at 0. If the character is a composed character sequence, the range returned will contain the whole sequence, else just the character itself. mask may contain `NSCaseInsensitiveSearch`, `NSLiteralSearch` (don't consider alternate forms of composed characters equal), or `NSBackwardsSearch` (search from end of string).

### rangeOfCharacterFromSet: options: range:

- (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet options: (NSUInteger)mask range: (NSRange)aRange;
Availability: OpenStep
Returns position of first character in this string that is in aSet. Positions start at 0. If the character is a composed character sequence, the range returned will contain the whole sequence, else just the character itself. mask may contain `NSCaseInsensitiveSearch`, `NSLiteralSearch` (don't consider alternate forms of composed characters equal), or `NSBackwardsSearch` (search from end of string). Search only carried out within aRange.

### rangeOfComposedCharacterSequenceAtIndex:

- (NSRange) rangeOfComposedCharacterSequenceAtIndex: (NSUInteger)anIndex;
Availability: OpenStep
Unicode utility method. If character at anIndex is part of a composed character sequence anIndex (note indices start from 0), returns the full range of this sequence.

### rangeOfComposedCharacterSequencesForRange:

- (NSRange) rangeOfComposedCharacterSequencesForRange: (NSRange)range;
Availability: MacOS-X 10.5.0
Not implemented

### rangeOfString:

- (NSRange) rangeOfString: (NSString*)string;
Availability: OpenStep
Invokes -rangeOfString:options: with no options.

### rangeOfString: options:

- (NSRange) rangeOfString: (NSString*)string options: (NSUInteger)mask;
Availability: OpenStep
Invokes -rangeOfString:options:range: with the range set set to the range of the whole of the receiver.

### rangeOfString: options: range:

- (NSRange) rangeOfString: (NSString*)aString options: (NSUInteger)mask range: (NSRange)aRange;
Availability: OpenStep
Returns the range giving the location and length of the first occurrence of aString within aRange.
If aString does not exist in the receiver (an empty string is never considered to exist in the receiver), the length of the returned range is zero.
If aString is `nil`, an exception is raised.
If any part of aRange lies outside the range of the receiver, an exception is raised.
The options mask may contain the following options -

- `NSCaseInsensitiveSearch`
- `NSLiteralSearch`
- `NSBackwardsSearch`
- `NSAnchoredSearch`

The `NSAnchoredSearch` option means aString must occur at the beginning (or end, if `NSBackwardsSearch` is also given) of the string. Options should be OR'd together using `'|'`.

### rangeOfString: options: range: locale:

- (NSRange) rangeOfString: (NSString*)aString options: (NSStringCompareOptions)mask range: (NSRange)searchRange locale: (NSLocale*)locale;
Availability: MacOS-X 10.5.0
Not implemented

### smallestEncoding

- (NSStringEncoding) smallestEncoding;
Availability: OpenStep
Returns the smallest encoding with which this string can be converted without information loss.

### stringByAbbreviatingWithTildeInPath

- (NSString*) stringByAbbreviatingWithTildeInPath;
Availability: OpenStep
Returns a string where a prefix of the current user's home directory is abbreviated by '~', or returns the receiver (or an immutable copy) if it was not found to have the home directory as a prefix.

### stringByAddingPercentEscapesUsingEncoding:

- (NSString*) stringByAddingPercentEscapesUsingEncoding: (NSStringEncoding)e;
Availability: MacOS-X 10.0.0
Constructs a new ASCII string which is a representation of the receiver in which characters are escaped where necessary in order to produce a version of the string legal for inclusion within a URL.
The original string is converted to bytes using the specified encoding and then those bytes are escaped unless they correspond to 'legal' ASCII characters. The byte values escaped are any below 32 and any above 126 as well as 32 (space), 34 ("), 35 (#), 37 (%), 60 (<), 62 (>), 91 ([), 92 (\), 93 (]), 94 (^), 96 (~), 123 ({), 124 (|), and 125 (}).
Returns `nil` if the receiver cannot be represented using the specified encoding.
NB. This behavior is MacOS-X (4.2) compatible, and it should be noted that it does not produce a string suitable for use as a field value in a url-encoded form as it does not escape the '+', '=' and '&' characters used in such forms. If you need to add a string as a form field value (or name) you must add percent escapes for those characters yourself.

### stringByAppendingFormat: ,...

- (NSString*) stringByAppendingFormat: (NSString*)format,...;
Availability: OpenStep
Constructs a new string consisting of this instance followed by the string specified by format.

### stringByAppendingPathComponent:

- (NSString*) stringByAppendingPathComponent: (NSString*)aString;
Availability: OpenStep
Returns a new string with the path component given in aString appended to the receiver.
This removes trailing path separators from the receiver and the root part from aString and replaces them with a single slash as a path separator.
Also condenses any multiple separator sequences in the result into single path separators.

       @"" with @"file" produces @"file"
       @"path" with @"file" produces @"path/file"
       @"/" with @"file" produces @"/file"
       @"/" with @"file" produces @"/file"
       @"/" with @"/file" produces @"/file"
       @"path with @"C:/file" produces @"path/file"

NB. Do not use this method to modify strings other than filesystem paths as the behavior in such cases is undefined... for instance the string may have repeated slashes or slash-dot-slash sequences removed.

### stringByAppendingPathExtension:

- (NSString*) stringByAppendingPathExtension: (NSString*)aString;
Availability: OpenStep
Returns a new string with the path extension given in aString appended to the receiver after an extensionSeparator ('.').
If the receiver has trailing path separator characters, they are stripped before the extension separator is added.
If the receiver contains no components after the root, the extension cannot be appended (an extension can only be appended to a file name), so a copy of the unmodified receiver is returned.
An empty string may be used as an extension... in which case the extension separator is appended.
This behavior mirrors that of the -stringByDeletingPathExtension method.

       @"Mail" with @"app" produces @"Mail.app"
       @"Mail.app" with @"old" produces @"Mail.app.old"
       @"file" with @"" produces @"file."
       @"/" with @"app" produces @"/" (no file name to append to)
       @"" with @"app" produces @"" (no file name to append to)

NB. Do not use this method to modify strings other than filesystem paths as the behavior in such cases is undefined... for instance the string may have repeated slashes or slash-dot-slash sequences removed.

### stringByAppendingString:

- (NSString*) stringByAppendingString: (NSString*)aString;
Availability: OpenStep
Constructs a new string consisting of this instance followed by the aString.

### stringByDeletingLastPathComponent

- (NSString*) stringByDeletingLastPathComponent;
Availability: OpenStep
Returns a new string with the last path component (including any final path separators) removed from the receiver.
A string without a path component other than the root is returned without alteration.
See -lastPathComponent for a definition of a path component.

       @"hello/there" produces @"hello" (a relative path)
       @"hello" produces @"" (a relative path)
       @"/hello" produces @"/" (an absolute unix path)
       @"/" produces @"/" (an absolute unix path)
       @"C:file" produces @"C:" (a relative windows path)
       @"C:" produces @"C:" (a relative windows path)
       @"C:/file" produces @"C:/" (an absolute windows path)
       @"C:/" produces @"C:/" (an absolute windows path)
       @"//host/share/file" produces @"//host/share/" (a UNC path)
       @"//host/share/" produces @"//host/share/" (a UNC path)
       @"//path/file" produces @"//path" (an absolute Unix path)

NB. Do not use this method to modify strings other than filesystem paths as the behavior in such cases is undefined... for instance the string may have repeated slashes or slash-dot-slash sequences removed.

### stringByDeletingPathExtension

- (NSString*) stringByDeletingPathExtension;
Availability: OpenStep
Returns a new string with the path extension removed from the receiver.
Strips any trailing path separators before checking for the extension separator.
NB. This method does not consider a string which contains nothing between the root part and the extension separator ('.') to be a path extension. This mirrors the behavior of the -stringByAppendingPathExtension: method.

       @"file.ext" produces @"file"
       @"/file.ext" produces @"/file"
       @"/file.ext/" produces @"/file" (trailing path separators are ignored)
       @"/file..ext" produces @"/file."
       @"/file." produces @"/file"
       @"/.ext" produces @"/.ext" (there is no file to strip from)
       @".ext" produces @".ext" (there is no file to strip from)

NB. Do not use this method to modify strings other than filesystem paths as the behavior in such cases is undefined... for instance the string may have repeated slashes or slash-dot-slash sequences removed.

### stringByExpandingTildeInPath

- (NSString*) stringByExpandingTildeInPath;
Availability: OpenStep
Returns a string created by expanding the initial tilde ('~') and any following username to be the home directory of the current user or the named user.
Returns the receiver or an immutable copy if it was not possible to expand it.

### stringByPaddingToLength: withString: startingAtIndex:

- (NSString*) stringByPaddingToLength: (NSUInteger)newLength withString: (NSString*)padString startingAtIndex: (NSUInteger)padIndex;
Availability: MacOS-X 10.0.0
Returns a string formed by extending or truncating the receiver to newLength characters. If the new string is larger, it is padded by appending characters from padString (appending it as many times as required). The first character from padString to be appended is specified by padIndex.

### stringByReplacingCharactersInRange: withString:

- (NSString*) stringByReplacingCharactersInRange: (NSRange)aRange withString: (NSString*)by;
Availability: MacOS-X 10.5.0
Returns a new string where the substring in the given range is replaced by the passed string.

### stringByReplacingOccurrencesOfString: withString:

- (NSString*) stringByReplacingOccurrencesOfString: (NSString*)replace withString: (NSString*)by;
Availability: MacOS-X 10.5.0
Description forthcoming.

### stringByReplacingOccurrencesOfString: withString: options: range:

- (NSString*) stringByReplacingOccurrencesOfString: (NSString*)replace withString: (NSString*)by options: (NSStringCompareOptions)opts range: (NSRange)searchRange;
Availability: MacOS-X 10.5.0
Description forthcoming.

### stringByReplacingPercentEscapesUsingEncoding:

- (NSString*) stringByReplacingPercentEscapesUsingEncoding: (NSStringEncoding)e;
Availability: MacOS-X 10.0.0
Returns a string created by replacing percent escape sequences in the receiver assuming that the resulting data represents characters in the specified encoding.
Returns `nil` if the result is not a string in the specified encoding.

### stringByResolvingSymlinksInPath

- (NSString*) stringByResolvingSymlinksInPath;
Availability: OpenStep
First calls -stringByExpandingTildeInPath if necessary.
Replaces path string by one in which path components representing symbolic links have been replaced by their referents.
Removes a leading '/private' if the result is valid.
If links cannot be resolved, returns an unmodified copy of the receiver.

### stringByStandardizingPath

- (NSString*) stringByStandardizingPath;
Availability: OpenStep
Returns a standardised form of the receiver, with unnecessary parts removed, tilde characters expanded, and symbolic links resolved where possible.
NB. Refers to the local filesystem to resolve symbolic links in absolute paths, and to expand tildes... so this can't be used for general path manipulation.
If the string is an invalid path, the unmodified receiver is returned.

Uses -stringByExpandingTildeInPath to expand tilde expressions.
Simplifies '//' and '/./' sequences and removes trailing '/' or '.'.

For absolute paths, uses -stringByResolvingSymlinksInPath to resolve any links, then gets rid of '/../' sequences and removes any '/private' prefix.

### stringByTrimmingCharactersInSet:

- (NSString*) stringByTrimmingCharactersInSet: (NSCharacterSet*)aSet;
Availability: MacOS-X 10.0.0
Return a string formed by removing characters from the ends of the receiver. Characters are removed only if they are in aSet.
If the string consists entirely of characters in aSet , an empty string is returned.
The aSet argument must not be `nil`.

### stringsByAppendingPaths:

- (NSArray*) stringsByAppendingPaths: (NSArray*)paths;
Availability: MacOS-X 10.0.0
Returns an array of strings made by appending the values in paths to the receiver.

### substringFromIndex:

- (NSString*) substringFromIndex: (NSUInteger)index;
Availability: OpenStep
Returns a substring of the receiver from character at the specified index to the end of the string.
So, supplying an index of 3 would return a substring consisting of the entire string apart from the first three character (those would be at index 0, 1, and 2).
If the supplied index is greater than or equal to the length of the receiver an exception is raised.

### substringToIndex:

- (NSString*) substringToIndex: (NSUInteger)index;
Availability: OpenStep
Returns a substring of the receiver from the start of the string to (but not including) the specified index position.
So, supplying an index of 3 would return a substring consisting of the first three characters of the receiver.
If the supplied index is greater than the length of the receiver an exception is raised.

### substringWithRange:

- (NSString*) substringWithRange: (NSRange)aRange;
Availability: MacOS-X 10.0.0
Returns a substring of the receiver containing the characters in aRange.
If aRange specifies any character position not present in the receiver, an exception is raised.
If aRange has a length of zero, an empty string is returned.

### uppercaseString

- (NSString*) uppercaseString;
Availability: OpenStep
Returns a copy of the receiver with all characters converted to uppercase.

### writeToFile: atomically:

- (BOOL) writeToFile: (NSString*)filename atomically: (BOOL)useAuxiliaryFile;
Availability: MacOS-X 10.0.0
Writes contents out to file at filename, using the default C string encoding unless this would result in information loss, otherwise straight unicode. The ' `atomically` ' option if set will cause the contents to be written to a temp file, which is then closed and renamed to filename. Thus, an incomplete file at filename should never result.

### writeToFile: atomically: encoding: error:

- (BOOL) writeToFile: (NSString*)path atomically: (BOOL)atomically encoding: (NSStringEncoding)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Writes contents out to file at filename, using the default C string encoding unless this would result in information loss, otherwise straight unicode. The ' `atomically` ' option if set will cause the contents to be written to a temp file, which is then closed and renamed to filename. Thus, an incomplete file at filename should never result.
If there is a problem and error is not NULL, the cause of the problem is returned in *error.

### writeToURL: atomically:

- (BOOL) writeToURL: (NSURL*)url atomically: (BOOL)atomically;
Availability: MacOS-X 10.0.0
Writes contents out to url, using the default C string encoding unless this would result in information loss, otherwise straight unicode. See [NSURLHandle -writeData:] on which URL types are supported. The ' `atomically` ' option is only heeded if the URL is a `file://` URL; see -writeToFile:atomically: .

### writeToURL: atomically: encoding: error:

- (BOOL) writeToURL: (NSURL*)url atomically: (BOOL)atomically encoding: (NSStringEncoding)enc error: (NSError**)error;
Availability: MacOS-X 10.4.0
Writes contents out to url, using the default C string encoding unless this would result in information loss, otherwise straight unicode. See [NSURLHandle -writeData:] on which URL types are supported. The ' `atomically` ' option is only heeded if the URL is a `file://` URL; see -writeToFile:atomically: .
If there is a problem and error is not NULL, the cause of the problem is returned in *error.

# Software documentation for the NXConstantString class

## NXConstantString : NSString

> Declared in:
>   Foundation/NSString.h

Availability: OpenStep

The NXConstantString class is used to hold constant 8-bit character string objects produced by the compiler where it sees @"..." in the source. The compiler generates the instances of this class - which has three instance variables -

- a pointer to the class (this is the sole ivar of NSObject)
- a pointer to the 8-bit data
- the length of the string

In older versions of the compiler, the isa variable is always set to the NXConstantString class. In newer versions a compiler option was added for GNUstep, to permit the isa variable to be set to another class, and GNUstep uses this to avoid conflicts with the default implementation of NXConstantString in the ObjC runtime library (the preprocessor is used to change all occurrences of NXConstantString in the source code to NSConstantString).

Since GNUstep will generally use the GNUstep extension to the compiler, you should never refer to the constant string class by name, but should use the [NSString +constantStringClass] method to get the actual class being used for constant strings.

What follows is a dummy declaration of the class to keep the compiler happy.

Instance Variables

## Instance Variables for NXConstantString Class

### nxcslen

@public const unsigned int nxcslen;
Availability: OpenStep
Description forthcoming.

### nxcsptr

@public const char* const nxcsptr;
Availability: OpenStep
Description forthcoming.

Up