Wednesday, 4 January 2017

NSString and NSMutableString -Text handling tools

Written by   on   in , , , , , ,   with 2 comments
Hello Friends,

We have covered Classes and objects concepts in my last post. We have seen how classes and objects
are created, how we define and use methods, their syntaxes etc.

Today we are going to see the most widely used Classes for text handling  in Objective- C i.e. NSString and NSMutableString.

1. NSString :

NSString is the basic tool or class which we use while dealing with text in objective-c. This class provides number of APIs for string operations such as comparison, matching modification etc.

How to create NSString ?

The simplest way to create a string is by using string literal .

e.g
NSString *myBlogName  =  @"All About iOS Development";

Though this is the simplest way to create NSString, we extensively use stringWithFormat: to declare a string which is composed of variable values.

e.g
NSString *user = @"Vishal Sonawane";
int birthYear = 1992;
NSString *greetings = [NSString stringWithFormat:@"Hello%@ , your birth year is %d!",
                     user, birthYear];
NSLog(@"%@", greetings);

Below is the list of all NSString APIs , taken from Apple documentation. They all are very well explained. You can go through those APIs to get in depth working.




All NSString APIs+

Returns an empty string.
- init
Returns an initialized NSString object that 
contains no characters.
- initWithBytes:length:encoding:
Returns an initialized NSString object containing a given number 
of bytes from a given buffer of bytes interpreted in a given encoding.
- initWithBytesNoCopy: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.
- initWithCharacters:length:
Returns an initialized NSString object that contains a given 
number of characters from a given C array of UTF-16 code units.
- initWithCharactersNoCopy:length:freeWhenDone:
Returns an initialized NSString object that contains a given 
number of characters from a given C array of UTF-16 code units.
- initWithString:
Returns an NSString object initialized by copying the 
characters from another given string.
- initWithCString:encoding:
Returns an NSString object initialized using the characters in 
a given C array, interpreted according to a given encoding.
- initWithUTF8String:
Returns an NSString object initialized by copying the 
characters from a given C array of UTF8-encoded bytes.
- initWithFormat:
Returns an NSString object initialized by using a given 
format string as a template into which the remaining 
argument values are substituted.
- initWithFormat:arguments:
Returns an NSString object initialized by using a given 
format string as a template into which the remaining 
rgument values are substituted without any localization.
 This method is meant to be called from within a variadic function, 
where the argument list will be available.
- initWithFormat: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.
- initWithFormat: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. This method is meant to 
be called from within a variadic function, where 
the argument list will be available.
- initWithData:encoding:
Returns an NSString object initialized by 
converting given data into UTF-16 code units 
using a given encoding.
+ stringWithFormat:
Returns a string created by using a given format 
string as a template into which the remaining 
argument values are substituted.
+ localizedStringWithFormat:
Returns a string created by using a given format 
string as a template into which the remaining argument 
values are substituted according to the current locale.
+ localizedUserNotificationStringForKey:arguments:
Returns a localized string intended for display
 in a notification alert.
+ stringWithCharacters:length:
Returns a string containing a given number of 
characters taken from a given C array of UTF-16 code units.
+ stringWithString:
Returns a string created by copying the characters 
from another given string.
+ stringWithCString:encoding:
Returns a string containing the bytes in a given 
C array, interpreted according to a given encoding.
+ stringWithUTF8String:
Returns a string created by copying the data 
from a given C array of UTF8-encoded bytes.

+

Returns a string created by reading data from 
the file at a given path interpreted using a given encoding.
- initWithContentsOfFile:encoding:error:
Returns an NSString object initialized by reading 
data from the file at a given path using a given encoding.
+ stringWithContentsOfFile: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.
- initWithContentsOfFile: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.

+ stringWithContentsOfURL:encoding:error:
Returns a string created by reading data from a 
given URL interpreted using a given encoding.
- initWithContentsOfURL:encoding:error:
Returns an NSString object initialized by reading 
data from a given URL interpreted using a given encoding.
+ stringWithContentsOfURL:usedEncoding:error:
Returns a string created by reading data from a given 
URL and returns by reference the encoding used to interpret the data.
- initWithContentsOfURL: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.

