Tag Parser  9.1.2
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 #include <c++utilities/misc/flagenumclass.h>
10 #include <c++utilities/misc/traits.h>
11 
12 #include <cstring>
13 #include <iosfwd>
14 #include <memory>
15 #include <string>
16 
17 namespace TagParser {
18 
19 class Tag;
20 class Id3v2Frame;
21 
25 enum class TagTextEncoding : unsigned int {
26  Latin1,
27  Utf8,
31 };
32 
37 constexpr int characterSize(TagTextEncoding encoding)
38 {
39  switch (encoding) {
42  return 1;
45  return 2;
46  default:
47  return 0;
48  }
49 }
50 
54 enum class TagDataType : unsigned int {
55  Text,
56  Integer,
59  TimeSpan,
60  DateTime,
61  Picture,
62  Binary,
63  Undefined
64 };
65 
69 enum class TagValueComparisionFlags : unsigned int {
70  None,
71  CaseInsensitive = 0x1,
72  IgnoreMetaData = 0x2,
73 };
74 
76 public:
77  // constructor, destructor
78  TagValue();
79  TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1,
82  TagValue(
83  const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
84  TagValue(int value);
85  TagValue(const char *data, std::size_t length, TagDataType type = TagDataType::Undefined, TagTextEncoding encoding = TagTextEncoding::Latin1);
86  TagValue(std::unique_ptr<char[]> &&data, std::size_t length, TagDataType type = TagDataType::Binary,
88  TagValue(PositionInSet value);
89  TagValue(CppUtilities::DateTime value);
90  TagValue(CppUtilities::TimeSpan value);
91  TagValue(const TagValue &other);
92  TagValue(TagValue &&other) = default;
93  ~TagValue();
94 
95  // operators
96  TagValue &operator=(const TagValue &other);
97  TagValue &operator=(TagValue &&other) = default;
98  bool operator==(const TagValue &other) const;
99  bool operator!=(const TagValue &other) const;
100 
101  // methods
102  bool isNull() const;
103  bool isEmpty() const;
104  void clearData();
105  void clearMetadata();
106  void clearDataAndMetadata();
107  TagDataType type() const;
108  std::string toString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
109  void toString(std::string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
110  std::u16string toWString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
111  void toWString(std::u16string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
112  std::int32_t toInteger() const;
113  int toStandardGenreIndex() const;
114  PositionInSet toPositionInSet() const;
115  CppUtilities::TimeSpan toTimeSpan() const;
116  CppUtilities::DateTime toDateTime() const;
117  std::size_t dataSize() const;
118  char *dataPointer();
119  const char *dataPointer() const;
120  const std::string &description() const;
121  void setDescription(const std::string &value, TagTextEncoding encoding = TagTextEncoding::Latin1);
122  const std::string &mimeType() const;
123  void setMimeType(const std::string &mimeType);
124  const std::string &language() const;
125  void setLanguage(const std::string &language);
126  bool isLabeledAsReadonly() const;
127  void setReadonly(bool readOnly);
128  TagTextEncoding dataEncoding() const;
129  void convertDataEncoding(TagTextEncoding encoding);
130  void convertDataEncodingForTag(const Tag *tag);
131  TagTextEncoding descriptionEncoding() const;
132  void convertDescriptionEncoding(TagTextEncoding encoding);
133  static const TagValue &empty();
134 
135  void assignText(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1,
137  void assignText(
138  const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
139  void assignInteger(int value);
140  void assignStandardGenreIndex(int index);
141  void assignData(const char *data, std::size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
142  void assignData(std::unique_ptr<char[]> &&data, std::size_t length, TagDataType type = TagDataType::Binary,
144  void assignPosition(PositionInSet value);
145  void assignTimeSpan(CppUtilities::TimeSpan value);
146  void assignDateTime(CppUtilities::DateTime value);
147 
148  static void stripBom(const char *&text, std::size_t &length, TagTextEncoding encoding);
149  static void ensureHostByteOrder(std::u16string &u16str, TagTextEncoding currentEncoding);
150  template <typename ContainerType,
151  CppUtilities::Traits::EnableIf<CppUtilities::Traits::IsIteratable<ContainerType>,
152  std::is_same<typename std::add_const<typename std::remove_pointer<typename ContainerType::value_type>::type>::type, const TagValue>>
153  * = nullptr>
154  static std::vector<std::string> toStrings(const ContainerType &values, TagTextEncoding encoding = TagTextEncoding::Utf8);
155  bool compareTo(const TagValue &other, TagValueComparisionFlags options = TagValueComparisionFlags::None) const;
156  bool compareData(const TagValue &other, bool ignoreCase = false) const;
157  static bool compareData(const std::string &data1, const std::string &data2, bool ignoreCase = false);
158  static bool compareData(const char *data1, std::size_t size1, const char *data2, std::size_t size2, bool ignoreCase = false);
159 
160 private:
161  std::unique_ptr<char[]> m_ptr;
162  std::size_t m_size;
163  std::string m_desc;
164  std::string m_mimeType;
165  std::string m_language;
166  TagDataType m_type;
167  TagTextEncoding m_encoding;
168  TagTextEncoding m_descEncoding;
169  bool m_labeledAsReadonly;
170 };
171 
176  : m_size(0)
177  , m_type(TagDataType::Undefined)
178  , m_encoding(TagTextEncoding::Latin1)
179  , m_descEncoding(TagTextEncoding::Latin1)
180  , m_labeledAsReadonly(false)
181 {
182 }
183 
188 {
189 }
190 
201 inline TagValue::TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding, TagTextEncoding convertTo)
202  : m_descEncoding(TagTextEncoding::Latin1)
203  , m_labeledAsReadonly(false)
204 {
205  assignText(text, textSize, textEncoding, convertTo);
206 }
207 
217 inline TagValue::TagValue(const char *text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
218 {
219  assignText(text, std::strlen(text), textEncoding, convertTo);
220 }
221 
231 inline TagValue::TagValue(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
232  : m_descEncoding(TagTextEncoding::Latin1)
233  , m_labeledAsReadonly(false)
234 {
235  assignText(text, textEncoding, convertTo);
236 }
237 
241 inline TagValue::TagValue(int value)
242  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::Integer)
243 {
244 }
245 
256 inline TagValue::TagValue(const char *data, std::size_t length, TagDataType type, TagTextEncoding encoding)
257  : m_size(length)
258  , m_type(type)
259  , m_encoding(encoding)
260  , m_descEncoding(TagTextEncoding::Latin1)
261  , m_labeledAsReadonly(false)
262 {
263  if (length) {
264  if (type == TagDataType::Text) {
265  stripBom(data, m_size, encoding);
266  }
267  m_ptr = std::make_unique<char[]>(m_size);
268  std::copy(data, data + m_size, m_ptr.get());
269  }
270 }
271 
284 inline TagValue::TagValue(std::unique_ptr<char[]> &&data, std::size_t length, TagDataType type, TagTextEncoding encoding)
285  : m_size(length)
286  , m_type(type)
287  , m_encoding(encoding)
288  , m_descEncoding(TagTextEncoding::Latin1)
289  , m_labeledAsReadonly(false)
290 {
291  if (length) {
292  m_ptr = move(data);
293  }
294 }
295 
300  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet)
301 {
302 }
303 
307 inline TagValue::TagValue(CppUtilities::DateTime value)
308  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::DateTime)
309 {
310 }
311 
315 inline TagValue::TagValue(CppUtilities::TimeSpan value)
316  : TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::TimeSpan)
317 {
318 }
319 
324 inline bool TagValue::operator==(const TagValue &other) const
325 {
327 }
328 
333 inline bool TagValue::operator!=(const TagValue &other) const
334 {
336 }
337 
347 inline void TagValue::assignText(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
348 {
349  assignText(text.data(), text.size(), textEncoding, convertTo);
350 }
351 
356 {
357  if (value.isNull()) {
359  clearData();
360  } else {
361  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet);
362  }
363 }
364 
368 inline void TagValue::assignTimeSpan(CppUtilities::TimeSpan value)
369 {
370  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::TimeSpan);
371 }
372 
376 inline void TagValue::assignDateTime(CppUtilities::DateTime value)
377 {
378  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::DateTime);
379 }
380 
387 {
388  assignInteger(index);
390 }
391 
396 {
397  return m_type;
398 }
399 
407 inline std::string TagValue::toString(TagTextEncoding encoding) const
408 {
409  std::string res;
410  toString(res, encoding);
411  return res;
412 }
413 
420 inline std::u16string TagValue::toWString(TagTextEncoding encoding) const
421 {
422  std::u16string res;
423  toWString(res, encoding);
424  return res;
425 }
426 
435 inline bool TagValue::isNull() const
436 {
437  return m_ptr == nullptr;
438 }
439 
449 inline bool TagValue::isEmpty() const
450 {
451  return m_ptr == nullptr || m_size == 0;
452 }
453 
460 inline void TagValue::clearData()
461 {
462  m_size = 0;
463  m_ptr.reset();
464 }
465 
472 {
473  clearData();
474  clearMetadata();
475 }
476 
481 inline std::size_t TagValue::dataSize() const
482 {
483  return m_size;
484 }
485 
492 inline char *TagValue::dataPointer()
493 {
494  return m_ptr.get();
495 }
496 
497 inline const char *TagValue::dataPointer() const
498 {
499  return m_ptr.get();
500 }
501 
511 inline const std::string &TagValue::description() const
512 {
513  return m_desc;
514 }
515 
526 inline void TagValue::setDescription(const std::string &value, TagTextEncoding encoding)
527 {
528  m_desc = value;
529  m_descEncoding = encoding;
530 }
531 
537 inline const std::string &TagValue::mimeType() const
538 {
539  return m_mimeType;
540 }
541 
547 inline void TagValue::setMimeType(const std::string &mimeType)
548 {
549  m_mimeType = mimeType;
550 }
551 
557 inline const std::string &TagValue::language() const
558 {
559  return m_language;
560 }
561 
567 inline void TagValue::setLanguage(const std::string &language)
568 {
569  m_language = language;
570 }
571 
580 inline bool TagValue::isLabeledAsReadonly() const
581 {
582  return m_labeledAsReadonly;
583 }
584 
593 inline void TagValue::setReadonly(bool readOnly)
594 {
595  m_labeledAsReadonly = readOnly;
596 }
597 
604 {
605  return m_encoding;
606 }
607 
614 {
615  return m_descEncoding;
616 }
617 
623 template <typename ContainerType,
624  CppUtilities::Traits::EnableIf<CppUtilities::Traits::IsIteratable<ContainerType>,
625  std::is_same<typename std::add_const<typename std::remove_pointer<typename ContainerType::value_type>::type>::type, const TagValue>> *>
626 std::vector<std::string> TagValue::toStrings(const ContainerType &values, TagTextEncoding encoding)
627 {
628  std::vector<std::string> res;
629  res.reserve(values.size());
630  for (const auto &value : values) {
631  res.emplace_back(CppUtilities::Traits::dereferenceMaybe(value).toString(encoding));
632  }
633  return res;
634 }
635 
639 inline bool TagValue::compareData(const TagValue &other, bool ignoreCase) const
640 {
641  return compareData(m_ptr.get(), m_size, other.m_ptr.get(), other.m_size, ignoreCase);
642 }
643 
647 inline bool TagValue::compareData(const std::string &data1, const std::string &data2, bool ignoreCase)
648 {
649  return compareData(data1.data(), data1.size(), data2.data(), data2.size(), ignoreCase);
650 }
651 
652 } // namespace TagParser
653 
655 
656 #endif // TAG_PARSER_TAGVALUE_H
positioninset.h
TagParser::TagValue::mimeType
const std::string & mimeType() const
Returns the MIME type.
Definition: tagvalue.h:537
TagParser::TagValueComparisionFlags::IgnoreMetaData
@ IgnoreMetaData
CPP_UTILITIES_MARK_FLAG_ENUM_CLASS
CPP_UTILITIES_MARK_FLAG_ENUM_CLASS(TagParser, TagParser::TagCreationFlags)
TagParser::TagValue::setReadonly
void setReadonly(bool readOnly)
Sets whether the TagValue is labeled as read-only.
Definition: tagvalue.h:593
TagParser::TagValue::assignTimeSpan
void assignTimeSpan(CppUtilities::TimeSpan value)
Assigns the given TimeSpan value.
Definition: tagvalue.h:368
TagParser::TagDataType::TimeSpan
@ TimeSpan
TagParser::TagTextEncoding::Utf8
@ Utf8
TagParser::TagValue::assignDateTime
void assignDateTime(CppUtilities::DateTime value)
Assigns the given DateTime value.
Definition: tagvalue.h:376
TagParser::TagValue::TagValue
TagValue()
Constructs an empty TagValue.
Definition: tagvalue.h:175
TagParser::TagValue::clearDataAndMetadata
void clearDataAndMetadata()
Wipes assigned data including meta data.
Definition: tagvalue.h:471
TagParser::TagTextEncoding
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:25
TagParser::TagValue::descriptionEncoding
TagTextEncoding descriptionEncoding() const
Returns the description encoding.
Definition: tagvalue.h:613
TagParser::TagValue::assignPosition
void assignPosition(PositionInSet value)
Assigns the given PositionInSet value.
Definition: tagvalue.h:355
TagParser::TagTextEncoding::Utf16BigEndian
@ Utf16BigEndian
TagParser::TagValue::compareData
bool compareData(const TagValue &other, bool ignoreCase=false) const
Returns whether the raw data of the current instance equals the raw data of other.
Definition: tagvalue.h:639
TagParser::TagTextEncoding::Unspecified
@ Unspecified
TagParser::Tag
The Tag class is used to store, read and write tag information.
Definition: tag.h:98
TagParser::TagValue::operator!=
bool operator!=(const TagValue &other) const
Returns whether both instances are not equal.
Definition: tagvalue.h:333
TagParser::TagValue::stripBom
static void stripBom(const char *&text, std::size_t &length, TagTextEncoding encoding)
Strips the byte order mask from the specified text.
Definition: tagvalue.cpp:876
TagParser::TagDataType::PositionInSet
@ PositionInSet
TagParser::TagDataType::StandardGenreIndex
@ StandardGenreIndex
TagParser::TagValue::dataPointer
char * dataPointer()
Returns a pointer to the raw data assigned to the current instance.
Definition: tagvalue.h:492
TagParser
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:10
TagParser::TagValueComparisionFlags::None
@ None
TagParser::TagValue::assignText
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:767
TagParser::characterSize
constexpr int characterSize(TagTextEncoding encoding)
Returns the size of one character for the specified encoding in bytes.
Definition: tagvalue.h:37
TagParser::MatroskaTagIds::language
constexpr const TAG_PARSER_EXPORT char * language()
Definition: matroskatagid.h:346
TagParser::TagValue::assignInteger
void assignInteger(int value)
Assigns the given integer value.
Definition: tagvalue.cpp:818
TagParser::TagValue::clearData
void clearData()
Clears the assigned data.
Definition: tagvalue.h:460
TagParser::TagDataType
TagDataType
Specifies the data type.
Definition: tagvalue.h:54
TagParser::TagValue::description
const std::string & description() const
Returns the description.
Definition: tagvalue.h:511
TagParser::TagValue::setMimeType
void setMimeType(const std::string &mimeType)
Sets the MIME type.
Definition: tagvalue.h:547
TagParser::TagValue::compareTo
bool compareTo(const TagValue &other, TagValueComparisionFlags options=TagValueComparisionFlags::None) const
Returns whether both instances are equal.
Definition: tagvalue.cpp:181
TagParser::operator==
constexpr bool operator==(std::uint8_t lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:18
TagParser::TagValue::isEmpty
bool isEmpty() const
Returns whether an empty value is assigned.
Definition: tagvalue.h:449
TagParser::TagValue::toStrings
static std::vector< std::string > toStrings(const ContainerType &values, TagTextEncoding encoding=TagTextEncoding::Utf8)
Converts the specified values to string using the specified encoding.
Definition: tagvalue.h:626
TagParser::PositionInSet::isNull
constexpr bool isNull() const
Returns an indication whether both the element position and total element count is 0.
Definition: positioninset.h:94
TagParser::TagTextEncoding::Latin1
@ Latin1
TagParser::TagDataType::Undefined
@ Undefined
TagParser::TagValue::toWString
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:420
TagParser::TagDataType::Text
@ Text
TagParser::operator!=
constexpr bool operator!=(std::uint8_t lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:23
TagParser::TagDataType::Picture
@ Picture
TagParser::TagValue::isNull
bool isNull() const
Returns whether no value is assigned at all.
Definition: tagvalue.h:435
TagParser::TagValue::assignStandardGenreIndex
void assignStandardGenreIndex(int index)
Assigns the given standard genre index to be assigned.
Definition: tagvalue.h:386
TagParser::TagValue::operator==
bool operator==(const TagValue &other) const
Returns whether both instances are equal.
Definition: tagvalue.h:324
TagParser::TagValue::clearMetadata
void clearMetadata()
Wipes assigned meta data.
Definition: tagvalue.cpp:307
TagParser::TagValue::dataSize
std::size_t dataSize() const
Returns the size of the assigned value in bytes.
Definition: tagvalue.h:481
TagParser::TagDataType::Binary
@ Binary
TagParser::TagValue
The TagValue class wraps values of different types. It is meant to be assigned to a tag field.
Definition: tagvalue.h:75
TagParser::TagValue::setDescription
void setDescription(const std::string &value, TagTextEncoding encoding=TagTextEncoding::Latin1)
Sets the description.
Definition: tagvalue.h:526
TagParser::TagTextEncoding::Utf16LittleEndian
@ Utf16LittleEndian
TagParser::TagDataType::DateTime
@ DateTime
TagParser::TagValueComparisionFlags::CaseInsensitive
@ CaseInsensitive
TagParser::MatroskaIds::Tag
@ Tag
Definition: matroskaid.h:204
TagParser::TagValue::toString
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:407
TagParser::TagValue::~TagValue
~TagValue()
Destroys the TagValue.
Definition: tagvalue.h:187
TAG_PARSER_EXPORT
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
TagParser::PositionInSet
The PositionInSet class describes the position of an element in a set which consists of a certain num...
Definition: positioninset.h:21
TagParser::TagValue::isLabeledAsReadonly
bool isLabeledAsReadonly() const
Returns an indication whether the value is labeled as read-only.
Definition: tagvalue.h:580
TagParser::TagValueComparisionFlags
TagValueComparisionFlags
The TagValueComparisionOption enum specifies options for TagValue::compareTo().
Definition: tagvalue.h:69
TagParser::TagValue::type
TagDataType type() const
Returns the type of the assigned value.
Definition: tagvalue.h:395
TagParser::TagValue::dataEncoding
TagTextEncoding dataEncoding() const
Returns the data encoding.
Definition: tagvalue.h:603
TagParser::TagValue::assignData
void assignData(const char *data, std::size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
TagParser::TagValue::setLanguage
void setLanguage(const std::string &language)
Sets the language.
Definition: tagvalue.h:567
TagParser::TagValue::language
const std::string & language() const
Returns the language.
Definition: tagvalue.h:557
TagParser::TagDataType::Integer
@ Integer
TagParser::MatroskaTagIds::description
constexpr const TAG_PARSER_EXPORT char * description()
Definition: matroskatagid.h:234