Deprecated NSString Methods

A method identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.4

stringWithContentsOfFile:

Returns a string created by reading data from the file named by a given path. (Deprecated in OS X v10.4. Use stringWithContentsOfFile:encoding:error: or stringWithContentsOfFile:usedEncoding:error: instead.)

+ (id)stringWithContentsOfFile:(NSString *)path
Discussion

If the contents begin with a Unicode byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters. If the contents begin with a UTF-8 byte-order mark (EFBBBF), interprets the contents as UTF-8. Otherwise, interprets the contents as data in the default C string encoding. Since the default C string encoding will vary with the user’s configuration, do not depend on this method unless you are using Unicode or UTF-8 or you can verify the default C string encoding. Returns nil if the file can’t be opened.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

stringWithContentsOfURL:

Returns a string created by reading data from the file named by a given URL. (Deprecated in OS X v10.4. Use stringWithContentsOfURL:encoding:error: or stringWithContentsOfURL:usedEncoding:error: instead.)

+ (id)stringWithContentsOfURL:(NSURL *)aURL
Discussion

If the contents begin with a byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters. If the contents begin with a UTF-8 byte-order mark (EFBBBF), interprets the contents as UTF-8. Otherwise interprets the contents as data in the default C string encoding. Since the default C string encoding will vary with the user’s configuration, do not depend on this method unless you are using Unicode or UTF-8 or you can verify the default C string encoding. Returns nil if the location can’t be opened.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

stringWithCString:

Creates a new string using a given C-string. (Deprecated in OS X v10.4. Use stringWithCString:encoding: instead.)

+ (id)stringWithCString:(const char *)cString
Discussion

cString should contain data in the default C string encoding. If the argument passed to stringWithCString: is not a zero-terminated C-string, the results are undefined.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

stringWithCString:length:

Returns a string containing the characters in a given C-string. (Deprecated in OS X v10.4. Use stringWithCString:encoding: instead.)

+ (id)stringWithCString:(const char *)cString length:(NSUInteger)length
Discussion

cString must not be NULL. cString should contain characters in the default C-string encoding. This method converts length * sizeof(char) bytes from cString and doesn’t stop short at a NULL character.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

cString

Returns a representation of the receiver as a C string in the default C-string encoding. (Deprecated in OS X v10.4. Use cStringUsingEncoding: or UTF8String instead.)

- (const char *)cString
Discussion

The returned C string will be automatically freed just as a returned object would be released; your code should copy the C string or use getCString: if it needs to store the C string outside of the autorelease context in which the C string is created.

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Related Sample Code
Declared In
NSString.h

cStringLength

Returns the length in char-sized units of the receiver’s C-string representation in the default C-string encoding. (Deprecated in OS X v10.4. Use lengthOfBytesUsingEncoding: or maximumLengthOfBytesUsingEncoding: instead.)

- (NSUInteger)cStringLength
Discussion

Raises if the receiver can’t be represented in the default C-string encoding without loss of information. You can also use canBeConvertedToEncoding: to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString to get a C-string representation with some loss of information, then check its length explicitly using the ANSI function strlen().

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

getCString:

Invokes getCString:maxLength:range:remainingRange: with NSMaximumStringLength as the maximum length, the receiver’s entire extent as the range, and NULL for the remaining range. (Deprecated in OS X v10.4. Use cStringUsingEncoding: or dataUsingEncoding:allowLossyConversion: instead.)

- (void)getCString:(char *)buffer
Discussion

buffer must be large enough to contain the resulting C-string plus a terminating NULL character (which this method adds—[string cStringLength]).

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

getCString:maxLength:

Invokes getCString:maxLength:range:remainingRange: with maxLength as the maximum length in char-sized units, the receiver’s entire extent as the range, and NULL for the remaining range. (Deprecated in OS X v10.4. Use getCString:maxLength:encoding: instead.)

- (void)getCString:(char *)buffer maxLength:(NSUInteger)maxLength
Discussion

buffer must be large enough to contain maxLength chars plus a terminating zero char (which this method adds).

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

getCString:maxLength:range:remainingRange:

Converts the receiver’s content to the default C-string encoding and stores them in a given buffer. (Deprecated in OS X v10.4. Use getCString:maxLength:encoding: instead.)

- (void)getCString:(char *)buffer maxLength:(NSUInteger)maxLength range:(NSRange)aRange remainingRange:(NSRangePointer)leftoverRange
Discussion

buffer must be large enough to contain maxLength bytes plus a terminating zero character (which this method adds). Copies and converts as many characters as possible from aRange and stores the range of those not converted in the range given by leftoverRange (if it’s non-nil). Raises an NSRangeException if any part of aRange lies beyond the end of the string.

Raises an NSCharacterConversionException if the receiver can’t be represented in the default C-string encoding without loss of information. Use canBeConvertedToEncoding: if necessary to check whether a string can be losslessly converted to the default C-string encoding. If it can’t, use lossyCString or dataUsingEncoding:allowLossyConversion: to get a C-string representation with some loss of information.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

initWithContentsOfFile:

Initializes the receiver, a newly allocated NSString object, by reading data from the file named by path. (Deprecated in OS X v10.4. Use initWithContentsOfFile:encoding:error: or initWithContentsOfFile:usedEncoding:error: instead.)

- (id)initWithContentsOfFile:(NSString *)path
Discussion

