home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / DEV.Z / NSString.h < prev    next >
Text File  |  1996-09-11  |  18KB  |  416 lines
  1. /*    NSString.h
  2.     Copyright 1994-1996, NeXT Software, Inc.  All rights reserved.
  3. */
  4.  
  5. /*
  6. NSString and NSMutableString are two abstract classes for string
  7. manipulation.  NSString provides methods for read-only access, while
  8. NSMutableString allows for changing the contents of the string. These
  9. classes provide factory methods which will return autoreleased
  10. instances of unspecified subclasses of strings.
  11.  
  12. Canonically, the contents of string objects are Unicode(tm) characters
  13. (defined by the unichar data type).  This means that the default set
  14. of methods where the word "character," "range," and "length" are used
  15. refer to strings of unichars and ranges and lengths of such strings.
  16. This is an important point, as the conversion between unichars and
  17. other character encodings is not one-to-one. For instance, a NEXTSTEP
  18. encoded string which is 10 characters might contain fewer or more
  19. characters when encoded as unichars. Another important point is that
  20. unichars don't necessarily have a one-to-one correspondence with
  21. what we tend to think of as "letters" in a string; if you need to go
  22. through a string in terms of "letters" (for instance, you are creating
  23. a crossword puzzle), use rangeOfComposedCharacterSequenceAtIndex:.
  24.  
  25. Methods which take "CString" arguments deal with the default 8-bit
  26. encoding of the environment. This is typically NEXTSTEP encoding, but
  27. could be EUC or ISOLatin1. You can also explicitly convert to and from
  28. any encoding by using methods such as initWithData:encoding: and
  29. dataUsingEncoding:. 
  30.  
  31. Constant NSStrings can be created with the @"..." option. At the
  32. moment they have a C-String backing. For most portable code, these
  33. strings should contain only ASCII chars, nothing more.
  34.  
  35. Strings are provided with generic coding behavior when used for
  36. storage or distribution.  This behavior is to copy the contents
  37. and provide a generic NSString implementation, losing class but
  38. preserving mutability.
  39. */
  40.  
  41. typedef unsigned short unichar;
  42.  
  43. #import <Foundation/NSObject.h>
  44. #import <Foundation/NSRange.h>
  45. #import <limits.h>
  46. #import <stdarg.h>
  47.  
  48. @class NSData, NSArray, NSDictionary, NSCharacterSet;
  49.  
  50. #define NSMaximumStringLength    (INT_MAX-1)
  51.  
  52. /* Flags passed to compare & rangeOf...: With a zero mask passed in, the searches are case sensitive, from the beginning, are non-anchored, and take Unicode floating diacritics and other non-visible characters into account.
  53. */
  54. enum {
  55.     NSCaseInsensitiveSearch = 1,
  56.     NSLiteralSearch = 2,    /* Character-by-character search */
  57.     NSBackwardsSearch = 4,    /* Search backwards in the range */
  58.     NSAnchoredSearch = 8    /* Search anchored within specified range (prefix or suffix) */
  59. };
  60.  
  61. typedef unsigned NSStringEncoding;
  62.  
  63. enum {    /* Encodings supported by all OpenStep implementations */
  64.     NSASCIIStringEncoding = 1,        /* 0..127 only */
  65.     NSNEXTSTEPStringEncoding = 2,
  66.     NSJapaneseEUCStringEncoding = 3,
  67.     NSUTF8StringEncoding = 4,
  68.     NSISOLatin1StringEncoding = 5,
  69.     NSSymbolStringEncoding = 6,
  70.     NSNonLossyASCIIStringEncoding = 7,    /* 7-bit verbose ASCII to represent all unichars */
  71.     NSShiftJISStringEncoding = 8,
  72.     NSISOLatin2StringEncoding = 9,
  73.     NSUnicodeStringEncoding = 10,
  74. #if !defined(STRICT_OPENSTEP)
  75.     NSWindowsCP1251StringEncoding = 11,    /* Cyrillic; same as AdobeStandardCyrillic */
  76.     NSWindowsCP1252StringEncoding = 12,    /* WinLatin1 */
  77.     NSWindowsCP1253StringEncoding = 13,    /* Greek */
  78.     NSWindowsCP1254StringEncoding = 14,    /* Turkish */
  79.     NSWindowsCP1250StringEncoding = 15,    /* WinLatin2 */
  80.     NSISO2022JPStringEncoding = 21         /* ISO 2022 Japanese encoding for e-mail */
  81. #endif /* !STRICT_OPENSTEP */
  82. };
  83.  
  84. FOUNDATION_EXPORT NSString *NSCharacterConversionException;
  85.  
  86. /**** The abstract NSString... ****/
  87.  
  88. @interface NSString : NSObject <NSCopying, NSMutableCopying, NSCoding>
  89.  
  90. /**** NSString primitives ****/
  91.  
  92. /* The most basic (primitive) string methods. Note that the methods
  93. length and characterAtIndex: work in terms of unichars, which don't
  94. necessarily have a one-to-one correspondence with the "letters" in a
  95. string.  All direct subclassers need to implement these methods. For
  96. efficiency, it's recommended that subclassers also implement
  97. getCharacters:range: (a non-primitive).
  98. */
  99. - (unsigned int)length;            
  100. - (unichar)characterAtIndex:(unsigned)index;
  101.  
  102. @end
  103.  
  104. @interface NSString (NSStringExtensionMethods)
  105.  
  106. /**** NSString methods built on the primitives ****/
  107.  
  108. /* Much faster alternative to multiple characterAtIndex: calls.
  109. */
  110. - (void)getCharacters:(unichar *)buffer;
  111. - (void)getCharacters:(unichar *)buffer range:(NSRange)aRange;
  112.  
  113. /* Substrings: Get a substring of an existing string. This operation is often fast. The first two methods are implemented in terms of the third one.
  114. */
  115. - (NSString *)substringFromIndex:(unsigned)from;    /* From location to end of string */
  116. - (NSString *)substringToIndex:(unsigned)to;        /* From beginning of string to location - 1 */
  117. - (NSString *)substringWithRange:(NSRange)range;
  118.  
  119. /* Comparison: Compare two strings. Possible options are: NSCaseInsensitiveSearch, NSLiteralSearch. If the range argument is provided, the specified range in the receiver is compared against the other string.
  120. */
  121. - (NSComparisonResult)compare:(NSString *)obj;
  122. - (NSComparisonResult)compare:(NSString *)obj options:(unsigned)mask;
  123. - (NSComparisonResult)compare:(NSString *)obj options:(unsigned)mask range:(NSRange)compareRange;
  124. - (NSComparisonResult)caseInsensitiveCompare:(NSString *)obj;
  125.  
  126. /* Check for equality.
  127. */
  128. - (BOOL)isEqualToString:(NSString *)aString;
  129.  
  130. /* Find: Find a string within another string.  If not found returned
  131. length is set to zero.  Possible options are: NSCaseInsensitiveSearch,
  132. NSLiteralSearch, NSBackwardsSearch, NSAnchoredSearch. hasPrefix: is a
  133. cover for [str rangeOfString:str options:NSAnchoredSearch].length != 0.
  134. Note that the search will fail if the searched string is the empty string.
  135. */
  136. - (BOOL)hasPrefix:(NSString *)aString;
  137. - (BOOL)hasSuffix:(NSString *)aString;
  138. - (NSRange)rangeOfString:(NSString *)aString;
  139. - (NSRange)rangeOfString:(NSString *)aString options:(unsigned)mask;
  140. - (NSRange)rangeOfString:(NSString *)aString options:(unsigned)mask range:(NSRange)searchRange;
  141.  
  142. /* Find: Find the first occurrence of a character from the specified
  143. set and returns its range. Note that the range covers only the first
  144. found character, not a sequence of characters. If not found, returned
  145. length is 0.  Possible options are: NSLiteralSearch, NSBackwardsSearch,
  146. NSAnchoredSearch.
  147. */
  148. - (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet;
  149. - (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(unsigned int)mask;
  150. - (NSRange)rangeOfCharacterFromSet:(NSCharacterSet *)aSet options:(unsigned int)mask range:(NSRange)searchRange;
  151.  
  152. /* This method returns the range of the "composed character sequence" at
  153. the specified location. Composed character sequences are what we normally
  154. think of as letters. In the Unicode standard, sometimes multiple characters
  155. combine to form one letter (for instance, "o" and dierisis).  You can use
  156. this method to traverse a string by letters:
  157.     NSRange range = NSMakeRange(0, 0);
  158.     while ((range.location = NSMaxRange(range)) < [string length]) {
  159.     range = [str rangeOfComposedCharacterSequenceAtIndex:range.location];
  160.     letter = [str substringWithRange:range];
  161.     }
  162. */
  163. - (NSRange)rangeOfComposedCharacterSequenceAtIndex:(unsigned)index;
  164.  
  165. /* Appending: These are immutable versions of some of the popular mutable methods.
  166. */
  167. - (NSString *)stringByAppendingString:(NSString *)aString;
  168. - (NSString *)stringByAppendingFormat:(NSString *)format, ...;
  169.  
  170. /* Float/Int Conversion: Simple-minded methods that skip whitespace and
  171. ignore bogus characters past the end. On overflow they return HUGE_VAL,
  172. -HUGE_VAL, INT_MIN, INT_MAX. doubleValue & floatValue return 0.0 on
  173. underflow. Use NSScanner for more sophisticated scanning.
  174. */
  175. - (double)doubleValue;
  176. - (float)floatValue;
  177. - (int)intValue;
  178.  
  179. /* Exploding: Returns an array holding the substrings in the string which
  180. are separated by the separator. All strings split into arrays of 1 or more
  181. elements. For instance, if the string is "/A/B//C" and the separator is
  182. "/", the return value will be ["", "A", "B", "", "C"]. The result will be
  183. [""] if the string is empty. See also componentsJoinedByString: in NSArray.
  184. */
  185. - (NSArray *)componentsSeparatedByString:(NSString *)separator;
  186.  
  187. /* Finds the longest common prefix between the two strings. Returns the substring of the receiver. Possible options are: NSCaseInsensitiveSearch, NSLiteralSearch.
  188. */
  189. - (NSString *)commonPrefixWithString:(NSString *)aString options:(unsigned)mask;
  190.  
  191. /* Methods to return uppercase (HI THERE), lowercase (hi there), and capitalized (Hi There) versions of a string.
  192. */
  193. - (NSString *)uppercaseString;
  194. - (NSString *)lowercaseString;
  195. - (NSString *)capitalizedString;
  196.  
  197. #if !defined(STRICT_OPENSTEP)
  198. /* Methods to extract ranges of lines. The first method basically expands the given
  199. range to line boundaries. The returned values are:
  200.  
  201.    start:         location of the first character of the line.
  202.    lineEnd:       location of the first character past the end of the line.
  203.    contentsEnd:   location of the first character of the line separator at the end of the line.
  204.  
  205. As usual, these return values are optional; if NULL is passed in as an argument,
  206. the work to compute the value will not be performed.
  207.  
  208.    string:                        A B C \n D E F \n G H  I \r \n \r \n  J...
  209.    locations:                     0 1 2  3 4 5 6  7 8 9 10 11 12 13 14 15...
  210.    start, lineEnd, contentsEnd:    (0,4,3)  (4,8,7)  (8,13,11) (13,15,13)...
  211.  
  212.    range   start  lineEnd   contentsEnd
  213.     0,0      0       4           3
  214.     3,0      0       4           3                                                                
  215.     4,0      4       8           7
  216.     5,3      4       8           7
  217.     5,4      4      13          11
  218.    14,0     13      15          13
  219.    
  220. The second method, lineRangeForRange: is a simple cover which returns the range {start, lineEnd-start}.
  221. */
  222. - (void)getLineStart:(unsigned *)startPtr end:(unsigned *)lineEndPtr contentsEnd:(unsigned *)contentsEndPtr forRange:(NSRange)range;
  223. - (NSRange)lineRangeForRange:(NSRange)range;
  224. #endif /* !STRICT_OPENSTEP */
  225.  
  226. /* Returns the string itself.
  227. */
  228. - (NSString *)description;
  229.  
  230. /* NSObject Protocol
  231. */
  232. - (unsigned)hash;
  233.  
  234.  
  235. /**** Encoding related methods follow. ****/
  236.  
  237. /* Default implementations of these methods might end up converting to Unicode and back in some cases; subclassers with non-Unicode backing stores might want to override some of these methods for added efficiency. */
  238.  
  239. /* Encoding in which this string can be expressed (with lossless conversion) in a quick manner (both this method and the conversion will be fast; space efficiency is a secondary issue).
  240. */
  241. - (NSStringEncoding)fastestEncoding;
  242.  
  243. /* Encoding in which this string can be expressed (with lossless conversion) in a space efficient manner (this method and the conversion might be slow; however, it will indicate the most space efficient encoding).
  244. */
  245. - (NSStringEncoding)smallestEncoding;
  246.  
  247. /* Contents in specified encoding, in the generic plain text format for
  248. the encoding. This method will return nil if the conversion cannot be
  249. performed. With this data and the encoding you can recreate the string
  250. using the initFromData:encoding: method. The result of this method is
  251. the only way you should make contents of strings persistent.
  252. */
  253. - (NSData *)dataUsingEncoding:(NSStringEncoding)encoding allowLossyConversion:(BOOL)lossy;
  254. - (NSData *)dataUsingEncoding:(NSStringEncoding)encoding;    /* Not lossy */
  255.  
  256. /* Returns whether it is possible to convert the whole string to the
  257. specified encoding. Might call dataUsingEncoding: in some cases, so if
  258. you are going to do the conversion anyway, you might as well skip this method.
  259. */
  260. - (BOOL)canBeConvertedToEncoding:(NSStringEncoding)encoding;
  261.  
  262. /* These methods basically use the default 8-bit character encoding.
  263. This encoding is most likely NEXTSTEP; use +defaultCStringEncoding if
  264. you need to know what it is. The getCString: methods all zero-terminate
  265. the buffer; so buffer should actually contain max + 1 bytes (when max
  266. is provided).
  267. */
  268. - (const char *)cString;    /* "Autoreleased," null-terminated C string. Raises if conversion not possible. */
  269. - (const char *)lossyCString;    /* "Autoreleased," null-terminated C string. */
  270. - (unsigned)cStringLength;
  271. - (void)getCString:(char *)bytes;
  272. - (void)getCString:(char *)bytes maxLength:(unsigned)maxLength;
  273. - (void)getCString:(char *)bytes maxLength:(unsigned)maxLength range:(NSRange)aRange remainingRange:(NSRange *)leftoverRange;
  274. + (NSStringEncoding)defaultCStringEncoding;    /* Returns the encoding used for the CString methods */
  275.  
  276. /* Writes the contents of the string to the specified file. This is a
  277. convenience method; it will first try to write the file in default
  278. CString encoding; if this isn't possible, it will write it in Unicode
  279. encoding. initWithContentsOfFile: is the corresponding method for input.
  280. If you want to write a file with a given encoding, use
  281. dataUsingEncoding:/initWithData:encoding:
  282. */
  283. - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;
  284.  
  285. /* Methods to obtain info about supported encodings.
  286. */
  287. + (const NSStringEncoding *)availableStringEncodings; /* 0 terminated array */
  288. + (NSString *)localizedNameOfStringEncoding:(NSStringEncoding)encoding;
  289.  
  290. /**** Methods to create strings ***/
  291.  
  292. /* Some cover methods to return autoreleased strings. These methods are the simple way to create new strings. A more complete set of initialization methods is presented further below.
  293. */
  294.  
  295. #if !defined(STRICT_OPENSTEP)
  296. + (id)string;
  297. + (id)stringWithString:(NSString *)string;
  298. #endif /* !STRICT_OPENSTEP */
  299.  
  300. + (id)stringWithCharacters:(const unichar *)characters length:(unsigned)length;
  301. + (id)stringWithCString:(const char *)bytes length:(unsigned)length;
  302. + (id)stringWithCString:(const char *)bytes;
  303. + (id)stringWithFormat:(NSString *)format, ...;
  304. + (id)stringWithContentsOfFile:(NSString *)path; /* defaultCString encoding OR Unicode encoding */ 
  305. + (id)localizedStringWithFormat:(NSString *)format, ...; /* Uses user's defaults */
  306.  
  307. /* Initialization methods which concrete subclasses of NSString and
  308. NSMutableString provided by foundation respond to. Note that because
  309. the alloc methods of NSString and NSMutableString return instances of
  310. a concrete subclass, these init methods can be sent to that object.
  311.  
  312. These methods will not work in custom subclasses of NSString &
  313. NSMutableString. Custom subclassers should provide their own init...
  314. methods, and call [super init] in their designated initializers.
  315. */
  316. - (id)init;
  317. - (id)initWithCharactersNoCopy:(unichar *)characters length:(unsigned)length freeWhenDone:(BOOL)freeBuffer;
  318. - (id)initWithCharacters:(const unichar *)characters length:(unsigned)length;
  319. - (id)initWithCStringNoCopy:(char *)bytes length:(unsigned)length freeWhenDone:(BOOL)freeBuffer;
  320. - (id)initWithCString:(const char *)bytes length:(unsigned)length;
  321. - (id)initWithCString:(const char *)bytes; /* Zero terminated */
  322. - (id)initWithString:(NSString *)aString;
  323. - (id)initWithFormat:(NSString *)format, ...; /* For localized formatting use initWithFormat:locale: */
  324. - (id)initWithFormat:(NSString *)format arguments:(va_list)argList;
  325. - (id)initWithFormat:(NSString *)format locale:(NSDictionary *)dict, ...;
  326. - (id)initWithFormat:(NSString *)format locale:(NSDictionary *)dict arguments:(va_list)argList;
  327. - (id)initWithData:(NSData *)data encoding:(NSStringEncoding)encoding;
  328. - (id)initWithContentsOfFile:(NSString *)path; /* defaultCString encoding OR Unicode encoding */
  329.  
  330. @end
  331.  
  332.  
  333. /**** Abstract mutable string class... ****/
  334.  
  335. @interface NSMutableString : NSString
  336.  
  337. /**** Primitives (needs to be implemented by subclassers)... ****/
  338.  
  339. - (void)replaceCharactersInRange:(NSRange)range withString:(NSString *)aString;
  340.  
  341. @end
  342.  
  343. @interface NSMutableString (NSMutableStringExtensionMethods)
  344.  
  345. /**** Mutable string methods built on the primitives ****/
  346.  
  347. - (void)insertString:(NSString *)aString atIndex:(unsigned)loc;
  348. - (void)deleteCharactersInRange:(NSRange)range;
  349. - (void)appendString:(NSString *)aString;
  350. - (void)appendFormat:(NSString *)format, ...;
  351. - (void)setString:(NSString *)aString;    /* Copy the contents of the other string */
  352.  
  353. /**** Methods to create mutable strings ****/
  354.  
  355. + (id)stringWithCapacity:(unsigned)capacity;
  356. - (id)initWithCapacity:(unsigned)capacity;
  357.  
  358. @end
  359.  
  360.  
  361. /***************    ASCII Property List encoding        ***********/
  362.  
  363. @interface NSString (NSExtendedStringPropertyListParsing)
  364.     
  365. - (id)propertyList;
  366.     /* understands the PropertyList classes (NSString, NSData, NSArray, NSDictionary);
  367.     May raise */
  368.  
  369. - (NSDictionary *)propertyListFromStringsFileFormat;
  370.     /* understands the .strings files;
  371.     Using -propertyList should be preferred for non .strings files.
  372.     May raise */
  373.  
  374. @end
  375.  
  376.  
  377. /**** The rest of this file is bookkeeping stuff that has to be here (for now). Don't use this stuff, don't refer to it.
  378. */
  379. /* To reduce confusion with the old (private) NXString. If you need to import the old headers, do so after NSString.h.
  380. */
  381. #if !defined(_OBJC_UNICHAR_H_)
  382. #define _OBJC_UNICHAR_H_
  383. #endif
  384. #define NS_UNICHAR_IS_EIGHT_BIT 0
  385.  
  386. @interface NSSimpleCString : NSString {
  387. @protected
  388.     char *bytes;
  389.     unsigned int numBytes;
  390. }
  391. @end
  392.  
  393. //#if defined(WIN32) || defined(SOLARIS) || defined(SUNOS) || defined(HPUX) || defined(OSF1)
  394. #if defined(NeXT_PDO)
  395. /* To please the compiler when it encounters @"..."
  396. */
  397. #if !defined(_OBJC_NXSTRING_H_)
  398. #if !defined(_OBJC_DEFINED_NXCONSTANTSTRING)
  399. #define _OBJC_DEFINED_NXCONSTANTSTRING
  400. @interface NXConstantString : NSSimpleCString
  401. @end
  402. #endif
  403. #endif
  404. #endif
  405.  
  406. /* NSConstantStrings are strings created by the compiler with the @" " construct.  Upon encountering @" ", the compiler will take the characters between the quotes and create an NSConstantString instance.
  407. Instances of NSConstantString cannot be created at runtime.
  408. */
  409. @interface NSConstantString : NSSimpleCString
  410. @end
  411.  
  412. // This is neccessary for the compiler, however it should never
  413. // be used explicitly, so don't.
  414. extern void* _NSConstantStringClassReference;
  415.  
  416.