You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

383 lines
13 KiB

  1. /*
  2. ** NSData+Extensions.h
  3. **
  4. ** Copyright (c) 2001-2007
  5. **
  6. ** Author: Ludovic Marcotte <ludovic@Sophos.ca>
  7. **
  8. ** This library is free software; you can redistribute it and/or
  9. ** modify it under the terms of the GNU Lesser General Public
  10. ** License as published by the Free Software Foundation; either
  11. ** version 2.1 of the License, or (at your option) any later version.
  12. **
  13. ** This library is distributed in the hope that it will be useful,
  14. ** but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  16. ** Lesser General Public License for more details.
  17. **
  18. ** You should have received a copy of the GNU Lesser General Public
  19. ** License along with this library; if not, write to the Free Software
  20. ** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  21. */
  22. #ifndef _Pantomime_H_NSData_Extensions
  23. #define _Pantomime_H_NSData_Extensions
  24. #import <Foundation/NSArray.h>
  25. #import <Foundation/NSData.h>
  26. #import <Foundation/NSString.h>
  27. /*!
  28. @category NSData (PantomimeExtensions)
  29. @abstract Pantomime extensions to NSData.
  30. @discussion This category provides useful extensions for handling
  31. NSData objects.
  32. */
  33. @interface NSData (PantomimeExtensions)
  34. /*!
  35. @method decodeBase64
  36. @abstract Decode using the base64 encoding.
  37. @discussion This method is used to decode data that has been encoded
  38. using the base64 method.
  39. @result Returns the decoded bytes, as a NSData instance.
  40. */
  41. - (NSData *) decodeBase64;
  42. /*!
  43. @method encodeBase64WithLineLength:
  44. @abstract Encoding the bytes using the base64 encoding
  45. @discussion Pending.
  46. @param theLength Specifies the length of the lines if wrapping
  47. should be done. 0 disables any wrapping.
  48. @result Returns a NSData object on success, nil on error.
  49. */
  50. - (NSData *) encodeBase64WithLineLength: (NSUInteger) theLength;
  51. /*!
  52. @method unfoldLines
  53. @abstract Unfold lines contained in this object.
  54. @discussion This method is used to replace all occurences
  55. of "\n " or "\n\t" by "\n".
  56. @result Returns a new NSData object.
  57. */
  58. - (NSData *) unfoldLines;
  59. /*!
  60. @method decodeQuotedPrintableInHeader
  61. @abstract Decode using the quoted-printable encoding.
  62. @discussion This method is used to decode data that has been
  63. encoded using the quoted-printable method.
  64. @param aBOOL Specifies if we are decoding data from a message header, or not.
  65. @result Returns a new NSData object with decoded data if the decoding succeeded, nil otherwize
  66. */
  67. - (NSData *)decodeQuotedPrintableInHeader:(BOOL)aBOOL;
  68. /*!
  69. @method encodeQuotedPrintableWithLineLength:inHeader:
  70. @abstract Encoding the bytes using the quoted-printable encoding
  71. @discussion Pending.
  72. @param aBOOL Specifies if we are encoding data from
  73. a message header, or not.
  74. @param theLength Specifies the length of the lines if wrapping
  75. should be done. 0 disables any wrapping.
  76. @result Returns a NSData object.
  77. */
  78. - (NSData *) encodeQuotedPrintableWithLineLength: (NSUInteger) theLength
  79. inHeader: (BOOL) aBOOL;
  80. /*!
  81. @method rangeOfData:
  82. @discussion This method searches for <i>theData</i> in the receiver
  83. and returns the associated NSRange.
  84. @param theData The data to search for in the receiver.
  85. @result The associated range if found, NSNotFound range otherwize
  86. */
  87. -(NSRange) rangeOfData:(NSData *)needle;
  88. /**
  89. Convenience method to get the full range.
  90. @return full range of data
  91. */
  92. - (NSRange)fullRange;
  93. /*!
  94. @method rangeOfCString:
  95. @discussion Invokes rangeOfCString:options:range: with no option
  96. and the complete range.
  97. @note Does not support UTF8 encoding for NSCaseInsensitiveSearch
  98. @param theCString The C string to search for.
  99. @result The associated range of the C string in the receiver.
  100. */
  101. -(NSRange) rangeOfCString: (const char *) theCString;
  102. /*!
  103. @method rangeOfCString:
  104. @discussion Invokes rangeOfCString:options:range: with <i>theOptions</i>
  105. and the complete range.
  106. @note Does not support UTF8 encoding for NSCaseInsensitiveSearch
  107. @param theCString The C string to search for.
  108. @param theOptions The options used during the search.
  109. @result The associated range of the C string in the receiver.
  110. */
  111. -(NSRange) rangeOfCString: (const char *) theCString
  112. options: (NSUInteger) theOptions;
  113. /*!
  114. @method rangeOfCString:
  115. @note does not support UTF8 encoding for NSCaseInsensitiveSearch
  116. @discussion Search for <i>theCString<i> using <i>theOptions</i>
  117. and <i>theRange</i> in the receiver.
  118. @note Does not support UTF8 encoding for NSCaseInsensitiveSearch
  119. @param theCString The C string to search for.
  120. @param theOptions The options used during the search.
  121. @param theRange The range to use when performing the search.
  122. @result The associated range of the C string in the receiver.
  123. */
  124. -(NSRange) rangeOfCString: (const char *) theCString
  125. options: (NSUInteger) theOptions
  126. range: (NSRange) theRange;
  127. /*!
  128. @method subdataFromIndex:
  129. @discussion This method is used to obtain the subdata from <i>theIndex</i>
  130. in the receiver. The byte at <i>theIndex</i> is part of the
  131. returned NSData instance.
  132. @param theIndex The index used to get the subdata from.
  133. @result The subdata.
  134. */
  135. - (NSData *) subdataFromIndex: (NSUInteger) theIndex;
  136. /*!
  137. @method subdataToIndex:
  138. @discussion This method is used to obtain the subdata to <i>theIndex</i>
  139. from the receiver. The byte at <i>theIndex</i> is not included in
  140. returned NSData instance.
  141. @param theIndex The index used to get the subdata to.
  142. @result The subdata.
  143. */
  144. - (NSData *) subdataToIndex: (NSUInteger) theIndex;
  145. /// Like `subDataWithRange`, but doesn't copy bytes, and instead points to the bytes from the original.
  146. - (NSData *)subdataUncopiedWithRange:(NSRange)range;
  147. /**
  148. @discussion Simple method to trim the leading and trailing whitespaces (characters with no visible
  149. representation). Cahracters currently taken into accout are:
  150. * " " (space)
  151. * "\t" (tab)
  152. @return The trimmed data.
  153. */
  154. - (NSData *)dataByTrimmingWhiteSpaces;
  155. /*!
  156. @method dataFromQuotedData
  157. @discussion This method returns an unquoted data if the
  158. data has a leading AND trailing quote.
  159. @result The unquoted data or the original if it does not
  160. match the criteria.
  161. */
  162. - (NSData *) dataFromQuotedData;
  163. /*!
  164. @method dataFromSemicolonTerminatedData
  165. @discussion This method returns the data by omitting the
  166. ending semicolon, if present.
  167. @result The data without the ending semicolon.
  168. */
  169. - (NSData *) dataFromSemicolonTerminatedData;
  170. /*!
  171. @method dataByRemovingLineFeedCharacters
  172. @discussion This method is used to return the receiver without
  173. any occurences of the line feed (LF, control-J, ASCII 10)
  174. character.
  175. @result The data withtout line feed characters.
  176. */
  177. - (NSData *) dataByRemovingLineFeedCharacters;
  178. /*!
  179. @method indexOfCharacter:
  180. @discussion This method finds the first occurence of
  181. the character in the receiver and returns its index (zero-based)
  182. @param theCharacter The caracter to be searched for.
  183. @result The index of the character, -1 if it's not found in the receiver.
  184. */
  185. - (NSInteger) indexOfCharacter: (char) theCharacter;
  186. /*!
  187. @method hasCPrefix:
  188. @discussion This method is used to verify if the receiver has <i>theCString</i>
  189. as a prefix.
  190. @param theCString The C string to look for.
  191. @result YES if <i>theCString</i> is a prefix of the receiver, NO otherwise.
  192. */
  193. - (BOOL) hasCPrefix: (const char *) theCString;
  194. /*!
  195. @method hasCSuffix:
  196. @discussion This method is used to verify if the receiver has <i>theCString</i>
  197. as a suffix.
  198. @param theCString The C string to look for.
  199. @result YES if <i>theCString</i> is a suffix of the receiver, NO otherwise.
  200. */
  201. - (BOOL) hasCSuffix: (const char *) theCString;
  202. /*!
  203. @method hasCaseInsensitiveCPrefix:
  204. @discussion Same as -hasCPrefix but the comparison is done
  205. in a case-insensitiveness matter.
  206. @param thePrefix The prefix to be used.
  207. @result YES the there is a match, NO otherwise.
  208. */
  209. - (BOOL) hasCaseInsensitiveCPrefix: (const char *) theCString;
  210. /*!
  211. @method hasCaseInsensitiveCSuffix:
  212. @discussion Same as -hasCSuffix but the comparison is done
  213. in a case-insensitiveness matter.
  214. @param theSuffix The suffix to be used.
  215. @result YES the there is a match, NO otherwise.
  216. */
  217. - (BOOL) hasCaseInsensitiveCSuffix: (const char *) theCString;
  218. /*!
  219. @method caseInsensitiveCCompare:
  220. @discussion This method is used to compare <i>theCString</i> with our
  221. receiver's bytes.
  222. @param theCString The C string to compare the receiver with.
  223. @result One of the three possible values of the NSComparisonResult enum.
  224. */
  225. - (NSComparisonResult) caseInsensitiveCCompare: (const char *) theCString;
  226. /*!
  227. @method componentsSeparatedByCString:
  228. @discussion This method is used to separate the receiver into subdata,
  229. using <i>theCString</i> as the separator.
  230. @param theCString The separator to use, as a C string.
  231. @result An instance of NSArray holding all components. The array is
  232. empty if the separator was not found in the receiver.
  233. */
  234. - (NSArray *) componentsSeparatedByCString: (const char *) theCString;
  235. /*!
  236. @method asciiString
  237. @discussion This method turns the receiver into a NSString object.
  238. The receiver's bytes must be all-ASCII bytes.
  239. @result A NSString instance, nil if the conversion failed.
  240. */
  241. -(NSString *) asciiString;
  242. /*!
  243. @discussion This method turns the receiver into a NSString object.
  244. The receiver's bytes must conform to the UTF-7_IMAP encoding, a UTF-7 variant for IMAP folders.
  245. @see RFC3501-5.1.3 for details.
  246. @result A NSString instance, nil if the conversion failed.
  247. */
  248. - (NSString *) imapUtf7String;
  249. /*!
  250. @method cString
  251. @discussion This method returns the receiver's byte as a NULL terminated
  252. C string.
  253. @result The NULL terminated C string.
  254. */
  255. -(const char *) cString;
  256. - (unichar) characterAtIndex: (NSUInteger) theIndex;
  257. /*!
  258. @method quoteWithLevel:wrappingLimit:
  259. @discussion This method is used to quote an unwrapped string.
  260. @param theLevel The quoting level.
  261. @param theLimit The line wrapping limit to use, in number of characters.
  262. @result Returns a quoted string as a NSData instance. An empty NSData
  263. instance is returned if <i>theLevel</i> is greater than <i>theLimit</i>.
  264. */
  265. - (NSData *) quoteWithLevel: (NSUInteger) theLevel
  266. wrappingLimit: (NSUInteger) theLimit;
  267. /**
  268. This method is used to unwrap the string which is wrapped with "<" and ">".
  269. @return If wrapped, the unwrapped string as a NSData instance, otherwize the unmodified data.
  270. */
  271. - (NSData *) unwrap;
  272. /*!
  273. @method unwrapWithLimit:
  274. @discussion This method is used to unwrap the string using a quote limit.
  275. This method implements the behavior specified in RFC2646.
  276. @param theQuoteLimit The quote limit to use for unwrapping the string.
  277. @result The unwrapped string, as a NSData instance.
  278. */
  279. - (NSData *) unwrapWithLimit: (NSUInteger) theQuoteLimit;
  280. /*!
  281. @method wrapWithLimit:
  282. @discussion This method wraps the string at the <i>theLimit</i> with
  283. respect to RFC2646.
  284. @param theLimit The limit to use for wrapping the string. The limit
  285. corresponds to the maximum length of a line, specified
  286. in characters.
  287. @result The wrapped string.
  288. */
  289. - (NSData *) wrapWithLimit: (NSUInteger) theLimit;
  290. @end
  291. /*!
  292. @category NSMutableData (PantomimeExtensions)
  293. @abstract Pantomime extensions to NSMutableData.
  294. @discussion This category provides useful extensions for handling
  295. NSMutableData objects.
  296. */
  297. @interface NSMutableData (PantomimeExtensions)
  298. /*!
  299. @method appendCFormat:
  300. @discussion This method is used to append the variable arguments
  301. to the receiver. The bytes of the arguments must
  302. be composed only of ASCII characters.
  303. @param theFormat The format of the rest of the argument, as this
  304. method is a variadic method.
  305. */
  306. -(void) appendCFormat: (NSString *) theFormat, ...;
  307. /*!
  308. @method appendCString:
  309. @discussion This method is used to append the C string to the receiver.
  310. @param theCString The C string to append.
  311. */
  312. -(void) appendCString: (const char *) theCString;
  313. /*!
  314. @method insertCString: atIndex:
  315. @discussion This method is used to insert the C string into
  316. the received at the specified index. If <i>theIndex</i> is zero
  317. or less, the C string will be added at the beginning of the
  318. receiver. If <i>theIndex</i> is greater than the receiver's length,
  319. the C string will be appended to the receiver.
  320. @param theCString The C string to insert into the receiver.
  321. @param theIndex The index where to insert the C string.
  322. */
  323. - (void) insertCString: (const char *) theCString
  324. atIndex: (NSUInteger) theIndex;
  325. /*!
  326. @method replaceCRLFWithLF
  327. @discussion This method destructively elides all carriage return
  328. (CR, Control-M, ASCII 13) from the receiver.
  329. */
  330. - (void) replaceCRLFWithLF;
  331. /*!
  332. @method replaceLFWithCRLF
  333. @discussion This method is used to replace all occurences of line feed
  334. characters by sequences of a carriage return followed by
  335. line feed characters in the receiver.
  336. */
  337. - (NSMutableData *) replaceLFWithCRLF;
  338. @end
  339. #endif // _Pantomime_H_NSData_Extensions