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 */ 978