/*! @header NSString+NDUtilities.h @abstract Defines the category NSString+NDUtilities @discussion Additonal useful methods for NSString, that can be used in general situations. Created by Nathan Day on Sun Dec 14 2003. Copyright © 2003 Nathan Day. All rights reserved. */ #import /*! @category NSString(NDUtilities) @abstract Addition methods for NSString @discussion Additonal useful methods for NSString, that can be used in general situations. see also NSString(NDContainsCharacterExtension), NSString(NDPathExtensions) and NSString(CarbonUtilitiesPaths). */ @interface NSString (NDUtilities) /*! @method stringWithNonLossyASCIIString: @abstract Create a NSString. @discussion Creates a NSString from NSNonLossyASCIIStringEncoding encoding, a 7-bit verbose ASCII to represent all Unicode characters @param ASCIIString A 7 bit ASCII string in NSNonLossyASCIIStringEncoding encoding. @result A new NSString */ + (id)stringWithNonLossyASCIIString:(const char *)ASCIIString; /*! @method stringWithFormat:arguments: @abstract Create a NSString. @discussion Creates a new string object, using format as a template into which the following argList values are substituted. Raises an NSInvalidArgumentException if format is nil. @param format The template string. @param argList The arguments to be inserted into format @result A new NSString */ + (id)stringWithFormat:(NSString *)format arguments:(va_list)argList; /*! @method initWithNonLossyASCIIString: @abstract Intialise a NSString. @discussion Initialises a NSString from NSNonLossyASCIIStringEncoding encoding, a 7-bit verbose ASCII to represent all Unicode characters. @param ASCIIString A 7 bit ASCII string in NSNonLossyASCIIStringEncoding encoding. @result A initialised NSString. */ - (id)initWithNonLossyASCIIString:(const char *)ASCIIString; /*! @method nonLossyASCIIString @abstract Get a 7 bit ASCII representation of a NSString containing Unicode characters. @discussion Returns a c string using NSNonLossyASCIIStringEncoding encoding, a 7-bit verbose ASCII to represent all Unicode characters. The returned C string will be automatically freed just as a returned object would be released; your code should copy the C string, if it needs to store the C string outside of the autorelease context in which the C string is created. @result A c string with NSNonLossyASCIIStringEncoding encoding. */ - (const char *)nonLossyASCIIString; /*! @method isCaseInsensitiveEqualToString: @abstract Test if a string is case insensitive equivelent. @discussion Returns YES if string is case insensitive equivalent to the receiver (if they have the same id or if they are NSOrderedSame in a litereral, case insensitive comparison), NO otherwise. . @param string The string to compare with. @result Returns YES string are equivelent NO. */ - (BOOL)isCaseInsensitiveEqualToString:(NSString *)string; /*! @method hasCaseInsensitivePrefix: @abstract Test prefix. @discussion Returns YES if string case insensitive matches the beginning characters of the receiver, NO otherwise. Returns NO if string is the nil string or empty. This method is a convenience for comparing strings using the NSAnchoredSearch option. See "Strings" for more information. @param string The string to check for. @result Returns YES if has case insensitive prefix string. */ - (BOOL)hasCaseInsensitivePrefix:(NSString *)string; /*! @method hasCaseInsensitiveSuffix: @abstract Test suffix. @discussion Returns YES if string case insensitive matches the ending characters of the receiver, NONOstring is the nil string or empty. This method is a convenience for comparing strings using the NSAnchoredSearch and NSBackwardsSearch options. See "Strings" for more information. @param string The string to check for. @result Returns YES if has case insensitive suffix string. */ - (BOOL)hasCaseInsensitiveSuffix:(NSString *)string; /*! @method containsString: @abstract Test if a string contains a substring. @discussion Invokes containsString:options: with no options. Raises an NSInvalidArgumentException if string is nil. @param subString The string to search for. @result Returns YES if substring found otherwise NO. */ - (BOOL)containsString:(NSString *)subString; /*! @method containsString:options: @abstract Test if a string contains a substring. @discussion Invokes containsString:options:range: with the options specified by mask and the entire extent of the receiver as the range. Raises an NSInvalidArgumentException if any of the arguments are nil. @param subString The string to search for. @param mask Mask values determining how to search. @result Returns YES if substring found otherwise NO. */ - (BOOL)containsString:(NSString *)subString options:(unsigned)mask; /*! @method containsString:options:range: @abstract Test if a string contains a substring. @discussion Returns YES if subString occurs within range in the receiver. If subString isn't found, returns a NO. The following options may be specified in mask by combining them with the C bitwise OR operator:
Search OptionEffect
NSCaseInsensitiveSearchIgnores case distinctions among characters.
NSLiteralSearchPerforms a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.
NSBackwardsSearchPerforms searching from the end of the range toward the beginning.
NSAnchoredSearchPerforms searching only on characters at the beginning or end of the range. No match at the beginning or end means nothing is found, even if a matching sequence of characters occurs elsewhere in the string.
Raises an NSRangeException if any part of range lies beyond the end of the string. @param subString The string to search for. @param mask Mask values determining how to search. @param range The range within the string to search. @result Returns YES if substring found otherwise NO. */ - (BOOL)containsString:(NSString *)subString options:(unsigned)mask range:(NSRange)range; /*! @method indexOfCharacter:range: @abstract Get the index of a character. @discussion Returns the index of the first occurance of the character character within the range range, if the receiver does not contain the character within the range then NSNotFound is return. @param character The character to look for. @param range The range to limit the search to. @result Returns the index of the character or NSNotFound if not found. */ - (unsigned int)indexOfCharacter:(unichar)character range:(NSRange)range; /*! @method indexOfCharacter: @abstract Get the index of a character. @discussion Returns the index of the first occurance of the character character, if the receiver does not contain the character then NSNotFound is return. @param character The character to look for. @result Returns the index of the character or NSNotFound if not found. */ - (unsigned int)indexOfCharacter:(unichar)character; /*! @method containsCharacter: @abstract Test if a string contains a character. @discussion Returns YES if the receiver contains the character character, otherwise returns NO. @param character The character to look for. @result Returns YES if the receiver contains the character. */ - (BOOL)containsCharacter:(unichar)character; /*! @method containsCharacter:range: @abstract Test if a string contains a character. @discussion Returns YES if the receiver contains the character character within the range range, otherwise returns NO. @param character The character to look for. @param range The range to limit the search to. @result Returns YES if the receiver contains the character. */ - (BOOL)containsCharacter:(unichar)character range:(NSRange)range; /*! @method containsAnyCharacterFromSet: @abstract Test if a string contains a character from a set. @discussion Returns YES if the receiver contains any character within set, otherwise returns NO. @param set The set of characters to look for. @result Returns YES if the receiver contains any of the characters. */ - (BOOL)containsAnyCharacterFromSet:(NSCharacterSet *)set; /*! @method containsAnyCharacterFromSet:options: @abstract Test if a string contains a character from a set. @discussion Returns YES if the receiver contains any character within set within the range range, otherwise returns NO. The following options may be specified in mask by combining them with the C bitwise OR operator:
Search Option Effect
NSCaseInsensitiveSearch Ignores case distinctions among characters.
NSLiteralSearch Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.
NSBackwardsSearch Performs searching from the end of the range toward the beginning.
See "Strings" for details on these options. Raises an NSInvalidArgumentException if any of the arguments are nil. @param set The set of characters to look for. @param mask Mask values determining how to search. @result Returns YES if the receiver contains any of the characters. */ - (BOOL)containsAnyCharacterFromSet:(NSCharacterSet *)set options:(unsigned int)mask; /*! @method containsAnyCharacterFromSet:options:range @abstract Test if a string contains a character from a set. @discussion Returns YES if the receiver contains any character within set within the range range, otherwise returns NO. The following options may be specified in mask by combining them with the C bitwise OR operator:
Search Option Effect
NSCaseInsensitiveSearch Ignores case distinctions among characters.
NSLiteralSearch Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.
NSBackwardsSearch Performs searching from the end of the range toward the beginning.
See "Strings" for details on these options. Raises an NSInvalidArgumentException if any of the arguments are nil. Raises an NSRangeException if any part of range lies beyond the end of the string. @param set The set of characters to look for. @param mask Mask values determining how to search. @param range The range to limit the search to. @result Returns YES if the receiver contains any of the characters. */ - (BOOL)containsAnyCharacterFromSet:(NSCharacterSet *)set options:(unsigned int)mask range:(NSRange)range; /*! @method containsOnlyCharactersFromSet: @abstract Test if a string contains only the characters from a set. @discussion Returns YES if the receiver contains only characters in set within set, otherwise returns NO. @param set The set of characters to look for. @result Returns YES if the receiver contains only the characters. */ - (BOOL)containsOnlyCharactersFromSet:(NSCharacterSet *)set; /*! @method containsOnlyCharactersFromSet:options: @abstract Test if a string contains only the characters from a set. @discussion Returns YES if the receiver contains only character from set, otherwise returns NO. The following options may be specified in mask by combining them with the C bitwise OR operator:
Search Option Effect
NSCaseInsensitiveSearch Ignores case distinctions among characters.
NSLiteralSearch Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.
NSBackwardsSearch Performs searching from the end of the range toward the beginning.
See "Strings" for details on these options. Raises an NSInvalidArgumentException if any of the arguments are nil. Raises an NSRangeException if any part of range lies beyond the end of the string. @param set The set of characters to look for. @param mask Mask values determining how to search. @result Returns YES if the receiver contains only the characters. */ - (BOOL)containsOnlyCharactersFromSet:(NSCharacterSet *)set options:(unsigned int)mask; /*! @method containsOnlyCharactersFromSet:options:range: @abstract Test if a string contains only the characters from a set. @discussion Returns YES if the receiver contains only character from set within the range range, otherwise returns NO. The following options may be specified in mask by combining them with the C bitwise OR operator:
Search Option Effect
NSCaseInsensitiveSearch Ignores case distinctions among characters.
NSLiteralSearch Performs a byte-for-byte comparison. Differing literal sequences (such as composed character sequences) that would otherwise be considered equivalent are considered not to match. Using this option can speed some operations dramatically.
NSBackwardsSearch Performs searching from the end of the range toward the beginning.
See "Strings" for details on these options. Raises an NSInvalidArgumentException if any of the arguments are nil. Raises an NSRangeException if any part of range lies beyond the end of the string. @param set The set of characters to look for. @param mask Mask values determining how to search. @param range The range to limit the search to. @result Returns YES if the receiver contains only the characters. */ - (BOOL)containsOnlyCharactersFromSet:(NSCharacterSet *)set options:(unsigned int)mask range:(NSRange)range; /*! @method componentsSeparatedByString:withOpeningQuote:closingQuote:singleQuote: @abstract Get an array of string componets. @discussion Returns an NSArray containing substrings from the receiver that have been divided by separator. The substrings in the array appear in the order they did in the receiver. @param separator The delimeter used to seperate the strings. @param openingQuote The string used to begin a quoted component, a component where the delimiter is ignored. @param closingQuote The string used to end a quoted component, a component where the delimiter is ignored. @param singleQuote The string used to quote a single character. @param flag Set to true if empty string are wanted. @result A NSArray of components. */ - (NSArray *)componentsSeparatedByString:(NSString *)separator withOpeningQuote:(NSString *)openingQuote closingQuote:(NSString *)closingQuote singleQuote:(NSString *)singleQuote includeEmptyComponents:(BOOL)flag; @end /*! @category NSMutableString(NDUtilities) @abstract Addition methods for NSString @discussion Additonal useful methods for NSMutableString, that can be used in general situations. */ @interface NSMutableString (NDUtilities) /*! @method prependString: @abstract Prepend a string. @discussion Adds the characters of string to the beginning of the receiver. string may not be nil. @param string The string to append. */ - (void)prependString:(NSString *)string; /*! @method prependFormat: @abstract Prepend a string format. @discussion Adds a constructed string to the beginning of the receiver. Creates the new string using NSString's stringWithFormat: method with the arguments listed. Raises an NSInvalidArgumentException if format is nil. @param format The format string to append, followed by values to insert. */ - (void)prependFormat:(NSString *)format, ...; @end