Up
Authors
- Andrew Kachites McCallum (
mccallum@gnu.ai.mit.edu
)
-
Version: 1.357
Date: 2005/11/28 15:41:34
Copyright: (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSString.h
Availability: OpenStep
This is the mutable form of the
NSString
class.
Method summary
+ (id)
string;
Availability: OpenStep
Constructs an empty string.
+ (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.)
+ (id)
stringWithCString: (const char*)byteString
length: (unsigned int)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.)
+ (
NSMutableString*)
stringWithCapacity: (unsigned int)capacity;
Availability: OpenStep
Constructs an empty string with initial buffer size of capacity.
+ (id)
stringWithCharacters: (const
unichar*)characters
length: (unsigned int)length;
Availability: OpenStep
Create a string of unicode characters.
+ (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.
+ (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.
- (void)
appendFormat: (
NSString*)format
,...;
Availability: OpenStep
Modifies this string by appending string described by given format.
- (void)
appendString: (
NSString*)aString;
Availability: OpenStep
Modifies this string by appending aString.
- (void)
deleteCharactersInRange: (
NSRange)range;
Availability: OpenStep
Modifies this instance by deleting specified range of characters.
- (id)
initWithCapacity: (unsigned int)capacity;
Availability: OpenStep
This is a designated initialiser for the class.
Subclasses
should 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.
- (void)
insertString: (
NSString*)aString
atIndex: (unsigned int)loc;
Availability: OpenStep
Modifies this instance by inserting aString at loc.
- (void)
replaceCharactersInRange: (
NSRange)range
withString: (
NSString*)aString;
Availability: OpenStep
Modifies this instance by deleting characters in range and then inserting aString at its beginning.
- (unsigned int)
replaceOccurrencesOfString: (
NSString*)replace
withString: (
NSString*)by
options: (unsigned int)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.
- (void)
setString: (
NSString*)aString;
Availability: OpenStep
Modifies this instance by replacing contents with those of aString.
- 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
+ (
NSStringEncoding*)
availableStringEncodings;
Availability: MacOS-X 10.0.0
Returns an array of all available string encodings, terminated by a null value.
+ (Class)
constantStringClass;
Availability: Base 0.0.0
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).
+ (
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.
+ (
NSString*)
localizedNameOfStringEncoding: (
NSStringEncoding)encoding;
Availability: MacOS-X 10.0.0
Returns the localized name of the encoding specified.
+ (
NSString*)
localizedStringWithFormat: (
NSString*)format
,...;
Availability: MacOS-X 10.0.0
Returns an autoreleased string with given format using the default locale.
+ (
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.
+ (id)
string;
Availability: OpenStep
Create an empty string.
+ (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.)
+ (id)
stringWithCString: (const char*)byteString
encoding: (
NSStringEncoding)encoding;
Availability: MacOS-X 10.0.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.
+ (id)
stringWithCString: (const char*)byteString
length: (unsigned int)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.)
+ (id)
stringWithCharacters: (const
unichar*)chars
length: (unsigned int)length;
Availability: OpenStep
Create a string of unicode characters.
+ (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.
+ (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.
+ (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.
+ (id)
stringWithString: (
NSString*)aString;
Availability: MacOS-X 10.0.0
Create a copy of aString.
+ (id)
stringWithUTF8String: (const char*)bytes;
Availability: MacOS-X 10.0.0
Create a string based on the given UTF-8 string, null-terminated.
- (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.
- (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.
- (BOOL)
boolValue;
Availability: Base 0.0.0
If the string consists of the words 'true' or 'yes' (case insensitive) or begins with a non-zero numeric value, return YES
, otherwise return NO
.
- (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:
.)
- (unsigned int)
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.
- (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.
- (BOOL)
canBeConvertedToEncoding: (
NSStringEncoding)encoding;
Availability: OpenStep
Returns whether this string can be converted to the given string encoding without information loss.
- (
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.
- (
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.
- (
unichar)
characterAtIndex: (unsigned int)index;
Availability: OpenStep
Returns unicode character at index. unichar
is an unsigned short. Thus, a 16-bit character is returned.
- (
NSString*)
commonPrefixWithString: (
NSString*)aString
options: (unsigned int)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.
- (
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.
- (
NSComparisonResult)
compare: (
NSString*)aString
options: (unsigned int)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.
- (
NSComparisonResult)
compare: (
NSString*)aString
options: (unsigned int)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.
- (
NSComparisonResult)
compare: (
NSString*)string
options: (unsigned int)mask
range: (
NSRange)compareRange
locale: (
NSDictionary*)dict;
Availability: MacOS-X 10.0.0
Compares this instance with string, using rules in locale given by dict. 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. 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.
Warning: this implementation and others in NSString IGNORE the locale.
- (unsigned int)
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.
- (
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.
- (
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.
- (
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.
- (
NSString*)
description;
Availability: OpenStep
Returns self
.
- (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.
- (
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.
- (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.
- (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.
- (void)
getCString: (char*)buffer;
Availability: OpenStep
Retrieve the contents of the receiver into the buffer.
The buffer must be large enough to contain the CString representation of the characters in the receiver, plus a nul terminator which this method adds.
- (void)
getCString: (char*)buffer
maxLength: (unsigned int)maxLength;
Availability: OpenStep
Retrieve up to maxLength bytes from the receiver into the buffer.
The buffer must be at least maxLength + 1 bytes long, so that it has room for the nul terminator that this method adds.
- (void)
getCString: (char*)buffer
maxLength: (unsigned int)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.
The buffer must be at least maxLength + 1 bytes long, so that it has room for the nul terminator that this method adds.
- (void)
getCString: (char*)buffer
maxLength: (unsigned int)maxLength
range: (
NSRange)aRange
remainingRange: (
NSRange*)leftoverRange;
Availability: OpenStep
Converts characters from the given range of the string to the c string encoding and stores the resulting bytes in the given buffer. As many characters are converted as will fit in the buffer. A trailing nul byte is always added, so the buffer needs to be big enough to hold maxLength+1 bytes.
If leftoverRange is non-NULL, the range of trailing characters that didn't will be stored in it.
- (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.
- (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.
- (BOOL)
getFileSystemRepresentation: (GSNativeChar*)buffer
maxLength: (unsigned int)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.
- (void)
getLineStart: (unsigned int*)startIndex
end: (unsigned int*)lineEndIndex
contentsEnd: (unsigned int*)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).
- (BOOL)
hasPrefix: (
NSString*)aString;
Availability: OpenStep
Returns whether this string starts with aString.
- (BOOL)
hasSuffix: (
NSString*)aString;
Availability: OpenStep
Returns whether this string ends with aString.
- (unsigned int)
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.
- (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 s expected an 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.
- (id)
initWithBytes: (const void*)bytes
length: (unsigned int)length
encoding: (
NSStringEncoding)encoding;
Availability: MacOS-X 10.0.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.
- (id)
initWithBytesNoCopy: (const void*)bytes
length: (unsigned int)length
encoding: (
NSStringEncoding)encoding
freeWhenDone: (BOOL)flag;
Availability: MacOS-X 10.0.0
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.
If the data can not be interpreted using the encoding, the receiver is released and nil
is returned.
- (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.
- (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.
- (id)
initWithCString: (const char*)byteString
length: (unsigned int)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.
- (id)
initWithCStringNoCopy: (char*)byteString
length: (unsigned int)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.
- (id)
initWithCharacters: (const
unichar*)chars
length: (unsigned int)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.
- (id)
initWithCharactersNoCopy: (
unichar*)chars
length: (unsigned int)length
freeWhenDone: (BOOL)flag;
Availability: OpenStep
This is a designated initialiser for the class.
Subclasses
should override this method.
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.
Note, 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.
- (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.
- (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.
- (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.
- (id)
initWithFormat: (
NSString*)format
,...;
Availability: OpenStep
- (id)
initWithFormat: (
NSString*)format
arguments: (va_list)argList;
Availability: OpenStep
- (id)
initWithFormat: (
NSString*)format
locale: (
NSDictionary*)locale
,...;
Availability: MacOS-X 10.0.0
- (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.
- (id)
initWithString: (
NSString*)string;
Availability: OpenStep
Initialize to be a copy of the given string.
- (id)
initWithUTF8String: (const char*)bytes;
Availability: MacOS-X 10.0.0
Initialize based on given null-terminated UTF-8 string bytes.
- (int)
intValue;
Availability: OpenStep
Returns the string's content as an int.
Current implementation uses C library atoi()
, which does not detect conversion errors -- use with care!
- (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 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.
- (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
.
- (BOOL)
isEqualToString: (
NSString*)aString;
Availability: OpenStep
Returns whether this instance is equal as a string to
aString. See also
-compare:
and related methods.
- (
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"
- (unsigned int)
length;
Availability: OpenStep
Returns the number of Unicode characters in this string, including the individual characters of composed character sequences,
- (unsigned)
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.
- (
NSRange)
lineRangeForRange: (
NSRange)aRange;
Availability: MacOS-X 10.0.0
- (
NSComparisonResult)
localizedCaseInsensitiveCompare: (
NSString*)string;
Availability: MacOS-X 10.0.0
Compares this instance with string, using rules in the default locale, ignoring case.
- (
NSComparisonResult)
localizedCompare: (
NSString*)string;
Availability: MacOS-X 10.0.0
Compares this instance with string, using rules in the default locale.
- (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.
- (
NSString*)
lowercaseString;
Availability: OpenStep
Returns a copy of the receiver with all characters converted to lowercase.
- (unsigned)
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.
- (
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.
A trailing path separator (which was not part of the root) is added as the last element in the array.
- (
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)
- (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.
- (
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";
- (
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.
- (
NSRange)
rangeOfCharacterFromSet: (
NSCharacterSet*)aSet
options: (unsigned int)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).
- (
NSRange)
rangeOfCharacterFromSet: (
NSCharacterSet*)aSet
options: (unsigned int)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.
- (
NSRange)
rangeOfComposedCharacterSequenceAtIndex: (unsigned int)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.
- (
NSRange)
rangeOfString: (
NSString*)string
options: (unsigned int)mask;
Availability: OpenStep
- (
NSRange)
rangeOfString: (
NSString*)aString
options: (unsigned int)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
'|'
.
- (
NSStringEncoding)
smallestEncoding;
Availability: OpenStep
Returns the smallest encoding with which this string can be converted without information loss.
- (
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.
- (
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 legal URL.
Returns nil
if the receiver cannot be represented using the specified encoding.
- (
NSString*)
stringByAppendingFormat: (
NSString*)format
,...;
Availability: OpenStep
Constructs a new string consisting of this instance followed by the string specified by format.
- (
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"
- (
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)
- (
NSString*)
stringByAppendingString: (
NSString*)aString;
Availability: OpenStep
Constructs a new string consisting of this instance followed by the aString.
- (
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" @"hello" produces @"" @"/hello" produces @"/" @"/" produces @"/" @"C:file" produces @"C:" @"C:" produces @"C:" @"C:/file" produces @"C:/" @"C:/" produces @"C:/" @"//host/share/file" produces @"//host/share/" @"//host/share/" produces @"/host/share/" @"//host/share" produces @"/host/share"
- (
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)
- (
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.
- (
NSString*)
stringByPaddingToLength: (unsigned int)newLength
withString: (
NSString*)padString
startingAtIndex: (unsigned int)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.
- (
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.
- (
NSString*)
stringByResolvingSymlinksInPath;
Availability: OpenStep
Replaces path string by one in which path components representing symbolic links have been replaced by their referents.
If links cannot be resolved, returns an unmodified copy of the receiver.
- (
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.
- (
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
.
- (
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.
- (
NSString*)
substringFromIndex: (unsigned int)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.
- (
NSString*)
substringToIndex: (unsigned int)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.
- (
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.
- (
NSString*)
uppercaseString;
Availability: OpenStep
Returns a copy of the receiver with all characters converted to uppercase.
- (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.
- (BOOL)
writeToURL: (
NSURL*)anURL
atomically: (BOOL)atomically;
Availability: MacOS-X 10.0.0
Writes contents out to
anURL, 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:
.
- 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
@protected const unsigned int nxcslen;
Description forthcoming.
@protected const char* const nxcsptr;
Description forthcoming.
- Declared in:
- Foundation/NSString.h
Availability: Base 0.0.0
GNUstep specific (non-standard) additions to the NSMutableString class. The methods in this category are not available in MacOS-X
Method summary
- (
NSString*)
immutableProxy;
Availability: Base 0.0.0
Returns a proxy to the receiver which will allow access to the receiver as an NSString, but which will not allow any of the extra NSMutableString methods to be used. You can use this method to provide other code with read-only access to a mutable string you own.
- Declared in:
- Foundation/NSString.h
Availability: Base 0.0.0
GNUstep specific (non-standard) additions to the NSMutableString class.
Method summary
- (void)
deletePrefix: (
NSString*)prefix;
Availability: Base 0.0.0
Removes the specified prefix from the string. Raises an exception if the prefix is not present.
- (void)
deleteSuffix: (
NSString*)suffix;
Availability: Base 0.0.0
Removes the specified suffix from the string. Raises an exception if the suffix is not present.
- (void)
replaceString: (
NSString*)replace
withString: (
NSString*)by;
Availability: Base 0.0.0
Replaces all occurrences of the string replace with the string by in the receiver.
Has no effect if replace does not occur within the receiver. NB. an empty string is not considered to exist within the receiver.
Calls - replaceOccurrencesOfString:withString:options:range: passing zero for the options and a range from 0 with the length of the receiver.
- (void)
trimLeadSpaces;
Availability: Base 0.0.0
Removes all leading white space from the receiver.
- (void)
trimSpaces;
Availability: Base 0.0.0
Removes all leading or trailing white space from the receiver.
- (void)
trimTailSpaces;
Availability: Base 0.0.0
Removes all trailing white space from the receiver.
- Declared in:
- Foundation/NSString.h
Availability: Base 0.0.0
Provides some additional (non-standard) utility methods.
Method summary
+ (id)
stringWithFormat: (
NSString*)format
arguments: (va_list)argList;
Availability: Base 0.0.0
Alternate way to invoke stringWithFormat
if you have or wish to build an explicit va_list
structure.
- (
NSString*)
stringByDeletingPrefix: (
NSString*)prefix;
Availability: Base 0.0.0
Returns a string formed by removing the prefix string from the receiver. Raises an exception if the prefix is not present.
- (
NSString*)
stringByDeletingSuffix: (
NSString*)suffix;
Availability: Base 0.0.0
Returns a string formed by removing the suffix string from the receiver. Raises an exception if the suffix is not present.
- (
NSString*)
stringByReplacingString: (
NSString*)replace
withString: (
NSString*)by;
Availability: Base 0.0.0
Returns a string in which any (and all) occurrences of replace in the receiver have been replaced with by. Returns the receiver if replace does not occur within the receiver. NB. an empty string is not considered to exist within the receiver.
- (
NSString*)
stringByTrimmingLeadSpaces;
Availability: Base 0.0.0
Returns a string formed by removing leading white space from the receiver.
- (
NSString*)
stringByTrimmingSpaces;
Availability: Base 0.0.0
Returns a string formed by removing both leading and trailing white space from the receiver.
- (
NSString*)
stringByTrimmingTailSpaces;
Availability: Base 0.0.0
Returns a string formed by removing trailing white space from the receiver.
Up