NSData+SA_NSDataExtensions.h

   1 //
   2 //  NSData+SA_NSDataExtensions.h
   3 //
   4 //  Copyright (c) 2015 Said Achmiz.
   5 //
   6 //      Permission is hereby granted, free of charge, to any person obtaining a copy
   7 //      of this software and associated documentation files (the "Software"), to deal
   8 //      in the Software without restriction, including without limitation the rights
   9 //      to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10 //      copies of the Software, and to permit persons to whom the Software is
  11 //      furnished to do so, subject to the following conditions:
  12 //
  13 //      The above copyright notice and this permission notice shall be included in all
  14 //      copies or substantial portions of the Software.
  15 //
  16 //      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17 //      IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18 //      FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19 //      AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20 //      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21 //      OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22 //      SOFTWARE.
  23
  24 #import <Foundation/Foundation.h>
  25
  26 /** \category NSData+SA_NSDataExtensions
  27  *      @brief Adds several utility methods to NSData.
  28  */
  29 @interface NSData (SA_NSDataExtensions)
  30
  31 //      NOTE on stripping nulls from the ends of byte arrays.
  32 //
  33 //      If you strip a null from the end of an array which is something other than
  34 //      a null-terminated C string (such as, for example, the bytes representing a
  35 //      UTF-16 string), and thereby cause yourself difficulties, you have only
  36 //      yourself to blame. Be sure that you know what your NSData objects are
  37 //      supposed to contain!
  38
  39 /**     Returns YES if the last byte of the stored data is null, NO otherwise.
  40  */
  41 @property (readonly, getter=isNullTerminated) BOOL nullTerminated;
  42
  43 /** Returns the stored bytes as a null-terminated C string (byte array).
  44
  45         If the stored data is already null-terminated, the returned pointer will
  46         be a pointer to the bytes managed by the receiver. If it is not already
  47         null-terminated, the returned pointer will point to bytes managed by a
  48         copy of the receiver (and the bytes of the copy will be null-terminated).
  49  */
  50 @property (readonly) const char *SA_terminatedCString;
  51
  52 /**     Returns data containing the stored bytes as a null-terminated C string
  53         (byte array).
  54
  55         If the stored data is already null-terminated, this method simply returns
  56         the receiver. If it is not already null-terminated, this method returns a
  57         reference to a fresh copy of the receiver (a copy that contains a
  58         null-terminated byte array, of course).
  59  */
  60 @property (readonly) NSData *SA_dataWithTerminatedCString;
  61
  62 /**     Returns the stored bytes as an non-null-terminated byte array.
  63
  64         If the stored data was not null-terminated to begin with, the returned
  65         pointer will be a pointer to the bytes managed by the receiver. If the
  66         stored data was null-terminated, the returned pointer will point to bytes
  67         managed by a copy of the receiver (and the bytes of the copy will not be
  68         null-terminated; but see NOTE).
  69
  70         NOTE: If the receiver's *last* byte is null, the bytes pointed to by the
  71         returned pointer will have that null stripped; but if there are any more
  72         null bytes prior to that last null, they will remain untouched!
  73  */
  74 @property (readonly) const char *SA_unterminatedByteString;
  75
  76 /**     Returns data containing the stored bytes as a non-null-terminated byte
  77         array.
  78
  79         If the stored data was not null-terminated to begin with, this method simply
  80         returns the receiver. If the stored data was null-terminated, this method
  81         returns a reference to a fresh copy of the receiver (a copy that contains a
  82         non-null-terminated byte array, of course; but see NOTE).
  83
  84         NOTE: If the receiver's *last* byte is null, the bytes managed by the
  85         returned object will have that null stripped; but if there are any more
  86         null bytes prior to that last null, they will remain untouched!
  87  */
  88 @property (readonly) NSData *SA_dataWithUnterminatedByteString;
  89
  90 /** Returns an NSData object containing a blank C string (i.e. a byte sequence
  91         of length 1, containing the null character '\0').
  92  */
  93 +(NSData *) dataWithBlankCString;
  94
  95 /** Returns an NSData object containing bytes copied from the given C string
  96         (sans the null terminator).
  97  */
  98 +(NSData *) dataFromCString:(const char *)cString;
  99
 100 /** Returns an NSData object containing the bytes of the given C string
 101         (sans the null terminator).
 102  */
 103 +(NSData *) dataWithCString:(char *)cString;
 104
 105 @end