Initializes the receiver, a newly allocated NSString object, by reading data from the file named by path. If the contents begin with a byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters; otherwise interprets the contents as data in the default C string encoding. Returns an initialized object, which might be different from the original receiver, or nil if the file can’t be opened.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

initWithContentsOfURL:

Initializes the receiver, a newly allocated NSString object, by reading data from the location named by a given URL. (Deprecated in OS X v10.4. Use initWithContentsOfURL:encoding:error: or initWithContentsOfURL:usedEncoding:error: instead.)

- (id)initWithContentsOfURL:(NSURL *)aURL
Discussion

Initializes the receiver, a newly allocated NSString object, by reading data from the location named by aURL. If the contents begin with a byte-order mark (U+FEFF or U+FFFE), interprets the contents as Unicode characters; otherwise interprets the contents as data in the default C string encoding. Returns an initialized object, which might be different from the original receiver, or nil if the location can’t be opened.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

initWithCString:

Initializes the receiver, a newly allocated NSString object, by converting the data in a given C-string from the default C-string encoding into the Unicode character encoding. (Deprecated in OS X v10.4. Use initWithCString:encoding: instead.)

- (id)initWithCString:(const char *)cString
Discussion

cString must be a zero-terminated C string in the default C string encoding, and may not be NULL. Returns an initialized object, which might be different from the original receiver.

To create an immutable string from an immutable C string buffer, do not attempt to use this method. Instead, use initWithCStringNoCopy:length:freeWhenDone:.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

initWithCString:length:

Initializes the receiver, a newly allocated NSString object, by converting the data in a given C-string from the default C-string encoding into the Unicode character encoding. (Deprecated in OS X v10.4. Use initWithBytes:length:encoding: instead.)

- (id)initWithCString:(const char *)cString length:(NSUInteger)length
Discussion

This method converts length * sizeof(char) bytes from cString and doesn’t stop short at a zero character. cString must contain bytes in the default C-string encoding and may not be NULL. Returns an initialized object, which might be different from the original receiver.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

initWithCStringNoCopy:length:freeWhenDone:

Initializes the receiver, a newly allocated NSString object, by converting the data in a given C-string from the default C-string encoding into the Unicode character encoding. (Deprecated in OS X v10.4. Use initWithBytesNoCopy:length:encoding:freeWhenDone: instead.)

- (id)initWithCStringNoCopy:(char *)cString length:(NSUInteger)length freeWhenDone:(BOOL)flag
Discussion

This method converts length * sizeof(char) bytes from cString and doesn’t stop short at a zero character. cString must contain data in the default C-string encoding and may not be NULL. The receiver becomes the owner of cString; if flag is YES it will free the memory when it no longer needs it, but if flag is NO it won’t. Returns an initialized object, which might be different from the original receiver.

You can use this method to create an immutable string from an immutable (const char *) C-string buffer. If you receive a warning message, you can disregard it; its purpose is simply to warn you that the C string passed as the method’s first argument may be modified. If you make certain the freeWhenDone argument to initWithStringNoCopy is NO, the C string passed as the method’s first argument cannot be modified, so you can safely use initWithStringNoCopy to create an immutable string from an immutable (const char *) C-string buffer.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

lossyCString

Returns a representation of the receiver as a C string in the default C-string encoding, possibly losing information in converting to that encoding. (Deprecated in OS X v10.4. Use cStringUsingEncoding: or dataUsingEncoding:allowLossyConversion: instead.)

- (const char *)lossyCString
Discussion

This method does not raise an exception if the conversion is lossy. The returned C string will be automatically freed just as a returned object would be released; your code should copy the C string or use getCString: if it needs to store the C string outside of the autorelease context in which the C string is created.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

writeToFile:atomically:

Writes the contents of the receiver to the file specified by a given path. (Deprecated in OS X v10.4. Use writeToFile:atomically:encoding:error: instead.)

- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)flag
Return Value

YES if the file is written successfully, otherwise NO.

Discussion

Writes the contents of the receiver to the file specified by path (overwriting any existing file at path). path is written in the default C-string encoding if possible (that is, if no information would be lost), in the Unicode encoding otherwise.

If flag is YES, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to path. If flag is NO, the receiver is written directly to path. The YES option guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.

If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

writeToURL:atomically:

Writes the contents of the receiver to the location specified by a given URL. (Deprecated in OS X v10.4. Use writeToURL:atomically:encoding:error: instead.)

- (BOOL)writeToURL:(NSURL *)aURL atomically:(BOOL)atomically
Return Value

YES if the location is written successfully, otherwise NO.

Discussion

If atomically is YES, the receiver is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If atomically is NO, the receiver is written directly to aURL. The YES option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing.

The atomically parameter is ignored if aURL is not of a type that can be accessed atomically.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.4.
Declared In
NSString.h

Deprecated in OS X v10.6

getCharacters:

Copies all characters from the receiver into a given buffer. (Deprecated in OS X v10.6. This method is unsafe because it could potentially cause buffer overruns. Use getCharacters:range: instead.)

- (void)getCharacters:(unichar *)buffer
Parameters
buffer

Upon return, contains the characters from the receiver. buffer must be large enough to contain all characters in the string ([string length]*sizeof(unichar)).

Discussion

Invokes getCharacters:range: with buffer and the entire extent of the receiver as the range.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
See Also
Declared In
NSString.h