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., 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
35namespace 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 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 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 */
633TAGLIB_EXPORT std::ostream &operator<<(std::ostream &s, const TagLib::ByteVector &v);
634
635#endif
636