Table of Contents

Previous Section

Creating Strings

+ string

Returns an empty string. Usually used to create NSMutableStrings. NSStrings created with this method are permanently empty.

		/* Most common use */
		id mutableString = [NSMutableString string];

		/* May not be what you want */
		id string = [NSString string];

+ stringWithFormat:

Returns a string created by substituting arguments into a specified format string just as printf() does in the C programming language. In WebScript, only the at sign (@) conversion character is supported, and it expects a corresponding id argument.

		// These are fine
		id party = [NSString stringWithFormat:@"Party date: %@", partyDate];
		id mailto = [NSString stringWithFormat:@"mailto: %@", 
			[person email]];
		id footer = [NSString stringWithFormat:
			@"Interaction %@ in session %@.",
			numberOfInteractions, sessionNumber];

		// NO! This won't work. Only %@ is supported.
		// (%d prints address, not value).
		id string = [NSString stringWithFormat:@"%d of %d %s", x, y, 
			cString];

+ stringWithString:

Returns a string containing the same contents as a specified string. This method is usually used to create an NSMutableString from an NSString. For example, the following statement creates an NSMutableString from a constant NSString object:

		id mutableString = [NSMutableString stringWithString:@"Change me."];

+ stringWithContentsOfFile:

Returns a string created by reading characters from a specified file. For example, the following statement creates an NSString containing the contents of the file specified in path:

		id fileContents = [NSString stringWithContentsOfFile:path];

See also writeToFile:atomically: .

- stringByAppendingFormat:

Returns a string made by appending to the receiver a string constructed from a specified format string and the arguments following it in the manner of stringWithFormat:. For example, assume the variable guestName contains the string "Rena". Then the following code excerpt produces the string message with contents "Hi, Rena!":

		id string = @"Hi";
		id message = [string stringByAppendingFormat:@", %@!", 
			guestName];

- stringByAppendingString:

Returns a string made by appending a specified string to the receiver. This code excerpt, for example, produces the string "Error: premature end of file.":

		id errorTag = @"Error: ";
		id errorString = @"premature end of file.";
		id errorMessage = [errorTag 
			stringByAppendingString:errorString];

- componentsSeparatedByString:

Returns an NSArray containing substrings from the receiver that have been divided by a specified separator string. For example, the following statements produce an NSArray containing the strings "wrenches", "hammers", and "saws":

		id toolString = @"wrenches, hammers, saws";
		id toolArray = [toolString componentsSeparatedByString:@", "];

See also componentsJoinedByString:.

- substringToIndex:

Returns a string object containing the characters of the receiver up to, but not including, the one at the specified index.

- substringFromIndex:

Returns a string containing the characters of the receiver from the character at the specified index to the end.

- compare:

Returns -1 if the receiver precedes a specified string in lexical ordering, 0 if it is equal, and 1 if it follows. For example, the following statements result in an NSString that has the contents "`hello' precedes `Hello' lexicographically.":

		if ([@"hello" compare:@"Hello"] == -1) {
			result = [NSString stringWithFormat:
				@"'%@' precedes '%@' lexicographically.",
				@"hello", @"Hello"];
		}

- caseInsensitiveCompare:

Same as compare:, but case distinctions among characters are ignored.

- isEqual:

Returns YES if a specified object is equivalent to the receiver; NO otherwise. An object is equivalent to a string if the object is an NSString or an NSMutableString and compare: returns 0. For example, the following statements:

		if ([string isEqual:newString]) {
			result = @"Found a match";
		}

assign the contents "Found a match" to result if string and newString are lexicographically equal.

- doubleValue

Returns the floating-point value of the receiver's text as a double, skipping white space at the beginning of the string.

- floatValue

Returns the floating-point value of the receiver's text as a float, skipping white space at the beginning of the string.

- intValue

Returns the integer value of the string's text, assuming a decimal representation and skipping white space at the beginning of the string.

- appendFormat:

Appends a constructed string to the receiver. Creates the new string by using the stringWithFormat: method with the arguments listed. For example, in the following code excerpt, if you assume the variable guestName contains the string "Rena", then message has the resulting contents "Hi, Rena!":

		id message = [NSMutableString stringWithString:@"Hi"];
		[message appendFormat:@", %@!", guestName];

- appendString:

Adds the characters of a specified string to the end of the receiver. For example, the following statements create an NSMutableString and append another string to its initial value:

		id mutableString = [NSMutableString stringWithFormat:@"Hello "];
		[mutableString appendString:@"world!"];

mutableString has the resulting contents "Hello world!".

- setString:

Replaces the characters of the receiver with those in a specified string. For example, the following statement replaces the contents of an NSMutableString with the empty string:

		[mutableString setString:@""];

- writeToFile:atomically:

Writes the string to a specified file, returning YES on success and NO on failure. If YES is specified for atomically:, this method writes the string to an auxiliary file and then renames the auxiliary file to the specified path. In this way, it ensures that the contents of the specified path do not become corrupted if the system crashes during writing. The resulting file is suitable for use with stringWithContentsOfFile:. For example, the following code excerpt reads the contents of an error log stored in a file, appends a new error to the log, and saves the updated log to the same file:

		id errorLog = [NSString stringWithContentsOfFile:errorPath];
		id newErrorLog = [errorLog stringByAppendingFormat:@"%@: %@.\n",
			timeStamp, @"premature end of file."];
		[newErrorLog writeToFile:errorPath atomically:YES];

Table of Contents Next Section