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.
 
 
 

391 lines
14 KiB

/*
** NSData+Extensions.h
**
** Copyright (c) 2001-2007
**
** Author: Ludovic Marcotte <ludovic@Sophos.ca>
**
** This library is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License as published by the Free Software Foundation; either
** version 2.1 of the License, or (at your option) any later version.
**
** This library is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
** Lesser General Public License for more details.
**
** You should have received a copy of the GNU Lesser General Public
** License along with this library; if not, write to the Free Software
** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef _Pantomime_H_NSData_Extensions
#define _Pantomime_H_NSData_Extensions
#import <Foundation/NSArray.h>
#import <Foundation/NSData.h>
#import <Foundation/NSString.h>
/*!
@category NSData (PantomimeExtensions)
@abstract Pantomime extensions to NSData.
@discussion This category provides useful extensions for handling
NSData objects.
*/
@interface NSData (PantomimeExtensions)
/*!
@method decodeBase64
@abstract Decode using the base64 encoding.
@discussion This method is used to decode data that has been encoded
using the base64 method.
@result Returns the decoded bytes, as a NSData instance.
*/
- (NSData *) decodeBase64;
/*!
@method encodeBase64WithLineLength:
@abstract Encoding the bytes using the base64 encoding
@discussion Pending.
@param theLength Specifies the length of the lines if wrapping
should be done. 0 disables any wrapping.
@result Returns a NSData object on success, nil on error.
*/
- (NSData *) encodeBase64WithLineLength: (NSUInteger) theLength;
/*!
@method unfoldLines
@abstract Unfold lines contained in this object.
@discussion This method is used to replace all occurences
of "\n " or "\n\t" by "\n".
@result Returns a new NSData object.
*/
- (NSData *) unfoldLines;
/*!
@method decodeQuotedPrintableInHeader
@abstract Decode using the quoted-printable encoding.
@discussion This method is used to decode data that has been
encoded using the quoted-printable method.
@param aBOOL Specifies if we are decoding data from a message header, or not.
@result Returns a new NSData object with decoded data if the decoding succeeded, nil otherwize
*/
- (NSData *)decodeQuotedPrintableInHeader:(BOOL)aBOOL;
/*!
@method encodeQuotedPrintableWithLineLength:inHeader:
@abstract Encoding the bytes using the quoted-printable encoding
@discussion Pending.
@param aBOOL Specifies if we are encoding data from
a message header, or not.
@param theLength Specifies the length of the lines if wrapping
should be done. 0 disables any wrapping.
@result Returns a NSData object.
*/
- (NSData *) encodeQuotedPrintableWithLineLength: (NSUInteger) theLength
inHeader: (BOOL) aBOOL;
/*!
@method rangeOfData:
@discussion This method searches for <i>theData</i> in the receiver
and returns the associated NSRange.
@param theData The data to search for in the receiver.
@result The associated range if found, NSNotFound range otherwize
*/
-(NSRange) rangeOfData:(NSData *)needle;
/**
Convenience method to get the full range.
@return full range of data
*/
- (NSRange)fullRange;
/*!
@method rangeOfCString:
@discussion Invokes rangeOfCString:options:range: with no option
and the complete range.
@note Does not support UTF8 encoding for NSCaseInsensitiveSearch
@param theCString The C string to search for.
@result The associated range of the C string in the receiver.
*/
-(NSRange) rangeOfCString: (const char *) theCString;
/*!
@method rangeOfCString:
@discussion Invokes rangeOfCString:options:range: with <i>theOptions</i>
and the complete range.
@note Does not support UTF8 encoding for NSCaseInsensitiveSearch
@param theCString The C string to search for.
@param theOptions The options used during the search.
@result The associated range of the C string in the receiver.
*/
-(NSRange) rangeOfCString: (const char *) theCString
options: (NSUInteger) theOptions;
/*!
@method rangeOfCString:
@note does not support UTF8 encoding for NSCaseInsensitiveSearch
@discussion Search for <i>theCString<i> using <i>theOptions</i>
and <i>theRange</i> in the receiver.
@note Does not support UTF8 encoding for NSCaseInsensitiveSearch
@param theCString The C string to search for.
@param theOptions The options used during the search.
@param theRange The range to use when performing the search.
@result The associated range of the C string in the receiver.
*/
-(NSRange) rangeOfCString: (const char *) theCString
options: (NSUInteger) theOptions
range: (NSRange) theRange;
/*!
@method subdataFromIndex:
@discussion This method is used to obtain the subdata from <i>theIndex</i>
in the receiver. The byte at <i>theIndex</i> is part of the
returned NSData instance.
@param theIndex The index used to get the subdata from.
@result The subdata.
*/
- (NSData *) subdataFromIndex: (NSUInteger) theIndex;
/*!
@method subdataToIndex:
@discussion This method is used to obtain the subdata to <i>theIndex</i>
from the receiver. The byte at <i>theIndex</i> is not included in
returned NSData instance.
@param theIndex The index used to get the subdata to.
@result The subdata.
*/
- (NSData *) subdataToIndex: (NSUInteger) theIndex;
/// Like `subDataWithRange`, but doesn't copy bytes, and instead points to the bytes from the original.
/// @note The caller has to make sure that the returned `NSData` does not exist longer than the `NSData` that owns
/// the actual bytes.
- (NSData *)subdataUncopiedWithRange:(NSRange)range;
/**
@discussion Simple method to trim the leading and trailing whitespaces (characters with no visible
representation). Cahracters currently taken into accout are:
* " " (space)
* "\t" (tab)
@return The trimmed data.
*/
- (NSData *)dataByTrimmingWhiteSpaces;
/*!
@method dataFromQuotedData
@discussion This method returns an unquoted data if the
data has a leading AND trailing quote.
@result The unquoted data or the original if it does not
match the criteria.
*/
- (NSData *) dataFromQuotedData;
/*!
@method dataFromSemicolonTerminatedData
@discussion This method returns the data by omitting the
ending semicolon, if present.
@result The data without the ending semicolon.
*/
- (NSData *) dataFromSemicolonTerminatedData;
/*!
@method dataByRemovingLineFeedCharacters
@discussion This method is used to return the receiver without
any occurences of the line feed (LF, control-J, ASCII 10)
character.
@result The data withtout line feed characters.
*/
- (NSData *) dataByRemovingLineFeedCharacters;
/*!
@method indexOfCharacter:
@discussion This method finds the first occurence of
the character in the receiver and returns its index (zero-based)
@param theCharacter The caracter to be searched for.
@result The index of the character, -1 if it's not found in the receiver.
*/
- (NSInteger) indexOfCharacter: (char) theCharacter;
/*!
@method hasCPrefix:
@discussion This method is used to verify if the receiver has <i>theCString</i>
as a prefix.
@param theCString The C string to look for.
@result YES if <i>theCString</i> is a prefix of the receiver, NO otherwise.
*/
- (BOOL) hasCPrefix: (const char *) theCString;
/*!
@method hasCSuffix:
@discussion This method is used to verify if the receiver has <i>theCString</i>
as a suffix.
@param theCString The C string to look for.
@result YES if <i>theCString</i> is a suffix of the receiver, NO otherwise.
*/
- (BOOL) hasCSuffix: (const char *) theCString;
/*!
@method hasCaseInsensitiveCPrefix:
@discussion Same as -hasCPrefix but the comparison is done
in a case-insensitiveness matter.
@param thePrefix The prefix to be used.
@result YES the there is a match, NO otherwise.
*/
- (BOOL) hasCaseInsensitiveCPrefix: (const char *) theCString;
/*!
@method hasCaseInsensitiveCSuffix:
@discussion Same as -hasCSuffix but the comparison is done
in a case-insensitiveness matter.
@param theSuffix The suffix to be used.
@result YES the there is a match, NO otherwise.
*/
- (BOOL) hasCaseInsensitiveCSuffix: (const char *) theCString;
/*!
@method caseInsensitiveCCompare:
@discussion This method is used to compare <i>theCString</i> with our
receiver's bytes.
@param theCString The C string to compare the receiver with.
@result One of the three possible values of the NSComparisonResult enum.
*/
- (NSComparisonResult) caseInsensitiveCCompare: (const char *) theCString;
/*!
@method componentsSeparatedByCString:
@discussion This method is used to separate the receiver into subdata,
using <i>theCString</i> as the separator.
@param theCString The separator to use, as a C string.
@result An instance of NSArray holding all components. The array is
empty if the separator was not found in the receiver.
*/
- (NSArray *) componentsSeparatedByCString: (const char *) theCString;
/// Like `componentsSeparatedByCString`, but calls the given block with each result and the current count.
/// The block will be invoked for every component, together with its count and a boolean denoting if it's the last element.
/// @note Uses `subdataUncopiedWithRange` to produce the `NSData` parts.
- (void)componentsSeparatedByCString:(const char *)theCString
block:(void (^)(NSData *aLine, NSUInteger count, BOOL isLast))block;
/*!
@method asciiString
@discussion This method turns the receiver into a NSString object.
The receiver's bytes must be all-ASCII bytes.
@result A NSString instance, nil if the conversion failed.
*/
-(NSString *) asciiString;
/*!
@discussion This method turns the receiver into a NSString object.
The receiver's bytes must conform to the UTF-7_IMAP encoding, a UTF-7 variant for IMAP folders.
@see RFC3501-5.1.3 for details.
@result A NSString instance, nil if the conversion failed.
*/
- (NSString *) imapUtf7String;
/*!
@method cString
@discussion This method returns the receiver's byte as a NULL terminated
C string.
@result The NULL terminated C string.
*/
-(const char *) cString;
- (unichar) characterAtIndex: (NSUInteger) theIndex;
/*!
@method quoteWithLevel:wrappingLimit:
@discussion This method is used to quote an unwrapped string.
@param theLevel The quoting level.
@param theLimit The line wrapping limit to use, in number of characters.
@result Returns a quoted string as a NSData instance. An empty NSData
instance is returned if <i>theLevel</i> is greater than <i>theLimit</i>.
*/
- (NSData *) quoteWithLevel: (NSUInteger) theLevel
wrappingLimit: (NSUInteger) theLimit;
/**
This method is used to unwrap the string which is wrapped with "<" and ">".
@return If wrapped, the unwrapped string as a NSData instance, otherwize the unmodified data.
*/
- (NSData *) unwrap;
/*!
@method unwrapWithLimit:
@discussion This method is used to unwrap the string using a quote limit.
This method implements the behavior specified in RFC2646.
@param theQuoteLimit The quote limit to use for unwrapping the string.
@result The unwrapped string, as a NSData instance.
*/
- (NSData *) unwrapWithLimit: (NSUInteger) theQuoteLimit;
/*!
@method wrapWithLimit:
@discussion This method wraps the string at the <i>theLimit</i> with
respect to RFC2646.
@param theLimit The limit to use for wrapping the string. The limit
corresponds to the maximum length of a line, specified
in characters.
@result The wrapped string.
*/
- (NSData *) wrapWithLimit: (NSUInteger) theLimit;
@end
/*!
@category NSMutableData (PantomimeExtensions)
@abstract Pantomime extensions to NSMutableData.
@discussion This category provides useful extensions for handling
NSMutableData objects.
*/
@interface NSMutableData (PantomimeExtensions)
/*!
@method appendCFormat:
@discussion This method is used to append the variable arguments
to the receiver. The bytes of the arguments must
be composed only of ASCII characters.
@param theFormat The format of the rest of the argument, as this
method is a variadic method.
*/
-(void) appendCFormat: (NSString *) theFormat, ...;
/*!
@method appendCString:
@discussion This method is used to append the C string to the receiver.
@param theCString The C string to append.
*/
-(void) appendCString: (const char *) theCString;
/*!
@method insertCString: atIndex:
@discussion This method is used to insert the C string into
the received at the specified index. If <i>theIndex</i> is zero
or less, the C string will be added at the beginning of the
receiver. If <i>theIndex</i> is greater than the receiver's length,
the C string will be appended to the receiver.
@param theCString The C string to insert into the receiver.
@param theIndex The index where to insert the C string.
*/
- (void) insertCString: (const char *) theCString
atIndex: (NSUInteger) theIndex;
/*!
@method replaceCRLFWithLF
@discussion This method destructively elides all carriage return
(CR, Control-M, ASCII 13) from the receiver.
*/
- (void) replaceCRLFWithLF;
/*!
@method replaceLFWithCRLF
@discussion This method is used to replace all occurences of line feed
characters by sequences of a carriage return followed by
line feed characters in the receiver.
*/
- (NSMutableData *) replaceLFWithCRLF;
@end
#endif // _Pantomime_H_NSData_Extensions