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.
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.)
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.)
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.
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.
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.
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.
NSString objects represent an immutable
string of Unicode 3.0 characters. These may be
accessed individually as type
unichar, an
unsignedshort.
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.
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 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.
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.
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.)
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.
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.)
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.
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.
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.
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.
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.
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.
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:
.)
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.
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.
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.
Compares this string with aString
ignoring case. Convenience for
-compare:options:range:
with the NSCaseInsensitiveSearch option,
in the default locale.
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.
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.
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.
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.
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.
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.
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.
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.
Conversion to an encoding where byte
order matters but is not specified
(NSUnicodeStringEncoding,
NSUTF16StringEncoding,
NSUTF32StringEncoding) produces data
with a Byte Order Marker (BOM) at the start of the
data. 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.
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.
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.
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.
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.
Returns this string as an array of 16-bit
unichar (
unsignedshort)
values. buffer must be preallocated and
should be capable of holding
-length
shorts.
Returns aRange of string as an array of
16-bit unichar (
unsignedshort)
values. buffer must be preallocated and
should be capable of holding a sufficient number of
shorts.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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!
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.
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"
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.
Determines the smallest range of lines
containing aRange and returns the
information as a range. Calls
-getLineStart:end:contentsEnd:forRange:
to do the work.
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.
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.
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.
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)
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 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.
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).
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";
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.
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).
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.
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.
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
'|'.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
.
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.
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.
Flags. The low 16 bits are reserved for the
compiler, the top 16 for use by the Foundation
Framework. Currently only the low 2 bits are
used, to indicate the encoding of the string, with
the following values: 0. ASCII (UTF-8 using only 7-bit
characters) 1. UTF-8 2. UTF-16 3. UTF-32