< Previous PageNext Page > Hide TOC

Creating and Converting String Objects

NSString and its subclass NSMutableString provide several ways to create string objects, most based around the various character encodings it supports. Although string objects always present their own contents as Unicode characters, they can convert their contents to and from many other encodings, such as 7-bit ASCII, ISO Latin 1, EUC, and Shift-JIS. The availableStringEncodings class method returns the encodings supported. You can specify an encoding explicitly when converting a C string to or from a string object, or use the default C string encoding, which varies from platform to platform and is returned by the defaultCStringEncoding class method.

Contents:

Creating Strings
Combining and Extracting Strings
Getting C Strings
Conversion Summary

Creating Strings

The simplest way to create a string object in source code is to use the Objective-C @"..." construct:

NSString *temp = @"/tmp/scratch";

Note that, when creating a string constant in this fashion, you should avoid using anything but 7-bit ASCII characters. Such an object is created at compile time and exists throughout your program’s execution. The compiler makes such object constants unique on a per-module basis, and they’re never deallocated, though you can retain and release them as you do any other object. You can also send messages directly to a string constant as you do any other string:

BOOL same = [@"comparison" isEqualToString:myString];

NSString from C Strings and Data

To create an NSString object from a C string, you use methods such as initWithCString:encoding:. It is important to correctly specify the character encoding of the C string. Similar methods allow you to create string objects from characters in a variety of encodings. The method initWithData:encoding: allows you to convert string data stored in an NSData object into an NSString object.

char *utf8String = /* assume this exists */ ;

NSString *stringFromUTFString = [[NSString alloc] initWithUTF8String:utf8String];

char *macOSRomanEncodedString = /* assume this exists */ ;

NSString *stringFromMORString =

            [[NSString alloc] initWithCString:macOSRomanEncodedString

                              encoding:NSMacOSRomanStringEncoding];

NSData *shiftJISData =  /* assume this exists */ ;

NSString *stringFromShiftJISData =

            [[NSString alloc] initWithData:shiftJISData

                              encoding:NSShiftJISStringEncoding];

The following example converts an NSString object containing a UTF-8 character to ASCII data then back to an NSString object.

unichar ellipsis = 0x2026;

NSString *theString = [NSString stringWithFormat:@"To be continued%C", ellipsis];

NSData *asciiData = [theString dataUsingEncoding:NSASCIIStringEncoding allowLossyConversion:YES];

NSString *asciiString = [[NSString alloc] initWithData:asciiData encoding:NSASCIIStringEncoding];

NSLog(@"Original: %@ (length %d)", theString, [theString length]);

NSLog(@"Converted: %@ (length %d)", asciiString, [asciiString length]);

// output:

// Original: To be continued… (length 16)

// Converted: To be continued... (length 18)

Variable Strings

To create a variable string, you typically use stringWithFormat:: or initWithFormat: (or for localized strings, localizedStringWithFormat:). These methods and their siblings use a format string as a template into which the values you provide (string and other objects, numerics values, and so on) are inserted. They and the supported format specifiers are described in “Formatting String Objects.”

You can build a string from existing string objects using the methods stringByAppendingString: and stringByAppendingFormat: to create a new string by adding one string after another, in the second case using a format string.

NSString *hString = @"Hello";

NSString *hwString = [hString stringByAppendingString:@", world!"];

Strings to Present to the User

When creating strings to present to the user, you should consider the importance of localizing your application. In general, you should avoid creating user-visible strings directly in code. Instead you should use strings in your code as a key to a localization dictionary that will supply the user-visible string in the user's preferred language. Typically this involves using NSLocalizedString and similar macros, as illustrated in the following example.

NSString *greeting = NSLocalizedStringFromTable

    (@"Hello", @"greeting to present in first launch panel", @"greetings");

For more about internationalizing your application, see Internationalization Programming Topics. Strings Files describes how to work with and reorder variable arguments in localized strings.

Combining and Extracting Strings

You can combine and extract strings in various ways. The simplest way to combine two strings is to append one to the other. The stringByAppendingString: method returns a string object formed from the receiver and the given argument.

NSString *beginning = @"beginning";

NSString *alphaAndOmega = [beginning stringByAppendingString:@" and end"];

// alphaAndOmega is @"beginning and end"

You can also combine several strings according to a template with the initWithFormat:, stringWithFormat:, and stringByAppendingFormat: methods; these are described in more detail in “Formatting String Objects.”

You can extract substrings from the beginning or end of a string to a particular index, or from a specific range, with the substringToIndex:, substringFromIndex:, and substringWithRange: methods. You can also split a string into substrings (based on a separator string) with the componentsSeparatedByString: method. These methods are illustrated in the following examples—notice that the index of the index-based methods starts at 0:

NSString *source = @"0123456789";

NSString *firstFour = [source substringToIndex:4];

// firstFour is @"0123"

NSString *allButFirstThree = [source substringFromIndex:3];

// allButFirstThree is @"3456789"

NSRange twoToSixRange = NSMakeRange(2, 4);

NSString *twoToSix = [source substringWithRange:twoToSixRange];

// twoToSix is @"2345"

NSArray *split = [source componentsSeparatedByString:@"45"];

// split contains { @"0123", @"6789" }

If you need to extract strings using pattern-matching rather than an index, you should use a scanner—see “Scanners.”

Getting C Strings

To get a C string from a string object, you are recommended to use UTF8String. This returns a const char * using UTF8 string encoding.

const char *cString = [@"Hello, world" UTF8String];

The C string you receive is owned by a temporary object, and will become invalid when automatic deallocation takes place. If you want to get a permanent C string, you must create a buffer and copy the contents of the const char * returned by the method.

Similar methods allow you to create string objects from characters in the Unicode encoding or an arbitrary encoding, and to extract data in these encodings. initWithData:encoding: and dataUsingEncoding: perform these conversions from and to NSData objects.

Conversion Summary

This table summarizes the most common means of creating and converting string objects:

< Previous PageNext Page > Hide TOC