NSString Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/Foundation.framework |
| Availability | Available in iOS 2.0 and later. |
| Declared in | NSLinguisticTagger.h NSPathUtilities.h NSString.h NSURL.h |
| Companion guides | |
Overview
The NSString class declares the programmatic interface for an object that manages immutable strings. An immutable string is a text string that is defined when it is created and subsequently cannot be changed. NSString is implemented to represent an array of Unicode characters, in other words, a text string.
The mutable subclass of NSString is NSMutableString.
The NSString class has two primitive methods—length and characterAtIndex:—that provide the basis for all other methods in its interface. The length method returns the total number of Unicode characters in the string. characterAtIndex: gives access to each character in the string by index, with index values starting at 0.
NSString declares methods for finding and comparing strings. It also declares methods for reading numeric values from strings, for combining strings in various ways, and for converting a string to different forms (such as encoding and case changes).
The Application Kit also uses NSParagraphStyle and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes. Additionally, methods to support string drawing are described in NSString Application Kit Additions Reference, found in the Application Kit.
NSString is “toll-free bridged” with its Core Foundation counterpart, CFStringRef. See “Toll-Free Bridging” for more information on toll-free bridging.
String Objects
NSString objects represent character strings in frameworks. Representing strings as objects allows you to use strings wherever you use other objects. It also provides the benefits of encapsulation, so that string objects can use whatever encoding and storage are needed for efficiency while simply appearing as arrays of characters. The cluster’s two public classes, NSString and NSMutableString, declare the programmatic interface for non-editable and editable strings, respectively.
The objects you create using NSString and NSMutableString are referred to as string objects (or, when no confusion will result, merely as strings). The term C string refers to the standard char * type. Because of the nature of class clusters, string objects aren’t actual instances of the NSString or NSMutableString classes but of one of their private subclasses. Although a string object’s class is private, its interface is public, as declared by these abstract superclasses, NSString and NSMutableString. The string classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert a string of one type to the other.
Understanding characters
A string object presents itself as an array of Unicode characters (Unicode is a registered trademark of Unicode, Inc.). You can determine how many characters a string object contains with the length method and can retrieve a specific character with the characterAtIndex: method. These two “primitive” methods provide basic access to a string object.
Most use of strings, however, is at a higher level, with the strings being treated as single entities: You compare strings against one another, search them for substrings, combine them into new strings, and so on. If you need to access string objects character by character, you must understand the Unicode character encoding, specifically issues related to composed character sequences. For details see The Unicode Standard, Version 4.0 (The Unicode Consortium, Boston: Addison-Wesley, 2003, ISBN 0-321-18578-1) and the Unicode Consortium web site: http://www.unicode.org/. See also “Characters and Grapheme Clusters” in String Programming Guide.
Interpreting UTF-16-encoded data
When creating an NSString object from a UTF-16-encoded string (or a byte stream interpreted as UTF-16), if the byte order is not otherwise specified, NSString assumes that the UTF-16 characters are big-endian, unless there is a BOM (byte-order mark), in which case the BOM dictates the byte order. When creating an NSString object from an array of Unicode characters, the returned string is always native-endian, since the array always contains Unicode characters in native byte order.
Distributed objects
Over distributed-object connections, mutable string objects are passed by-reference and immutable string objects are passed by-copy.
Subclassing Notes
It is possible to subclass NSString (and NSMutableString), but doing so requires providing storage facilities for the string (which is not inherited by subclasses) and implementing two primitive methods. The abstract NSString and NSMutableString classes are the public interface of a class cluster consisting mostly of private, concrete classes that create and return a string object appropriate for a given situation. Making your own concrete subclass of this cluster imposes certain requirements (discussed in “Methods to Override”).
Make sure your reasons for subclassing NSString are valid. Instances of your subclass should represent a string and not something else. Thus the only attributes the subclass should have are the length of the character buffer it’s managing and access to individual characters in the buffer. Valid reasons for making a subclass of NSString include providing a different backing store (perhaps for better performance) or implementing some aspect of object behavior differently, such as memory management. If your purpose is to add non-essential attributes or metadata to your subclass of NSString, a better alternative would be object composition (see “Alternatives to Subclassing”). Cocoa already provides an example of this with the NSAttributedString class.
Methods to Override
Any subclass of NSString must override the primitive instance methods length and characterAtIndex:. These methods must operate on the backing store that you provide for the characters of the string. For this backing store you can use a static array, a dynamically allocated buffer, a standard NSString object, or some other data type or mechanism. You may also choose to override, partially or fully, any other NSString method for which you want to provide an alternative implementation. For example, for better performance it is recommended that you override getCharacters:range: and give it a faster implementation.
You might want to implement an initializer for your subclass that is suited to the backing store that the subclass is managing. The NSString class does not have a designated initializer, so your initializer need only invoke the init method of super. The NSString class adopts the NSCopying, NSMutableCopying, and NSCoding protocols; if you want instances of your own custom subclass created from copying or coding, override the methods in these protocols.
Note that you shouldn’t override the hash method.
Alternatives to Subclassing
Often a better and easier alternative to making a subclass of NSString—or of any other abstract, public class of a class cluster, for that matter—is object composition. This is especially the case when your intent is to add to the subclass metadata or some other attribute that is not essential to a string object. In object composition, you would have an NSString object as one instance variable of your custom class (typically a subclass of NSObject) and one or more instance variables that store the metadata that you want for the custom object. Then just design your subclass interface to include accessor methods for the embedded string object and the metadata.
If the behavior you want to add supplements that of the existing class, you could write a category on NSString. Keep in mind, however, that this category will be in effect for all instances of NSString that you use, and this might have unintended consequences.
Adopted Protocols
Tasks
Creating and Initializing Strings
-
+ string -
– init -
– initWithBytes:length:encoding: -
– initWithBytesNoCopy:length:encoding:freeWhenDone: -
– initWithCharacters:length: -
– initWithCharactersNoCopy:length:freeWhenDone: -
– initWithString: -
– initWithCString:encoding: -
– initWithUTF8String: -
– initWithFormat: -
– initWithFormat:arguments: -
– initWithFormat:locale: -
– initWithFormat:locale:arguments: -
– initWithData:encoding: -
+ stringWithFormat: -
+ localizedStringWithFormat: -
+ stringWithCharacters:length: -
+ stringWithString: -
+ stringWithCString:encoding: -
+ stringWithUTF8String: -
+ stringWithCString:Deprecated in iOS 2.0 -
+ stringWithCString:length:Deprecated in iOS 2.0 -
– initWithCString:Deprecated in iOS 2.0 -
– initWithCString:length:Deprecated in iOS 2.0 -
– initWithCStringNoCopy:length:freeWhenDone:Deprecated in iOS 2.0
Creating and Initializing a String from a File
-
+ stringWithContentsOfFile:encoding:error: -
– initWithContentsOfFile:encoding:error: -
+ stringWithContentsOfFile:usedEncoding:error: -
– initWithContentsOfFile:usedEncoding:error: -
+ stringWithContentsOfFile:Deprecated in iOS 2.0 -
– initWithContentsOfFile:Deprecated in iOS 2.0
Creating and Initializing a String from an URL
-
+ stringWithContentsOfURL:encoding:error: -
– initWithContentsOfURL:encoding:error: -
+ stringWithContentsOfURL:usedEncoding:error: -
– initWithContentsOfURL:usedEncoding:error: -
+ stringWithContentsOfURL:Deprecated in iOS 2.0 -
– initWithContentsOfURL:Deprecated in iOS 2.0
Writing to a File or URL
-
– writeToFile:atomically:encoding:error: -
– writeToURL:atomically:encoding:error: -
– writeToFile:atomically:Deprecated in iOS 2.0 -
– writeToURL:atomically:Deprecated in iOS 2.0
Getting a String’s Length
Getting Characters and Bytes
-
– characterAtIndex: -
– getCharacters:range: -
– getBytes:maxLength:usedLength:encoding:options:range:remainingRange: -
– getCharacters:Deprecated in iOS 4.0
Getting C Strings
-
– cStringUsingEncoding: -
– getCString:maxLength:encoding: -
– UTF8String -
– cStringDeprecated in iOS 2.0 -
– cStringLengthDeprecated in iOS 2.0 -
– getCString:Deprecated in iOS 2.0 -
– getCString:maxLength:Deprecated in iOS 2.0 -
– getCString:maxLength:range:remainingRange:Deprecated in iOS 2.0 -
– lossyCStringDeprecated in iOS 2.0
Combining Strings
-
– stringByAppendingFormat: -
– stringByAppendingString: -
– stringByPaddingToLength:withString:startingAtIndex:
Dividing Strings
-
– componentsSeparatedByString: -
– componentsSeparatedByCharactersInSet: -
– stringByTrimmingCharactersInSet: -
– substringFromIndex: -
– substringWithRange: -
– substringToIndex:
Finding Characters and Substrings
-
– rangeOfCharacterFromSet: -
– rangeOfCharacterFromSet:options: -
– rangeOfCharacterFromSet:options:range: -
– rangeOfString: -
– rangeOfString:options: -
– rangeOfString:options:range: -
– rangeOfString:options:range:locale: -
– enumerateLinesUsingBlock: -
– enumerateSubstringsInRange:options:usingBlock:
Replacing Substrings
-
– stringByReplacingOccurrencesOfString:withString: -
– stringByReplacingOccurrencesOfString:withString:options:range: -
– stringByReplacingCharactersInRange:withString:
Determining Line and Paragraph Ranges
-
– getLineStart:end:contentsEnd:forRange: -
– lineRangeForRange: -
– getParagraphStart:end:contentsEnd:forRange: -
– paragraphRangeForRange:
Determining Composed Character Sequences
Converting String Contents Into a Property List
Identifying and Comparing Strings
-
– caseInsensitiveCompare: -
– localizedCaseInsensitiveCompare: -
– compare: -
– localizedCompare: -
– compare:options: -
– compare:options:range: -
– compare:options:range:locale: -
– localizedStandardCompare: -
– hasPrefix: -
– hasSuffix: -
– isEqualToString: -
– hash
Folding Strings
Getting a Shared Prefix
Changing Case
-
– capitalizedString -
– capitalizedStringWithLocale: -
– lowercaseString -
– lowercaseStringWithLocale: -
– uppercaseString -
– uppercaseStringWithLocale:
Getting Strings with Mapping
-
– decomposedStringWithCanonicalMapping -
– decomposedStringWithCompatibilityMapping -
– precomposedStringWithCanonicalMapping -
– precomposedStringWithCompatibilityMapping
Getting Numeric Values
Working with Encodings
-
+ availableStringEncodings -
+ defaultCStringEncoding -
+ localizedNameOfStringEncoding: -
– canBeConvertedToEncoding: -
– dataUsingEncoding: -
– dataUsingEncoding:allowLossyConversion: -
– description -
– fastestEncoding -
– smallestEncoding
Working with Paths
-
+ pathWithComponents: -
– pathComponents -
– completePathIntoString:caseSensitive:matchesIntoArray:filterTypes: -
– fileSystemRepresentation -
– getFileSystemRepresentation:maxLength: -
– isAbsolutePath -
– lastPathComponent -
– pathExtension -
– stringByAbbreviatingWithTildeInPath -
– stringByAppendingPathComponent: -
– stringByAppendingPathExtension: -
– stringByDeletingLastPathComponent -
– stringByDeletingPathExtension -
– stringByExpandingTildeInPath -
– stringByResolvingSymlinksInPath -
– stringByStandardizingPath -
– stringsByAppendingPaths:
Working with URLs
Linguistic Tagging and Analysis
Class Methods
availableStringEncodings
Returns a zero-terminated list of the encodings string objects support in the application’s environment.
Return Value
A zero-terminated list of the encodings string objects support in the application’s environment.
Discussion
Among the more commonly used encodings are:
See the “Constants” section for a larger list and descriptions of many supported encodings. In addition to those encodings listed here, you can also use the encodings defined for CFString in Core Foundation; you just need to call the CFStringConvertEncodingToNSStringEncoding function to convert them to a usable format.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hdefaultCStringEncoding
Returns the C-string encoding assumed for any method accepting a C string as an argument.
Return Value
The C-string encoding assumed for any method accepting a C string as an argument.
Discussion
This method returns a user-dependent encoding who value is derived from user's default language and potentially other factors. You might sometimes need to use this encoding when interpreting user documents with unknown encodings, in the absence of other hints, but in general this encoding should be used rarely, if at all. Note that some potential values might result in unexpected encoding conversions of even fairly straightforward NSString content—for example, punctuation characters with a bidirectional encoding.
Methods that accept a C string as an argument use ...CString... in the keywords for such arguments: for example, stringWithCString:—note, though, that these are deprecated. The default C-string encoding is determined from system information and can’t be changed programmatically for an individual process. See “String Encodings” for a full list of supported encodings.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hlocalizedNameOfStringEncoding:
Returns a human-readable string giving the name of a given encoding.
Parameters
- encoding
A string encoding.
Return Value
A human-readable string giving the name of encoding in the current locale’s language.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hlocalizedStringWithFormat:
Returns a string created by using a given format string as a template into which the remaining argument values are substituted according to the user's default locale.
Parameters
- format
A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif format isnil.- ...
A comma-separated list of arguments to substitute into format.
Return Value
A string created by using format as a template into which the following argument values are substituted according to the formatting information to the user's default locale.
Discussion
This method is equivalent to using initWithFormat:locale: and passing [[NSUserDefaults standardUserDefaults] dictionaryRepresentation] as the locale argument.
As an example of formatting, this method replaces the decimal according to the locale in %f and %d substitutions, and calls descriptionWithLocale: instead of description where necessary.
This code excerpt creates a string from another string and a float:
NSString *myString = [NSString localizedStringWithFormat:@"%@: %f\n", @"Cost", 1234.56]; |
The resulting string has the value “Cost: 1234.560000\n” if the locale is en_US, and “Cost: 1234,560000\n” if the locale is fr_FR.
See “Formatting String Objects” for more information.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hpathWithComponents:
Returns a string built from the strings in a given array by concatenating them with a path separator between each pair.
Parameters
- components
An array of
NSStringobjects representing a file path. To create an absolute path, use a slash mark (“/”) as the first component. To include a trailing path divider, use an empty string as the last component.
Return Value
A string built from the strings in components by concatenating them (in the order they appear in the array) with a path separator between each pair.
Discussion
This method doesn’t clean up the path created; use stringByStandardizingPath to resolve empty components, references to the parent directory, and so on.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSPathUtilities.hstring
Returns an empty string.
Return Value
An empty string.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringWithCharacters:length:
Returns a string containing a given number of characters taken from a given C array of Unicode characters.
Parameters
- chars
A C array of Unicode characters; the value must not be
NULL.- length
The number of characters to use from chars.
Return Value
A string containing length Unicode characters taken (starting with the first) from chars.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringWithContentsOfFile:encoding:error:
Returns a string created by reading data from the file at a given path interpreted using a given encoding.
Parameters
- path
A path to a file.
- enc
The encoding of the file at path.
- error
If an error occurs, upon returns contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, pass inNULL.
Return Value
A string created by reading data from the file named by path using the encoding, enc. If the file can’t be opened or there is an encoding error, returns nil.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringWithContentsOfFile:usedEncoding:error:
Returns a string created by reading data from the file at a given path and returns by reference the encoding used to interpret the file.
Parameters
- path
A path to a file.
- enc
Upon return, if the file is read successfully, contains the encoding used to interpret the file at path.
- error
If an error occurs, upon returns contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, you may pass inNULL.
Return Value
A string created by reading data from the file named by path. If the file can’t be opened or there is an encoding error, returns nil.
Discussion
This method attempts to determine the encoding of the file at path.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringWithContentsOfURL:encoding:error:
Returns a string created by reading data from a given URL interpreted using a given encoding.
Parameters
- url
The URL to read.
- enc
The encoding of the data at url.
- error
If an error occurs, upon returns contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, you may pass inNULL.
Return Value
A string created by reading data from URL using the encoding, enc. If the URL can’t be opened or there is an encoding error, returns nil.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringWithContentsOfURL:usedEncoding:error:
Returns a string created by reading data from a given URL and returns by reference the encoding used to interpret the data.
Parameters
- url
The URL from which to read data.
- enc
Upon return, if url is read successfully, contains the encoding used to interpret the data.
- error
If an error occurs, upon returns contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, you may pass inNULL.
Return Value
A string created by reading data from url. If the URL can’t be opened or there is an encoding error, returns nil.
Discussion
This method attempts to determine the encoding at url.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringWithCString:encoding:
Returns a string containing the bytes in a given C array, interpreted according to a given encoding.
Parameters
- cString
A C array of bytes. The array must end with a
NULLcharacter; intermediateNULLcharacters are not allowed.- enc
The encoding of cString.
Return Value
A string containing the characters described in cString.
Discussion
If cString is not a NULL-terminated C string, or encoding does not match the actual encoding, the results are undefined.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringWithFormat:
Returns a string created by using a given format string as a template into which the remaining argument values are substituted.
Parameters
- format
A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif format isnil.- ...
A comma-separated list of arguments to substitute into format.
Return Value
A string created by using format as a template into which the remaining argument values are substituted according to the canonical locale.
Discussion
This method is similar to localizedStringWithFormat:, but using the canonical locale to format numbers. This is useful, for example, if you want to produce “non-localized” formatting which needs to be written out to files and parsed back later.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringWithString:
Returns a string created by copying the characters from another given string.
Parameters
- aString
The string from which to copy characters. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aString isnil.
Return Value
A string created by copying the characters from aString.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringWithUTF8String:
Returns a string created by copying the data from a given C array of UTF8-encoded bytes.
Parameters
- bytes
A
NULL-terminated C array of bytes in UTF8 encoding.
Return Value
A string created by copying the data from bytes.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hInstance Methods
boolValue
Returns the Boolean value of the receiver’s text.
Return Value
The Boolean value of the receiver’s text. Returns YES on encountering one of "Y", "y", "T", "t", or a digit 1-9—the method ignores any trailing characters. Returns NO if the receiver doesn’t begin with a valid decimal text representation of a number.
Discussion
The method assumes a decimal representation and skips whitespace at the beginning of the string. It also skips initial whitespace characters, or optional -/+ sign followed by zeroes.
Availability
- Available in iOS 2.0 and later.
See Also
-
– integerValue -
scanInt:(NSScanner)
Declared In
NSString.hcanBeConvertedToEncoding:
Returns a Boolean value that indicates whether the receiver can be converted to a given encoding without loss of information.
Parameters
- encoding
A string encoding.
Return Value
YES if the receiver can be converted to encoding without loss of information. Returns NO if characters would have to be changed or deleted in the process of changing encodings.
Discussion
If you plan to actually convert a string, the dataUsingEncoding:... methods return nil on failure, so you can avoid the overhead of invoking this method yourself by simply trying to convert the string.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hcapitalizedString
Returns a capitalized representation of the receiver.
Return Value
A string with the first character from each word in the receiver changed to its corresponding uppercase value, and all remaining characters set to their corresponding lowercase values.
Discussion
A “word” here is any sequence of characters delimited by spaces, tabs, or line terminators (listed under getLineStart:end:contentsEnd:forRange:). Other common word delimiters such as hyphens and other punctuation aren’t considered, so this method may not generally produce the desired results for multiword strings.
Case transformations aren’t guaranteed to be symmetrical or to produce strings of the same lengths as the originals. See lowercaseString for an example.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hcapitalizedStringWithLocale:
Returns a capitalized representation of the receiver using the specified locale.
Parameters
- locale
The locale. Passing
nilindicates the canonical mapping.
Return Value
A capitalized string using the locale.
Discussion
For the user preference locale setting, pass the result of the NSLocale method currentLocale.
Availability
- Available in iOS 6.0 and later.
See Also
Declared In
NSString.hcaseInsensitiveCompare:
Returns the result of invoking compare:options: with NSCaseInsensitiveSearch as the only option.
Parameters
- aString
The string with which to compare the receiver.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.
Return Value
The result of invoking compare:options: with NSCaseInsensitiveSearch as the only option.
Discussion
If you are comparing strings to present to the end-user, you should typically use localizedCaseInsensitiveCompare: instead.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hcharacterAtIndex:
Returns the character at a given array position.
Parameters
- index
The index of the character to retrieve. The index value must not lie outside the bounds of the receiver.
Return Value
The character at the array position given by index.
Discussion
Raises an NSRangeException if index lies beyond the end of the receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hcommonPrefixWithString:options:
Returns a string containing characters the receiver and a given string have in common, starting from the beginning of each up to the first characters that aren’t equivalent.
Parameters
- aString
The string with which to compare the receiver.
- mask
Options for the comparison. The following search options may be specified by combining them with the C bitwise
ORoperator:NSCaseInsensitiveSearch,NSLiteralSearch. See String Programming Guide for details on these options.
Return Value
A string containing characters the receiver and aString have in common, starting from the beginning of each up to the first characters that aren’t equivalent.
Discussion
The returned string is based on the characters of the receiver. For example, if the receiver is “Ma¨dchen” and aString is “Mädchenschule”, the string returned is “Ma¨dchen”, not “Mädchen”.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hcompare:
Returns the result of invoking compare:options:range: with no options and the receiver’s full extent as the range.
Parameters
- aString
The string with which to compare the receiver.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.
Return Value
The result of invoking compare:options:range: with no options and the receiver’s full extent as the range.
Discussion
If you are comparing strings to present to the end-user, you should typically use localizedCompare: or localizedCaseInsensitiveCompare: instead.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hcompare:options:
Returns the result of invoking compare:options:range: with a given mask as the options and the receiver’s full extent as the range.
Parameters
- aString
The string with which to compare the receiver.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.- mask
Options for the search—you can combine any of the following using a C bitwise OR operator:
NSCaseInsensitiveSearch,NSLiteralSearch,NSNumericSearch. See String Programming Guide for details on these options.
Return Value
The result of invoking compare:options:range: with a given mask as the options and the receiver’s full extent as the range.
Discussion
If you are comparing strings to present to the end-user, you should typically use localizedCompare: or localizedCaseInsensitiveCompare: instead, or use compare:options:range:locale: and pass the user’s locale.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hcompare:options:range:
Returns the result of invoking compare:options:range:locale: with a nil locale.
Parameters
- aString
The string with which to compare the range of the receiver specified by range.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.- mask
Options for the search—you can combine any of the following using a C bitwise OR operator:
NSCaseInsensitiveSearch,NSLiteralSearch,NSNumericSearch.See String Programming Guide for details on these options.
- range
The range of the receiver over which to perform the comparison. The range must not exceed the bounds of the receiver.
Important: Raises an
NSRangeExceptionif range exceeds the bounds of the receiver.
Return Value
The result of invoking compare:options:range:locale: with a nil locale.
Discussion
If you are comparing strings to present to the end-user, you should typically use compare:options:range:locale: instead and pass the user’s locale (currentLocale [NSLocale]).
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hcompare:options:range:locale:
Returns an NSComparisonResult value that indicates the lexical ordering of a specified range within the receiver and a given string.
Parameters
- aString
The string with which to compare the range of the receiver specified by range.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.- mask
Options for the search—you can combine any of the following using a C bitwise OR operator:
NSCaseInsensitiveSearch,NSLiteralSearch,NSNumericSearch.See String Programming Guide for details on these options.
- range
The range of the receiver over which to perform the comparison. The range must not exceed the bounds of the receiver.
Important: Raises an
NSRangeExceptionif range exceeds the bounds of the receiver.- locale
An instance of
NSLocale. If this value notniland is not an instance ofNSLocale, uses the current locale instead. If you are comparing strings to present to the end-user, you should typically pass the user’s locale (currentLocale[NSLocale]).The locale argument affects both equality and ordering algorithms. For example, in some locales, accented characters are ordered immediately after the base; other locales order them after “z”.
Return Value
NSOrderedAscending if the substring of the receiver given by range precedes aString in lexical ordering for the locale given in dict, NSOrderedSame if the substring of the receiver and aString are equivalent in lexical value, and NSOrderedDescending if the substring of the receiver follows aString.
Special Considerations
Prior to OS X v10.5, the locale argument was an instance of NSDictionary. On OS X v10.5 and later, if you pass an instance of NSDictionary the current locale is used instead.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hcompletePathIntoString:caseSensitive:matchesIntoArray:filterTypes:
Interprets the receiver as a path in the file system and attempts to perform filename completion, returning a numeric value that indicates whether a match was possible, and by reference the longest path that matches the receiver.
Parameters
- outputName
Upon return, contains the longest path that matches the receiver.
- flag
If
YES, the methods considers case for possible completions.- outputArray
Upon return, contains all matching filenames.
- filterTypes
An array of
NSStringobjects specifying path extensions to consider for completion. only paths whose extensions (not including the extension separator) match one of those strings.
Return Value
0 if no matches are found and 1 if exactly one match is found. In the case of multiple matches, returns the actual number of matching paths if outputArray is provided, or simply a positive value if outputArray is NULL.
Discussion
You can check for the existence of matches without retrieving by passing NULL as outputArray.
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hcomponentsSeparatedByCharactersInSet:
Returns an array containing substrings from the receiver that have been divided by characters in a given set.
Parameters
- separator
A character set containing the characters to to use to split the receiver. Must not be
nil.
Return Value
An NSArray object containing substrings from the receiver that have been divided by characters in separator.
Discussion
The substrings in the array appear in the order they did in the receiver. Adjacent occurrences of the separator characters produce empty strings in the result. Similarly, if the string begins or ends with separator characters, the first or last substring, respectively, is empty.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hcomponentsSeparatedByString:
Returns an array containing substrings from the receiver that have been divided by a given separator.
Parameters
- separator
The separator string.
Return Value
An NSArray object containing substrings from the receiver that have been divided by separator.
Discussion
The substrings in the array appear in the order they did in the receiver. Adjacent occurrences of the separator string produce empty strings in the result. Similarly, if the string begins or ends with the separator, the first or last substring, respectively, is empty. For example, this code fragment:
NSString *list = @"Norman, Stanley, Fletcher"; |
NSArray *listItems = [list componentsSeparatedByString:@", "]; |
produces an array { @"Norman", @"Stanley", @"Fletcher" }.
If list begins with a comma and space—for example, ", Norman, Stanley, Fletcher"—the array has these contents: { @"", @"Norman", @"Stanley", @"Fletcher" }
If list has no separators—for example, "Norman"—the array contains the string itself, in this case { @"Norman" }.
Availability
- Available in iOS 2.0 and later.
See Also
-
componentsJoinedByString:(NSArray) -
– pathComponents
Declared In
NSString.hcStringUsingEncoding:
Returns a representation of the receiver as a C string using a given encoding.
Parameters
- encoding
The encoding for the returned C string.
Return Value
A C string representation of the receiver using the encoding specified by encoding. Returns NULL if the receiver cannot be losslessly converted to encoding.
Discussion
The returned C string is guaranteed to be valid only until either the receiver is freed, or until the current autorelease pool is emptied, whichever occurs first. You should copy the C string or use getCString:maxLength:encoding: if it needs to store the C string beyond this time.
You can use canBeConvertedToEncoding: to check whether a string can be losslessly converted to encoding. If it can’t, you can use dataUsingEncoding:allowLossyConversion: to get a C-string representation using encoding, allowing some loss of information (note that the data returned by dataUsingEncoding:allowLossyConversion: is not a strict C-string since it does not have a NULL terminator).
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hdataUsingEncoding:
Returns an NSData object containing a representation of the receiver encoded using a given encoding.
Parameters
- encoding
A string encoding.
Return Value
The result of invoking dataUsingEncoding:allowLossyConversion: with NO as the second argument (that is, requiring lossless conversion).
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hdataUsingEncoding:allowLossyConversion:
Returns an NSData object containing a representation of the receiver encoded using a given encoding.
Parameters
- encoding
A string encoding.
- flag
If
YES, then allows characters to be removed or altered in conversion.
Return Value
An NSData object containing a representation of the receiver encoded using encoding. Returns nil if flag is NO and the receiver can’t be converted without losing some information (such as accents or case).
Discussion
If flag is YES and the receiver can’t be converted without losing some information, some characters may be removed or altered in conversion. For example, in converting a character from NSUnicodeStringEncoding to NSASCIIStringEncoding, the character ‘Á’ becomes ‘A’, losing the accent.
This method creates an external representation (with a byte order marker, if necessary, to indicate endianness) to ensure that the resulting NSData object can be written out to a file safely. The result of this method, when lossless conversion is made, is the default “plain text” format for encoding and is the recommended way to save or transmit a string object.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hdecomposedStringWithCanonicalMapping
Returns a string made by normalizing the receiver’s contents using Form D.
Return Value
A string made by normalizing the receiver’s contents using the Unicode Normalization Form D.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hdecomposedStringWithCompatibilityMapping
Returns a string made by normalizing the receiver’s contents using Form KD.
Return Value
A string made by normalizing the receiver’s contents using the Unicode Normalization Form KD.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hdescription
Returns the receiver.
Return Value
The receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hdoubleValue
Returns the floating-point value of the receiver’s text as a double.
Return Value
The floating-point value of the receiver’s text as a double. Returns HUGE_VAL or –HUGE_VAL on overflow, 0.0 on underflow. Returns 0.0 if the receiver doesn’t begin with a valid text representation of a floating-point number.
Discussion
This method skips any whitespace at the beginning of the string. This method uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.
Availability
- Available in iOS 2.0 and later.
See Also
-
– floatValue -
– longLongValue -
– integerValue -
scanDouble:(NSScanner)
Declared In
NSString.henumerateLinesUsingBlock:
Enumerates all the lines in a string.
Parameters
- block
The block executed for the enumeration.
The block takes two arguments:
- line
The current line of the string being enumerated. The line contains just the contents of the line, without the line terminators.
- stop
A reference to a Boolean value that the block can use to stop the enumeration by setting
*stop = YES; it should not touch*stopotherwise.
Availability
- Available in iOS 4.0 and later.
Declared In
NSString.henumerateLinguisticTagsInRange:scheme:options:orthography:usingBlock:
Performs linguistic analysis on the specified string by enumerating the specific range of the string, providing the Block with the located tags.
Parameters
- range
The range of the string to analyze.
- tagScheme
The tag scheme to use. See
Linguistic Tag Schemesfor supported values.- opts
The linguistic tagger options to use. See
NSLinguisticTaggerOptionsfor the constants. These constants can be combined using the C-Bitwise OR operator.- orthography
The orthography of the string. If nil, the linguistic tagger will attempt to determine the orthography from the string content.
- block
The Block to apply to the string.
The block takes four arguments:
- tag
The tag scheme for the token. The opts parameter specifies the types of tagger options that are located.
- tokenRange
The range of a string matching the tag scheme.
- sentenceRange
The range of the sentence in which the token is found.
- stop
A reference to a Boolean value. The block can set the value to
YESto stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean toYESwithin the Block.
Discussion
This is a convenience method. It is the equivalent of creating an instance of NSLinguisticTagger, specifying the receiver as the string to be analyzed, and the orthography (or nil) and then invoking the NSLinguisticTagger method or enumerateTagsInRange:scheme:options:usingBlock:.
Availability
- Available in iOS 5.0 and later.
Declared In
NSLinguisticTagger.henumerateSubstringsInRange:options:usingBlock:
Enumerates the substrings of the specified type in the specified range of the string.
Parameters
- range
The range within the string to enumerate substrings.
- opts
Options specifying types of substrings and enumeration styles.
- block
The block executed for the enumeration.
The block takes four arguments:
- substring
The enumerated string.
- substringRange
The range of the enumerated string in the receiver.
- enclosingRange
The range that includes the substring as well as any separator or filler characters that follow. For instance, for lines, enclosingRange contains the line terminators. The enclosingRange for the first string enumerated also contains any characters that occur before the string. Consecutive enclosing ranges are guaranteed not to overlap, and every single character in the enumerated range is included in one and only one enclosing range.
- stop
A reference to a Boolean value that the block can use to stop the enumeration by setting
*stop = YES; it should not touch*stopotherwise.
Discussion
If this method is sent to an instance of NSMutableString, mutation (deletion, addition, or change) is allowed, as long as it is within enclosingRange. After a mutation, the enumeration continues with the range immediately following the processed range, after the length of the processed range is adjusted for the mutation. (The enumerator assumes any change in length occurs in the specified range.)
For example, if the block is called with a range starting at location N, and the block deletes all the characters in the supplied range, the next call will also pass N as the index of the range. This is the case even if mutation of the previous range changes the string in such a way that the following substring would have extended to include the already enumerated range. For example, if the string "Hello World" is enumerated via words, and the block changes "Hello " to "Hello", thus forming "HelloWorld", the next enumeration will return "World" rather than "HelloWorld".
Availability
- Available in iOS 4.0 and later.
Declared In
NSString.hfastestEncoding
Returns the fastest encoding to which the receiver may be converted without loss of information.
Return Value
The fastest encoding to which the receiver may be converted without loss of information.
Discussion
“Fastest” applies to retrieval of characters from the string. This encoding may not be space efficient.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hfileSystemRepresentation
Returns a file system-specific representation of the receiver.
Return Value
A file system-specific representation of the receiver, as described for getFileSystemRepresentation:maxLength:.
Discussion
The returned C string will be automatically freed just as a returned object would be released; your code should copy the representation or use getFileSystemRepresentation:maxLength: if it needs to store the representation outside of the autorelease context in which the representation is created.
Raises an NSCharacterConversionException if the receiver can’t be represented in the file system’s encoding. It also raises an exception if the string contains no characters.
Note that this method only works with file paths (not, for example, string representations of URLs).
To convert a char * path (such as you might get from a C library routine) to an NSString object, use NSFileManager‘s stringWithFileSystemRepresentation:length: method.
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hfloatValue
Returns the floating-point value of the receiver’s text as a float.
Return Value
The floating-point value of the receiver’s text as a float, skipping whitespace at the beginning of the string. Returns HUGE_VAL or –HUGE_VAL on overflow, 0.0 on underflow. Also returns 0.0 if the receiver doesn’t begin with a valid text representation of a floating-point number.
Discussion
This method uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.
Availability
- Available in iOS 2.0 and later.
See Also
-
– doubleValue -
– longLongValue -
– integerValue -
scanFloat:(NSScanner)
Declared In
NSString.hgetBytes:maxLength:usedLength:encoding:options:range:remainingRange:
Gets a given range of characters as bytes in a specified encoding.
Parameters
- buffer
A buffer into which to store the bytes from the receiver. The returned bytes are not
NULL-terminated.- maxBufferCount
The maximum number of bytes to write to buffer.
- usedBufferCount
The number of bytes used from buffer. Pass
NULLif you do not need this value.- encoding
The encoding to use for the returned bytes.
- options
A mask to specify options to use for converting the receiver’s contents to encoding (if conversion is necessary).
- range
The range of characters in the receiver to get.
- leftover
The remaining range. Pass
NULLIf you do not need this value.
Return Value
YES if some characters were converted, otherwise NO.
Discussion
Conversion might stop when the buffer fills, but it might also stop when the conversion isn't possible due to the chosen encoding.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hgetCharacters:range:
Copies characters from a given range in the receiver into a given buffer.
Parameters
- buffer
Upon return, contains the characters from the receiver. buffer must be large enough to contain the characters in the range aRange (
aRange.length*sizeof(unichar)).- aRange
The range of characters to retrieve. The range must not exceed the bounds of the receiver.
Important: Raises an
NSRangeExceptionif any part of aRange lies beyond the bounds of the receiver.
Discussion
This method does not add a NULL character.
The abstract implementation of this method uses characterAtIndex: repeatedly, correctly extracting the characters, though very inefficiently. Subclasses should override it to provide a fast implementation.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hgetCString:maxLength:encoding:
Converts the receiver’s content to a given encoding and stores them in a buffer.
Parameters
- buffer
Upon return, contains the converted C-string plus the
NULLtermination byte. The buffer must include room for maxBufferCount bytes.- maxBufferCount
The maximum number of bytes in the string to return in buffer (including the
NULLtermination byte).- encoding
The encoding for the returned C string.
Return Value
YES if the operation was successful, otherwise NO. Returns NO if conversion is not possible due to encoding errors or if buffer is too small.
Discussion
Note that in the treatment of the maxBufferCount argument, this method differs from the deprecated getCString:maxLength: method which it replaces. (The buffer should include room for maxBufferCount bytes; this number should accommodate the expected size of the return value plus the NULL termination byte, which this method adds.)
You can use canBeConvertedToEncoding: to check whether a string can be losslessly converted to encoding. If it can’t, you can use dataUsingEncoding:allowLossyConversion: to get a C-string representation using encoding, allowing some loss of information (note that the data returned by dataUsingEncoding:allowLossyConversion: is not a strict C-string since it does not have a NULL terminator).
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hgetFileSystemRepresentation:maxLength:
Interprets the receiver as a system-independent path and fills a buffer with a C-string in a format and encoding suitable for use with file-system calls.
Parameters
- buffer
Upon return, contains a C-string that represent the receiver as as a system-independent path, plus the
NULLtermination byte. The size of buffer must be large enough to contain maxLength bytes.- maxLength
The maximum number of bytes in the string to return in buffer (including a terminating
NULLcharacter, which this method adds).
Return Value
YES if buffer is successfully filled with a file-system representation, otherwise NO (for example, if maxLength would be exceeded or if the receiver can’t be represented in the file system’s encoding).
Discussion
This method operates by replacing the abstract path and extension separator characters (‘/’ and ‘.’ respectively) with their equivalents for the operating system. If the system-specific path or extension separator appears in the abstract representation, the characters it is converted to depend on the system (unless they’re identical to the abstract separators).
Note that this method only works with file paths (not, for example, string representations of URLs).
The following example illustrates the use of the maxLength argument. The first method invocation returns failure as the file representation of the string (@"/mach_kernel") is 12 bytes long and the value passed as the maxLength argument (12) does not allow for the addition of a NULL termination byte.
char filenameBuffer[13]; |
BOOL success; |
success = [@"/mach_kernel" getFileSystemRepresentation:filenameBuffer maxLength:12]; |
// success == NO |
// Changing the length to include the NULL character does work |
success = [@"/mach_kernel" getFileSystemRepresentation:filenameBuffer maxLength:13]; |
// success == YES |
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSPathUtilities.hgetLineStart:end:contentsEnd:forRange:
Returns by reference the beginning of the first line and the end of the last line touched by the given range.
Parameters
- startIndex
Upon return, contains the index of the first character of the line containing the beginning of aRange. Pass
NULLif you do not need this value (in which case the work to compute the value isn’t performed).- lineEndIndex
Upon return, contains the index of the first character past the terminator of the line containing the end of aRange. Pass
NULLif you do not need this value (in which case the work to compute the value isn’t performed).- contentsEndIndex
Upon return, contains the index of the first character of the terminator of the line containing the end of aRange. Pass
NULLif you do not need this value (in which case the work to compute the value isn’t performed).- aRange
A range within the receiver. The value must not exceed the bounds of the receiver.
Important: Raises an
NSRangeExceptionif any part of aRange lies beyond the end of the string.
Discussion
A line is delimited by any of these characters, the longest possible sequence being preferred to any shorter:
U+000D(\rorCR)U+2028(Unicode line separator)U+000A(\norLF)U+2029(Unicode paragraph separator)\r\n, in that order (also known asCRLF)
If aRange is contained with a single line, of course, the returned indexes all belong to that line. You can use the results of this method to construct ranges for lines by using the start index as the range’s location and the difference between the end index and the start index as the range’s length.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hgetParagraphStart:end:contentsEnd:forRange:
Returns by reference the beginning of the first paragraph and the end of the last paragraph touched by the given range.
Parameters
- startIndex
Upon return, contains the index of the first character of the paragraph containing the beginning of aRange. Pass
NULLif you do not need this value (in which case the work to compute the value isn’t performed).- endIndex
Upon return, contains the index of the first character past the terminator of the paragraph containing the end of aRange. Pass
NULLif you do not need this value (in which case the work to compute the value isn’t performed).- contentsEndIndex
Upon return, contains the index of the first character of the terminator of the paragraph containing the end of aRange. Pass
NULLif you do not need this value (in which case the work to compute the value isn’t performed).- aRange
A range within the receiver. The value must not exceed the bounds of the receiver.
Discussion
If aRange is contained with a single paragraph, of course, the returned indexes all belong to that paragraph. Similar to getLineStart:end:contentsEnd:forRange:, you can use the results of this method to construct the ranges for paragraphs.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hhash
Returns an unsigned integer that can be used as a hash table address.
Return Value
An unsigned integer that can be used as a hash table address.
Discussion
If two string objects are equal (as determined by the isEqualToString: method), they must have the same hash value. The abstract implementation of this method fulfills this requirement, so subclasses of NSString shouldn’t override it.
You should not rely on this method returning the same hash value across releases of OS X.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hhasPrefix:
Returns a Boolean value that indicates whether a given string matches the beginning characters of the receiver.
Parameters
- aString
A string.
Return Value
YES if aString matches the beginning characters of the receiver, otherwise NO. Returns NO if aString is empty.
Discussion
This method is a convenience for comparing strings using the NSAnchoredSearch option. See String Programming Guide for more information.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hhasSuffix:
Returns a Boolean value that indicates whether a given string matches the ending characters of the receiver.
Parameters
- aString
A string.
Return Value
YES if aString matches the ending characters of the receiver, otherwise NO. Returns NO if aString is empty.
Discussion
This method is a convenience for comparing strings using the NSAnchoredSearch and NSBackwardsSearch options. See String Programming Guide for more information.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinit
Returns an initialized NSString object that contains no characters.
Return Value
An initialized NSString object that contains no characters. The returned object may be different from the original receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithBytes:length:encoding:
Returns an initialized NSString object containing a given number of bytes from a given buffer of bytes interpreted in a given encoding.
Parameters
- bytes
A buffer of bytes interpreted in the encoding specified by encoding.
- length
The number of bytes to use from bytes.
- encoding
The character encoding applied to bytes.
Return Value
An initialized NSString object containing length bytes from bytes interpreted using the encoding encoding. The returned object may be different from the original receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithBytesNoCopy:length:encoding:freeWhenDone:
Returns an initialized NSString object that contains a given number of bytes from a given buffer of bytes interpreted in a given encoding, and optionally frees the buffer.
Parameters
- bytes
A buffer of bytes interpreted in the encoding specified by encoding.
- length
The number of bytes to use from bytes.
- encoding
The character encoding of bytes.
- flag
If
YES, the receiver frees the memory when it no longer needs the data; ifNOit won’t.
Return Value
An initialized NSString object containing length bytes from bytes interpreted using the encoding encoding. The returned object may be different from the original receiver.
Special Considerations
If an error occurs during the creation of the string, then bytes is not freed even if flag is YES. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithCharacters:length:
Returns an initialized NSString object that contains a given number of characters from a given C array of Unicode characters.
Parameters
- characters
A C array of Unicode characters; the value must not be
NULL.- length
The number of characters to use from characters.
Return Value
An initialized NSString object containing length characters taken from characters. The returned object may be different from the original receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithCharactersNoCopy:length:freeWhenDone:
Returns an initialized NSString object that contains a given number of characters from a given C array of Unicode characters.
Parameters
- characters
A C array of Unicode characters.
- length
The number of characters to use from characters.
- flag
If
YES, the receiver will free the memory when it no longer needs the characters; ifNOit won’t.
Return Value
An initialized NSString object that contains length characters from characters. The returned object may be different from the original receiver.
Special Considerations
If an error occurs during the creation of the string, then bytes is not freed even if flag is YES. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithContentsOfFile:encoding:error:
Returns an NSString object initialized by reading data from the file at a given path using a given encoding.
Parameters
- path
A path to a file.
- enc
The encoding of the file at path.
- error
If an error occurs, upon return contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, pass inNULL.
Return Value
An NSString object initialized by reading data from the file named by path using the encoding, enc. The returned object may be different from the original receiver. If the file can’t be opened or there is an encoding error, returns nil.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithContentsOfFile:usedEncoding:error:
Returns an NSString object initialized by reading data from the file at a given path and returns by reference the encoding used to interpret the characters.
Parameters
- path
A path to a file.
- enc
Upon return, if the file is read successfully, contains the encoding used to interpret the file at path.
- error
If an error occurs, upon returns contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, pass inNULL.
Return Value
An NSString object initialized by reading data from the file named by path. The returned object may be different from the original receiver. If the file can’t be opened or there is an encoding error, returns nil.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithContentsOfURL:encoding:error:
Returns an NSString object initialized by reading data from a given URL interpreted using a given encoding.
Parameters
- url
The URL to read.
- enc
The encoding of the file at path.
- error
If an error occurs, upon returns contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, pass inNULL.
Return Value
An NSString object initialized by reading data from url. The returned object may be different from the original receiver. If the URL can’t be opened or there is an encoding error, returns nil.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithContentsOfURL:usedEncoding:error:
Returns an NSString object initialized by reading data from a given URL and returns by reference the encoding used to interpret the data.
Parameters
- url
The URL from which to read data.
- enc
Upon return, if url is read successfully, contains the encoding used to interpret the data.
- error
If an error occurs, upon returns contains an
NSErrorobject that describes the problem. If you are not interested in possible errors, pass inNULL.
Return Value
An NSString object initialized by reading data from url. If url can’t be opened or the encoding cannot be determined, returns nil. The returned initialized object might be different from the original receiver
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithCString:encoding:
Returns an NSString object initialized using the characters in a given C array, interpreted according to a given encoding.
Parameters
- nullTerminatedCString
A C array of characters. The array must end with a
NULLcharacter; intermediateNULLcharacters are not allowed.- encoding
The encoding of nullTerminatedCString.
Return Value
An NSString object initialized using the characters from nullTerminatedCString. The returned object may be different from the original receiver
Discussion
If nullTerminatedCString is not a NULL-terminated C string, or encoding does not match the actual encoding, the results are undefined.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithData:encoding:
Returns an NSString object initialized by converting given data into Unicode characters using a given encoding.
Parameters
- data
An
NSDataobject containing bytes in encoding and the default plain text format (that is, pure content with no attributes or other markups) for that encoding.- encoding
The encoding used by data.
Return Value
An NSString object initialized by converting the bytes in data into Unicode characters using encoding. The returned object may be different from the original receiver. Returns nil if the initialization fails for some reason (for example if data does not represent valid data for encoding).
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithFormat:
Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted.
Parameters
- format
A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif format isnil.- ...
A comma-separated list of arguments to substitute into format.
Return Value
An NSString object initialized by using format as a template into which the remaining argument values are substituted according to the canonical locale. The returned object may be different from the original receiver.
Discussion
Invokes initWithFormat:locale:arguments: with nil as the locale, hence using the canonical locale to format numbers. This is useful, for example, if you want to produce "non-localized" formatting which needs to be written out to files and parsed back later.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hinitWithFormat:arguments:
Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted according to the user’s default locale.
Parameters
- format
A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif format isnil.- argList
A list of arguments to substitute into format.
Return Value
An NSString object initialized by using format as a template into which the values in argList are substituted according to the user’s default locale. The returned object may be different from the original receiver.
Discussion
Invokes initWithFormat:locale:arguments: with nil as the locale.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithFormat:locale:
Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted according to given locale information.
Parameters
- format
A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif format isnil.- locale
This may be an instance of
NSDictionarycontaining locale information or an instance ofNSLocale. If this value isnil, uses the canonical locale.To use a dictionary containing the current user's locale, you can use
[[NSUserDefaults standardUserDefaults] dictionaryRepresentation].- ...
A comma-separated list of arguments to substitute into format.
Discussion
Invokes initWithFormat:locale:arguments: with locale as the locale.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithFormat:locale:arguments:
Returns an NSString object initialized by using a given format string as a template into which the remaining argument values are substituted according to given locale information.
Parameters
- format
A format string. See “Formatting String Objects” for examples of how to use this method, and “String Format Specifiers” for a list of format specifiers. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif format isnil.- locale
This may be an instance of
NSDictionarycontaining locale information or an instance ofNSLocale. If this value isnil, uses the canonical locale.To use a dictionary containing the current user's locale, you can use
[[NSUserDefaults standardUserDefaults] dictionaryRepresentation].- argList
A list of arguments to substitute into format.
Return Value
An NSString object initialized by using format as a template into which values in argList are substituted according the locale information in locale. The returned object may be different from the original receiver.
Discussion
The following code fragment illustrates how to create a string from myArgs, which is derived from a string object with the value “Cost:” and an int with the value 32:
va_list myArgs; |
NSString *myString = [[NSString alloc] initWithFormat:@"%@: %d\n" |
locale:[[NSUserDefaults standardUserDefaults] dictionaryRepresentation] |
arguments:myArgs]; |
The resulting string has the value “Cost: 32\n”.
See String Programming Guide for more information.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithString:
Returns an NSString object initialized by copying the characters from another given string.
Parameters
- aString
The string from which to copy characters. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aString isnil.
Return Value
An NSString object initialized by copying the characters from aString. The returned object may be different from the original receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hinitWithUTF8String:
Returns an NSString object initialized by copying the characters a given C array of UTF8-encoded bytes.
Parameters
- bytes
A
NULL-terminated C array of bytes in UTF-8 encoding. This value must not beNULL.
Return Value
An NSString object initialized by copying the bytes from bytes. The returned object may be different from the original receiver.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hintegerValue
Returns the NSInteger value of the receiver’s text.
Return Value
The NSInteger value of the receiver’s text, assuming a decimal representation and skipping whitespace at the beginning of the string. Returns 0 if the receiver doesn’t begin with a valid decimal text representation of a number.
Discussion
This method uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.
Availability
- Available in iOS 2.0 and later.
See Also
-
– doubleValue -
– floatValue -
scanInt:(NSScanner)
Declared In
NSString.hintValue
Returns the integer value of the receiver’s text.
Return Value
The integer value of the receiver’s text, assuming a decimal representation and skipping whitespace at the beginning of the string. Returns INT_MAX or INT_MIN on overflow. Returns 0 if the receiver doesn’t begin with a valid decimal text representation of a number.
Discussion
This method uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.
Special Considerations
On OS X v10.5 and later, use integerValue instead.
Availability
- Available in iOS 2.0 and later.
See Also
-
– integerValue -
– doubleValue -
– floatValue -
scanInt:(NSScanner)
Declared In
NSString.hisAbsolutePath
Returning a Boolean value that indicates whether the receiver represents an absolute path.
Return Value
YES if the receiver (if interpreted as a path) represents an absolute path, otherwise NO (if the receiver represents a relative path).
Discussion
See String Programming Guide for more information on paths.
Note that this method only works with file paths (not, for example, string representations of URLs). The method does not check the filesystem for the existence of the path (use fileExistsAtPath: or similar methods in NSFileManager for that task).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hisEqualToString:
Returns a Boolean value that indicates whether a given string is equal to the receiver using a literal Unicode-based comparison.
Parameters
- aString
The string with which to compare the receiver.
Return Value
YES if aString is equivalent to the receiver (if they have the same id or if they are NSOrderedSame in a literal comparison), otherwise NO.
Discussion
The comparison uses the canonical representation of strings, which for a particular string is the length of the string plus the Unicode characters that make up the string. When this method compares two strings, if the individual Unicodes are the same, then the strings are equal, regardless of the backing store. “Literal” when applied to string comparison means that various Unicode decomposition rules are not applied and Unicode characters are individually compared. So, for instance, “Ö” represented as the composed character sequence “O” and umlaut would not compare equal to “Ö” represented as one Unicode character.
Special Considerations
When you know both objects are strings, this method is a faster way to check equality than isEqual:.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hlastPathComponent
Returns the last path component of the receiver.
Return Value
The last path component of the receiver.
Discussion
Path components are alphanumeric strings delineated by the path separator (slash “/”) or the beginning or end of the path string. Multiple path separators at the end of the string are stripped.
The following table illustrates the effect of lastPathComponent on a variety of different paths:
Receiver’s String Value |
String Returned |
|---|---|
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“/” |
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hlength
Returns the number of Unicode characters in the receiver.
Return Value
The number of Unicode characters in the receiver.
Discussion
The number returned includes the individual characters of composed character sequences, so you cannot use this method to determine if a string will be visible when printed or how long it will appear.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hlengthOfBytesUsingEncoding:
Returns the number of bytes required to store the receiver in a given encoding.
Parameters
- enc
The encoding for which to determine the receiver's length.
Return Value
The number of bytes required to store the receiver in the encoding enc in a non-external representation. The length does not include space for a terminating NULL character. Returns 0 if the specified encoding cannot be used to convert the receiver or if the amount of memory required for storing the results of the encoding conversion would exceed NSIntegerMax.
Discussion
The result is exact and is returned in O(n) time.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hlineRangeForRange:
Returns the range of characters representing the line or lines containing a given range.
Parameters
- aRange
A range within the receiver.
Return Value
The range of characters representing the line or lines containing aRange, including the line termination characters.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hlinguisticTagsInRange:scheme:options:orthography:tokenRanges:
Returns an array of linguistic tags for the specified range and requested tags within the receiving string.
Parameters
- range
The range of the string to analyze.
- tagScheme
The tag scheme to use. See
Linguistic Tag Schemesfor supported values.- opts
The linguistic tagger options to use. See
NSLinguisticTaggerOptionsfor the constants. These constants can be combined using the C-Bitwise OR operator.- orthography
The orthography of the string. If
nil, the linguistic tagger will attempt to determine the orthography from the string content.- tokenRanges
An array returned by-reference containing the token ranges of the linguistic tags wrapped in
NSValueobjects.
Return Value
Returns an array containing the linguistic tags for the tokenRanges within the receiving string.
Discussion
This is a convenience method. It is the equivalent of creating an instance of NSLinguisticTagger, specifying the receiver as the string to be analyzed, and the orthography (or nil) and then invoking the NSLinguisticTagger method or linguisticTagsInRange:scheme:options:orthography:tokenRanges:.
Availability
- Available in iOS 5.0 and later.
Declared In
NSLinguisticTagger.hlocalizedCaseInsensitiveCompare:
Returns an NSComparisonResult value that indicates the lexical ordering of the receiver and a given string using a case-insensitive, localized, comparison.
Parameters
- aString
The string with which to compare the receiver.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.
Return Value
NSOrderedAscending the receiver precedes aString in lexical ordering, NSOrderedSame the receiver and aString are equivalent in lexical value, and NSOrderedDescending if the receiver follows aString.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hlocalizedCompare:
Returns an NSComparisonResult value that indicates the lexical ordering of the receiver and another given string using a localized comparison.
Parameters
- aString
The string with which to compare the receiver.
This value must not be
nil. If this value isnil, the behavior is undefined and may change in future versions of OS X.
Return Value
NSOrderedAscending the receiver precedes string in lexical ordering, NSOrderedSame the receiver and string are equivalent in lexical value, and NSOrderedDescending if the receiver follows string.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hlocalizedStandardCompare:
Compares strings as sorted by the Finder.
Parameters
- string
The string to compare with the receiver.
Return Value
The result of the comparison.
Discussion
This method should be used whenever file names or other strings are presented in lists and tables where Finder-like sorting is appropriate. The exact sorting behavior of this method is different under different locales and may be changed in future releases.
Availability
- Available in iOS 4.0 and later.
Declared In
NSString.hlongLongValue
Returns the long long value of the receiver’s text.
Return Value
The long long value of the receiver’s text, assuming a decimal representation and skipping whitespace at the beginning of the string. Returns LLONG_MAX or LLONG_MIN on overflow. Returns 0 if the receiver doesn’t begin with a valid decimal text representation of a number.
Discussion
This method uses formatting information stored in the non-localized value; use an NSScanner object for localized scanning of numeric values from a string.
Availability
- Available in iOS 2.0 and later.
See Also
-
– doubleValue -
– floatValue -
scanInt:(NSScanner)
Declared In
NSString.hlowercaseString
Returns lowercased representation of the receiver.
Return Value
A string with each character from the receiver changed to its corresponding lowercase value.
Discussion
Case transformations aren’t guaranteed to be symmetrical or to produce strings of the same lengths as the originals. The result of this statement:
lcString = [myString lowercaseString]; |
might not be equal to this statement:
lcString = [[myString uppercaseString] lowercaseString]; |
For example, the uppercase form of “ß” in German is “SS”, so converting “Straße” to uppercase, then lowercase, produces this sequence of strings:
“Straße”
“STRASSE”
“strasse”
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hlowercaseStringWithLocale:
Returns lowercased representation of the receiver with the specified locale.
Parameters
- locale
The locale. Passing
nilindicates the canonical mapping.
Return Value
A lowercase string using the locale.
Discussion
For the user preference locale setting, pass the result of the NSLocale method currentLocale.
Availability
- Available in iOS 6.0 and later.
Declared In
NSString.hmaximumLengthOfBytesUsingEncoding:
Returns the maximum number of bytes needed to store the receiver in a given encoding.
Parameters
- enc
The encoding for which to determine the receiver's length.
Return Value
The maximum number of bytes needed to store the receiver in encoding in a non-external representation. The length does not include space for a terminating NULL character. Returns 0 if the amount of memory required for storing the results of the encoding conversion would exceed NSIntegerMax.
Discussion
The result is an estimate and is returned in O(1) time; the estimate may be considerably greater than the actual length needed.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hparagraphRangeForRange:
Returns the range of characters representing the paragraph or paragraphs containing a given range.
Parameters
- aRange
A range within the receiver. The range must not exceed the bounds of the receiver.
Return Value
The range of characters representing the paragraph or paragraphs containing aRange, including the paragraph termination characters.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hpathComponents
Returns an array of NSString objects containing, in order, each path component of the receiver.
Return Value
An array of NSString objects containing, in order, each path component of the receiver.
Discussion
The strings in the array appear in the order they did in the receiver. If the string begins or ends with the path separator, then the first or last component, respectively, will contain the separator. Empty components (caused by consecutive path separators) are deleted. For example, this code excerpt:
NSString *path = @"tmp/scratch"; |
NSArray *pathComponents = [path pathComponents]; |
produces an array with these contents:
Index |
Path Component |
|---|---|
0 |
“ |
1 |
“ |
If the receiver begins with a slash—for example, “/tmp/scratch”—the array has these contents:
Index |
Path Component |
|---|---|
0 |
“ |
1 |
“ |
2 |
“ |
If the receiver has no separators—for example, “scratch”—the array contains the string itself, in this case “scratch”.
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hpathExtension
Interprets the receiver as a path and returns the receiver’s extension, if any.
Return Value
The receiver’s extension, if any (not including the extension divider).
Discussion
The path extension is the portion of the last path component which follows the final period, if there is one. The following table illustrates the effect of pathExtension on a variety of different paths:
Receiver’s String Value |
String Returned |
|---|---|
“ |
“ |
“ | “ |
“ |
“” (an empty string) |
“ |
“” (an empty string) |
“ |
“ |
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hprecomposedStringWithCanonicalMapping
Returns a string made by normalizing the receiver’s contents using Form C.
Return Value
A string made by normalizing the receiver’s contents using the Unicode Normalization Form C.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hprecomposedStringWithCompatibilityMapping
Returns a string made by normalizing the receiver’s contents using Form KC.
Return Value
A string made by normalizing the receiver’s contents using the Unicode Normalization Form KC.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hpropertyList
Parses the receiver as a text representation of a property list, returning an NSString, NSData, NSArray, or NSDictionary object, according to the topmost element.
Return Value
A property list representation of returning an NSString, NSData, NSArray, or NSDictionary object, according to the topmost element.
Discussion
The receiver must contain a string in a property list format. For a discussion of property list formats, see Property List Programming Guide.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hpropertyListFromStringsFileFormat
Returns a dictionary object initialized with the keys and values found in the receiver.
Return Value
A dictionary object initialized with the keys and values found in the receiver
Discussion
The receiver must contain text in the format used for .strings files. In this format, keys and values are separated by an equal sign, and each key-value pair is terminated with a semicolon. The value is optional—if not present, the equal sign is also omitted. The keys and values themselves are always strings enclosed in straight quotation marks. Comments may be included, delimited by /* and */ as for ANSI C comments. Here’s a short example of a strings file:
/* Question in confirmation panel for quitting. */ |
"Confirm Quit" = "Are you sure you want to quit?"; |
/* Message when user tries to close unsaved document */ |
"Close or Save" = "Save changes before closing?"; |
/* Word for Cancel */ |
"Cancel"; |
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfCharacterFromSet:
Finds and returns the range in the receiver of the first character from a given character set.
Parameters
- aSet
A character set. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aSet isnil.
Return Value
The range in the receiver of the first character found from aSet. Returns a range of {NSNotFound, 0} if none of the characters in aSet are found.
Discussion
Invokes rangeOfCharacterFromSet:options: with no options.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfCharacterFromSet:options:
Finds and returns the range in the receiver of the first character, using given options, from a given character set.
Parameters
- aSet
A character set. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aSet isnil.- mask
A mask specifying search options. The following options may be specified by combining them with the C bitwise
ORoperator:NSCaseInsensitiveSearch,NSLiteralSearch,NSBackwardsSearch. See String Programming Guide for details on these options.
Return Value
The range in the receiver of the first character found from aSet. Returns a range of {NSNotFound, 0} if none of the characters in aSet are found.
Discussion
Invokes rangeOfCharacterFromSet:options:range: with mask for the options and the entire extent of the receiver for the range.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfCharacterFromSet:options:range:
Finds and returns the range in the receiver of the first character from a given character set found in a given range with given options.
Parameters
- aSet
A character set. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aSet isnil.- mask
A mask specifying search options. The following options may be specified by combining them with the C bitwise
ORoperator:NSCaseInsensitiveSearch,NSLiteralSearch,NSBackwardsSearch. See String Programming Guide for details on these options.- aRange
The range in which to search. aRange must not exceed the bounds of the receiver.
Important: Raises an
NSRangeExceptionif any part of aRange lies beyond the end of the string.
Return Value
The range in the receiver of the first character found from aSet within aRange. Returns a range of {NSNotFound, 0} if none of the characters in aSet are found.
Discussion
Because pre-composed characters in aSet can match composed character sequences in the receiver, the length of the returned range can be greater than 1. For example, if you search for “ü” in the string “stru¨del”, the returned range is {3,2}.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfComposedCharacterSequenceAtIndex:
Returns the range in the receiver of the composed character sequence located at a given index.
Parameters
- anIndex
The index of a character in the receiver. The value must not exceed the bounds of the receiver.
Return Value
The range in the receiver of the composed character sequence located at anIndex.
Discussion
The composed character sequence includes the first base character found at or before anIndex, and its length includes the base character and all non-base characters following the base character.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfComposedCharacterSequencesForRange:
Returns the range in the string of the composed character sequences for a given range.
Parameters
- range
A range in the receiver. The range must not exceed the bounds of the receiver.
Return Value
The range in the receiver that includes the composed character sequences in range.
Discussion
This method provides a convenient way to grow a range to include all composed character sequences it overlaps.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfString:
Finds and returns the range of the first occurrence of a given string within the receiver.
Parameters
- aString
The string to search for. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aString isnil.
Return Value
An NSRange structure giving the location and length in the receiver of the first occurrence of aString. Returns {NSNotFound, 0} if aString is not found or is empty (@"").
Discussion
Invokes rangeOfString:options: with no options.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfString:options:
Finds and returns the range of the first occurrence of a given string within the receiver, subject to given options.
Parameters
- aString
The string to search for. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aString isnil.- mask
A mask specifying search options. The following options may be specified by combining them with the C bitwise
ORoperator:NSCaseInsensitiveSearch,NSLiteralSearch,NSBackwardsSearch,NSAnchoredSearch. See String Programming Guide for details on these options.
Return Value
An NSRange structure giving the location and length in the receiver of the first occurrence of aString, modulo the options in mask. Returns {NSNotFound, 0} if aString is not found or is empty (@"").
Discussion
Invokes rangeOfString:options:range: with the options specified by mask and the entire extent of the receiver as the range.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfString:options:range:
Finds and returns the range of the first occurrence of a given string, within the given range of the receiver, subject to given options.
Parameters
- aString
The string for which to search. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aString isnil.- mask
A mask specifying search options. The following options may be specified by combining them with the C bitwise
ORoperator:NSCaseInsensitiveSearch,NSLiteralSearch,NSBackwardsSearch, andNSAnchoredSearch. See String Programming Guide for details on these options.- aRange
The range within the receiver for which to search for aString.
Important: Raises an
NSRangeExceptionif any part of aRange lies beyond the end of the string.
Return Value
An NSRange structure giving the location and length in the receiver of aString within aRange in the receiver, modulo the options in mask. The range returned is relative to the start of the string, not to the passed-in range. Returns {NSNotFound, 0} if aString is not found or is empty (@"").
Discussion
The length of the returned range and that of aString may differ if equivalent composed character sequences are matched.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hrangeOfString:options:range:locale:
Finds and returns the range of the first occurrence of a given string within a given range of the receiver, subject to given options, using the specified locale, if any.
Parameters
- aString
The string for which to search. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aString isnil.- mask
A mask specifying search options. The following options may be specified by combining them with the C bitwise
ORoperator:NSCaseInsensitiveSearch,NSLiteralSearch,NSBackwardsSearch, andNSAnchoredSearch. See String Programming Guide for details on these options.- aRange
The range within the receiver for which to search for aString.
Important: Raises an
NSRangeExceptionif any part of aRange lies beyond the end of the string.- locale
The locale to use when comparing the receiver with aString. If this value is
nil, uses the current locale.The locale argument affects the equality checking algorithm. For example, for the Turkish locale, case-insensitive compare matches “I” to “ı” (Unicode code point U+0131, Latin Small Dotless I), not the normal “i” character.
Return Value
An NSRange structure giving the location and length in the receiver of aString within aRange in the receiver, modulo the options in mask. The range returned is relative to the start of the string, not to the passed-in range. Returns {NSNotFound, 0} if aString is not found or is empty (@"").
Discussion
The length of the returned range and that of aString may differ if equivalent composed character sequences are matched.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hsmallestEncoding
Returns the smallest encoding to which the receiver can be converted without loss of information.
Return Value
The smallest encoding to which the receiver can be converted without loss of information.
Discussion
The returned encoding may not be the fastest for accessing characters, but is space-efficient. This method may take some time to execute.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringByAbbreviatingWithTildeInPath
Returns a new string representing the receiver as a path with a tilde (~) substituted for the full path to the current user’s home directory.
Return Value
A new string representing the receiver as a path with a tilde (~) substituted for the full path to the current user’s home directory. Returns a new string matching the receiver if the receiver doesn’t begin with a user’s home directory.
Discussion
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSPathUtilities.hstringByAddingPercentEscapesUsingEncoding:
Returns a representation of the receiver using a given encoding to determine the percent escapes necessary to convert the receiver into a legal URL string.
Parameters
- encoding
The encoding to use for the returned string. If you are uncertain of the correct encoding you should use
NSUTF8StringEncoding.
Return Value
A representation of the receiver using encoding to determine the percent escapes necessary to convert the receiver into a legal URL string. Returns nil if encoding cannot encode a particular character.
Discussion
It may be difficult to use this function to "clean up" unescaped or partially escaped URL strings where sequences are unpredictable. See CFURLCreateStringByAddingPercentEscapes for more information.
Availability
- Available in iOS 2.0 and later.
Declared In
NSURL.hstringByAppendingFormat:
Returns a string made by appending to the receiver a string constructed from a given format string and the following arguments.
Parameters
- format
A format string. See “Formatting String Objects” for more information. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif format isnil.- ...
A comma-separated list of arguments to substitute into format.
Return Value
A string made by appending to the receiver a string constructed from format and the following arguments, in the manner of stringWithFormat:.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringByAppendingPathComponent:
Returns a new string made by appending to the receiver a given string.
Parameters
- aString
The path component to append to the receiver.
Return Value
A new string made by appending aString to the receiver, preceded if necessary by a path separator.
Discussion
The following table illustrates the effect of this method on a variety of different paths, assuming that aString is supplied as “scratch.tiff”:
Receiver’s String Value |
Resulting String |
|---|---|
“ |
“ |
“ |
“ |
“ |
“ |
“” (an empty string) |
“ |
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSPathUtilities.hstringByAppendingPathExtension:
Returns a new string made by appending to the receiver an extension separator followed by a given extension.
Parameters
- ext
The extension to append to the receiver.
Return Value
A new string made by appending to the receiver an extension separator followed by ext.
Discussion
The following table illustrates the effect of this method on a variety of different paths, assuming that ext is supplied as @"tiff":
Receiver’s String Value |
Resulting String |
|---|---|
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
Note that adding an extension to @"/tmp/" causes the result to be @"/tmp.tiff" instead of @"/tmp/.tiff". This difference is because a file named @".tiff" is not considered to have an extension, so the string is appended to the last nonempty path component.
This method does not allow you to append file extensions to filenames starting with the tilde character (~).
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hstringByAppendingString:
Returns a new string made by appending a given string to the receiver.
Parameters
- aString
The string to append to the receiver. This value must not be
nil.Important: Raises an
NSInvalidArgumentExceptionif aString isnil.
Return Value
A new string made by appending aString to the receiver.
Discussion
This code excerpt, for example:
NSString *errorTag = @"Error: "; |
NSString *errorString = @"premature end of file."; |
NSString *errorMessage = [errorTag stringByAppendingString:errorString]; |
produces the string “Error: premature end of file.”.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringByDeletingLastPathComponent
Returns a new string made by deleting the last path component from the receiver, along with any final path separator.
Return Value
A new string made by deleting the last path component from the receiver, along with any final path separator. If the receiver represents the root path it is returned unaltered.
Discussion
The following table illustrates the effect of this method on a variety of different paths:
Receiver’s String Value |
Resulting String |
|---|---|
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“” (an empty string) |
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hstringByDeletingPathExtension
Returns a new string made by deleting the extension (if any, and only the last) from the receiver.
Return Value
a new string made by deleting the extension (if any, and only the last) from the receiver. Strips any trailing path separator before checking for an extension. If the receiver represents the root path, it is returned unaltered.
Discussion
The following table illustrates the effect of this method on a variety of different paths:
Receiver’s String Value |
Resulting String |
|---|---|
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
“ |
Note that attempting to delete an extension from @".tiff" causes the result to be @".tiff" instead of an empty string. This difference is because a file named @".tiff" is not considered to have an extension, so nothing is deleted. Note also that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hstringByExpandingTildeInPath
Returns a new string made by expanding the initial component of the receiver to its full path value.
Return Value
A new string made by expanding the initial component of the receiver, if it begins with “~” or “~user”, to its full path value. Returns a new string matching the receiver if the receiver’s initial component can’t be expanded.
Discussion
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hstringByFoldingWithOptions:locale:
Returns a string with the given character folding options applied.
Parameters
- options
A mask of compare flags with a suffix
InsensitiveSearch.- locale
The locale to use for the folding. The locale affects the folding logic. For example, for the Turkish locale, case-insensitive compare matches “I” to “ı” (Unicode code point U+0131, Latin Small Dotless I), not the normal “i” character.
Return Value
A string with the character folding options applied.
Discussion
Character folding operations remove distinctions between characters. For example, case folding may replace uppercase letters with their lowercase equivalents.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringByPaddingToLength:withString:startingAtIndex:
Returns a new string formed from the receiver by either removing characters from the end, or by appending as many occurrences as necessary of a given pad string.
Parameters
- newLength
The new length for the receiver.
- padString
The string with which to extend the receiver.
- padIndex
The index in padString from which to start padding.
Return Value
A new string formed from the receiver by either removing characters from the end, or by appending as many occurrences of padString as necessary.
Discussion
Here are some examples of usage:
[@"abc" stringByPaddingToLength: 9 withString: @"." startingAtIndex:0]; |
// Results in "abc......" |
[@"abc" stringByPaddingToLength: 2 withString: @"." startingAtIndex:0]; |
// Results in "ab" |
[@"abc" stringByPaddingToLength: 9 withString: @". " startingAtIndex:1]; |
// Results in "abc . . ." |
// Notice that the first character in the padding is " " |
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringByReplacingCharactersInRange:withString:
Returns a new string in which the characters in a specified range of the receiver are replaced by a given string.
Parameters
- range
A range of characters in the receiver.
- replacement
The string with which to replace the characters in range.
Return Value
A new string in which the characters in range of the receiver are replaced by replacement.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringByReplacingOccurrencesOfString:withString:
Returns a new string in which all occurrences of a target string in the receiver are replaced by another given string.
Parameters
- target
The string to replace.
- replacement
The string with which to replace target.
Return Value
A new string in which all occurrences of target in the receiver are replaced by replacement.
Discussion
Invokes stringByReplacingOccurrencesOfString:withString:options:range:with 0 options and range of the whole string.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringByReplacingOccurrencesOfString:withString:options:range:
Returns a new string in which all occurrences of a target string in a specified range of the receiver are replaced by another given string.
Parameters
- target
The string to replace.
- replacement
The string with which to replace target.
- options
A mask of options to use when comparing target with the receiver. Pass
0to specify no options.- searchRange
The range in the receiver in which to search for target.
Return Value
A new string in which all occurrences of target, matched using options, in searchRange of the receiver are replaced by replacement.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hstringByReplacingPercentEscapesUsingEncoding:
Returns a new string made by replacing in the receiver all percent escapes with the matching characters as determined by a given encoding.
Parameters
- encoding
The encoding to use for the returned string.
Return Value
A new string made by replacing in the receiver all percent escapes with the matching characters as determined by the given encoding encoding. Returns nil if the transformation is not possible, for example, the percent escapes give a byte sequence not legal in encoding.
Discussion
See CFURLCreateStringByReplacingPercentEscapes for more complex transformations.
Availability
- Available in iOS 2.0 and later.
Declared In
NSURL.hstringByResolvingSymlinksInPath
Returns a new string made from the receiver by resolving all symbolic links and standardizing path.
Return Value
A new string made by expanding an initial tilde expression in the receiver, then resolving all symbolic links and references to current or parent directories if possible, to generate a standardized path. If the original path is absolute, all symbolic links are guaranteed to be removed; if it’s a relative path, symbolic links that can’t be resolved are left unresolved in the returned string. Returns self if an error occurs.
Discussion
If the name of the receiving path begins with /private, the stringByResolvingSymlinksInPath method strips off the /private designator, provided the result is the name of an existing file.
Note that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hstringByStandardizingPath
Returns a new string made by removing extraneous path components from the receiver.
Return Value
A new string made by removing extraneous path components from the receiver.
Discussion
If an invalid pathname is provided, stringByStandardizingPath may attempt to resolve it by calling stringByResolvingSymlinksInPath, and the results are undefined. If any other kind of error is encountered (such as a path component not existing), self is returned.
This method can make the following changes in the provided string:
Expand an initial tilde expression using
stringByExpandingTildeInPath.Reduce empty components and references to the current directory (that is, the sequences “//” and “/./”) to single path separators.
In absolute paths only, resolve references to the parent directory (that is, the component “..”) to the real parent directory if possible using
stringByResolvingSymlinksInPath, which consults the file system to resolve each potential symbolic link.In relative paths, because symbolic links can’t be resolved, references to the parent directory are left in place.
Remove an initial component of “
/private” from the path if the result still indicates an existing file or directory (checked by consulting the file system).
Note that the path returned by this method may still have symbolic link components in it. Note also that this method only works with file paths (not, for example, string representations of URLs).
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hstringByTrimmingCharactersInSet:
Returns a new string made by removing from both ends of the receiver characters contained in a given character set.
Parameters
- set
A character set containing the characters to remove from the receiver. set must not be
nil.
Return Value
A new string made by removing from both ends of the receiver characters contained in set. If the receiver is composed entirely of characters from set, the empty string is returned.
Discussion
Use whitespaceCharacterSet or whitespaceAndNewlineCharacterSet to remove whitespace around strings.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hstringsByAppendingPaths:
Returns an array of strings made by separately appending to the receiver each string in in a given array.
Parameters
- paths
An array of
NSStringobjects specifying paths to add to the receiver.
Return Value
An array of NSString objects made by separately appending each string in paths to the receiver, preceded if necessary by a path separator.
Discussion
Note that this method only works with file paths (not, for example, string representations of URLs). See stringByAppendingPathComponent: for an individual example.
Availability
- Available in iOS 2.0 and later.
Declared In
NSPathUtilities.hsubstringFromIndex:
Returns a new string containing the characters of the receiver from the one at a given index to the end.
Parameters
- anIndex
An index. The value must lie within the bounds of the receiver, or be equal to the length of the receiver.
Important: Raises an
NSRangeExceptionif anIndex lies beyond the end of the receiver.
Return Value
A new string containing the characters of the receiver from the one at anIndex to the end. If anIndex is equal to the length of the string, returns an empty string.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.hsubstringToIndex:
Returns a new string containing the characters of the receiver up to, but not including, the one at a given index.
Parameters
- anIndex
An index. The value must lie within the bounds of the receiver, or be equal to the length of the receiver.
Important: Raises an
NSRangeExceptionif (anIndex - 1) lies beyond the end of the receiver.
Return Value
A new string containing the characters of the receiver up to, but not including, the one at anIndex. If anIndex is equal to the length of the string, returns a copy of the receiver.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hsubstringWithRange:
Returns a string object containing the characters of the receiver that lie within a given range.
Parameters
- aRange
A range. The range must not exceed the bounds of the receiver.
Important: Raises an
NSRangeExceptionif any part of aRange lies beyond the end of the receiver.
Return Value
A string object containing the characters of the receiver that lie within aRange.
Discussion
This method treats the length of the string as a valid range value that returns an empty string.
This method detects all invalid ranges (including those with negative lengths). For applications linked against OS X v10.6 and later, this error causes an exception; for applications linked against earlier releases, this error causes a warning, which is displayed just once per application execution.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
NSString.huppercaseString
Returns an uppercased representation of the receiver.
Return Value
A string with each character from the receiver changed to its corresponding uppercase value.
Discussion
Case transformations aren’t guaranteed to be symmetrical or to produce strings of the same lengths as the originals. See lowercaseString for an example.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.huppercaseStringWithLocale:
Returns uppercased representation of the receiver with the specified locale.
Parameters
- locale
The locale. Passing
nilindicates the canonical mapping.
Return Value
An uppercase string using the locale.
Discussion
For the user preference locale setting, pass the result of the NSLocale method currentLocale.
Availability
- Available in iOS 6.0 and later.
Declared In
NSString.hUTF8String
Returns a null-terminated UTF8 representation of the receiver.
Return Value
A null-terminated UTF8 representation of the receiver.
Discussion
The returned C string is automatically freed just as a returned object would be released; you should copy the C string if it needs to store it outside of the autorelease context in which the C string is created.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hwriteToFile:atomically:encoding:error:
Writes the contents of the receiver to a file at a given path using a given encoding.
Parameters
- path
The file to which to write the receiver. If path contains a tilde (
~) character, you must expand it withstringByExpandingTildeInPathbefore invoking this method.- useAuxiliaryFile
If
YES, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to path. IfNO, the receiver is written directly to path. TheYESoption guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.- enc
The encoding to use for the output.
- error
If there is an error, upon return contains an
NSErrorobject that describes the problem. If you are not interested in details of errors, you may pass inNULL.
Return Value
YES if the file is written successfully, otherwise NO (if there was a problem writing to the file or with the encoding).
Discussion
This method overwrites any existing file at path.
This method stores the specified encoding with the file in an extended attribute under the name com.apple.TextEncoding. The value contains the IANA name for the encoding and the CFStringEncoding value for the encoding, separated by a semicolon. The CFStringEncoding value is written as an ASCII string containing an unsigned 32-bit decimal integer and is not terminated by a null character. One or both of these values may be missing. Examples of the value written include the following:
MACINTOSH;0 |
UTF-8;134217984 |
UTF-8; |
;3071 |
The methods initWithContentsOfFile:usedEncoding:error:, initWithContentsOfURL:usedEncoding:error:, stringWithContentsOfFile:usedEncoding:error:, and stringWithContentsOfURL:usedEncoding:error: use this information to open the file using the right encoding.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hwriteToURL:atomically:encoding:error:
Writes the contents of the receiver to the URL specified by url using the specified encoding.
Parameters
- url
The URL to which to write the receiver.
- useAuxiliaryFile
If
YES, the receiver is written to an auxiliary file, and then the auxiliary file is renamed to url. IfNO, the receiver is written directly to url. TheYESoption guarantees that url, if it exists at all, won’t be corrupted even if the system should crash during writing.The useAuxiliaryFile parameter is ignored if url is not of a type that can be accessed atomically.
- enc
The encoding to use for the output.
- error
If there is an error, upon return contains an
NSErrorobject that describes the problem. If you are not interested in details of errors, you may pass inNULL.
Return Value
YES if the URL is written successfully, otherwise NO (if there was a problem writing to the URL or with the encoding).
Discussion
This method stores the specified encoding with the file in an extended attribute under the name com.apple.TextEncoding. The value contains the IANA name for the encoding and the CFStringEncoding value for the encoding, separated by a semicolon. The CFStringEncoding value is written as an ASCII string containing an unsigned 32-bit decimal integer and is not terminated by a null character. One or both of these values may be missing. Examples of the value written include the following:
MACINTOSH;0 |
UTF-8;134217984 |
UTF-8; |
;3071 |
The methods initWithContentsOfFile:usedEncoding:error:, initWithContentsOfURL:usedEncoding:error:, stringWithContentsOfFile:usedEncoding:error:, and stringWithContentsOfURL:usedEncoding:error: use this information to open the file using the right encoding.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hConstants
unichar
Type for Unicode characters.
typedef unsigned short unichar;
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hNSMaximumStringLength
A constant to define the maximum number of characters in an NSString object. (Deprecated. This constant is not available in OS X v10.5 and later.)
#define NSMaximumStringLength (INT_MAX-1)
Constants
NSMaximumStringLengthMaximum number of characters in an
NSStringobject.Available in iOS 5.0 and later.
Declared in
NSString.h.
Availability
- Available in OS X v10.0.
- Removed in OS X v10.5.
Declared In
NSString.hNSStringCompareOptions
Type for string comparison options.
typedef NSUInteger NSStringCompareOptions;
Discussion
See “Search and Comparison Options” for possible values.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hSearch and Comparison Options
These values represent the options available to many of the string classes’ search and comparison methods.
enum {
NSCaseInsensitiveSearch = 1,
NSLiteralSearch = 2,
NSBackwardsSearch = 4,
NSAnchoredSearch = 8,
NSNumericSearch = 64,
NSDiacriticInsensitiveSearch = 128,
NSWidthInsensitiveSearch = 256,
NSForcedOrderingSearch = 512,
NSRegularExpressionSearch = 1024
};
Constants
NSCaseInsensitiveSearchA case-insensitive search.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSLiteralSearchExact character-by-character equivalence.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSBackwardsSearchSearch from end of source string.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSAnchoredSearchSearch is limited to start (or end, if
NSBackwardsSearch) of source string.Available in iOS 2.0 and later.
Declared in
NSString.h.NSNumericSearchNumbers within strings are compared using numeric value, that is,
Name2.txt<Name7.txt<Name25.txt.This option only applies to compare methods, not find.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSDiacriticInsensitiveSearchSearch ignores diacritic marks.
For example, ‘ö’ is equal to ‘o’.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSWidthInsensitiveSearchSearch ignores width differences in characters that have full-width and half-width forms, as occurs in East Asian character sets.
For example, with this option, the full-width Latin small letter 'a' (Unicode code point U+FF41) is equal to the basic Latin small letter 'a' (Unicode code point U+0061).
Available in iOS 2.0 and later.
Declared in
NSString.h.NSForcedOrderingSearchComparisons are forced to return either
NSOrderedAscendingorNSOrderedDescendingif the strings are equivalent but not strictly equal.This option gives stability when sorting. For example, “aaa” is greater than "AAA” if
NSCaseInsensitiveSearchis specified.Available in iOS 2.0 and later.
Declared in
NSString.h.NSRegularExpressionSearchThe search string is treated as an ICU-compatible regular expression. If set, no other options can apply except
NSCaseInsensitiveSearchandNSAnchoredSearch. You can use this option only with therangeOfString:...methods andstringByReplacingOccurrencesOfString:withString:options:range:.Available in iOS 3.2 and later.
Declared in
NSString.h.
Discussion
See “Searching, Comparing, and Sorting Strings” for details on the effects of these options.
Declared In
NSString.hNSStringEncodingConversionOptions
Type for encoding conversion options.
typedef NSUInteger NSStringEncodingConversionOptions;
Discussion
See “Encoding Conversion Options” for possible values.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hEncoding Conversion Options
Options for converting string encodings.
enum {
NSStringEncodingConversionAllowLossy = 1,
NSStringEncodingConversionExternalRepresentation = 2
};
Constants
NSStringEncodingConversionAllowLossyAllows lossy conversion.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSStringEncodingConversionExternalRepresentationSpecifies an external representation (with a byte-order mark, if necessary, to indicate endianness).
Available in iOS 2.0 and later.
Declared in
NSString.h.
Special Considerations
These constants are available in OS X v10.4; they are, however, differently named:
typedef enum { |
NSAllowLossyEncodingConversion = 1, |
NSExternalRepresentationEncodingConversion = 2 |
} NSStringEncodingConversionOptions; |
You can use them on OS X v10.4 if you define the symbols as extern constants.
Declared In
NSString.hNSString Handling Exception Names
These constants define the names of exceptions raised if NSString cannot represent a string in a given encoding, or parse a string as a property list.
extern NSString *NSParseErrorException; extern NSString *NSCharacterConversionException;
Constants
NSCharacterConversionExceptionNSStringraises anNSCharacterConversionExceptionif a string cannot be represented in a file-system or string encoding.Available in iOS 2.0 and later.
Declared in
NSString.h.NSParseErrorExceptionNSStringraises anNSParseErrorExceptionif a string cannot be parsed as a property list.Available in iOS 2.0 and later.
Declared in
NSString.h.
Declared In
NSString.hNSStringEncoding
Type for string encoding.
typedef NSUInteger NSStringEncoding;
Discussion
See “String Encodings” for possible values.
Availability
- Available in iOS 2.0 and later.
Declared In
NSString.hString Encodings
The following constants are provided by NSString as possible string encodings.
enum {
NSASCIIStringEncoding = 1,
NSNEXTSTEPStringEncoding = 2,
NSJapaneseEUCStringEncoding = 3,
NSUTF8StringEncoding = 4,
NSISOLatin1StringEncoding = 5,
NSSymbolStringEncoding = 6,
NSNonLossyASCIIStringEncoding = 7,
NSShiftJISStringEncoding = 8,
NSISOLatin2StringEncoding = 9,
NSUnicodeStringEncoding = 10,
NSWindowsCP1251StringEncoding = 11,
NSWindowsCP1252StringEncoding = 12,
NSWindowsCP1253StringEncoding = 13,
NSWindowsCP1254StringEncoding = 14,
NSWindowsCP1250StringEncoding = 15,
NSISO2022JPStringEncoding = 21,
NSMacOSRomanStringEncoding = 30,
NSUTF16StringEncoding = NSUnicodeStringEncoding,
NSUTF16BigEndianStringEncoding = 0x90000100,
NSUTF16LittleEndianStringEncoding = 0x94000100,
NSUTF32StringEncoding = 0x8c000100,
NSUTF32BigEndianStringEncoding = 0x98000100,
NSUTF32LittleEndianStringEncoding = 0x9c000100,
NSProprietaryStringEncoding = 65536
};
Constants
NSASCIIStringEncodingStrict 7-bit ASCII encoding within 8-bit chars; ASCII values 0…127 only.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSNEXTSTEPStringEncoding8-bit ASCII encoding with NEXTSTEP extensions.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSJapaneseEUCStringEncoding8-bit EUC encoding for Japanese text.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSUTF8StringEncodingAn 8-bit representation of Unicode characters, suitable for transmission or storage by ASCII-based systems.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSISOLatin1StringEncoding8-bit ISO Latin 1 encoding.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSSymbolStringEncoding8-bit Adobe Symbol encoding vector.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSNonLossyASCIIStringEncoding7-bit verbose ASCII to represent all Unicode characters.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSShiftJISStringEncoding8-bit Shift-JIS encoding for Japanese text.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSISOLatin2StringEncoding8-bit ISO Latin 2 encoding.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSUnicodeStringEncodingThe canonical Unicode encoding for string objects.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSWindowsCP1251StringEncodingMicrosoft Windows codepage 1251, encoding Cyrillic characters; equivalent to AdobeStandardCyrillic font encoding.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSWindowsCP1252StringEncodingMicrosoft Windows codepage 1252; equivalent to WinLatin1.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSWindowsCP1253StringEncodingMicrosoft Windows codepage 1253, encoding Greek characters.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSWindowsCP1254StringEncodingMicrosoft Windows codepage 1254, encoding Turkish characters.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSWindowsCP1250StringEncodingMicrosoft Windows codepage 1250; equivalent to WinLatin2.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSISO2022JPStringEncodingISO 2022 Japanese encoding for email.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSMacOSRomanStringEncodingClassic Macintosh Roman encoding.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSUTF16StringEncodingAn alias for
NSUnicodeStringEncoding.Available in iOS 2.0 and later.
Declared in
NSString.h.NSUTF16BigEndianStringEncodingNSUTF16StringEncodingencoding with explicit endianness specified.Available in iOS 2.0 and later.
Declared in
NSString.h.NSUTF16LittleEndianStringEncodingNSUTF16StringEncodingencoding with explicit endianness specified.Available in iOS 2.0 and later.
Declared in
NSString.h.NSUTF32StringEncoding32-bit UTF encoding.
Available in iOS 2.0 and later.
Declared in
NSString.h.NSUTF32BigEndianStringEncodingNSUTF32StringEncodingencoding with explicit endianness specified.Available in iOS 2.0 and later.
Declared in
NSString.h.NSUTF32LittleEndianStringEncodingNSUTF32StringEncodingencoding with explicit endianness specified.Available in iOS 2.0 and later.
Declared in
NSString.h.NSProprietaryStringEncodingInstallation-specific encoding. (Deprecated. This encoding has been deprecated—there is no replacement.)
Proprietary encodings have not been used since OS X v10.0. You should specify a standard encoding instead.
Available in iOS 5.0 and later.
Declared in
NSString.h.
Discussion
These values represent the various character encodings supported by the NSString classes. This is an incomplete list. Additional encodings are defined in String Programming Guide for Core Foundation (see CFStringEncodingExt.h); these encodings can be used with NSString by first passing the Core Foundation encoding to the CFStringConvertEncodingToNSStringEncoding function.
String Enumeration Options
Constants to specify kinds of substrings and styles of enumeration.
typedef NSUInteger NSStringEnumerationOptions;
enum {
NSStringEnumerationByLines = 0,
NSStringEnumerationByParagraphs = 1,
NSStringEnumerationByComposedCharacterSequences = 2,
NSStringEnumerationByWords = 3,
NSStringEnumerationBySentences = 4,
NSStringEnumerationReverse = 1UL << 8,
NSStringEnumerationSubstringNotRequired = 1UL << 9,
NSStringEnumerationLocalized = 1UL << 10
};
Constants
NSStringEnumerationByLinesEnumerates by lines. Equivalent to
lineRangeForRange:.Available in iOS 4.0 and later.
Declared in
NSString.h.NSStringEnumerationByParagraphsEnumerates by paragraphs. Equivalent to
paragraphRangeForRange:.Available in iOS 4.0 and later.
Declared in
NSString.h.NSStringEnumerationByComposedCharacterSequencesEnumerates by composed character sequences. Equivalent to
rangeOfComposedCharacterSequencesForRange:.Available in iOS 4.0 and later.
Declared in
NSString.h.NSStringEnumerationByWordsEnumerates by words.
Available in iOS 4.0 and later.
Declared in
NSString.h.NSStringEnumerationBySentencesEnumerates by sentences.
Available in iOS 4.0 and later.
Declared in
NSString.h.NSStringEnumerationReverseCauses enumeration to occur from the end of the specified range to the start.
Available in iOS 4.0 and later.
Declared in
NSString.h.NSStringEnumerationSubstringNotRequiredA way to indicate that the block does not need substring, in which case nil will be passed. This is simply a performance shortcut.
Available in iOS 4.0 and later.
Declared in
NSString.h.NSStringEnumerationLocalizedCauses the enumeration to occur using user's default locale. This does not make a difference in line, paragraph, or composed character sequence enumeration, but it may for words or sentences.
Available in iOS 4.0 and later.
Declared in
NSString.h.
Discussion
These options are used with the enumerateSubstringsInRange:options:usingBlock: method. Pass in one NSStringEnumerationBy... option and combine with any of the remaining enumeration style constants using the C bitwise OR operator.
© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-01-28)