NSString $Revision$ $Date$ NSString Foundation/NSString.h NSCoding

NSString objects represent an immutable string of characters. NSString itself is an abstract class which provides factory methods to generate objects of unspecified subclasses.

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

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.

availableStringEncodings

Returns an array of all available string encodings, terminated by a null value.

defaultCStringEncoding

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

You should NOT override this method in an attempt to change the encoding being used.

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.

The default C string encoding must be a characterset containing 7 or 8 bit characters, and where the characters are a superset of the 7-bit ASCII characterset. In particular, this means that NSUTF8StringEncoding and NSUnicodeStringEncoding are not permissable.

localizedNameOfStringEncoding: encoding

Returns the localized name of the encoding specified by encoding.

localizedStringWithFormat: format, pathWithComponents: components string stringWithCharacters: chars length: length stringWithContentsOfFile: path stringWithCString: cString stringWithCString: cString stringWithFormat: format, stringWithString: aString canBeConvertedToEncoding: encoding capitalizedString caseInsensitiveCompare: aString characterAtIndex: index commonPrefixWithString: aString compare: aString compare: aString compare: aString options: mask range: aRange completePathIntoString: outputName caseSensitive: flag matchesIntoArray: outputArray componentsSeparatedByString: separator cString Returns a pointer to a nul 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. cStringLength dataUsingEncoding: encoding dataUsingEncoding: encoding allowLossyConversion: flag description doubleValue fastestEncoding fileSystemRepresentation floatValue getCharacters: buffer getCharacters: buffer getCString: buffer getCString: buffer maxLength: maxLength getCString: buffer maxLength: maxLength range: aRange remainingRange: leftoverRange getFileSystemRepresentation: buffer maxLength: maxLength getLineStart: startIndex end: lineEndIndex contentsEnd: contentsEndIndex hash hasPrefix: aString hasSuffix: aString init initWithCharacters: characters initWithCharactersNoCopy: characters length: length freeWhenDone: flag This is the most basic initialiser for unicode strings. In the GNUstep implementation, your subclasses may override this initialiser in order to have all others function. initWithContentsOfFile: path initWithCString: cString initWithCString: cString initWithCStringNoCopy: cString length: length freeWhenDone: flag initWithData: data encoding: encoding initWithFormat: format Invokes initWithFormat:locale:arguments with a nil locale. initWithFormat: format arguments: argList Invokes initWithFormat:locale:arguments with a nil locale. initWithFormat: format locale: dictionary Initialises the string using the specified format and local to format the following arguments. initWithFormat: format arguments: argList Invokes initWithFormat:locale:,... with a nil locale. initWithFormat: format locale: dictionary arguments: argList Initialises the string using the specified format and local to format the following arguments. initWithString: aString intValue isAbsolutePath isEqualToString: aString lastPathComponent length lineRangeForRange: aRange lossyCString lowercaseString Returns a copy of the receiver with all characters converted to lowercase. pathComponents pathExtension propertyList propertyListFromStringsFileFormat rangeOfCharacterFromSet: aSet rangeOfCharacterFromSet: aSet options: mask rangeOfCharacterFromSet: aSet options: mask range: aRange rangeOfComposedCharacterSequenceAtIndex: anIndex rangeOfString: aString Invokes rangeOfString:options: with the options mask set to zero. rangeOfString: aString options: mask Invokes rangeOfString:options:range with the range set set to the range of the whole of the reciever. rangeOfString: subString options: mask range: aRange Returns the range giving the location and length of the first occurrence of subString within aRange.
If subString 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 substring is nil, an exception is raised.
If any part of aRange lies outside the range of the receiver, an exception is raised.
The optionsm mask may contain the following options - NSCaseInsensitiveSearch NSLiteralSearch NSBackwardsSearch NSAnchoredSearch smallestEncoding stringByAbbreviatingWithTildeInPath stringByAppendingFormat: format, stringByAppendingPathComponent: aString stringByAppendingPathExtension: string stringByAppendingString: aString stringByDeletingLastPathComponent stringByDeletingPathExtension stringByExpandingTildeInPath stringByReplacingString: aString withString: replacement Returns a string in which any (and all) occurrances of aString in the receiver have been replaced by replacement. Returns the receiver if aString does not occur within the receiver. NB. an empty string is not considered to exist within the receiver. stringsByAppendingPaths: paths substringFromIndex: anIndex substringToIndex: anIndex substringWithRange: aRange uppercaseString Returns a copy of the receiver with all characters converted to uppercase. writeToFile: path atomically: flag