- writeToFile:atomically:encoding:error:
Writes the contents of the receiver to a file at a 
given path using a given encoding.
- writeToURL:atomically:encoding:error:
Writes the contents of the receiver to the URL 
specified by url using the specified encoding.

length
The number of UTF-16 code units in the receiver.
- lengthOfBytesUsingEncoding:
Returns the number of bytes required to store 
the receiver in a given encoding.
- maximumLengthOfBytesUsingEncoding:
Returns the maximum number of bytes needed 
to store the receiver in a given encoding.

- characterAtIndex:
Returns the character at a given UTF-16 
code unit index.
- getCharacters:range:
Copies characters from a given range in the 
receiver into a given buffer.
- getBytes:maxLength:usedLength:encoding:options
:range:remainingRange:
Gets a given range of characters as bytes in a specified encoding.

- cStringUsingEncoding:
Returns a representation of the receiver as a C 
string using a given encoding.
- getCString:maxLength:encoding:
Converts the receiver’s content to a given 
encoding and stores them in a buffer.
UTF8String
A null-terminated UTF8 representation of the string.

- caseInsensitiveCompare:
Returns the result of invoking compare:options: with 
NSCaseInsensitiveSearch as the only option.
- localizedCaseInsensitiveCompare:
Compares the string with a given string using a 
case-insensitive, localized, comparison.
- compare:
Returns the result of invoking compare:options:range: with 
no options and the receiver’s full extent as the range.
- localizedCompare:
Compares the string and a given string using a 
localized comparison.
- compare:options:
Compares the string with the specified string 
using the given options.
- compare:options:range:
Returns the result of invoking 
compare:options:range:locale: with a nil locale.
- compare:options:range:locale:
Compares the string using the specified options 
and returns the lexical ordering for the range.
- localizedStandardCompare:
Compares strings as sorted by the Finder.
- hasPrefix:
Returns a Boolean value that indicates whether a 
given string matches the beginning characters 
of the receiver.
- hasSuffix:
Returns a Boolean value that indicates whether a 
given string matches the ending characters 
of the receiver.
- isEqualToString:
Returns a Boolean value that indicates whether a 
given string is equal to the receiver using a literal 
Unicode-based comparison.
hash
An unsigned integer that can be 
used as a hash table address.

- stringByAppendingFormat:
Returns a string made by appending to the 
receiver a string constructed from a given 
format string and the following arguments.
- stringByAppendingString:
Returns a new string made by appending 
a given string to the receiver.
- stringByPaddingToLength: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.

- componentsSeparatedByString:
Returns an array containing substrings from the 
receiver that have been divided by a given separator.
- componentsSeparatedByCharactersInSet:
Returns an array containing substrings from the receiver 
that have been divided by characters in a given set.
- stringByTrimmingCharactersInSet:
Returns a new string made by removing from both ends 
of the receiver characters contained in a given character set.
- substringFromIndex:
Returns a new string containing the characters of the
 receiver from the one at a given index to the end.
- substringWithRange:
Returns a string object containing the characters 
of the receiver that lie within a given range.
- substringToIndex:
Returns a new string containing the characters of 
the receiver up to, but not including, the one at a given index.

- containsString:
Returns whether the receiver contains a given 
string by performing a case-sensitive, 
locale-unaware search.
- localizedCaseInsensitiveContainsString:
Returns whether the receiver contains a given 
string by performing a case-insensitive, 
locale-aware search.
- localizedStandardContainsString:
Returns whether the receiver contains a given
 string by performing a case and diacritic 
insensitive, locale-aware search.
- rangeOfCharacterFromSet:
Finds and returns the range in the receiver 
of the first character from a given character set.
- rangeOfCharacterFromSet:options:
Finds and returns the range in the receiver 
of the first character, using given options,
from a given character set.
- rangeOfCharacterFromSet: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.
- rangeOfString:
Finds and returns the range of the first 
occurrence of a given string within the receiver.
- rangeOfString:options:
Finds and returns the range of the first 
occurrence of a given string within the 
receiver, subject to given options.
- rangeOfString: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.
- rangeOfString: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.
- localizedStandardRangeOfString:
Finds and returns the range of the first occurrence 
of a given string within the receiver by performing 
a case and diacritic insensitive, locale-aware search.
- enumerateLinesUsingBlock:
Enumerates all the lines in a string.
- enumerateSubstringsInRange:options:usingBlock:
Enumerates the substrings of the specified 
type in the specified range of the string.

