NSData+SA_NSDataExtensions.h

   1 //
   2 //  NSData+SA_NSDataExtensions.h
   3 //
   4 //  Copyright 2015-2021 Said Achmiz.
   5 //  See LICENSE and README.md for more info.
   6
   7 #import <Foundation/Foundation.h>
   8
   9 /** \category NSData+SA_NSDataExtensions
  10  *      @brief Adds several utility methods to NSData.
  11  */
  12 @interface NSData (SA_NSDataExtensions)
  13
  14 //      NOTE on stripping nulls from the ends of byte arrays.
  15 //
  16 //      If you strip a null from the end of an array which is something other than
  17 //      a null-terminated C string (such as, for example, the bytes representing a
  18 //      UTF-16 string), and thereby cause yourself difficulties, you have only
  19 //      yourself to blame. Be sure that you know what your NSData objects are
  20 //      supposed to contain!
  21
  22 /**     Returns YES if the last byte of the stored data is null, NO otherwise.
  23  */
  24 @property (readonly, getter=isNullTerminated) BOOL nullTerminated;
  25
  26 /** Returns the stored bytes as a null-terminated C string (byte array).
  27
  28         If the stored data is already null-terminated, the returned pointer will
  29         be a pointer to the bytes managed by the receiver. If it is not already
  30         null-terminated, the returned pointer will point to bytes managed by a
  31         copy of the receiver (and the bytes of the copy will be null-terminated).
  32  */
  33 @property (readonly) const char *terminatedCString;
  34
  35 /**     Returns data containing the stored bytes as a null-terminated C string
  36         (byte array).
  37
  38         If the stored data is already null-terminated, this method simply returns
  39         the receiver. If it is not already null-terminated, this method returns a
  40         reference to a fresh copy of the receiver (a copy that contains a
  41         null-terminated byte array, of course).
  42  */
  43 @property (readonly) NSData *dataWithTerminatedCString;
  44
  45 /*      Range manipulation.
  46  */
  47
  48 @property (readonly) NSRange startRange;
  49 @property (readonly) NSRange fullRange;
  50 @property (readonly) NSRange endRange;
  51
  52 -(NSRange) rangeAfterRange:(NSRange)aRange;
  53 -(NSRange) rangeFromEndOfRange:(NSRange)aRange;
  54 -(NSRange) rangeToEndFrom:(NSRange)aRange;
  55
  56 /** Returns an NSData object containing a blank C string (i.e. a byte sequence
  57         of length 1, containing the null character '\0').
  58  */
  59 +(NSData *) dataWithBlankCString;
  60
  61 /** Returns an NSData object containing bytes copied from the given C string
  62         (sans the null terminator).
  63  */
  64 +(NSData *) dataFromCString:(const char *)cString;
  65
  66 /** Returns an NSData object containing the bytes of the given C string
  67         (sans the null terminator).
  68  */
  69 +(NSData *) dataWithCString:(char *)cString;
  70
  71 @end