1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
/*!
@header NSString+NDUtilities.h
@abstract Defines the category <tt>NSString+NDUtilities</tt>
@discussion Additonal useful methods for <tt>NSString</tt>, that can be used in general situations.
Created by Nathan Day on Sun Dec 14 2003.
Copyright © 2003 Nathan Day. All rights reserved.
*/
#import <Foundation/Foundation.h>
/*!
@category NSString(NDUtilities)
@abstract Addition methods for <tt>NSString</tt>
@discussion Additonal useful methods for <tt>NSString</tt>, that can be used in general situations. see also NSString(NDContainsCharacterExtension), NSString(NDPathExtensions) and NSString(CarbonUtilitiesPaths).
*/
@interface NSString (NDUtilities)
/*!
@method stringWithNonLossyASCIIString:
@abstract Create a <tt>NSString</tt>.
@discussion Creates a <tt>NSString</tt> from <tt>NSNonLossyASCIIStringEncoding</tt> encoding, a 7-bit verbose ASCII to represent all Unicode characters
@param ASCIIString A 7 bit ASCII string in <tt>NSNonLossyASCIIStringEncoding</tt> encoding.
@result A new <tt>NSString</tt>
*/
+ (id)stringWithNonLossyASCIIString:(const char *)ASCIIString;
/*!
@method stringWithFormat:arguments:
@abstract Create a <tt>NSString</tt>.
@discussion Creates a new string object, using <tt><i>format</i></tt> as a template into which the following <tt><i>argList</i></tt> values are substituted. Raises an <tt>NSInvalidArgumentException</tt> if <tt><i>format</i></tt> is <tt>nil</tt>.
@param format The template string.
@param argList The arguments to be inserted into <tt><i>format</i></tt>
@result A new <tt>NSString</tt>
*/
+ (id)stringWithFormat:(NSString *)format arguments:(va_list)argList;
/*!
@method initWithNonLossyASCIIString:
@abstract Intialise a <tt>NSString</tt>.
@discussion Initialises a <tt>NSString</tt> from <tt>NSNonLossyASCIIStringEncoding</tt> encoding, a 7-bit verbose ASCII to represent all Unicode characters.
@param ASCIIString A 7 bit ASCII string in <tt>NSNonLossyASCIIStringEncoding</tt> encoding.
@result A initialised <tt>NSString</tt>.
*/
- (id)initWithNonLossyASCIIString:(const char *)ASCIIString;
/*!
@method nonLossyASCIIString
@abstract Get a 7 bit ASCII representation of a <tt>NSString</tt> containing Unicode characters.
@discussion Returns a c string using <tt>NSNonLossyASCIIStringEncoding</tt> 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 <tt>NSNonLossyASCIIStringEncoding</tt> encoding.
*/
- (const char *)nonLossyASCIIString;
/*!
@method isCaseInsensitiveEqualToString:
@abstract Test if a string is case insensitive equivelent.
@discussion Returns <tt>YES</tt> if string is case insensitive equivalent to the receiver (if they have the same <tt>id</tt> or if they are <tt>NSOrderedSame</tt> in a litereral, case insensitive comparison), <tt>NO</tt> otherwise. .
@param string The string to compare with.
@result Returns <tt>YES</tt> string are equivelent <tt>NO</tt>.
*/
- (BOOL)isCaseInsensitiveEqualToString:(NSString *)string;
/*!
@method hasCaseInsensitivePrefix:
@abstract Test prefix.
@discussion Returns <tt>YES</tt> if <tt><i>string</i></tt> case insensitive matches the beginning characters of the receiver, <tt>NO</tt> otherwise. Returns <tt>NO</tt> if <tt><i>string</i></tt> is the <tt>nil</tt> string or empty. This method is a convenience for comparing strings using the <tt>NSAnchoredSearch</tt> option. See "Strings" for more information.
@param string The string to check for.
@result Returns <tt>YES</tt> if has case insensitive prefix <tt><i>string</i></tt>.
*/
- (BOOL)hasCaseInsensitivePrefix:(NSString *)string;
/*!
@method hasCaseInsensitiveSuffix:
@abstract Test suffix.
@discussion Returns <tt>YES</tt> if <tt><i>string</i></tt> case insensitive matches the ending characters of the receiver, <tt>NO</tt otherwise. Returns <tt>NO</tt if <tt><i>string</i></tt> is the <tt>nil</tt> string or empty. This method is a convenience for comparing strings using the <tt>NSAnchoredSearch</tt> and <tt>NSBackwardsSearch</tt> options. See "Strings" for more information.
@param string The string to check for.
@result Returns <tt>YES</tt> if has case insensitive suffix <tt><i>string</i></tt>.
*/
- (BOOL)hasCaseInsensitiveSuffix:(NSString *)string;
/*!
@method containsString:
@abstract Test if a string contains a substring.
@discussion Invokes <tt>containsString:options:</tt> with no options. Raises an <tt>NSInvalidArgumentException</tt> if string is <tt>nil</tt>.
@param subString The string to search for.
@result Returns <tt>YES</tt> if substring found otherwise <tt>NO</tt>.
*/
- (BOOL)containsString:(NSString *)subString;
/*!
@method containsString:options:
@abstract Test if a string contains a substring.
@discussion Invokes <tt>containsString:options:range:</tt> with the options specified by <tt><i>mask</i></tt> and the entire extent of the receiver as the range. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>.
@param subString The string to search for.
@param mask Mask values determining how to search.
@result Returns <tt>YES</tt> if substring found otherwise <tt>NO</tt>.
*/
- (BOOL)containsString:(NSString *)subString options:(unsigned)mask;
/*!
@method containsString:options:range:
@abstract Test if a string contains a substring.
@discussion Returns <tt>YES</tt> if <tt><i>subString</i></tt> occurs within range in the receiver. If <tt><i>subString</i></tt> isn't found, returns a <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
<blockquote><table border = "1" width = "90%">
<thead><tr><th>Search Option</th><th>Effect</th></tr></thead>
<tr><td align = "center"><tt>NSCaseInsensitiveSearch</tt></td><td>Ignores case distinctions among characters.</td></tr>
<tr><td align = "center"><tt>NSLiteralSearch</tt></td><td>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.</td></tr>
<tr><td align = "center"><tt>NSBackwardsSearch</tt></td><td>Performs searching from the end of the range toward the beginning.</td></tr>
<tr><td align = "center"><tt>NSAnchoredSearch</tt></td><td>Performs 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.</td></tr>
</table ></blockquote >
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 <tt>YES</tt> if substring found otherwise <tt>NO</tt>.
*/
- (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 <tt><i>character</i></tt> within the range <tt><i>range</i></tt>, if the receiver does not contain the character within the range then <tt>NSNotFound</tt> 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 <tt>NSNotFound</tt> 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 <tt><i>character</i></tt>, if the receiver does not contain the character then <tt>NSNotFound</tt> is return.
@param character The character to look for.
@result Returns the index of the character or <tt>NSNotFound</tt> if not found.
*/
- (unsigned int)indexOfCharacter:(unichar)character;
/*!
@method containsCharacter:
@abstract Test if a string contains a character.
@discussion Returns <tt>YES</tt> if the receiver contains the character <tt><i>character</i></tt>, otherwise returns <tt>NO</tt>.
@param character The character to look for.
@result Returns <tt>YES</tt> if the receiver contains the character.
*/
- (BOOL)containsCharacter:(unichar)character;
/*!
@method containsCharacter:range:
@abstract Test if a string contains a character.
@discussion Returns <tt>YES</tt> if the receiver contains the character <tt><i>character</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>.
@param character The character to look for.
@param range The range to limit the search to.
@result Returns <tt>YES</tt> 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 <tt>YES</tt> if the receiver contains any character within <tt><i>set</i></tt>, otherwise returns <tt>NO</tt>.
@param set The set of characters to look for.
@result Returns <tt>YES</tt> 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 <tt>YES</tt> if the receiver contains any character within <tt><i>set</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
<blockquote><blockquote><table border = "1" width = "90%">
<thead>
<th>Search Option</th>
<th>Effect</th>
</thead>
<tr>
<td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
<td>Ignores case distinctions among characters.</td>
</tr>
<tr>
<td align = "center"><tt>NSLiteralSearch</tt></td>
<td>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.</td>
</tr>
<tr>
<td align = "center"><tt>NSBackwardsSearch</tt></td>
<td>Performs searching from the end of the range toward the beginning.</td>
</tr>
</table></blockquote></blockquote>
See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>.
@param set The set of characters to look for.
@param mask Mask values determining how to search.
@result Returns <tt>YES</tt> 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 <tt>YES</tt> if the receiver contains any character within <tt><i>set</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
<blockquote><blockquote><table border = "1" width = "90%">
<thead>
<th>Search Option</th>
<th>Effect</th>
</thead>
<tr>
<td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
<td>Ignores case distinctions among characters.</td>
</tr>
<tr>
<td align = "center"><tt>NSLiteralSearch</tt></td>
<td>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.</td>
</tr>
<tr>
<td align = "center"><tt>NSBackwardsSearch</tt></td>
<td>Performs searching from the end of the range toward the beginning.</td>
</tr>
</table></blockquote></blockquote>
See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>. Raises an <tt>NSRangeException</tt> if any part of <tt><i>range</i></tt> 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 <tt>YES</tt> 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 <tt>YES</tt> if the receiver contains only characters in <tt><i>set</i></tt> within <tt><i>set</i></tt>, otherwise returns <tt>NO</tt>.
@param set The set of characters to look for.
@result Returns <tt>YES</tt> 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 <tt>YES</tt> if the receiver contains only character from <tt><i>set</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
<blockquote><blockquote><table border = "1" width = "90%">
<thead>
<th>Search Option</th>
<th>Effect</th>
</thead>
<tr>
<td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
<td>Ignores case distinctions among characters.</td>
</tr>
<tr>
<td align = "center"><tt>NSLiteralSearch</tt></td>
<td>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.</td>
</tr>
<tr>
<td align = "center"><tt>NSBackwardsSearch</tt></td>
<td>Performs searching from the end of the range toward the beginning.</td>
</tr>
</table></blockquote></blockquote>
See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>. Raises an <tt>NSRangeException</tt> if any part of <tt><i>range</i></tt> 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 <tt>YES</tt> 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 <tt>YES</tt> if the receiver contains only character from <tt><i>set</i></tt> within the range <tt><i>range</i></tt>, otherwise returns <tt>NO</tt>. The following options may be specified in <tt><i>mask</i></tt> by combining them with the C bitwise OR operator:
<blockquote><blockquote><table border = "1" width = "90%">
<thead>
<th>Search Option</th>
<th>Effect</th>
</thead>
<tr>
<td align = "center"><tt>NSCaseInsensitiveSearch</tt></td>
<td>Ignores case distinctions among characters.</td>
</tr>
<tr>
<td align = "center"><tt>NSLiteralSearch</tt></td>
<td>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.</td>
</tr>
<tr>
<td align = "center"><tt>NSBackwardsSearch</tt></td>
<td>Performs searching from the end of the range toward the beginning.</td>
</tr>
</table></blockquote></blockquote>
See "Strings" for details on these options. Raises an <tt>NSInvalidArgumentException</tt> if any of the arguments are <tt>nil</tt>. Raises an <tt>NSRangeException</tt> if any part of <tt><i>range</i></tt> 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 <tt>YES</tt> 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 <tt>NSArray</tt> 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 <tt>NSArray</tt> 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 <tt>NSString</tt>
@discussion Additonal useful methods for <tt>NSMutableString</tt>, that can be used in general situations.
*/
@interface NSMutableString (NDUtilities)
/*!
@method prependString:
@abstract Prepend a string.
@discussion Adds the characters of <tt><i>string</i></tt> to the beginning of the receiver. <tt><i>string</i></tt> may not be <tt>nil</tt>.
@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 <tt>NSString</tt>'s <tt>stringWithFormat:</tt> method with the arguments listed. Raises an <tt>NSInvalidArgumentException</tt> if <tt><i>format</i></tt> is <tt>nil</tt>.
@param format The format string to append, followed by values to insert.
*/
- (void)prependFormat:(NSString *)format, ...;
@end
|
