libs-base/Documentation/gsdoc/NSString.gsdoc
CaS e9286f7697 Some formatting changes
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@11371 72102866-910b-0410-8b05-ffd578937521
2001-11-12 13:01:09 +00:00

791 lines
22 KiB
XML

<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
<gsdoc base="NSString" prev="NSSet" next="NSTask" up="Base">
<head>
<title>NSString</title>
<author name="Richard Frith-Macdonald">
<email address="rfm@gnu.org"/>
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
</author>
<author name="James Dessart">
<email address="skwirl@cam.org"/>
</author>
<version>$Revision$</version>
<date>$Date$</date>
</head>
<body>
<chapter>
<heading>NSString</heading>
<class name="NSString" super="NSObject">
<declared>Foundation/NSString.h</declared>
<conform>NSCoding</conform>
<desc>
<p>
NSString objects represent an immutable string of characters.
NSString itself is an abstract class which provides factory
methods to generate objects of unspecified subclasses.
</p>
<p>
A constant NSString can be created using the following syntax:
<code>@"..."</code>, where the contents of the quotes are the
string, using only ASCII characters.
</p>
<p>
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:
</p>
<p>
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 <em>designated initialiser</em> and the other
initialisation methods should work.
</p>
</desc>
<method type="const NSStringEncoding*" factory="yes">
<sel>availableStringEncodings</sel>
<desc>
<p>
Returns an array of all available string encodings,
terminated by a null value.
</p>
</desc>
</method>
<method type="NSStringEncoding" factory="yes">
<sel>defaultCStringEncoding</sel>
<desc>
<p>
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.
</p>
<p>
You should <em>NOT</em> override this method in an attempt to
change the encoding being used.
</p>
<p>
In GNUstep, this encoding is determined by the initial value
of the <code>GNUSTEP_STRING_ENCODING</code> environment
variable. If this is not defined,
<code>NSISOLatin1StringEncoding</code> is assumed.
</p>
<p>
The default C string encoding must be a characterset containing
7 or 8 bit characters, and where the characters are a superset
of the 7-bit ASCII characterset. In particular, this means
that NSUTF8StringEncoding and NSUnicodeStringEncoding are not
permissable.
</p>
</desc>
</method>
<method type="NSString*" factory="yes">
<sel>localizedNameOfStringEncoding:</sel>
<arg type="NSStringEncoding">encoding</arg>
<desc>
<p>
Returns the localized name of the encoding specified
by <var>encoding</var>.
</p>
</desc>
</method>
<method type="NSString*" factory="yes">
<sel>localizedStringWithFormat:</sel>
<arg type="NSString*">format,</arg>
<desc>
</desc>
</method>
<method type="NSString*" factory="yes">
<sel>pathWithComponents:</sel>
<arg type="NSArray*">components</arg>
<desc>
</desc>
</method>
<method type="id" factory="yes">
<sel>string</sel>
<desc>
</desc>
</method>
<method type="id" factory="yes">
<sel>stringWithCharacters:</sel>
<arg type="const unichar*">chars</arg>
<sel>length:</sel>
<arg type="unsigned int">length</arg>
<desc>
</desc>
</method>
<method type="id" factory="yes">
<sel>stringWithContentsOfFile:</sel>
<arg type="NSString*">path</arg>
<desc>
</desc>
</method>
<method type="id" factory="yes">
<sel>stringWithCString:</sel>
<arg type="const char*">cString</arg>
<desc>
</desc>
</method>
<method type="id" factory="yes">
<sel>stringWithCString:</sel>
<arg type="const char*">cString</arg>
<desc>
</desc>
</method>
<method type="id" factory="yes">
<sel>stringWithFormat:</sel>
<arg type="NSString*">format,</arg>
<desc>
</desc>
</method>
<method type="id" factory="yes">
<sel>stringWithString:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>canBeConvertedToEncoding:</sel>
<arg type="NSStringEncoding">encoding</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>capitalizedString</sel>
<desc>
</desc>
</method>
<method type="NSComparisonResult">
<sel>caseInsensitiveCompare:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="unichar">
<sel>characterAtIndex:</sel>
<arg type="unsigned int">index</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>commonPrefixWithString:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="NSComparisonResult">
<sel>compare:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="NSComparisonResult">
<sel>compare:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="NSComparisonResult">
<sel>compare:</sel>
<arg type="NSString*">aString</arg>
<sel>options:</sel>
<arg type="unsigned int">mask</arg>
<sel>range:</sel>
<arg type="NSRange">aRange</arg>
<desc>
</desc>
</method>
<method type="unsigned int">
<sel>completePathIntoString:</sel>
<arg type="NSString**">outputName</arg>
<sel>caseSensitive:</sel>
<arg type="BOOL">flag</arg>
<sel>matchesIntoArray:</sel>
<arg type="NSArray**">outputArray</arg>
<desc>
</desc>
</method>
<method type="NSArray*">
<sel>componentsSeparatedByString:</sel>
<arg type="NSString*">separator</arg>
<desc>
</desc>
</method>
<method type="const char*">
<sel>cString</sel>
<desc>
Returns a pointer to a nul terminated string of 8-bit
characters in the default encoding. The memory pointed
to is not owned by the caller, so the caller must copy
its contents to keep it.
</desc>
</method>
<method type="unsigned int">
<sel>cStringLength</sel>
<desc>
</desc>
</method>
<method type="NSData*">
<sel>dataUsingEncoding:</sel>
<arg type="NSStringEncoding">encoding</arg>
<desc>
</desc>
</method>
<method type="NSData*">
<sel>dataUsingEncoding:</sel>
<arg type="NSStringEncoding">encoding</arg>
<sel>allowLossyConversion:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>description</sel>
<desc>
</desc>
</method>
<method type="double">
<sel>doubleValue</sel>
<desc>
</desc>
</method>
<method type="NSStringEncoding">
<sel>fastestEncoding</sel>
<desc>
</desc>
</method>
<method type="const char*">
<sel>fileSystemRepresentation</sel>
<desc>
</desc>
</method>
<method type="float">
<sel>floatValue</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>getCharacters:</sel>
<arg type="unichar*">buffer</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>getCharacters:</sel>
<arg type="unichar*">buffer</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>getCString:</sel>
<arg type="char*">buffer</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>getCString:</sel>
<arg type="char*">buffer</arg>
<sel>maxLength:</sel>
<arg type="unsigned int">maxLength</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>getCString:</sel>
<arg type="char*">buffer</arg>
<sel>maxLength:</sel>
<arg type="unsigned int">maxLength</arg>
<sel>range:</sel>
<arg type="NSRange">aRange</arg>
<sel>remainingRange:</sel>
<arg type="NSRange*">leftoverRange</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>getFileSystemRepresentation:</sel>
<arg type="char*">buffer</arg>
<sel>maxLength:</sel>
<arg type="unsigned int">maxLength</arg>
<desc>
</desc>
</method>
<method type="void" factory="yes">
<sel>getLineStart:</sel>
<arg type="unsigned int*">startIndex</arg>
<sel>end:</sel>
<arg type="unsigned int*">lineEndIndex</arg>
<sel>contentsEnd:</sel>
<arg type="unsigned int*">contentsEndIndex</arg>
<desc>
</desc>
</method>
<method type="unsigned int">
<sel>hash</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>hasPrefix:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>hasSuffix:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="id">
<sel>init</sel>
<desc>
</desc>
</method>
<method type="id">
<sel>initWithCharacters:</sel>
<arg type="const unichar*">characters</arg>
<desc>
</desc>
</method>
<method type="id" init="yes">
<sel>initWithCharactersNoCopy:</sel>
<arg type="unichar*">characters</arg>
<sel>length:</sel>
<arg type="unsigned int">length</arg>
<sel>freeWhenDone:</sel>
<arg type="BOOL">flag</arg>
<desc>
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.
</desc>
</method>
<method type="id">
<sel>initWithContentsOfFile:</sel>
<arg type="NSString*">path</arg>
<desc>
</desc>
</method>
<method type="id">
<sel>initWithCString:</sel>
<arg type="const char*">cString</arg>
<desc>
</desc>
</method>
<method type="id">
<sel>initWithCString:</sel>
<arg type="const char*">cString</arg>
<desc>
</desc>
</method>
<method type="id">
<sel>initWithCStringNoCopy:</sel>
<arg type="char*">cString</arg>
<sel>length:</sel>
<arg type="unsigned int">length</arg>
<sel>freeWhenDone:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
<method type="id">
<sel>initWithData:</sel>
<arg type="NSData*">data</arg>
<sel>encoding:</sel>
<arg type="NSStringEncoding">encoding</arg>
<desc>
</desc>
</method>
<method type="id">
<sel>initWithFormat:</sel>
<arg type="NSString*">format</arg>
<vararg/>
<desc>
Invokes initWithFormat:locale:arguments with a nil locale.
</desc>
</method>
<method type="id">
<sel>initWithFormat:</sel>
<arg type="NSString*">format</arg>
<sel>arguments:</sel>
<arg type="va_list">argList</arg>
<desc>
Invokes initWithFormat:locale:arguments with a nil locale.
</desc>
</method>
<method type="id">
<sel>initWithFormat:</sel>
<arg type="NSString*">format</arg>
<sel>locale:</sel>
<arg type="NSDictionary*">dictionary</arg>
<vararg/>
<desc>
Initialises the string using the specified format and local
to format the following arguments.
</desc>
</method>
<method type="id">
<sel>initWithFormat:</sel>
<arg type="NSString*">format</arg>
<sel>arguments:</sel>
<arg type="va_list">argList</arg>
<desc>
Invokes initWithFormat:locale:,... with a nil locale.
</desc>
</method>
<method type="id">
<sel>initWithFormat:</sel>
<arg type="NSString*">format</arg>
<sel>locale:</sel>
<arg type="NSDictionary*">dictionary</arg>
<sel>arguments:</sel>
<arg type="va_list">argList</arg>
<desc>
Initialises the string using the specified format and local
to format the following arguments.
</desc>
</method>
<method type="id">
<sel>initWithString:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="int">
<sel>intValue</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>isAbsolutePath</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>isEqualToString:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>lastPathComponent</sel>
<desc>
</desc>
</method>
<method type="unsigned int">
<sel>length</sel>
<desc>
</desc>
</method>
<method type="NSRange" factory="yes">
<sel>lineRangeForRange:</sel>
<arg type="NSRange">aRange</arg>
<desc>
</desc>
</method>
<method type="const char*">
<sel>lossyCString</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>lowercaseString</sel>
<desc>
Returns a copy of the receiver with all characters converted
to lowercase.
</desc>
</method>
<method type="NSArray*">
<sel>pathComponents</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>pathExtension</sel>
<desc>
</desc>
</method>
<method type="id">
<sel>propertyList</sel>
<desc>
</desc>
</method>
<method type="NSDictionary*">
<sel>propertyListFromStringsFileFormat</sel>
<desc>
</desc>
</method>
<method type="NSRange">
<sel>rangeOfCharacterFromSet:</sel>
<arg type="NSCharacterSet*">aSet</arg>
<desc>
</desc>
</method>
<method type="NSRange">
<sel>rangeOfCharacterFromSet:</sel>
<arg type="NSCharacterSet*">aSet</arg>
<sel>options:</sel>
<arg type="unsigned int">mask</arg>
<desc>
</desc>
</method>
<method type="NSRange">
<sel>rangeOfCharacterFromSet:</sel>
<arg type="NSCharacterSet*">aSet</arg>
<sel>options:</sel>
<arg type="unsigned int">mask</arg>
<sel>range:</sel>
<arg type="NSRange">aRange</arg>
<desc>
</desc>
</method>
<method type="NSRange">
<sel>rangeOfComposedCharacterSequenceAtIndex:</sel>
<arg type="unsigned int">anIndex</arg>
<desc>
</desc>
</method>
<method type="NSRange">
<sel>rangeOfString:</sel>
<arg type="NSString*">aString</arg>
<desc>
Invokes <em>rangeOfString:options:</em> with the options mask
set to zero.
</desc>
</method>
<method type="NSRange">
<sel>rangeOfString:</sel>
<arg type="NSString*">aString</arg>
<sel>options:</sel>
<arg type="unsigned int">mask</arg>
<desc>
Invokes <em>rangeOfString:options:range</em> with the range set
set to the range of the whole of the reciever.
</desc>
</method>
<method type="NSRange">
<sel>rangeOfString:</sel>
<arg type="NSString*">subString</arg>
<sel>options:</sel>
<arg type="unsigned int">mask</arg>
<sel>range:</sel>
<arg type="NSRange">aRange</arg>
<desc>
Returns the range giving the location and length of the first
occurrence of <em>subString</em> within <em>aRange</em>.
<br/>
If <em>subString</em> does not exist in the receiver (an empty
string is <em>never</em> considered to exist in the receiver),
the length of the returned range is zero.
<br/>
If <em>substring</em> is nil, an exception is raised.
<br/>
If any part of <em>aRange</em> lies outside the range of the
receiver, an exception is raised.
<br/>
The optionsm mask may contain the following options -
<list>
<item>NSCaseInsensitiveSearch</item>
<item>NSLiteralSearch</item>
<item>NSBackwardsSearch</item>
<item>NSAnchoredSearch</item>
</list>
</desc>
</method>
<method type="NSStringEncoding">
<sel>smallestEncoding</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByAbbreviatingWithTildeInPath</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByAppendingFormat:</sel>
<arg type="NSString*">format,</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByAppendingPathComponent:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByAppendingPathExtension:</sel>
<arg type="NSString*">string</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByAppendingString:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByDeletingLastPathComponent</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByDeletingPathExtension</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByExpandingTildeInPath</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>stringByReplacingString:</sel>
<arg type="NSString*">aString</arg>
<sel>withString:</sel>
<arg type="NSString*">replacement</arg>
<desc>
Returns a string in which any (and all) occurrances of
<em>aString</em> in the receiver have been replaced by
<em>replacement</em>. Returns the receiver if <em>aString</em>
does not occur within the receiver. NB. an empty string is
not considered to exist within the receiver.
</desc>
<standards><GNUstep/><NotMacOS-X/><NotOpenStep/></standards>
</method>
<method type="NSArray*">
<sel>stringsByAppendingPaths:</sel>
<arg type="NSArray*">paths</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>substringFromIndex:</sel>
<arg type="unsigned int">anIndex</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>substringToIndex:</sel>
<arg type="unsigned int">anIndex</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>substringWithRange:</sel>
<arg type="NSRange">aRange</arg>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>uppercaseString</sel>
<desc>
Returns a copy of the receiver with all characters converted
to uppercase.
</desc>
</method>
<method type="BOOL">
<sel>writeToFile:</sel>
<arg type="NSString*">path</arg>
<sel>atomically:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
</class>
</chapter>
</body>
</gsdoc>