git.maemo.org Git - someplayer/blob - src/taglib/toolkit/tbytevector.h

   1 /***************************************************************************
   2     copyright            : (C) 2002 - 2008 by Scott Wheeler
   3     email                : wheeler@kde.org
   4  ***************************************************************************/
   5
   6 /***************************************************************************
   7  *   This library is free software; you can redistribute it and/or modify  *
   8  *   it under the terms of the GNU Lesser General Public License version   *
   9  *   2.1 as published by the Free Software Foundation.                     *
  10  *                                                                         *
  11  *   This library is distributed in the hope that it will be useful, but   *
  12  *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
  14  *   Lesser General Public License for more details.                       *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU Lesser General Public      *
  17  *   License along with this library; if not, write to the Free Software   *
  18  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
  19  *   USA                                                                   *
  20  *                                                                         *
  21  *   Alternatively, this file is available under the Mozilla Public        *
  22  *   License Version 1.1.  You may obtain a copy of the License at         *
  23  *   http://www.mozilla.org/MPL/                                           *
  24  ***************************************************************************/
  25
  26 #ifndef TAGLIB_BYTEVECTOR_H
  27 #define TAGLIB_BYTEVECTOR_H
  28
  29 #include "taglib.h"
  30 #include "taglib_export.h"
  31
  32 #include <vector>
  33 #include <iostream>
  34
  35 namespace TagLib {
  36
  37   //! A byte vector
  38
  39   /*!
  40    * This class provides a byte vector with some methods that are useful for
  41    * tagging purposes.  Many of the search functions are tailored to what is
  42    * useful for finding tag related paterns in a data array.
  43    */
  44
  45   class TAGLIB_EXPORT ByteVector
  46   {
  47   public:
  48 #ifndef DO_NOT_DOCUMENT
  49     typedef std::vector<char>::iterator Iterator;
  50     typedef std::vector<char>::const_iterator ConstIterator;
  51 #endif
  52
  53     /*!
  54      * Constructs an empty byte vector.
  55      */
  56     ByteVector();
  57
  58     /*!
  59      * Construct a vector of size \a size with all values set to \a value by
  60      * default.
  61      */
  62     ByteVector(uint size, char value = 0);
  63
  64     /*!
  65      * Contructs a byte vector that is a copy of \a v.
  66      */
  67     ByteVector(const ByteVector &v);
  68
  69     /*!
  70      * Contructs a byte vector that contains \a c.
  71      */
  72     ByteVector(char c);
  73
  74     /*!
  75      * Constructs a byte vector that copies \a data for up to \a length bytes.
  76      */
  77     ByteVector(const char *data, uint length);
  78
  79     /*!
  80      * Constructs a byte vector that copies \a data up to the first null
  81      * byte.  The behavior is undefined if \a data is not null terminated.
  82      * This is particularly useful for constructing byte arrays from string
  83      * constants.
  84      */
  85     ByteVector(const char *data);
  86
  87     /*!
  88      * Destroys this ByteVector instance.
  89      */
  90     virtual ~ByteVector();
  91
  92     /*!
  93      * Sets the data for the byte array using the first \a length bytes of \a data
  94      */
  95     ByteVector &setData(const char *data, uint length);
  96
  97     /*!
  98      * Sets the data for the byte array copies \a data up to the first null
  99      * byte.  The behavior is undefined if \a data is not null terminated.
 100      */
 101     ByteVector &setData(const char *data);
 102
 103     /*!
 104      * Returns a pointer to the internal data structure.
 105      *
 106      * \warning Care should be taken when modifying this data structure as it is
 107      * easy to corrupt the ByteVector when doing so.  Specifically, while the
 108      * data may be changed, its length may not be.
 109      */
 110     char *data();
 111
 112     /*!
 113      * Returns a pointer to the internal data structure which may not be modified.
 114      */
 115     const char *data() const;
 116
 117     /*!
 118      * Returns a byte vector made up of the bytes starting at \a index and
 119      * for \a length bytes.  If \a length is not specified it will return the bytes
 120      * from \a index to the end of the vector.
 121      */
 122     ByteVector mid(uint index, uint length = 0xffffffff) const;
 123
 124     /*!
 125      * This essentially performs the same as operator[](), but instead of causing
 126      * a runtime error if the index is out of bounds, it will return a null byte.
 127      */
 128     char at(uint index) const;
 129
 130     /*!
 131      * Searches the ByteVector for \a pattern starting at \a offset and returns
 132      * the offset.  Returns -1 if the pattern was not found.  If \a byteAlign is
 133      * specified the pattern will only be matched if it starts on a byte divisible
 134      * by \a byteAlign (starting from \a offset).
 135      */
 136     int find(const ByteVector &pattern, uint offset = 0, int byteAlign = 1) const;
 137
 138     /*!
 139      * Searches the ByteVector for \a pattern starting from either the end of the
 140      * vector or \a offset and returns the offset.  Returns -1 if the pattern was
 141      * not found.  If \a byteAlign is specified the pattern will only be matched
 142      * if it starts on a byte divisible by \a byteAlign (starting from \a offset).
 143      */
 144     int rfind(const ByteVector &pattern, uint offset = 0, int byteAlign = 1) const;
 145
 146     /*!
 147      * Checks to see if the vector contains the \a pattern starting at position
 148      * \a offset.  Optionally, if you only want to search for part of the pattern
 149      * you can specify an offset within the pattern to start from.  Also, you can
 150      * specify to only check for the first \a patternLength bytes of \a pattern with
 151      * the \a patternLength argument.
 152      */
 153     bool containsAt(const ByteVector &pattern, uint offset, uint patternOffset = 0, uint patternLength = 0xffffffff) const;
 154
 155     /*!
 156      * Returns true if the vector starts with \a pattern.
 157      */
 158     bool startsWith(const ByteVector &pattern) const;
 159
 160     /*!
 161      * Returns true if the vector ends with \a pattern.
 162      */
 163     bool endsWith(const ByteVector &pattern) const;
 164
 165     /*!
 166      * Replaces \a pattern with \a with and returns a reference to the ByteVector
 167      * after the operation.  This \e does modify the vector.
 168      */
 169     ByteVector &replace(const ByteVector &pattern, const ByteVector &with);
 170
 171     /*!
 172      * Checks for a partial match of \a pattern at the end of the vector.  It
 173      * returns the offset of the partial match within the vector, or -1 if the
 174      * pattern is not found.  This method is particularly useful when searching for
 175      * patterns that start in one vector and end in another.  When combined with
 176      * startsWith() it can be used to find a pattern that overlaps two buffers.
 177      *
 178      * \note This will not match the complete pattern at the end of the string; use
 179      * endsWith() for that.
 180      */
 181     int endsWithPartialMatch(const ByteVector &pattern) const;
 182
 183     /*!
 184      * Appends \a v to the end of the ByteVector.
 185      */
 186     ByteVector &append(const ByteVector &v);
 187
 188     /*!
 189      * Clears the data.
 190      */
 191     ByteVector &clear();
 192
 193     /*!
 194      * Returns the size of the array.
 195      */
 196     uint size() const;
 197
 198     /*!
 199      * Resize the vector to \a size.  If the vector is currently less than
 200      * \a size, pad the remaining spaces with \a padding.  Returns a reference
 201      * to the resized vector.
 202      */
 203     ByteVector &resize(uint size, char padding = 0);
 204
 205     /*!
 206      * Returns an Iterator that points to the front of the vector.
 207      */
 208     Iterator begin();
 209
 210     /*!
 211      * Returns a ConstIterator that points to the front of the vector.
 212      */
 213     ConstIterator begin() const;
 214
 215     /*!
 216      * Returns an Iterator that points to the back of the vector.
 217      */
 218     Iterator end();
 219
 220     /*!
 221      * Returns a ConstIterator that points to the back of the vector.
 222      */
 223     ConstIterator end() const;
 224
 225     /*!
 226      * Returns true if the vector is null.
 227      *
 228      * \note A vector may be empty without being null.
 229      * \see isEmpty()
 230      */
 231     bool isNull() const;
 232
 233     /*!
 234      * Returns true if the ByteVector is empty.
 235      *
 236      * \see size()
 237      * \see isNull()
 238      */
 239     bool isEmpty() const;
 240
 241     /*!
 242      * Returns a CRC checksum of the byte vector's data.
 243      */
 244     uint checksum() const;
 245
 246     /*!
 247      * Converts the first 4 bytes of the vector to an unsigned integer.
 248      *
 249      * If \a mostSignificantByteFirst is true this will operate left to right
 250      * evaluating the integer.  For example if \a mostSignificantByteFirst is
 251      * true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00 ==
 252      * 0x01000000 == 1.
 253      *
 254      * \see fromUInt()
 255      */
 256     uint toUInt(bool mostSignificantByteFirst = true) const;
 257
 258     /*!
 259      * Converts the first 2 bytes of the vector to a short.
 260      *
 261      * If \a mostSignificantByteFirst is true this will operate left to right
 262      * evaluating the integer.  For example if \a mostSignificantByteFirst is
 263      * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1.
 264      *
 265      * \see fromShort()
 266      */
 267     short toShort(bool mostSignificantByteFirst = true) const;
 268
 269     /*!
 270      * Converts the first 8 bytes of the vector to a (signed) long long.
 271      *
 272      * If \a mostSignificantByteFirst is true this will operate left to right
 273      * evaluating the integer.  For example if \a mostSignificantByteFirst is
 274      * true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1,
 275      * if false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1.
 276      *
 277      * \see fromUInt()
 278      */
 279     long long toLongLong(bool mostSignificantByteFirst = true) const;
 280
 281     /*!
 282      * Creates a 4 byte ByteVector based on \a value.  If
 283      * \a mostSignificantByteFirst is true, then this will operate left to right
 284      * in building the ByteVector.  For example if \a mostSignificantByteFirst is
 285      * true then $00 00 00 01 == 0x00000001 == 1, if false, $01 00 00 00 ==
 286      * 0x01000000 == 1.
 287      *
 288      * \see toUInt()
 289      */
 290     static ByteVector fromUInt(uint value, bool mostSignificantByteFirst = true);
 291
 292     /*!
 293      * Creates a 2 byte ByteVector based on \a value.  If
 294      * \a mostSignificantByteFirst is true, then this will operate left to right
 295      * in building the ByteVector.  For example if \a mostSignificantByteFirst is
 296      * true then $00 01 == 0x0001 == 1, if false, $01 00 == 0x0100 == 1.
 297      *
 298      * \see toShort()
 299      */
 300     static ByteVector fromShort(short value, bool mostSignificantByteFirst = true);
 301
 302     /*!
 303      * Creates a 8 byte ByteVector based on \a value.  If
 304      * \a mostSignificantByteFirst is true, then this will operate left to right
 305      * in building the ByteVector.  For example if \a mostSignificantByteFirst is
 306      * true then $00 00 00 01 == 0x0000000000000001 == 1, if false,
 307      * $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1.
 308      *
 309      * \see toLongLong()
 310      */
 311     static ByteVector fromLongLong(long long value, bool mostSignificantByteFirst = true);
 312
 313     /*!
 314      * Returns a ByteVector based on the CString \a s.
 315      */
 316     static ByteVector fromCString(const char *s, uint length = 0xffffffff);
 317
 318     /*!
 319      * Returns a const refernence to the byte at \a index.
 320      */
 321     const char &operator[](int index) const;
 322
 323     /*!
 324      * Returns a reference to the byte at \a index.
 325      */
 326     char &operator[](int index);
 327
 328     /*!
 329      * Returns true if this ByteVector and \a v are equal.
 330      */
 331     bool operator==(const ByteVector &v) const;
 332
 333     /*!
 334      * Returns true if this ByteVector and \a v are not equal.
 335      */
 336     bool operator!=(const ByteVector &v) const;
 337
 338     /*!
 339      * Returns true if this ByteVector and the null terminated C string \a s
 340      * contain the same data.
 341      */
 342     bool operator==(const char *s) const;
 343
 344     /*!
 345      * Returns true if this ByteVector and the null terminated C string \a s
 346      * do not contain the same data.
 347      */
 348     bool operator!=(const char *s) const;
 349
 350     /*!
 351      * Returns true if this ByteVector is less than \a v.  The value of the
 352      * vectors is determined by evaluating the character from left to right, and
 353      * in the event one vector is a superset of the other, the size is used.
 354      */
 355     bool operator<(const ByteVector &v) const;
 356
 357     /*!
 358      * Returns true if this ByteVector is greater than \a v.
 359      */
 360     bool operator>(const ByteVector &v) const;
 361
 362     /*!
 363      * Returns a vector that is \a v appended to this vector.
 364      */
 365     ByteVector operator+(const ByteVector &v) const;
 366
 367     /*!
 368      * Copies ByteVector \a v.
 369      */
 370     ByteVector &operator=(const ByteVector &v);
 371
 372     /*!
 373      * Copies ByteVector \a v.
 374      */
 375     ByteVector &operator=(char c);
 376
 377     /*!
 378      * Copies ByteVector \a v.
 379      */
 380     ByteVector &operator=(const char *data);
 381
 382     /*!
 383      * A static, empty ByteVector which is convenient and fast (since returning
 384      * an empty or "null" value does not require instantiating a new ByteVector).
 385      */
 386     static ByteVector null;
 387
 388   protected:
 389     /*
 390      * If this ByteVector is being shared via implicit sharing, do a deep copy
 391      * of the data and separate from the shared members.  This should be called
 392      * by all non-const subclass members.
 393      */
 394     void detach();
 395
 396   private:
 397     class ByteVectorPrivate;
 398     ByteVectorPrivate *d;
 399   };
 400
 401 }
 402
 403 /*!
 404  * \relates TagLib::ByteVector
 405  * Streams the ByteVector \a v to the output stream \a s.
 406  */
 407 TAGLIB_EXPORT std::ostream &operator<<(std::ostream &s, const TagLib::ByteVector &v);
 408
 409 #endif