1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : [email protected] 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., 51 Franklin Street, Fifth Floor, Boston, MA * 19 * 02110-1301 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 patterns 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 typedef std::vector<char>::reverse_iterator ReverseIterator; 52 typedef std::vector<char>::const_reverse_iterator ConstReverseIterator; 53 #endif 54 55 /*! 56 * Constructs an empty byte vector. 57 */ 58 ByteVector(); 59 60 /*! 61 * Construct a vector of size \a size with all values set to \a value by 62 * default. 63 */ 64 ByteVector(unsigned int size, char value = 0); 65 66 /*! 67 * Constructs a byte vector that is a copy of \a v. 68 */ 69 ByteVector(const ByteVector &v); 70 71 /*! 72 * Constructs a byte vector that is a copy of \a v. 73 */ 74 ByteVector(const ByteVector &v, unsigned int offset, unsigned int length); 75 76 /*! 77 * Constructs a byte vector that contains \a c. 78 */ 79 ByteVector(char c); 80 81 /*! 82 * Constructs a byte vector that copies \a data for up to \a length bytes. 83 */ 84 ByteVector(const char *data, unsigned int length); 85 86 /*! 87 * Constructs a byte vector that copies \a data up to the first null 88 * byte. This is particularly useful for constructing byte arrays from 89 * string constants. 90 * 91 * \warning The behavior is undefined if \a data is not null terminated. 92 */ 93 ByteVector(const char *data); 94 95 /*! 96 * Destroys this ByteVector instance. 97 */ 98 virtual ~ByteVector(); 99 100 /*! 101 * Sets the data for the byte array using the first \a length bytes of \a data 102 */ 103 ByteVector &setData(const char *data, unsigned int length); 104 105 /*! 106 * Sets the data for the byte array copies \a data up to the first null 107 * byte. The behavior is undefined if \a data is not null terminated. 108 */ 109 ByteVector &setData(const char *data); 110 111 /*! 112 * Returns a pointer to the internal data structure. 113 * 114 * \warning Care should be taken when modifying this data structure as it is 115 * easy to corrupt the ByteVector when doing so. Specifically, while the 116 * data may be changed, its length may not be. 117 */ 118 char *data(); 119 120 /*! 121 * Returns a pointer to the internal data structure which may not be modified. 122 */ 123 const char *data() const; 124 125 /*! 126 * Returns a byte vector made up of the bytes starting at \a index and 127 * for \a length bytes. If \a length is not specified it will return the bytes 128 * from \a index to the end of the vector. 129 */ 130 ByteVector mid(unsigned int index, unsigned int length = 0xffffffff) const; 131 132 /*! 133 * This essentially performs the same as operator[](), but instead of causing 134 * a runtime error if the index is out of bounds, it will return a null byte. 135 */ 136 char at(unsigned int index) const; 137 138 /*! 139 * Searches the ByteVector for \a pattern starting at \a offset and returns 140 * the offset. Returns -1 if the pattern was not found. If \a byteAlign is 141 * specified the pattern will only be matched if it starts on a byte divisible 142 * by \a byteAlign (starting from \a offset). 143 */ 144 int find(const ByteVector &pattern, unsigned int offset = 0, int byteAlign = 1) const; 145 146 /*! 147 * Searches the char for \a c starting at \a offset and returns 148 * the offset. Returns \a -1 if the pattern was not found. If \a byteAlign is 149 * specified the pattern will only be matched if it starts on a byte divisible 150 * by \a byteAlign (starting from \a offset). 151 */ 152 int find(char c, unsigned int offset = 0, int byteAlign = 1) const; 153 154 /*! 155 * Searches the ByteVector for \a pattern starting from either the end of the 156 * vector or \a offset and returns the offset. Returns -1 if the pattern was 157 * not found. If \a byteAlign is specified the pattern will only be matched 158 * if it starts on a byte divisible by \a byteAlign (starting from \a offset). 159 */ 160 int rfind(const ByteVector &pattern, unsigned int offset = 0, int byteAlign = 1) const; 161 162 /*! 163 * Checks to see if the vector contains the \a pattern starting at position 164 * \a offset. Optionally, if you only want to search for part of the pattern 165 * you can specify an offset within the pattern to start from. Also, you can 166 * specify to only check for the first \a patternLength bytes of \a pattern with 167 * the \a patternLength argument. 168 */ 169 bool containsAt(const ByteVector &pattern, unsigned int offset, 170 unsigned int patternOffset = 0, unsigned int patternLength = 0xffffffff) const; 171 172 /*! 173 * Returns true if the vector starts with \a pattern. 174 */ 175 bool startsWith(const ByteVector &pattern) const; 176 177 /*! 178 * Returns true if the vector ends with \a pattern. 179 */ 180 bool endsWith(const ByteVector &pattern) const; 181 182 /*! 183 * Replaces \a oldByte with \a newByte and returns a reference to the 184 * ByteVector after the operation. This \e does modify the vector. 185 */ 186 ByteVector &replace(char oldByte, char newByte); 187 188 /*! 189 * Replaces \a pattern with \a with and returns a reference to the ByteVector 190 * after the operation. This \e does modify the vector. 191 */ 192 ByteVector &replace(const ByteVector &pattern, const ByteVector &with); 193 194 /*! 195 * Checks for a partial match of \a pattern at the end of the vector. It 196 * returns the offset of the partial match within the vector, or -1 if the 197 * pattern is not found. This method is particularly useful when searching for 198 * patterns that start in one vector and end in another. When combined with 199 * startsWith() it can be used to find a pattern that overlaps two buffers. 200 * 201 * \note This will not match the complete pattern at the end of the string; use 202 * endsWith() for that. 203 */ 204 int endsWithPartialMatch(const ByteVector &pattern) const; 205 206 /*! 207 * Appends \a v to the end of the ByteVector. 208 */ 209 ByteVector &append(const ByteVector &v); 210 211 /*! 212 * Appends \a c to the end of the ByteVector. 213 */ 214 ByteVector &append(char c); 215 216 /*! 217 * Clears the data. 218 */ 219 ByteVector &clear(); 220 221 /*! 222 * Returns the size of the array. 223 */ 224 unsigned int size() const; 225 226 /*! 227 * Resize the vector to \a size. If the vector is currently less than 228 * \a size, pad the remaining spaces with \a padding. Returns a reference 229 * to the resized vector. 230 */ 231 ByteVector &resize(unsigned int size, char padding = 0); 232 233 /*! 234 * Returns an Iterator that points to the front of the vector. 235 */ 236 Iterator begin(); 237 238 /*! 239 * Returns a ConstIterator that points to the front of the vector. 240 */ 241 ConstIterator begin() const; 242 243 /*! 244 * Returns an Iterator that points to the back of the vector. 245 */ 246 Iterator end(); 247 248 /*! 249 * Returns a ConstIterator that points to the back of the vector. 250 */ 251 ConstIterator end() const; 252 253 /*! 254 * Returns a ReverseIterator that points to the front of the vector. 255 */ 256 ReverseIterator rbegin(); 257 258 /*! 259 * Returns a ConstReverseIterator that points to the front of the vector. 260 */ 261 ConstReverseIterator rbegin() const; 262 263 /*! 264 * Returns a ReverseIterator that points to the back of the vector. 265 */ 266 ReverseIterator rend(); 267 268 /*! 269 * Returns a ConstReverseIterator that points to the back of the vector. 270 */ 271 ConstReverseIterator rend() const; 272 273 /*! 274 * Returns true if the vector is null. 275 * 276 * \note A vector may be empty without being null. So do not use this 277 * method to check if the vector is empty. 278 * 279 * \see isEmpty() 280 * 281 * \deprecated 282 */ 283 // BIC: remove 284 TAGLIB_DEPRECATED bool isNull() const; 285 286 /*! 287 * Returns true if the ByteVector is empty. 288 * 289 * \see size() 290 * \see isNull() 291 */ 292 bool isEmpty() const; 293 294 /*! 295 * Returns a CRC checksum of the byte vector's data. 296 * 297 * \note This uses an uncommon variant of CRC32 specializes in Ogg. 298 */ 299 // BIC: Remove or make generic. 300 unsigned int checksum() const; 301 302 /*! 303 * Converts the first 4 bytes of the vector to an unsigned integer. 304 * 305 * If \a mostSignificantByteFirst is true this will operate left to right 306 * evaluating the integer. For example if \a mostSignificantByteFirst is 307 * true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00 == 308 * 0x01000000 == 1. 309 * 310 * \see fromUInt() 311 */ 312 unsigned int toUInt(bool mostSignificantByteFirst = true) const; 313 314 /*! 315 * Converts the 4 bytes at \a offset of the vector to an unsigned integer. 316 * 317 * If \a mostSignificantByteFirst is true this will operate left to right 318 * evaluating the integer. For example if \a mostSignificantByteFirst is 319 * true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00 == 320 * 0x01000000 == 1. 321 * 322 * \see fromUInt() 323 */ 324 unsigned int toUInt(unsigned int offset, bool mostSignificantByteFirst = true) const; 325 326 /*! 327 * Converts the \a length bytes at \a offset of the vector to an unsigned 328 * integer. If \a length is larger than 4, the excess is ignored. 329 * 330 * If \a mostSignificantByteFirst is true this will operate left to right 331 * evaluating the integer. For example if \a mostSignificantByteFirst is 332 * true then $00 $00 $00 $01 == 0x00000001 == 1, if false, $01 00 00 00 == 333 * 0x01000000 == 1. 334 * 335 * \see fromUInt() 336 */ 337 unsigned int toUInt(unsigned int offset, unsigned int length, 338 bool mostSignificantByteFirst = true) const; 339 340 /*! 341 * Converts the first 2 bytes of the vector to a (signed) short. 342 * 343 * If \a mostSignificantByteFirst is true this will operate left to right 344 * evaluating the integer. For example if \a mostSignificantByteFirst is 345 * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. 346 * 347 * \see fromShort() 348 */ 349 short toShort(bool mostSignificantByteFirst = true) const; 350 351 /*! 352 * Converts the 2 bytes at \a offset of the vector to a (signed) short. 353 * 354 * If \a mostSignificantByteFirst is true this will operate left to right 355 * evaluating the integer. For example if \a mostSignificantByteFirst is 356 * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. 357 * 358 * \see fromShort() 359 */ 360 short toShort(unsigned int offset, bool mostSignificantByteFirst = true) const; 361 362 /*! 363 * Converts the first 2 bytes of the vector to a unsigned short. 364 * 365 * If \a mostSignificantByteFirst is true this will operate left to right 366 * evaluating the integer. For example if \a mostSignificantByteFirst is 367 * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. 368 * 369 * \see fromShort() 370 */ 371 unsigned short toUShort(bool mostSignificantByteFirst = true) const; 372 373 /*! 374 * Converts the 2 bytes at \a offset of the vector to a unsigned short. 375 * 376 * If \a mostSignificantByteFirst is true this will operate left to right 377 * evaluating the integer. For example if \a mostSignificantByteFirst is 378 * true then $00 $01 == 0x0001 == 1, if false, $01 00 == 0x01000000 == 1. 379 * 380 * \see fromShort() 381 */ 382 unsigned short toUShort(unsigned int offset, bool mostSignificantByteFirst = true) const; 383 384 /*! 385 * Converts the first 8 bytes of the vector to a (signed) long long. 386 * 387 * If \a mostSignificantByteFirst is true this will operate left to right 388 * evaluating the integer. For example if \a mostSignificantByteFirst is 389 * true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, 390 * if false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. 391 * 392 * \see fromUInt() 393 */ 394 long long toLongLong(bool mostSignificantByteFirst = true) const; 395 396 /*! 397 * Converts the 8 bytes at \a offset of the vector to a (signed) long long. 398 * 399 * If \a mostSignificantByteFirst is true this will operate left to right 400 * evaluating the integer. For example if \a mostSignificantByteFirst is 401 * true then $00 00 00 00 00 00 00 01 == 0x0000000000000001 == 1, 402 * if false, $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. 403 * 404 * \see fromUInt() 405 */ 406 long long toLongLong(unsigned int offset, bool mostSignificantByteFirst = true) const; 407 408 /* 409 * Converts the 4 bytes at \a offset of the vector to a float as an IEEE754 410 * 32-bit little-endian floating point number. 411 */ 412 float toFloat32LE(size_t offset) const; 413 414 /* 415 * Converts the 4 bytes at \a offset of the vector to a float as an IEEE754 416 * 32-bit big-endian floating point number. 417 */ 418 float toFloat32BE(size_t offset) const; 419 420 /* 421 * Converts the 8 bytes at \a offset of the vector to a double as an IEEE754 422 * 64-bit little-endian floating point number. 423 */ 424 double toFloat64LE(size_t offset) const; 425 426 /* 427 * Converts the 8 bytes at \a offset of the vector to a double as an IEEE754 428 * 64-bit big-endian floating point number. 429 */ 430 double toFloat64BE(size_t offset) const; 431 432 /* 433 * Converts the 10 bytes at \a offset of the vector to a long double as an 434 * IEEE754 80-bit little-endian floating point number. 435 * 436 * \note This may compromise the precision depends on the size of long double. 437 */ 438 long double toFloat80LE(size_t offset) const; 439 440 /* 441 * Converts the 10 bytes at \a offset of the vector to a long double as an 442 * IEEE754 80-bit big-endian floating point number. 443 * 444 * \note This may compromise the precision depends on the size of long double. 445 */ 446 long double toFloat80BE(size_t offset) const; 447 448 /*! 449 * Creates a 4 byte ByteVector based on \a value. If 450 * \a mostSignificantByteFirst is true, then this will operate left to right 451 * in building the ByteVector. For example if \a mostSignificantByteFirst is 452 * true then $00 00 00 01 == 0x00000001 == 1, if false, $01 00 00 00 == 453 * 0x01000000 == 1. 454 * 455 * \see toUInt() 456 */ 457 static ByteVector fromUInt(unsigned int value, bool mostSignificantByteFirst = true); 458 459 /*! 460 * Creates a 2 byte ByteVector based on \a value. If 461 * \a mostSignificantByteFirst is true, then this will operate left to right 462 * in building the ByteVector. For example if \a mostSignificantByteFirst is 463 * true then $00 01 == 0x0001 == 1, if false, $01 00 == 0x0100 == 1. 464 * 465 * \see toShort() 466 */ 467 static ByteVector fromShort(short value, bool mostSignificantByteFirst = true); 468 469 /*! 470 * Creates a 8 byte ByteVector based on \a value. If 471 * \a mostSignificantByteFirst is true, then this will operate left to right 472 * in building the ByteVector. For example if \a mostSignificantByteFirst is 473 * true then $00 00 00 01 == 0x0000000000000001 == 1, if false, 474 * $01 00 00 00 00 00 00 00 == 0x0100000000000000 == 1. 475 * 476 * \see toLongLong() 477 */ 478 static ByteVector fromLongLong(long long value, bool mostSignificantByteFirst = true); 479 480 /*! 481 * Creates a 4 byte ByteVector based on \a value as an IEEE754 32-bit 482 * little-endian floating point number. 483 * 484 * \see fromFloat32BE() 485 */ 486 static ByteVector fromFloat32LE(float value); 487 488 /*! 489 * Creates a 4 byte ByteVector based on \a value as an IEEE754 32-bit 490 * big-endian floating point number. 491 * 492 * \see fromFloat32LE() 493 */ 494 static ByteVector fromFloat32BE(float value); 495 496 /*! 497 * Creates a 8 byte ByteVector based on \a value as an IEEE754 64-bit 498 * little-endian floating point number. 499 * 500 * \see fromFloat64BE() 501 */ 502 static ByteVector fromFloat64LE(double value); 503 504 /*! 505 * Creates a 8 byte ByteVector based on \a value as an IEEE754 64-bit 506 * big-endian floating point number. 507 * 508 * \see fromFloat64LE() 509 */ 510 static ByteVector fromFloat64BE(double value); 511 512 /*! 513 * Returns a ByteVector based on the CString \a s. 514 */ 515 static ByteVector fromCString(const char *s, unsigned int length = 0xffffffff); 516 517 /*! 518 * Returns a const reference to the byte at \a index. 519 */ 520 const char &operator[](int index) const; 521 522 /*! 523 * Returns a reference to the byte at \a index. 524 */ 525 char &operator[](int index); 526 527 /*! 528 * Returns true if this ByteVector and \a v are equal. 529 */ 530 bool operator==(const ByteVector &v) const; 531 532 /*! 533 * Returns true if this ByteVector and \a v are not equal. 534 */ 535 bool operator!=(const ByteVector &v) const; 536 537 /*! 538 * Returns true if this ByteVector and the null terminated C string \a s 539 * contain the same data. 540 */ 541 bool operator==(const char *s) const; 542 543 /*! 544 * Returns true if this ByteVector and the null terminated C string \a s 545 * do not contain the same data. 546 */ 547 bool operator!=(const char *s) const; 548 549 /*! 550 * Returns true if this ByteVector is less than \a v. The value of the 551 * vectors is determined by evaluating the character from left to right, and 552 * in the event one vector is a superset of the other, the size is used. 553 */ 554 bool operator<(const ByteVector &v) const; 555 556 /*! 557 * Returns true if this ByteVector is greater than \a v. 558 */ 559 bool operator>(const ByteVector &v) const; 560 561 /*! 562 * Returns a vector that is \a v appended to this vector. 563 */ 564 ByteVector operator+(const ByteVector &v) const; 565 566 /*! 567 * Copies ByteVector \a v. 568 */ 569 ByteVector &operator=(const ByteVector &v); 570 571 /*! 572 * Copies a byte \a c. 573 */ 574 ByteVector &operator=(char c); 575 576 /*! 577 * Copies \a data up to the first null byte. 578 * 579 * \warning The behavior is undefined if \a data is not null terminated. 580 */ 581 ByteVector &operator=(const char *data); 582 583 /*! 584 * Exchanges the content of the ByteVector by the content of \a v. 585 */ 586 void swap(ByteVector &v); 587 588 /*! 589 * A static, empty ByteVector which is convenient and fast (since returning 590 * an empty or "null" value does not require instantiating a new ByteVector). 591 * 592 * \warning Do not modify this variable. It will mess up the internal state 593 * of TagLib. 594 * 595 * \deprecated 596 */ 597 // BIC: remove 598 TAGLIB_DEPRECATED static ByteVector null; 599 600 /*! 601 * Returns a hex-encoded copy of the byte vector. 602 */ 603 ByteVector toHex() const; 604 605 /*! 606 * Returns a base64 encoded copy of the byte vector 607 */ 608 ByteVector toBase64() const; 609 610 /*! 611 * Decodes the base64 encoded byte vector. 612 */ 613 static ByteVector fromBase64(const ByteVector &); 614 615 protected: 616 /* 617 * If this ByteVector is being shared via implicit sharing, do a deep copy 618 * of the data and separate from the shared members. This should be called 619 * by all non-const subclass members. 620 */ 621 void detach(); 622 623 private: 624 class ByteVectorPrivate; 625 ByteVectorPrivate *d; 626 }; 627 } 628 629 /*! 630 * \relates TagLib::ByteVector 631 * Streams the ByteVector \a v to the output stream \a s. 632 */ 633 TAGLIB_EXPORT std::ostream &operator<<(std::ostream &s, const TagLib::ByteVector &v); 634 635 #endif 636