Tag Parser  7.1.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
tagvalue.h
Go to the documentation of this file.
1 #ifndef TAG_PARSER_TAGVALUE_H
2 #define TAG_PARSER_TAGVALUE_H
3 
4 #include "./positioninset.h"
5 
6 #include <c++utilities/chrono/datetime.h>
7 #include <c++utilities/chrono/timespan.h>
8 #include <c++utilities/conversion/binaryconversion.h>
9 
10 #include <cstring>
11 #include <iosfwd>
12 #include <memory>
13 #include <string>
14 
15 namespace TagParser {
16 
17 class Tag;
18 class Id3v2Frame;
19 
23 enum class TagTextEncoding : unsigned int {
24  Latin1,
25  Utf8,
29 };
30 
35 constexpr int characterSize(TagTextEncoding encoding)
36 {
37  switch (encoding) {
40  return 1;
43  return 2;
44  default:
45  return 0;
46  }
47 }
48 
52 enum class TagDataType : unsigned int {
53  Text,
54  Integer,
57  TimeSpan,
58  DateTime,
59  Picture,
60  Binary,
61  Undefined
62 };
63 
65 public:
66  // constructor, destructor
67  TagValue();
68  TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1,
71  TagValue(
72  const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
73  TagValue(int value);
74  TagValue(const char *data, std::size_t length, TagDataType type = TagDataType::Undefined, TagTextEncoding encoding = TagTextEncoding::Latin1);
75  TagValue(std::unique_ptr<char[]> &&data, std::size_t length, TagDataType type = TagDataType::Binary,
77  TagValue(const PositionInSet &value);
78  TagValue(const TagValue &other);
79  TagValue(TagValue &&other) = default;
80  ~TagValue();
81 
82  // operators
83  TagValue &operator=(const TagValue &other);
84  TagValue &operator=(TagValue &&other) = default;
85  bool operator==(const TagValue &other) const;
86  bool operator!=(const TagValue &other) const;
87 
88  // methods
89  bool isEmpty() const;
90  void clearData();
91  void clearMetadata();
92  void clearDataAndMetadata();
93  TagDataType type() const;
94  std::string toString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
95  void toString(std::string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
96  std::u16string toWString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
97  void toWString(std::u16string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
98  int32 toInteger() const;
99  int toStandardGenreIndex() const;
100  PositionInSet toPositionInSet() const;
101  ChronoUtilities::TimeSpan toTimeSpan() const;
102  ChronoUtilities::DateTime toDateTime() const;
103  std::size_t dataSize() const;
104  char *dataPointer();
105  const char *dataPointer() const;
106  const std::string &description() const;
107  void setDescription(const std::string &value, TagTextEncoding encoding = TagTextEncoding::Latin1);
108  const std::string &mimeType() const;
109  void setMimeType(const std::string &mimeType);
110  const std::string &language() const;
111  void setLanguage(const std::string &language);
112  bool isLabeledAsReadonly() const;
113  void setReadonly(bool readOnly);
114  TagTextEncoding dataEncoding() const;
115  void convertDataEncoding(TagTextEncoding encoding);
116  void convertDataEncodingForTag(const Tag *tag);
117  TagTextEncoding descriptionEncoding() const;
118  static const TagValue &empty();
119 
120  void assignText(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1,
122  void assignText(
123  const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
124  void assignInteger(int value);
125  void assignStandardGenreIndex(int index);
126  void assignData(const char *data, std::size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
127  void assignData(std::unique_ptr<char[]> &&data, std::size_t length, TagDataType type = TagDataType::Binary,
129  void assignPosition(PositionInSet value);
130  void assignTimeSpan(ChronoUtilities::TimeSpan value);
131  void assignDateTime(ChronoUtilities::DateTime value);
132 
133  static void stripBom(const char *&text, std::size_t &length, TagTextEncoding encoding);
134  static void ensureHostByteOrder(std::u16string &u16str, TagTextEncoding currentEncoding);
135 
136 private:
137  std::unique_ptr<char[]> m_ptr;
138  std::size_t m_size;
139  std::string m_desc;
140  std::string m_mimeType;
141  std::string m_language;
142  TagDataType m_type;
143  TagTextEncoding m_encoding;
144  TagTextEncoding m_descEncoding;
145  bool m_labeledAsReadonly;
146 };
147 
152  : m_size(0)
153  , m_type(TagDataType::Undefined)
154  , m_encoding(TagTextEncoding::Latin1)
155  , m_descEncoding(TagTextEncoding::Latin1)
156  , m_labeledAsReadonly(false)
157 {
158 }
159 
164 {
165 }
166 
177 inline TagValue::TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding, TagTextEncoding convertTo)
178  : m_descEncoding(TagTextEncoding::Latin1)
179  , m_labeledAsReadonly(false)
180 {
181  assignText(text, textSize, textEncoding, convertTo);
182 }
183 
193 inline TagValue::TagValue(const char *text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
194 {
195  assignText(text, std::strlen(text), textEncoding, convertTo);
196 }
197 
207 inline TagValue::TagValue(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
208  : m_descEncoding(TagTextEncoding::Latin1)
209  , m_labeledAsReadonly(false)
210 {
211  assignText(text, textEncoding, convertTo);
212 }
213 
217 inline TagValue::TagValue(int value)
218  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::Integer)
219 {
220 }
221 
232 inline TagValue::TagValue(const char *data, std::size_t length, TagDataType type, TagTextEncoding encoding)
233  : m_size(length)
234  , m_type(type)
235  , m_encoding(encoding)
236  , m_descEncoding(TagTextEncoding::Latin1)
237  , m_labeledAsReadonly(false)
238 {
239  if (length) {
240  if (type == TagDataType::Text) {
241  stripBom(data, m_size, encoding);
242  }
243  m_ptr = std::make_unique<char[]>(m_size);
244  std::copy(data, data + m_size, m_ptr.get());
245  }
246 }
247 
260 inline TagValue::TagValue(std::unique_ptr<char[]> &&data, std::size_t length, TagDataType type, TagTextEncoding encoding)
261  : m_size(length)
262  , m_type(type)
263  , m_encoding(encoding)
264  , m_descEncoding(TagTextEncoding::Latin1)
265  , m_labeledAsReadonly(false)
266 {
267  if (length) {
268  m_ptr = move(data);
269  }
270 }
271 
277 inline TagValue::TagValue(const PositionInSet &value)
278  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet)
279 {
280 }
281 
286 inline bool TagValue::operator!=(const TagValue &other) const
287 {
288  return !(*this == other);
289 }
290 
300 inline void TagValue::assignText(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
301 {
302  assignText(text.data(), text.size(), textEncoding, convertTo);
303 }
304 
309 {
310  if (value.isNull()) {
312  clearData();
313  } else {
314  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet);
315  }
316 }
317 
322 {
323  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::TimeSpan);
324 }
325 
330 {
331  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::DateTime);
332 }
333 
340 {
341  assignInteger(index);
343 }
344 
349 {
350  return m_type;
351 }
352 
360 inline std::string TagValue::toString(TagTextEncoding encoding) const
361 {
362  std::string res;
363  toString(res, encoding);
364  return res;
365 }
366 
373 inline std::u16string TagValue::toWString(TagTextEncoding encoding) const
374 {
375  std::u16string res;
376  toWString(res, encoding);
377  return res;
378 }
379 
384 inline bool TagValue::isEmpty() const
385 {
386  return m_ptr == nullptr || m_size == 0;
387 }
388 
395 inline void TagValue::clearData()
396 {
397  m_size = 0;
398  m_ptr.reset();
399 }
400 
407 {
408  clearData();
409  clearMetadata();
410 }
411 
416 inline std::size_t TagValue::dataSize() const
417 {
418  return m_size;
419 }
420 
427 inline char *TagValue::dataPointer()
428 {
429  return m_ptr.get();
430 }
431 
432 inline const char *TagValue::dataPointer() const
433 {
434  return m_ptr.get();
435 }
436 
443 inline const std::string &TagValue::description() const
444 {
445  return m_desc;
446 }
447 
456 inline void TagValue::setDescription(const std::string &value, TagTextEncoding encoding)
457 {
458  m_desc = value;
459  m_descEncoding = encoding;
460 }
461 
467 inline const std::string &TagValue::mimeType() const
468 {
469  return m_mimeType;
470 }
471 
478 inline void TagValue::setMimeType(const std::string &mimeType)
479 {
480  m_mimeType = mimeType;
481 }
482 
488 inline const std::string &TagValue::language() const
489 {
490  return m_language;
491 }
492 
499 inline void TagValue::setLanguage(const std::string &language)
500 {
501  m_language = language;
502 }
503 
512 inline bool TagValue::isLabeledAsReadonly() const
513 {
514  return m_labeledAsReadonly;
515 }
516 
525 inline void TagValue::setReadonly(bool readOnly)
526 {
527  m_labeledAsReadonly = readOnly;
528 }
529 
536 {
537  return m_encoding;
538 }
539 
546 {
547  return m_descEncoding;
548 }
549 
550 } // namespace TagParser
551 
552 #endif // TAG_PARSER_TAGVALUE_H
TAG_PARSER_EXPORT const char * language()
TagTextEncoding dataEncoding() const
Returns the data encoding.
Definition: tagvalue.h:535
TAG_PARSER_EXPORT const char * description()
static void stripBom(const char *&text, std::size_t &length, TagTextEncoding encoding)
Strips the byte order mask from the specified text.
Definition: tagvalue.cpp:688
The Tag class is used to store, read and write tag information.
Definition: tag.h:95
TagTextEncoding descriptionEncoding() const
Returns the description encoding.
Definition: tagvalue.h:545
const std::string & description() const
Returns the description.
Definition: tagvalue.h:443
void setMimeType(const std::string &mimeType)
Sets the MIME type.
Definition: tagvalue.h:478
void setReadonly(bool readOnly)
Sets whether the TagValue is labeled as read-only.
Definition: tagvalue.h:525
std::u16string toWString(TagTextEncoding encoding=TagTextEncoding::Unspecified) const
Converts the value of the current TagValue object to its equivalent std::wstring representation.
Definition: tagvalue.h:373
bool operator!=(const TagValue &other) const
Returns whether both instances are not equal.
Definition: tagvalue.h:286
The PositionInSet class describes the position of an element in a set which consists of a certain num...
Definition: positioninset.h:21
TagDataType
Specifies the data type.
Definition: tagvalue.h:52
void clearDataAndMetadata()
Wipes assigned data including meta data.
Definition: tagvalue.h:406
constexpr bool operator==(byte lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:19
bool isEmpty() const
Returns an indication whether an value is assigned.
Definition: tagvalue.h:384
const std::string & mimeType() const
Returns the MIME type.
Definition: tagvalue.h:467
std::size_t dataSize() const
Returns the size of the assigned value in bytes.
Definition: tagvalue.h:416
constexpr bool operator!=(byte lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:24
void assignDateTime(ChronoUtilities::DateTime value)
Assigns the given DateTime value.
Definition: tagvalue.h:329
void clearMetadata()
Wipes assigned meta data.
Definition: tagvalue.cpp:161
const std::string & language() const
Returns the language.
Definition: tagvalue.h:488
void assignPosition(PositionInSet value)
Assigns the given PositionInSet value.
Definition: tagvalue.h:308
void assignStandardGenreIndex(int index)
Assigns the given standard genre index to be assigned.
Definition: tagvalue.h:339
~TagValue()
Destroys the TagValue.
Definition: tagvalue.h:163
TagValue()
Constructs an empty TagValue.
Definition: tagvalue.h:151
void setLanguage(const std::string &language)
Sets the language.
Definition: tagvalue.h:499
char * dataPointer()
Returns a pointer to the raw data assigned to the current instance.
Definition: tagvalue.h:427
constexpr bool isNull() const
Returns an indication whether both the element position and total element count is 0...
Definition: positioninset.h:92
TagDataType type() const
Returns the type of the assigned value.
Definition: tagvalue.h:348
void assignInteger(int value)
Assigns the given integer value.
Definition: tagvalue.cpp:630
void assignText(const char *text, std::size_t textSize, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
Assigns a copy of the given text.
Definition: tagvalue.cpp:579
void clearData()
Clears the assigned data.
Definition: tagvalue.h:395
bool isLabeledAsReadonly() const
Returns an indication whether the value is labeled as read-only.
Definition: tagvalue.h:512
void setDescription(const std::string &value, TagTextEncoding encoding=TagTextEncoding::Latin1)
Sets the description.
Definition: tagvalue.h:456
void assignData(const char *data, std::size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
std::string toString(TagTextEncoding encoding=TagTextEncoding::Unspecified) const
Converts the value of the current TagValue object to its equivalent std::string representation.
Definition: tagvalue.h:360
void assignTimeSpan(ChronoUtilities::TimeSpan value)
Assigns the given TimeSpan value.
Definition: tagvalue.h:321
constexpr int characterSize(TagTextEncoding encoding)
Returns the size of one character for the specified encoding in bytes.
Definition: tagvalue.h:35
The TagValue class wraps values of different types.
Definition: tagvalue.h:64
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:23
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:9
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.