- stringByReplacingOccurrencesOfString:withString:
Returns a new string in which all occurrences 
of a target string in the receiver are replaced 
by another given string.
- stringByReplacingOccurrencesOfString: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.
- stringByReplacingCharactersInRange:withString:
Returns a new string in which the characters 
in a specified range of the receiver are replaced 
by a given string.

- getLineStart:end:contentsEnd:forRange:
Returns by reference the beginning of the first 
line and the end of the last line touched by the given range.
- lineRangeForRange:
Returns the range of characters representing 
the line or lines containing a given range.
- getParagraphStart:end:contentsEnd:forRange:
Returns by reference the beginning of the first 
paragraph and the end of the last paragraph touched 
by the given range.
- paragraphRangeForRange:
Returns the range of characters representing the 
paragraph or paragraphs containing a given range.

- rangeOfComposedCharacterSequenceAtIndex:
Returns the range in the receiver of the composed
 character sequence located at a given index.
- rangeOfComposedCharacterSequencesForRange:
Returns the range in the string of the composed 
character sequences for a given range.

- propertyList
Parses the receiver as a text representation 
of a property list, returning an NSString, NSData, 
NSArray, or NSDictionary object, according 
to the topmost element.
- propertyListFromStringsFileFormat
Returns a dictionary object initialized with 
the keys and values found in the receiver.

- drawAtPoint:withAttributes:
Draws the receiver with the font and other 
display characteristics of the given attributes, 
at the specified point in the current graphics context.
- drawInRect:withAttributes:
Draws the attributed string inside the specified 
bounding rectangle.
- drawWithRect:options:attributes:context:
Draws the attributed string in the specified 
bounding rectangle using the provided options.
- boundingRectWithSize:options:attributes:context:
Calculates and returns the bounding rect for 
the receiver drawn using the given options 
and display characteristics, within the specified 
rectangle in the current graphics context.
- sizeWithAttributes:
Returns the bounding box size the receiver 
occupies when drawn with the given attributes.

- stringByFoldingWithOptions:locale:
Returns a string with the given character 
folding options applied.

- commonPrefixWithString: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.

lowercaseString
A lowercase representation of the string.
localizedLowercaseString
Returns a version of the string with all 
etters converted to lowercase, taking into 
account the current locale.
- lowercaseStringWithLocale:
Returns a version of the string with all letters
 converted to lowercase, taking into account
 the specified locale.
uppercaseString
An uppercase representation of the string.
localizedUppercaseString
Returns a version of the string with all 
letters converted to uppercase, taking 
into account the current locale.
- uppercaseStringWithLocale:
Returns a version of the string with all 
letters converted to uppercase, taking 
into account the specified locale.
capitalizedString
A capitalized representation of the receiver.
localizedCapitalizedString
Returns a capitalized representation of 
the receiver using the current locale.
- capitalizedStringWithLocale:
Returns a capitalized representation of 
the receiver using the specified locale.

decomposedStringWithCanonicalMapping
A string made by normalizing the string’s 
contents using the Unicode Normalization Form D.
decomposedStringWithCompatibilityMapping
A string made by normalizing the receiver’s 
contents using the Unicode Normalization Form KD.
precomposedStringWithCanonicalMapping
A string made by normalizing the string’s 
contents using the Unicode Normalization Form C.
precomposedStringWithCompatibilityMapping
A string made by normalizing the receiver’s 
contents using the Unicode Normalization Form KC.

doubleValue
The floating-point value of the string as a double.
floatValue
The floating-point value of the string as a float.
intValue
The integer value of the string.
integerValue
The NSInteger value of the string.
longLongValue
The long long value of the string.
boolValue
The Boolean value of the string.

