ADC Home > Reference Library > Reference > Cocoa > Data Management > NSString Class Reference >

< Previous PageNext Page > Hide TOC

Deprecated NSString Methods

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

Deprecated in Mac OS X v10.4

stringWithContentsOfFile:

Returns a string created by reading data from the file named by a given path. (Deprecated in Mac 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
See Also
Related Sample Code
Declared In
NSString.h

stringWithContentsOfURL:

Returns a string created by reading data from the file named by a given URL. (Deprecated in Mac 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
See Also
Declared In
NSString.h

stringWithCString:

Creates a new string using a given C-string. (Deprecated in Mac 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
See Also
Related Sample Code
Declared In
NSString.h

stringWithCString:length:

Returns a string containing the characters in a given C-string. (Deprecated in Mac 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
See Also
Related Sample Code
Declared In
NSString.h

cString

Returns a representation of the receiver as a C string in the default C-string encoding. (Deprecated in Mac 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
See Also
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 Mac 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
See Also
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 Mac 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
See Also
Related Sample Code
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 Mac 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
See Also
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 Mac 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
See Also
Declared In
NSString.h

initWithContentsOfFile:

Initializes the receiver, a newly allocated NSString object, by reading data from the file named by path. (Deprecated in Mac 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
See Also
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 Mac 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
See Also
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 Mac 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
See Also
Related Sample Code
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 Mac OS X v10.4. Use initWithCString: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
See Also
Related Sample Code
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 Mac 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
See Also
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 Mac 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
See Also
Declared In
NSString.h

writeToFile:atomically:

Writes the contents of the receiver to the file specified by a given path. (Deprecated in Mac 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
See Also
Related Sample Code
Declared In
NSString.h

writeToURL:atomically:

Writes the contents of the receiver to the location specified by a given URL. (Deprecated in Mac 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
See Also
Declared In
NSString.h

< Previous PageNext Page > Hide TOC

© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-02-04)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.