mccallum@gnu.ai.mit.edu
)Version: 1.318
Date: 2004/06/05 09:34:41
Copyright: (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSString.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
This is the mutable form of the NSString class.
Method summaryDescription forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
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 occurrances (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.
Description forthcoming.
- Declared in:
- Foundation/NSString.h
- Conforms to:
- NSCoding
- NSCopying
- NSMutableCopying
Standards:
- MacOS-X
- OpenStep
- GNUstep
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.
Method summary
Returns an array of all available string encodings, terminated by a null value.
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).
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... 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.
Returns the localized name of the encoding specified.
Description forthcoming.
Concatenates the strings in the components array placing a path separator between each one and returns the result.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
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.
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
.
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.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Returns the strings content as a double. Skips
leading whitespace.
Conversion is not
localised (ie uses '.' as the decimal separator).
Returns 0.0 on underflow or if the string
does not contain a number.
Description forthcoming.
Description forthcoming.
Returns the strings content as a double. Skips
leading whitespace.
Conversion is not
localised (ie uses '.' as the decimal separator).
Returns 0.0 on underflow or if the string
does not contain a number.
Retrieve the contents of the receiver into the
buffer.
The buffer must
be large enought to contain the CString representation
of the characters in the receiver, plus a nul terminator
which this method adds.
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.
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.
Description forthcoming.
Description forthcoming.
Description forthcoming.
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.
Description forthcoming.
Description forthcoming.
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.
Description forthcoming.
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.
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.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
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.
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.
Description forthcoming.
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.
Invokes
-initWithFormat:locale:arguments:
with a nil
locale.
Invokes
-initWithFormat:locale:arguments:
with a nil
locale.
Invokes -initWithFormat:locale:arguments:
Initialises the string using the specified format and locale to format the following arguments.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
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 is an empty string, it is
simply returned.
If there are no non-empty
substrings, the root string is returned.
Description forthcoming.
Determines the smallest range of lines
containing aRange and returns the
information as a range.
Calls
-getLineStart:end:contentsEnd:forRange:
to do the work.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Returns a copy of the receiver with all characters converted to lowercase.
Returns the path components of the reciever
separated into an array.
If the receiver
begins with a '/' character then that is used as the
first element in the array.
Empty components
are removed.
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.
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
.
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 ObjectiveC programming are supported, while in XML format, the standard SGML comment sequences are used.
A property list may only be one of the following classes -
( "one", "two", "three" )In XML format, an array is an element whose name is
array
and whose content is the array
content.
<array><string>one</string><string>two</string><string>three</string></array>
< 54637374 696D67 >In XML format, a data object is an element whose name is
data
and whose content is a stream of
base64 encoded bytes.
<*D2002-03-22 11:30:00 +0100>In XML format, a date object is an element whose name is
date
and whose content is a date in the
above format.
<date>2002-03-22 11:30:00 +0100</date>
{ "key1" = "value1"; }In XML format, a dictionary is an element whose name is
dictionary
and whose content consists
of pairs of strings and other property list
objects.
<dictionary> <string>key1</string> <string>value1</string> </dictionary>
<*BY>
for YES
or <*BN>
for NO
. <true />
or
<false />
<*INNN>
where
NNN is an integer. <integer>NNN<integer>
<*RNNN>
where NNN is
a real number. <real>NNN<real>
"hello world & others"In XML format, the string is simply stored in UTF8 format as the content of a
string
element, and the only character escapes required
are those used by XML such as the '<' markup
representing a '<' character.
<string>hello world & others</string>"
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";
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Invokes -rangeOfString:options: with the options mask set to zero.
Invokes -rangeOfString:options:range: with the range set set to the range of the whole of the reciever.
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 -
Description forthcoming.
Returns a string where a prefix of the current user's home directory is abbreviated by '~', or returns the receiver if it was not found to have the home directory as a prefix.
Description forthcoming.
Returns a new string with the path component given in aString appended to the receiver. Removes trailing separators and multiple separators.
Returns a new string with the path extension given
in aString appended to the receiver after the
extensionSeparator ('.').
If the
receiver has trailing '/' characters which are not
part of the root directory, those '/' characters are
stripped before the extension separator is added.
Description forthcoming.
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.
Returns a new string with the path extension
removed from the receiver.
Strips any
trailing path separators before checking for the
extension separator.
Does not consider a
string starting with the extension separator ('.')
to be a path extension.
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 if it was not possible
to expand it.
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.
Description forthcoming.
Returns a standardised form of the receiver, with
unnecessary parts removed, tilde characters
expanded, and symbolic links resolved where
possible.
If the string is an invalid
path, the unmodified receiver is returned.
Uses
-stringByExpandingTildeInPath
to expand tilde expressions.
Simplifies '//'
and '/./' sequences.
Removes any '/private'
prefix.
For absolute paths, uses -stringByResolvingSymlinksInPath to resolve any links, then gets rid of '/../' sequences.
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 nust not be nil
.
Returns an array of strings made by appending the values in paths to the receiver.
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.
An obsolete name for -substringWithRange: ... deprecated.
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.
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.
Returns a copy of the receiver with all characters converted to uppercase.
Description forthcoming.
Description forthcoming.
- Declared in:
- Foundation/NSString.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
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 -
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 occurances 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 constnat 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.
Description forthcoming.
Description forthcoming.
- Declared in:
- Foundation/NSString.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
GNUstep specific (non-standard) additions to the NSMutableString class. The methods in this category are not available in MacOS-X
Method summaryReturns 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
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
Description forthcoming.
Method summaryDescription forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
- Declared in:
- Foundation/NSString.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
Description forthcoming.
Method summaryDescription forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.