1 /* Interface for NSString for GNUstep
2 Copyright (C) 1995, 1996, 1999 Free Software Foundation, Inc.
3
4 Written by: Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
5 Date: 1995
6
7 This file is part of the GNUstep Base Library.
8
9 This library is free software; you can redistribute it and/or
10 modify it under the terms of the GNU Lesser General Public
11 License as published by the Free Software Foundation; either
12 version 2 of the License, or (at your option) any later version.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Library General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library; if not, write to the Free
21 Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 Boston, MA 02111 USA.
23 */
24
25 /**
26 <chapter>
27 <heading>Portable path handling</heading>
28 <p>Portable path handling (across both unix-like and mswindows operating
29 systems) requires some care. A modern operating system uses the concept
30 of a single root to the filesystem, but mswindows has multiple filesystems
31 with no common root, so code must be aware of this. There is also the
32 more minor issue that windows often uses a backslash as a separator between
33 the components of a path and unix-like systems always use forward slash.<br />
34 On windows there is also the issue that two styles of path are used,
35 most commonly with a drive letter and a path on that drive
36 (eg. 'C:\directory\file') but also UNC paths
37 (eg. '//host/share/directory/file') so path handling functions must deal
38 with both formats.
39 </p>
40 <p>GNUstep has three path handling modes, 'gnustep', 'unix', and 'windows'.
41 The mode defaults to 'gnustep' but may be set using the GSPathHandling()
42 function.<br />
43 You should probably stick to using the default 'gnustep' mode in which the
44 path handling methods cope with both 'unix' and 'windows' style paths in
45 portable and tolerant manner:<br />
46 Paths are read in literally so they can be in the native format provided
47 by the operating system or in a non-native format. See
48 [NSFileManager-stringWithFileSystemRepresentation:length:].<br />
49 Paths are written out using the native format of the system the application
50 is running on (eg on windows slashes are converted to backslashes).
51 See [NSFileManager-fileSystemRepresentationWithPath:].<br />
52 The path handling methods accept either a forward or backward slash as a
53 path separator when parsing any path.<br />
54 Unless operating in 'unix' mode, a leading letter followed by a colon is
55 considered the start of a windows style path (the drive specifier), and a
56 path beginning with something of the form '//host/share/' is considered
57 the start of a UNC style path.<br />
58 The path handling methods add forward slashes when building new paths
59 internally or when standardising paths, so those path strings provide
60 a portable representation (as long as they are relative paths, not including
61 system specific roots).<br />
62 An important case to note is that on windows a path which looks at first
63 glance like an absolute path may actually be a relative one.<br />
64 'C:file' is a relative path because it specifies a file on the C drive
65 but does not say what directory it is in.<br />
66 Similarly, '/dir/file' is a relative path because it specifies the full
67 location fo a file on a drive, but does not specify which drive it is on.
68 </p>
69 <p>As a consequence of this path handling, you are able to work completely
70 portably using relative paths (adding components, extensions and
71 relative paths to a pth, or removing components, extensions and relative
72 paths from a path etc), and when you save paths as strings in files
73 which may be transferred to another platform, you should save a relative
74 path.<br />
75 When you need to know absolute paths of various points in the filesystem,
76 you can use various path utility functions to obtain those absolute paths.
77 For instance, instead of saving an absolute path to a file, you might want
78 to save a path relative to a user's home directory. You could do that by
79 calling NSHomeDirectory() to get the home directory, and only saving the
80 part of the full path after that prefix.
81 </p>
82 </chapter>
83 */
84
85 #ifndef __NSString_h_GNUSTEP_BASE_INCLUDE
86 #define __NSString_h_GNUSTEP_BASE_INCLUDE
87 #import "../GNUstepBase/GSVersionMacros.h"
88
89 #import "NSObject.h"
90 #import "NSRange.h"
91
92 #if defined(__cplusplus)
93 extern "C" {
94 #endif
95
96 /**
97 * Type for representing unicode characters. (16-bit)
98 */
99 typedef uint16_t unichar;
100
101 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5,GS_API_LATEST)
102 #define NSMaximumStringLength (INT_MAX-1)
103 #endif
104
105 @class NSArray;
106 @class NSCharacterSet;
107 @class NSData;
108 @class NSDictionary;
109 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
110 @class NSError;
111 @class NSLocale;
112 @class NSURL;
113 #endif
114
115 #define NSMaximumStringLength (INT_MAX-1)
116
117 enum
118 {
119 NSCaseInsensitiveSearch = 1,
120 NSLiteralSearch = 2,
121 NSBackwardsSearch = 4,
122 NSAnchoredSearch = 8,
123 NSNumericSearch = 64 /* MacOS-X 10.2 */
124 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5,GS_API_LATEST)
125 ,
126 NSDiacriticInsensitiveSearch = 128,
127 NSWidthInsensitiveSearch = 256,
128 NSForcedOrderingSearch = 512
129 #endif
130 #if OS_API_VERSION(MAC_OS_X_VERSION_10_7,GS_API_LATEST)
131 ,
132 /**
133 * Treats the search string as a regular expression. This option may be
134 * combined with NSCaseInsensitiveSearch and NSAnchoredSearch, but no other
135 * search options.
136 *
137 * This option may only be used with the -rangeOfString: family of methods.
138 */
139 NSRegularExpressionSearch = 1024
140 #endif
141 };
142 typedef NSUInteger NSStringCompareOptions;
143
144 /**
145 * <p>Enumeration of available encodings for converting between bytes and
146 * characters (in [NSString]s). The ones that are shared with OpenStep and
147 * Cocoa are: <code>NSASCIIStringEncoding, NSNEXTSTEPStringEncoding,
148 * NSJapaneseEUCStringEncoding, NSUTF8StringEncoding,
149 * NSISOLatin1StringEncoding, NSSymbolStringEncoding,
150 * NSNonLossyASCIIStringEncoding, NSShiftJISStringEncoding,
151 * NSISOLatin2StringEncoding, NSUnicodeStringEncoding,
152 * NSWindowsCP1251StringEncoding, NSWindowsCP1252StringEncoding,
153 * NSWindowsCP1253StringEncoding, NSWindowsCP1254StringEncoding,
154 * NSWindowsCP1250StringEncoding, NSISO2022JPStringEncoding,
155 * NSMacOSRomanStringEncoding, NSProprietaryStringEncoding</code>.</p>
156 *
157 * <p>Additional encodings available under GNUstep are:
158 * <code>NSKOI8RStringEncoding, NSISOLatin3StringEncoding,
159 * NSISOLatin4StringEncoding, NSISOCyrillicStringEncoding,
160 * NSISOArabicStringEncoding, NSISOGreekStringEncoding,
161 * NSISOHebrewStringEncoding, NSISOLatin5StringEncoding,
162 * NSISOLatin6StringEncoding, NSISOThaiStringEncoding,
163 * NSISOLatin7StringEncoding, NSISOLatin8StringEncoding,
164 * NSISOLatin9StringEncoding, NSGB2312StringEncoding, NSUTF7StringEncoding,
165 * NSGSM0338StringEncoding, NSBIG5StringEncoding,
166 * NSKoreanEUCStringEncoding</code>.</p>
167 */
168 typedef enum _NSStringEncoding
169 {
170 /* NB. Must not have an encoding with value zero - so we can use zero to
171 tell that a variable that should contain an encoding has not yet been
172 initialised */
173 GSUndefinedEncoding = 0,
174 NSASCIIStringEncoding = 1,
175 NSNEXTSTEPStringEncoding = 2,
176 NSJapaneseEUCStringEncoding = 3,
177 NSUTF8StringEncoding = 4,
178 NSISOLatin1StringEncoding = 5, // ISO-8859-1; West European
179 NSSymbolStringEncoding = 6,
180 NSNonLossyASCIIStringEncoding = 7,
181 NSShiftJISStringEncoding = 8,
182 NSISOLatin2StringEncoding = 9, // ISO-8859-2; East European
183 NSUnicodeStringEncoding = 10,
184 NSUTF16StringEncoding = NSUnicodeStringEncoding, // An alias
185 NSWindowsCP1251StringEncoding = 11,
186 NSWindowsCP1252StringEncoding = 12, // WinLatin1
187 NSWindowsCP1253StringEncoding = 13, // Greek
188 NSWindowsCP1254StringEncoding = 14, // Turkish
189 NSWindowsCP1250StringEncoding = 15, // WinLatin2
190 NSISO2022JPStringEncoding = 21,
191 NSMacOSRomanStringEncoding = 30,
192 NSProprietaryStringEncoding = 31,
193
194 NSKOI8RStringEncoding = 50, // Russian/Cyrillic
195 NSISOLatin3StringEncoding = 51, // ISO-8859-3; South European
196 NSISOLatin4StringEncoding = 52, // ISO-8859-4; North European
197 NSISOCyrillicStringEncoding = 22, // ISO-8859-5
198 NSISOArabicStringEncoding = 53, // ISO-8859-6
199 NSISOGreekStringEncoding = 54, // ISO-8859-7
200 NSISOHebrewStringEncoding = 55, // ISO-8859-8
201 NSISOLatin5StringEncoding = 57, // ISO-8859-9; Turkish
202 NSISOLatin6StringEncoding = 58, // ISO-8859-10; Nordic
203 NSISOThaiStringEncoding = 59, // ISO-8859-11
204 /* Possible future ISO-8859 additions
205 // ISO-8859-12
206 */
207 NSISOLatin7StringEncoding = 61, // ISO-8859-13
208 NSISOLatin8StringEncoding = 62, // ISO-8859-14
209 NSISOLatin9StringEncoding = 63, // ISO-8859-15; Replaces ISOLatin1
210 NSGB2312StringEncoding = 56,
211 NSUTF7StringEncoding = 64, // RFC 2152
212 NSGSM0338StringEncoding, // GSM (mobile phone) default alphabet
213 NSBIG5StringEncoding, // Traditional chinese
214 NSKoreanEUCStringEncoding // Korean
215
216 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST)
217 ,
218 NSUTF16BigEndianStringEncoding = 0x90000100,
219 NSUTF16LittleEndianStringEncoding = 0x94000100,
220 NSUTF32StringEncoding = 0x8c000100,
221 NSUTF32BigEndianStringEncoding = 0x98000100,
222 NSUTF32LittleEndianStringEncoding = 0x9c000100
223 #endif
224 } NSStringEncoding;
225
226 enum {
227 NSOpenStepUnicodeReservedBase = 0xF400
228 };
229
230 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST)
231 enum {
232 NSStringEncodingConversionAllowLossy = 1,
233 NSStringEncodingConversionExternalRepresentation = 2
234 };
235 typedef NSUInteger NSStringEncodingConversionOptions;
236 #endif
237
238 /**
239 * <p>
240 * <code>NSString</code> objects represent an immutable string of Unicode 3.0
241 * characters. These may be accessed individually as type
242 * <code>unichar</code>, an unsigned short.<br/>
243 * The [NSMutableString] subclass represents a modifiable string. Both are
244 * implemented as part of a class cluster and the instances you receive may
245 * actually be of unspecified concrete subclasses.
246 * </p>
247 * <p>
248 * A constant <code>NSString</code> can be created using the following syntax:
249 * <code>@"..."</code>, where the contents of the quotes are the
250 * string, using only ASCII characters.
251 * </p>
252 * <p>
253 * A variable string can be created using a C printf-like <em>format</em>,
254 * as in <code>[NSString stringWithFormat: @"Total is %f", t]</code>.
255 * </p>
256 * <p>
257 * To create a concrete subclass of <code>NSString</code>, you must have your
258 * class inherit from <code>NSString</code> and override at least the two
259 * primitive methods - -length and -characterAtIndex:
260 * </p>
261 * <p>
262 * In general the rule is that your subclass must override any
263 * initialiser that you want to use with it. The GNUstep
264 * implementation relaxes that to say that, you may override
265 * only the <em>designated initialiser</em> and the other
266 * initialisation methods should work.
267 * </p>
268 * <p>
269 * Where an NSString instance method returns an NSString object,
270 * the class of the actual object returned may be any subclass
271 * of NSString. The actual value returned may be a new
272 * autoreleased object, an autoreleased copy of the receiver,
273 * or the receiver itsself. While the abstract base class
274 * implementations of methods (other than initialisers) will
275 * avoid returning mutable strings by returning an autoreleased
276 * copy of a mutable receiver, concrete subclasses may behave
277 * differently, so code should not rely upon the mutability of
278 * returned strings nor upon their lifetime being greater than
279 * that of the receiver which returned them.
280 * </p>
281 */
282 @interface NSString :NSObject <NSCoding, NSCopying, NSMutableCopying>
283
284 + (id) string;
285 + (id) stringWithCharacters: (const unichar*)chars
286 length: (NSUInteger)length;
287 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) && GS_API_VERSION( 10200,GS_API_LATEST)
288 + (id) stringWithCString: (const char*)byteString
289 encoding: (NSStringEncoding)encoding;
290 #endif
291 + (id) stringWithCString: (const char*)byteString
292 length: (NSUInteger)length;
293 + (id) stringWithCString: (const char*)byteString;
294 + (id) stringWithFormat: (NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
295 + (id) stringWithContentsOfFile:(NSString *)path;
296
297 // Initializing Newly Allocated Strings
298 - (id) init;
299 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) && GS_API_VERSION( 10200,GS_API_LATEST)
300 - (id) initWithBytes: (const void*)bytes
301 length: (NSUInteger)length
302 encoding: (NSStringEncoding)encoding;
303 - (id) initWithBytesNoCopy: (void*)bytes
304 length: (NSUInteger)length
305 encoding: (NSStringEncoding)encoding
306 freeWhenDone: (BOOL)flag;
307 #endif
308 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST)
309 + (id) stringWithContentsOfFile: (NSString*)path
310 usedEncoding: (NSStringEncoding*)enc
311 error: (NSError**)error;
312 - (id) initWithContentsOfFile: (NSString*)path
313 usedEncoding: (NSStringEncoding*)enc
314 error: (NSError**)error;
315 + (id) stringWithContentsOfFile: (NSString*)path
316 encoding: (NSStringEncoding)enc
317 error: (NSError**)error;
318 - (id) initWithContentsOfFile: (NSString*)path
319 encoding: (NSStringEncoding)enc
320 error: (NSError**)error;
321 + (id) stringWithContentsOfURL: (NSURL*)url
322 usedEncoding: (NSStringEncoding*)enc
323 error: (NSError**)error;
324 - (id) initWithContentsOfURL: (NSURL*)url
325 usedEncoding: (NSStringEncoding*)enc
326 error: (NSError**)error;
327 + (id) stringWithContentsOfURL: (NSURL*)url
328 encoding: (NSStringEncoding)enc
329 error: (NSError**)error;
330 - (id) initWithContentsOfURL: (NSURL*)url
331 encoding: (NSStringEncoding)enc
332 error: (NSError**)error;
333 - (BOOL) writeToFile: (NSString*)path
334 atomically: (BOOL)atomically
335 encoding: (NSStringEncoding)enc
336 error: (NSError**)error;
337 - (BOOL) writeToURL: (NSURL*)url
338 atomically: (BOOL)atomically
339 encoding: (NSStringEncoding)enc
340 error: (NSError**)error;
341 #endif
342 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5,GS_API_LATEST)
343 - (NSString*)stringByReplacingOccurrencesOfString: (NSString*)replace
344 withString: (NSString*)by
345 options: (NSStringCompareOptions)opts
346 range: (NSRange)searchRange;
347 - (NSString*)stringByReplacingOccurrencesOfString: (NSString*)replace
348 withString: (NSString*)by;
349 - (NSString*) stringByReplacingCharactersInRange: (NSRange)aRange
350 withString: (NSString*)by;
351 #endif
352 - (id) initWithCharactersNoCopy: (unichar*)chars
353 length: (NSUInteger)length
354 freeWhenDone: (BOOL)flag;
355 - (id) initWithCharacters: (const unichar*)chars
356 length: (NSUInteger)length;
357 - (id) initWithCStringNoCopy: (char*)byteString
358 length: (NSUInteger)length
359 freeWhenDone: (BOOL)flag;
360 - (id) initWithCString: (const char*)byteString
361 length: (NSUInteger)length;
362 - (id) initWithCString: (const char*)byteString;
363 - (id) initWithString: (NSString*)string;
364 - (id) initWithFormat: (NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
365 - (id) initWithFormat: (NSString*)format
366 arguments: (va_list)argList NS_FORMAT_FUNCTION(1,0);
367 - (id) initWithData: (NSData*)data
368 encoding: (NSStringEncoding)encoding;
369 - (id) initWithContentsOfFile: (NSString*)path;
370
371 // Getting a String's Length
372 - (NSUInteger) length;
373
374 // Accessing Characters
375 - (unichar) characterAtIndex: (NSUInteger)index;
376 - (void) getCharacters: (unichar*)buffer;
377 - (void) getCharacters: (unichar*)buffer
378 range: (NSRange)aRange;
379
380 // Combining Strings
381 - (NSString*) stringByAppendingFormat: (NSString*)format, ...
382 NS_FORMAT_FUNCTION(1,2);
383 - (NSString*) stringByAppendingString: (NSString*)aString;
384
385 // Dividing Strings into Substrings
386 - (NSArray*) componentsSeparatedByString: (NSString*)separator;
387 - (NSString*) substringFromIndex: (NSUInteger)index;
388 - (NSString*) substringToIndex: (NSUInteger)index;
389
390 // Finding Ranges of Characters and Substrings
391 - (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet;
392 - (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet
393 options: (NSUInteger)mask;
394 - (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet
395 options: (NSUInteger)mask
396 range: (NSRange)aRange;
397 - (NSRange) rangeOfString: (NSString*)string;
398 - (NSRange) rangeOfString: (NSString*)string
399 options: (NSUInteger)mask;
400 - (NSRange) rangeOfString: (NSString*)aString
401 options: (NSUInteger)mask
402 range: (NSRange)aRange;
403
404 // Determining Composed Character Sequences
405 - (NSRange) rangeOfComposedCharacterSequenceAtIndex: (NSUInteger)anIndex;
406
407 #if OS_API_VERSION(MAC_OS_X_VERSION_10_2,GS_API_LATEST)
408 /** Returns a copy of the receiver normalised using the KD form.
409 */
410 - (NSString *) decomposedStringWithCompatibilityMapping;
411
412 /** Returns a copy of the receiver normalised using the D form.
413 */
414 - (NSString *) decomposedStringWithCanonicalMapping;
415
416 /** Returns a copy of the receiver normalised using the KC form.
417 */
418 - (NSString *) precomposedStringWithCompatibilityMapping;
419
420 /** Returns a copy of the receiver normalised using the C form.
421 */
422 - (NSString *) precomposedStringWithCanonicalMapping;
423 #endif
424
425 // Converting String Contents into a Property List
426 - (id) propertyList;
427 - (NSDictionary*) propertyListFromStringsFileFormat;
428
429 // Identifying and Comparing Strings
430 - (NSComparisonResult) compare: (NSString*)aString;
431 - (NSComparisonResult) compare: (NSString*)aString
432 options: (NSUInteger)mask;
433 - (NSComparisonResult) compare: (NSString*)aString
434 options: (NSUInteger)mask
435 range: (NSRange)aRange;
436 - (BOOL) hasPrefix: (NSString*)aString;
437 - (BOOL) hasSuffix: (NSString*)aString;
438 - (BOOL) isEqual: (id)anObject;
439 - (BOOL) isEqualToString: (NSString*)aString;
440 - (NSUInteger) hash;
441
442 // Getting a Shared Prefix
443 - (NSString*) commonPrefixWithString: (NSString*)aString
444 options: (NSUInteger)mask;
445
446 // Changing Case
447 - (NSString*) capitalizedString;
448 - (NSString*) lowercaseString;
449 - (NSString*) uppercaseString;
450
451 // Getting C Strings
452 - (const char*) cString;
453 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
454
455 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4,GS_API_LATEST) && GS_API_VERSION( 10200,GS_API_LATEST)
456 - (const char*) cStringUsingEncoding: (NSStringEncoding)encoding;
457 - (BOOL) getCString: (char*)buffer
458 maxLength: (NSUInteger)maxLength
459 encoding: (NSStringEncoding)encoding;
460 - (id) initWithCString: (const char*)byteString
461 encoding: (NSStringEncoding)encoding;
462 - (NSUInteger) lengthOfBytesUsingEncoding: (NSStringEncoding)encoding;
463 - (NSUInteger) maximumLengthOfBytesUsingEncoding: (NSStringEncoding)encoding;
464 #endif
465
466 #endif
467 - (NSUInteger) cStringLength;
468 - (void) getCString: (char*)buffer;
469 - (void) getCString: (char*)buffer
470 maxLength: (NSUInteger)maxLength;
471 - (void) getCString: (char*)buffer
472 maxLength: (NSUInteger)maxLength
473 range: (NSRange)aRange
474 remainingRange: (NSRange*)leftoverRange;
475
476 // Getting Numeric Values
477 - (float) floatValue;
478 - (int) intValue;
479
480 // Working With Encodings
481 - (BOOL) canBeConvertedToEncoding: (NSStringEncoding)encoding;
482 - (NSData*) dataUsingEncoding: (NSStringEncoding)encoding;
483 - (NSData*) dataUsingEncoding: (NSStringEncoding)encoding
484 allowLossyConversion: (BOOL)flag;
485 + (NSStringEncoding) defaultCStringEncoding;
486 - (NSString*) description;
487 - (NSStringEncoding) fastestEncoding;
488 - (NSStringEncoding) smallestEncoding;
489
490 /**
491 * Attempts to complete this string as a path in the filesystem by finding
492 * a unique completion if one exists and returning it by reference in
493 * outputName (which must be a non-nil pointer), or if it finds a set of
494 * completions they are returned by reference in outputArray, if it is non-nil.
495 * filterTypes can be an array of strings specifying extensions to consider;
496 * files without these extensions will be ignored and will not constitute
497 * completions. Returns 0 if no match found, else a positive number that is
498 * only accurate if outputArray was non-nil.
499 */
500 - (NSUInteger) completePathIntoString: (NSString**)outputName
501 caseSensitive: (BOOL)flag
502 matchesIntoArray: (NSArray**)outputArray
503 filterTypes: (NSArray*)filterTypes;
504
505 /**
506 * Converts the receiver to a C string path expressed in the character
507 * encoding appropriate for the local host file system. This string will be
508 * automatically freed soon after it is returned, so copy it if you need it
509 * for long.<br />
510 * NB. On mingw32 systems the filesystem representation of a path is a 16-bit
511 * unicode character string, so you should only pass the value returned by
512 * this method to functions expecting wide characters.<br />
513 * This method uses [NSFileManager-fileSystemRepresentationWithPath:] to
514 * perform the conversion.
515 */
516 - (const GSNativeChar*) fileSystemRepresentation;
517
518 /**
519 * Converts the receiver to a C string path using the character encoding
520 * appropriate to the local file system. This string will be stored
521 * into buffer if it is shorter (number of characters) than size,
522 * otherwise NO is returned.<br />
523 * NB. On mingw32 systems the filesystem representation of a path is a 16-bit
524 * unicode character string, so the buffer you pass to this method must be
525 * twice as many bytes as the size (number of characters) you expect to
526 * receive.<br />
527 * This method uses [NSFileManager-fileSystemRepresentationWithPath:] to
528 * perform the conversion.
529 */
530 - (BOOL) getFileSystemRepresentation: (GSNativeChar*)buffer
531 maxLength: (NSUInteger)size;
532
533 /**
534 * Returns a string containing the last path component of the receiver.<br />
535 * The path component is the last non-empty substring delimited by the ends
536 * of the string, or by path separator characters.<br />
537 * If the receiver only contains a root part, this method returns it.<br />
538 * If there are no non-empty substrings, this returns an empty string.<br />
539 * NB. In a windows UNC path, the host and share specification is treated as
540 * a single path component, even though it contains separators.
541 * So a string of the form '//host/share' may be returned.<br />
542 * Other special cases are apply when the string is the root.
543 * <example>
544 * @"foo/bar" produces @"bar"
545 * @"foo/bar/" produces @"bar"
546 * @"/foo/bar" produces @"bar"
547 * @"/foo" produces @"foo"
548 * @"/" produces @"/" (root is a special case)
549 * @"" produces @""
550 * @"C:/" produces @"C:/" (root is a special case)
551 * @"C:" produces @"C:"
552 * @"//host/share/" produces @"//host/share/" (root is a special case)
553 * @"//host/share" produces @"//host/share"
554 * </example>
555 */
556 - (NSString*) lastPathComponent;
557
558 /**
559 * Returns a new string containing the path extension of the receiver.<br />
560 * The path extension is a suffix on the last path component which starts
561 * with the extension separator (a '.') (for example .tiff is the
562 * pathExtension for /foo/bar.tiff).<br />
563 * Returns an empty string if no such extension exists.
564 * <example>
565 * @"a.b" produces @"b"
566 * @"a.b/" produces @"b"
567 * @"/path/a.ext" produces @"ext"
568 * @"/path/a." produces @""
569 * @"/path/.a" produces @"" (.a is not an extension to a file)
570 * @".a" produces @"" (.a is not an extension to a file)
571 * </example>
572 */
573 - (NSString*) pathExtension;
574
575 /**
576 * Returns a string where a prefix of the current user's home directory is
577 * abbreviated by '~', or returns the receiver (or an immutable copy) if
578 * it was not found to have the home directory as a prefix.
579 */
580 - (NSString*) stringByAbbreviatingWithTildeInPath;
581
582 /**
583 * Returns a new string with the path component given in aString
584 * appended to the receiver.<br />
585 * This removes trailing path separators from the receiver and the root
586 * part from aString and replaces them with a single slash as a path
587 * separator.<br />
588 * Also condenses any multiple separator sequences in the result into
589 * single path separators.
590 * <example>
591 * @"" with @"file" produces @"file"
592 * @"path" with @"file" produces @"path/file"
593 * @"/" with @"file" produces @"/file"
594 * @"/" with @"file" produces @"/file"
595 * @"/" with @"/file" produces @"/file"
596 * @"path with @"C:/file" produces @"path/file"
597 * </example>
598 * NB. Do not use this method to modify strings other than filesystem
599 * paths as the behavior in such cases is undefined ... for instance
600 * the string may have repeated slashes or slash-dot-slash sequences
601 * removed.
602 */
603 - (NSString*) stringByAppendingPathComponent: (NSString*)aString;
604
605 /**
606 * Returns a new string with the path extension given in aString
607 * appended to the receiver after an extensionSeparator ('.').<br />
608 * If the receiver has trailing path separator characters, they are
609 * stripped before the extension separator is added.<br />
610 * If the receiver contains no components after the root, the extension
611 * cannot be appended (an extension can only be appended to a file name),
612 * so a copy of the unmodified receiver is returned.<br />
613 * An empty string may be used as an extension ... in which case the extension
614 * separator is appended.<br />
615 * This behavior mirrors that of the -stringByDeletingPathExtension method.
616 * <example>
617 * @"Mail" with @"app" produces @"Mail.app"
618 * @"Mail.app" with @"old" produces @"Mail.app.old"
619 * @"file" with @"" produces @"file."
620 * @"/" with @"app" produces @"/" (no file name to append to)
621 * @"" with @"app" produces @"" (no file name to append to)
622 * </example>
623 * NB. Do not use this method to modify strings other than filesystem
624 * paths as the behavior in such cases is undefined ... for instance
625 * the string may have repeated slashes or slash-dot-slash sequences
626 * removed.
627 */
628 - (NSString*) stringByAppendingPathExtension: (NSString*)aString;
629
630 /**
631 * Returns a new string with the last path component (including any final
632 * path separators) removed from the receiver.<br />
633 * A string without a path component other than the root is returned
634 * without alteration.<br />
635 * See -lastPathComponent for a definition of a path component.
636 * <example>
637 * @"hello/there" produces @"hello" (a relative path)
638 * @"hello" produces @"" (a relative path)
639 * @"/hello" produces @"/" (an absolute unix path)
640 * @"/" produces @"/" (an absolute unix path)
641 * @"C:file" produces @"C:" (a relative windows path)
642 * @"C:" produces @"C:" (a relative windows path)
643 * @"C:/file" produces @"C:/" (an absolute windows path)
644 * @"C:/" produces @"C:/" (an absolute windows path)
645 * @"//host/share/file" produces @"//host/share/" (a UNC path)
646 * @"//host/share/" produces @"//host/share/" (a UNC path)
647 * @"//path/file" produces @"//path" (an absolute Unix path)
648 * </example>
649 * NB. Do not use this method to modify strings other than filesystem
650 * paths as the behavior in such cases is undefined ... for instance
651 * the string may have repeated slashes or slash-dot-slash sequences
652 * removed.
653 */
654 - (NSString*) stringByDeletingLastPathComponent;
655
656 /**
657 * Returns a new string with the path extension removed from the receiver.<br />
658 * Strips any trailing path separators before checking for the extension
659 * separator.<br />
660 * NB. This method does not consider a string which contains nothing
661 * between the root part and the extension separator ('.') to be a path
662 * extension. This mirrors the behavior of the -stringByAppendingPathExtension:
663 * method.
664 * <example>
665 * @"file.ext" produces @"file"
666 * @"/file.ext" produces @"/file"
667 * @"/file.ext/" produces @"/file" (trailing path separators are ignored)
668 * @"/file..ext" produces @"/file."
669 * @"/file." produces @"/file"
670 * @"/.ext" produces @"/.ext" (there is no file to strip from)
671 * @".ext" produces @".ext" (there is no file to strip from)
672 * </example>
673 * NB. Do not use this method to modify strings other than filesystem
674 * paths as the behavior in such cases is undefined ... for instance
675 * the string may have repeated slashes or slash-dot-slash sequences
676 * removed.
677 */
678 - (NSString*) stringByDeletingPathExtension;
679
680 /**
681 * Returns a string created by expanding the initial tilde ('~') and any
682 * following username to be the home directory of the current user or the
683 * named user.<br />
684 * Returns the receiver or an immutable copy if it was not possible to
685 * expand it.
686 */
687 - (NSString*) stringByExpandingTildeInPath;
688
689 /**
690 * First calls -stringByExpandingTildeInPath if necessary.<br />
691 * Replaces path string by one in which path components representing symbolic
692 * links have been replaced by their referents.<br />
693 * Removes a leading '/private' if the result is valid.<br />
694 * If links cannot be resolved, returns an unmodified copy of the receiver.
695 */
696 - (NSString*) stringByResolvingSymlinksInPath;
697
698 /**
699 * Returns a standardised form of the receiver, with unnecessary parts
700 * removed, tilde characters expanded, and symbolic links resolved
701 * where possible.<br />
702 * NB. Refers to the local filesystem to resolve symbolic links in
703 * absolute paths, and to expand tildes ... so this can't be used for
704 * general path manipulation.<br />
705 * If the string is an invalid path, the unmodified receiver is returned.<br />
706 * <p>
707 * Uses -stringByExpandingTildeInPath to expand tilde expressions.<br />
708 * Simplifies '//' and '/./' sequences and removes trailing '/' or '.'.<br />
709 * </p>
710 * <p>
711 * For absolute paths, uses -stringByResolvingSymlinksInPath to resolve
712 * any links, then gets rid of '/../' sequences and removes any '/private'
713 * prefix.
714 * </p>
715 */
716 - (NSString*) stringByStandardizingPath;
717
718
719 // for methods working with decomposed strings
720 - (int) _baseLength;
721
722 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
723 /**
724 * Concatenates the path components in the array and returns the result.<br />
725 * This method does not remove empty path components, but does recognize an
726 * empty initial component as a special case meaning that the string
727 * returned will begin with a slash.
728 */
729 + (NSString*) pathWithComponents: (NSArray*)components;
730
731 /**
732 * Returns YES if the receiver represents an absolute path ...<br />
733 * Returns NO otherwise.<br />
734 * An absolute path in unix mode is one which begins
735 * with a slash or tilde.<br />
736 * In windows mode a drive specification (eg C:) followed by a slash or
737 * backslash, is an absolute path, as is any path beginning with a tilde.<br />
738 * In any mode a UNC path (//host/share...) is always absolute.<br />
739 * In the default gnustep path handling mode,
740 * the rules are the same as for windows,
741 * except that a path whose root is a slash denotes an absolute path
742 * when running on unix and a relative path when running under windows.
743 */
744 - (BOOL) isAbsolutePath;
745
746 /**
747 * Returns the path components of the receiver separated into an array.<br />
748 * If the receiver begins with a root sequence such as the path separator
749 * character (or a drive specification in windows) then that is used as the
750 * first element in the array.<br />
751 * Empty components are removed.<br />
752 * If a trailing path separator (which was not part of the root) was present,
753 * it is added as the last element in the array.
754 */
755 - (NSArray*) pathComponents;
756
757 /**
758 * Returns an array of strings made by appending the values in paths
759 * to the receiver.
760 */
761 - (NSArray*) stringsByAppendingPaths: (NSArray*)paths;
762
763 + (NSString*) localizedStringWithFormat: (NSString*)format, ...
764 NS_FORMAT_FUNCTION(1,2);
765
766 + (id) stringWithString: (NSString*)aString;
767 + (id) stringWithContentsOfURL: (NSURL*)url;
768 + (id) stringWithUTF8String: (const char*)bytes;
769 - (id) initWithFormat: (NSString*)format
770 locale: (NSDictionary*)locale, ... NS_FORMAT_FUNCTION(1,3);
771 - (id) initWithFormat: (NSString*)format
772 locale: (NSDictionary*)locale
773 arguments: (va_list)argList NS_FORMAT_FUNCTION(1,0);
774 - (id) initWithUTF8String: (const char *)bytes;
775 - (id) initWithContentsOfURL: (NSURL*)url;
776 - (NSString*) substringWithRange: (NSRange)aRange;
777 - (NSComparisonResult) caseInsensitiveCompare: (NSString*)aString;
778 - (NSComparisonResult) compare: (NSString*)string
779 options: (NSUInteger)mask
780 range: (NSRange)compareRange
781 locale: (id)locale;
782 - (NSComparisonResult) localizedCompare: (NSString *)string;
783 - (NSComparisonResult) localizedCaseInsensitiveCompare: (NSString *)string;
784 - (BOOL) writeToFile: (NSString*)filename
785 atomically: (BOOL)useAuxiliaryFile;
786 - (BOOL) writeToURL: (NSURL*)url atomically: (BOOL)atomically;
787 - (double) doubleValue;
788 + (NSStringEncoding*) availableStringEncodings;
789 + (NSString*) localizedNameOfStringEncoding: (NSStringEncoding)encoding;
790 - (void) getLineStart: (NSUInteger *)startIndex
791 end: (NSUInteger *)lineEndIndex
792 contentsEnd: (NSUInteger *)contentsEndIndex
793 forRange: (NSRange)aRange;
794 - (NSRange) lineRangeForRange: (NSRange)aRange;
795 - (const char*) lossyCString;
796 - (NSString*) stringByAddingPercentEscapesUsingEncoding: (NSStringEncoding)e;
797 - (NSString*) stringByPaddingToLength: (NSUInteger)newLength
798 withString: (NSString*)padString
799 startingAtIndex: (NSUInteger)padIndex;
800 - (NSString*) stringByReplacingPercentEscapesUsingEncoding: (NSStringEncoding)e;
801 - (NSString*) stringByTrimmingCharactersInSet: (NSCharacterSet*)aSet;
802 - (const char *)UTF8String;
803 #endif
804
805 #if OS_API_VERSION(MAC_OS_X_VERSION_10_9,GS_API_LATEST)
806 - (NSString *) stringByAddingPercentEncodingWithAllowedCharacters: (NSCharacterSet *)aSet;
807 - (NSString *) stringByRemovingPercentEncoding;
808 #endif
809
810 #if OS_API_VERSION(MAC_OS_X_VERSION_10_3,GS_API_LATEST)
811 /** Not implemented */
812 - (void) getParagraphStart: (NSUInteger *)startIndex
813 end: (NSUInteger *)parEndIndex
814 contentsEnd: (NSUInteger *)contentsEndIndex
815 forRange: (NSRange)range;
816 /** Not implemented */
817 - (NSRange) paragraphRangeForRange: (NSRange)range;
818 #endif
819
820 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5,GS_API_LATEST)
821 /**
822 * Returns YES when scanning the receiver's text from left to right
823 * finds an initial digit in the range 1-9 or a letter in the set
824 * ('Y', 'y', 'T', 't').<br />
825 * Any trailing characters are ignored.<br />
826 * Any leading whitespace or zeros or signs are also ignored.<br />
827 * Returns NO if the above conditions are not met.
828 */
829 - (BOOL) boolValue;
830 - (NSArray *) componentsSeparatedByCharactersInSet: (NSCharacterSet *)separator;
831 - (NSInteger) integerValue;
832 - (long long) longLongValue;
833 /** Not implemented */
834 - (NSRange) rangeOfComposedCharacterSequencesForRange: (NSRange)range;
835 /** Not implemented */
836 - (NSRange) rangeOfString: (NSString *)aString
837 options: (NSStringCompareOptions)mask
838 range: (NSRange)searchRange
839 locale: (NSLocale *)locale;
840
841 #endif
842
843 #if OS_API_VERSION(MAC_OS_X_VERSION_10_10,GS_API_LATEST)
844
845 /**
846 * Returns YES if the receiver contains string, otherwise, NO.
847 */
848 - (BOOL) containsString: (NSString *)string;
849
850 #endif
851
852 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE)
853 + (Class) constantStringClass;
854 #endif /* GS_API_NONE */
855
856 @end
857
858 @interface NSMutableString : NSString
859
860 // Creating Temporary Strings
861 + (id) string;
862 + (id) stringWithCharacters: (const unichar*)characters
863 length: (NSUInteger)length;
864 + (id) stringWithCString: (const char*)byteString
865 length: (NSUInteger)length;
866 + (id) stringWithCString: (const char*)byteString;
867 + (id) stringWithFormat: (NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
868 + (id) stringWithContentsOfFile: (NSString*)path;
869 + (NSMutableString*) stringWithCapacity: (NSUInteger)capacity;
870
871 // Initializing Newly Allocated Strings
872 - (id) initWithCapacity: (NSUInteger)capacity;
873
874 // Modify A String
875 - (void) appendFormat: (NSString*)format, ... NS_FORMAT_FUNCTION(1,2);
876 - (void) appendString: (NSString*)aString;
877 - (void) deleteCharactersInRange: (NSRange)range;
878 - (void) insertString: (NSString*)aString atIndex: (NSUInteger)loc;
879 - (void) replaceCharactersInRange: (NSRange)range
880 withString: (NSString*)aString;
881 - (NSUInteger) replaceOccurrencesOfString: (NSString*)replace
882 withString: (NSString*)by
883 options: (NSUInteger)opts
884 range: (NSRange)searchRange;
885 - (void) setString: (NSString*)aString;
886
887 @end
888
889 #ifdef __OBJC_GNUSTEP_RUNTIME_ABI__
890 # if __OBJC_GNUSTEP_RUNTIME_ABI__ >= 20
891 # define GNUSTEP_NEW_STRING_ABI
892 # endif
893 #endif
894
895 /**
896 * <p>The NXConstantString class is used to hold constant 8-bit character
897 * string objects produced by the compiler where it sees @"..." in the
898 * source. The compiler generates the instances of this class - which
899 * has three instance variables -</p>
900 * <list>
901 * <item>a pointer to the class (this is the sole ivar of NSObject)</item>
902 * <item>a pointer to the 8-bit data</item>
903 * <item>the length of the string</item>
904 * </list>
905 * <p>In older versions of the compiler, the isa variable is always set to
906 * the NXConstantString class. In newer versions a compiler option was
907 * added for GNUstep, to permit the isa variable to be set to another
908 * class, and GNUstep uses this to avoid conflicts with the default
909 * implementation of NXConstantString in the ObjC runtime library (the
910 * preprocessor is used to change all occurrences of NXConstantString
911 * in the source code to NSConstantString).</p>
912 * <p>Since GNUstep will generally use the GNUstep extension to the
913 * compiler, you should never refer to the constant string class by
914 * name, but should use the [NSString+constantStringClass] method to
915 * get the actual class being used for constant strings.</p>
916 * What follows is a dummy declaration of the class to keep the compiler
917 * happy.
918 */
919 @interface NXConstantString : NSString
920 {
921 @public
922 #ifdef GNUSTEP_NEW_STRING_ABI
923 /**
924 * Flags. The low 16 bits are reserved for the compiler, the top 16 for use
925 * by the Foundation Framework. Currently only the low 2 bits are used, to
926 * indicate the encoding of the string, with the following values:
927 *
928 * 0. ASCII (UTF-8 using only 7-bit characters)
929 * 1. UTF-8
930 * 2. UTF-16
931 * 3. UTF-32
932 *
933 */
934 uint32_t flags;
935 /**
936 * The number of characters (UTF-16 code units) in the string.
937 */
938 uint32_t nxcslen;
939 /**
940 * The number of bytes in the string. For fixed-length encodings, this is a
941 * fixed multiple of nxcslen, but for UTF-8 it can be different.
942 */
943 uint32_t size;
944 /**
945 * Hash value.
946 */
947 uint32_t hash;
948 /**
949 * Pointer to the byte data of the string. Note that `char*` is the correct
950 * type only if the low two bits of the flags indicate that this is an ASCII
951 * or UTF-8 string, otherwise it is a pointer to 16- or 32-bit characters in
952 * native byte order.
953 */
954 const char * const nxcsptr;
955 #else
956 const char * const nxcsptr;
957 const unsigned int nxcslen;
958 #endif
959 }
960 @end
961
962 #ifdef NeXT_RUNTIME
963 /** For internal use with NeXT runtime;
964 needed, until Apple Radar 2870817 is fixed. */
965 extern struct objc_class _NSConstantStringClassReference;
966 #endif
967
968 #if defined(__cplusplus)
969 }
970 #endif
971
972 #if !NO_GNUSTEP && !defined(GNUSTEP_BASE_INTERNAL)
973 #import "../GNUstepBase/NSString+GNUstepBase.h"
974 #import "../GNUstepBase/NSMutableString+GNUstepBase.h"
975 #endif
976
977 #endif /* __NSString_h_GNUSTEP_BASE_INCLUDE */