Tag Parser  7.0.1
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 <iosfwd>
11 #include <memory>
12 #include <string>
13 
14 namespace TagParser {
15 
16 class Tag;
17 class Id3v2Frame;
18 
22 enum class TagTextEncoding : unsigned int {
23  Latin1,
24  Utf8,
28 };
29 
34 constexpr int characterSize(TagTextEncoding encoding)
35 {
36  switch (encoding) {
39  return 1;
42  return 2;
43  default:
44  return 0;
45  }
46 }
47 
51 enum class TagDataType : unsigned int {
52  Text,
53  Integer,
56  TimeSpan,
57  DateTime,
58  Picture,
59  Binary,
60  Undefined
61 };
62 
64 public:
65  // constructor, destructor
66  TagValue();
67  TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1,
69  TagValue(
70  const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
71  TagValue(int value);
72  TagValue(const char *data, size_t length, TagDataType type = TagDataType::Undefined, TagTextEncoding encoding = TagTextEncoding::Latin1);
73  TagValue(
74  std::unique_ptr<char[]> &&data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
75  TagValue(const PositionInSet &value);
76  TagValue(const TagValue &other);
77  TagValue(TagValue &&other) = default;
78  ~TagValue();
79 
80  // operators
81  TagValue &operator=(const TagValue &other);
82  TagValue &operator=(TagValue &&other) = default;
83  bool operator==(const TagValue &other) const;
84  bool operator!=(const TagValue &other) const;
85 
86  // methods
87  bool isEmpty() const;
88  void clearData();
89  void clearMetadata();
90  void clearDataAndMetadata();
91  TagDataType type() const;
92  std::string toString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
93  void toString(std::string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
94  std::u16string toWString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
95  void toWString(std::u16string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
96  int32 toInteger() const;
97  int toStandardGenreIndex() const;
98  PositionInSet toPositionInSet() const;
99  ChronoUtilities::TimeSpan toTimeSpan() const;
100  ChronoUtilities::DateTime toDateTime() const;
101  std::size_t dataSize() const;
102  char *dataPointer();
103  const char *dataPointer() const;
104  const std::string &description() const;
105  void setDescription(const std::string &value, TagTextEncoding encoding = TagTextEncoding::Latin1);
106  const std::string &mimeType() const;
107  void setMimeType(const std::string &mimeType);
108  const std::string &language() const;
109  void setLanguage(const std::string &language);
110  bool isLabeledAsReadonly() const;
111  void setReadonly(bool readOnly);
112  TagTextEncoding dataEncoding() const;
113  void convertDataEncoding(TagTextEncoding encoding);
114  void convertDataEncodingForTag(const Tag *tag);
115  TagTextEncoding descriptionEncoding() const;
116  static const TagValue &empty();
117 
118  void assignText(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1,
120  void assignText(
121  const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
122  void assignInteger(int value);
123  void assignStandardGenreIndex(int index);
124  void assignData(const char *data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
125  void assignData(
126  std::unique_ptr<char[]> &&data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
127  void assignPosition(PositionInSet value);
128  void assignTimeSpan(ChronoUtilities::TimeSpan value);
129  void assignDateTime(ChronoUtilities::DateTime value);
130 
131  static void stripBom(const char *&text, size_t &length, TagTextEncoding encoding);
132  static void ensureHostByteOrder(std::u16string &u16str, TagTextEncoding currentEncoding);
133 
134 private:
135  std::unique_ptr<char[]> m_ptr;
136  std::size_t m_size;
137  std::string m_desc;
138  std::string m_mimeType;
139  std::string m_language;
140  TagDataType m_type;
141  TagTextEncoding m_encoding;
142  TagTextEncoding m_descEncoding;
143  bool m_labeledAsReadonly;
144 };
145 
150  : m_size(0)
151  , m_type(TagDataType::Undefined)
152  , m_encoding(TagTextEncoding::Latin1)
153  , m_descEncoding(TagTextEncoding::Latin1)
154  , m_labeledAsReadonly(false)
155 {
156 }
157 
162 {
163 }
164 
175 inline TagValue::TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding, TagTextEncoding convertTo)
176  : m_descEncoding(TagTextEncoding::Latin1)
177  , m_labeledAsReadonly(false)
178 {
179  assignText(text, textSize, textEncoding, convertTo);
180 }
181 
191 inline TagValue::TagValue(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
192  : m_descEncoding(TagTextEncoding::Latin1)
193  , m_labeledAsReadonly(false)
194 {
195  assignText(text, textEncoding, convertTo);
196 }
197 
201 inline TagValue::TagValue(int value)
202  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::Integer)
203 {
204 }
205 
216 inline TagValue::TagValue(const char *data, std::size_t length, TagDataType type, TagTextEncoding encoding)
217  : m_size(length)
218  , m_type(type)
219  , m_encoding(encoding)
220  , m_descEncoding(TagTextEncoding::Latin1)
221  , m_labeledAsReadonly(false)
222 {
223  if (length) {
224  if (type == TagDataType::Text) {
225  stripBom(data, m_size, encoding);
226  }
227  m_ptr = std::make_unique<char[]>(m_size);
228  std::copy(data, data + m_size, m_ptr.get());
229  }
230 }
231 
244 inline TagValue::TagValue(std::unique_ptr<char[]> &&data, std::size_t length, TagDataType type, TagTextEncoding encoding)
245  : m_size(length)
246  , m_type(type)
247  , m_encoding(encoding)
248  , m_descEncoding(TagTextEncoding::Latin1)
249  , m_labeledAsReadonly(false)
250 {
251  if (length) {
252  m_ptr = move(data);
253  }
254 }
255 
260 inline TagValue::TagValue(const PositionInSet &value)
261  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet)
262 {
263 }
264 
269 inline bool TagValue::operator!=(const TagValue &other) const
270 {
271  return !(*this == other);
272 }
273 
283 inline void TagValue::assignText(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
284 {
285  assignText(text.data(), text.size(), textEncoding, convertTo);
286 }
287 
292 {
293  if (value.isNull()) {
295  clearData();
296  } else {
297  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet);
298  }
299 }
300 
305 {
306  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::TimeSpan);
307 }
308 
313 {
314  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::DateTime);
315 }
316 
323 {
324  assignInteger(index);
326 }
327 
332 {
333  return m_type;
334 }
335 
343 inline std::string TagValue::toString(TagTextEncoding encoding) const
344 {
345  std::string res;
346  toString(res, encoding);
347  return res;
348 }
349 
356 inline std::u16string TagValue::toWString(TagTextEncoding encoding) const
357 {
358  std::u16string res;
359  toWString(res, encoding);
360  return res;
361 }
362 
367 inline bool TagValue::isEmpty() const
368 {
369  return m_ptr == nullptr || m_size == 0;
370 }
371 
378 inline void TagValue::clearData()
379 {
380  m_size = 0;
381  m_ptr.reset();
382 }
383 
390 {
391  clearData();
392  clearMetadata();
393 }
394 
399 inline size_t TagValue::dataSize() const
400 {
401  return m_size;
402 }
403 
410 inline char *TagValue::dataPointer()
411 {
412  return m_ptr.get();
413 }
414 
415 inline const char *TagValue::dataPointer() const
416 {
417  return m_ptr.get();
418 }
419 
426 inline const std::string &TagValue::description() const
427 {
428  return m_desc;
429 }
430 
439 inline void TagValue::setDescription(const std::string &value, TagTextEncoding encoding)
440 {
441  m_desc = value;
442  m_descEncoding = encoding;
443 }
444 
450 inline const std::string &TagValue::mimeType() const
451 {
452  return m_mimeType;
453 }
454 
461 inline void TagValue::setMimeType(const std::string &mimeType)
462 {
463  m_mimeType = mimeType;
464 }
465 
471 inline const std::string &TagValue::language() const
472 {
473  return m_language;
474 }
475 
482 inline void TagValue::setLanguage(const std::string &language)
483 {
484  m_language = language;
485 }
486 
495 inline bool TagValue::isLabeledAsReadonly() const
496 {
497  return m_labeledAsReadonly;
498 }
499 
508 inline void TagValue::setReadonly(bool readOnly)
509 {
510  m_labeledAsReadonly = readOnly;
511 }
512 
519 {
520  return m_encoding;
521 }
522 
529 {
530  return m_descEncoding;
531 }
532 
533 } // namespace TagParser
534 
535 #endif // TAG_PARSER_TAGVALUE_H
TAG_PARSER_EXPORT const char * language()
TagTextEncoding dataEncoding() const
Returns the data encoding.
Definition: tagvalue.h:518
TAG_PARSER_EXPORT const char * description()
TagTextEncoding descriptionEncoding() const
Returns the description encoding.
Definition: tagvalue.h:528
const std::string & description() const
Returns the description.
Definition: tagvalue.h:426
void setMimeType(const std::string &mimeType)
Sets the MIME type.
Definition: tagvalue.h:461
void setReadonly(bool readOnly)
Sets whether the TagValue is labeled as read-only.
Definition: tagvalue.h:508
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:356
std::size_t dataSize() const
Returns the size of the assigned value in bytes.
Definition: tagvalue.h:399
bool operator!=(const TagValue &other) const
Returns whether both instances are not equal.
Definition: tagvalue.h:269
TagDataType
Specifies the data type.
Definition: tagvalue.h:51
void clearDataAndMetadata()
Wipes assigned data including meta data.
Definition: tagvalue.h:389
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:367
const std::string & mimeType() const
Returns the MIME type.
Definition: tagvalue.h:450
constexpr bool operator!=(byte lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:24
void assignDateTime(ChronoUtilities::DateTime value)
Assigns the given DateTime value.
Definition: tagvalue.h:312
void clearMetadata()
Wipes assigned meta data.
Definition: tagvalue.cpp:132
const std::string & language() const
Returns the language.
Definition: tagvalue.h:471
void assignPosition(PositionInSet value)
Assigns the given PositionInSet value.
Definition: tagvalue.h:291
void assignStandardGenreIndex(int index)
Assigns the given standard genre index to be assigned.
Definition: tagvalue.h:322
~TagValue()
Destroys the TagValue.
Definition: tagvalue.h:161
TagValue()
Constructs an empty TagValue.
Definition: tagvalue.h:149
void setLanguage(const std::string &language)
Sets the language.
Definition: tagvalue.h:482
char * dataPointer()
Returns a pointer to the raw data assigned to the current instance.
Definition: tagvalue.h:410
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:331
void assignInteger(int value)
Assigns the given integer value.
Definition: tagvalue.cpp:603
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:552
void clearData()
Clears the assigned data.
Definition: tagvalue.h:378
bool isLabeledAsReadonly() const
Returns an indication whether the value is labeled as read-only.
Definition: tagvalue.h:495
void setDescription(const std::string &value, TagTextEncoding encoding=TagTextEncoding::Latin1)
Sets the description.
Definition: tagvalue.h:439
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:343
void assignTimeSpan(ChronoUtilities::TimeSpan value)
Assigns the given TimeSpan value.
Definition: tagvalue.h:304
constexpr int characterSize(TagTextEncoding encoding)
Returns the size of one character for the specified encoding in bytes.
Definition: tagvalue.h:34
static void stripBom(const char *&text, size_t &length, TagTextEncoding encoding)
Strips the byte order mask from the specified text.
Definition: tagvalue.cpp:661
void assignData(const char *data, size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
Assigns a copy of the given data.
Definition: tagvalue.cpp:620
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:22
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.