+ stringEncodingForData:encodingOptions:convertedString:usedLossyConversion:
Returns the string encoding for the given 
data as detected by attempting to create 
a string according to the specified encoding options.
+ localizedNameOfStringEncoding:
Returns a human-readable string giving the 
name of a given encoding.
- canBeConvertedToEncoding:
Returns a Boolean value that indicates whether 
the receiver can be converted to a given 
encoding without loss of information.
- dataUsingEncoding:
Returns an NSData object containing a 
representation of the receiver encoded using 
a given encoding.
- dataUsingEncoding:allowLossyConversion:
Returns an NSData object containing a 
representation of the receiver encoded 
using a given encoding.
description
This NSString object.
fastestEncoding
The fastest encoding to which the receiver 
may be converted without loss of information.
smallestEncoding
The smallest encoding to which the receiver 
can be converted without loss of information.

+ pathWithComponents:
Returns a string built from the strings in a given
 array by concatenating them with a path separator 
between each pair.
pathComponents
The file-system path components of the receiver.
- completePathIntoString: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.
fileSystemRepresentation
A file system-specific representation of the receiver.
- getFileSystemRepresentation: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.
absolutePath
A Boolean value that indicates whether the 
receiver represents an absolute path.
lastPathComponent
The last path component of the receiver.
pathExtension
The path extension, if any, of the string as 
interpreted as a path.
stringByAbbreviatingWithTildeInPath
A new string that replaces the current home 
directory portion of the current path with 
a tilde (~) character.
- stringByAppendingPathComponent:
Returns a new string made by appending to 
the receiver a given string.
- stringByAppendingPathExtension:
Returns a new string made by appending to 
the receiver an extension separator followed 
by a given extension.
stringByDeletingLastPathComponent
A new string made by deleting the last path 
component from the receiver, along with any 
final path separator.
stringByDeletingPathExtension
A new string made by deleting the extension 
(if any, and only the last) from the receiver.
stringByExpandingTildeInPath
A new string made by expanding the initial 
component of the receiver to its full path value.
stringByResolvingSymlinksInPath
A new string made from the receiver by
 resolving all symbolic links and standardizing path.
stringByStandardizingPath
A new string made by removing extraneous 
path components from the receiver.
- stringsByAppendingPaths:
Returns an array of strings made by separately 
appending to the receiver each string in in a given array.

- stringByAddingPercentEncodingWithAllowedCharacters:
Returns a new string made from the receiver by 
replacing all characters not in the specified set 
with percent encoded characters.
stringByRemovingPercentEncoding
Returns a new string made from the receiver by 
replacing all percent encoded sequences with the 
matching UTF-8 characters.

- enumerateLinguisticTagsInRange: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.
- linguisticTagsInRange:scheme:options:orthography:tokenRanges:
Returns an array of linguistic tags for the specified 
range and requested tags within the receiving string.
2. NSMutableString :

 This is the editable version of NSString. The word mutable means changeable. NSMutableString mean a string whose contents can be changed.

Below are all the NSMutableString APIs , listed from Apple Documentation.






+ stringWithCapacity:
Returns an empty NSMutableString object with
initial storage for a given number of characters.
- initWithCapacity:
Returns an NSMutableString object initialized with
 initial storage for a given number of characters,

- appendFormat:
Adds a constructed string to the receiver.
- appendString:
Adds to the end of the receiver the characters
of a given string.
- applyTransform:reverse:range:updatedRange:
Transliterates the receiver by applying a
specified ICU string transform.
- deleteCharactersInRange:
Removes from the receiver the characters in a given range.
- insertString:atIndex:
Inserts into the receiver the characters
of a given string at a given location.
- replaceCharactersInRange:withString:
Replaces the characters from aRange
with those in aString.
- replaceOccurrencesOfString:withString:options:range:
Replaces all occurrences of a given string
in a given range with another given string,
returning the number of replacements.
- setString:
Replaces the characters of the receiver
with those in a given string.

String Transformations
These constants specify transforms used
by the applyTransform:reverse:range:updatedRange:method.


--------------------------------------------------------------------------------------------------------------------------

NOTE: + and - symbols in from of the API describes if the API is class method or object method. + indicates for class method and - indicates for instance method. We will see these in depth in upcoming posts.

--------------------------------------------------------------------------------------------------------------------------

That's  all for today. Visit all the APIs to get familiar with them.

As a fun assignment, you can try :

1)  Counting number of occurrences of a character in a string.
2)  Matching provided string input with the string.
3)  Checking if a string is palindrome or not.
4)  Reversing the provided string.


Hope you will enjoy working with string functions. See you all in my next post. Till then......



Share:

2 comments: