Tag Parser  6.5.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 TAGVALUE_H
2 #define TAGVALUE_H
3 
4 #include "./positioninset.h"
5 
6 #include <c++utilities/conversion/binaryconversion.h>
7 #include <c++utilities/chrono/timespan.h>
8 #include <c++utilities/chrono/datetime.h>
9 
10 #include <iosfwd>
11 #include <string>
12 #include <memory>
13 
14 namespace Media {
15 
16 class Tag;
17 class Id3v2Frame;
18 
22 enum class TagTextEncoding : unsigned int
23 {
24  Latin1,
25  Utf8,
29 };
30 
35 inline int characterSize(TagTextEncoding encoding) {
36  switch(encoding) {
39  return 1;
42  return 2;
43  default:
44  return 0;
45  }
46 }
47 
51 enum class TagDataType : unsigned int
52 {
53  Text,
54  Integer,
57  TimeSpan,
58  DateTime,
59  Picture,
60  Binary,
61  Undefined
62 };
63 
65 {
66  friend class Id3v2Frame; // FIXME: make ensureHostByteOrder() public in next minor release
67 
68 public:
69  // constructor, destructor
70  TagValue();
71  TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
72  TagValue(const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
73  TagValue(int value);
74  TagValue(const char *data, size_t length, TagDataType type = TagDataType::Undefined, TagTextEncoding encoding = TagTextEncoding::Latin1);
75  TagValue(std::unique_ptr<char[]> &&data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
76  TagValue(const PositionInSet &value);
77  TagValue(const TagValue &other);
78  TagValue(TagValue &&other) = default;
79  ~TagValue();
80 
81  // operators
82  TagValue &operator=(const TagValue &other);
83  TagValue &operator=(TagValue &&other) = default;
84  bool operator==(const TagValue &other) const;
85  bool operator!=(const TagValue &other) const;
86 
87  // methods
88  bool isEmpty() const;
89  void clearData();
90  void clearMetadata();
91  void clearDataAndMetadata();
92  TagDataType type() const;
93  std::string toString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
94  void toString(std::string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
95  std::u16string toWString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
96  void toWString(std::u16string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
97  int32 toInteger() const;
98  int toStandardGenreIndex() const;
99  PositionInSet toPositionInSet() const;
100  ChronoUtilities::TimeSpan toTimeSpan() const;
101  ChronoUtilities::DateTime toDateTime() const;
102  size_t dataSize() const;
103  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 &value);
108  const std::string &language() const;
109  void setLanguage(const std::string &value);
110  bool isLabeledAsReadonly() const;
111  void setReadonly(bool value);
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, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
119  void assignText(const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
120  void assignInteger(int value);
121  void assignStandardGenreIndex(int index);
122  void assignData(const char *data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
123  void assignData(std::unique_ptr<char[]> &&data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
124  void assignPosition(PositionInSet value);
125  void assignTimeSpan(ChronoUtilities::TimeSpan value);
126  void assignDateTime(ChronoUtilities::DateTime value);
127 
128 
129 private:
130  static void stripBom(const char *&text, size_t &length, TagTextEncoding encoding);
131  static void ensureHostByteOrder(std::u16string &u16str, TagTextEncoding currentEncoding);
132 
133  std::unique_ptr<char[]> m_ptr;
134  std::string::size_type m_size;
135  TagDataType m_type;
136  std::string m_desc;
137  std::string m_mimeType;
138  std::string m_lng;
139  bool m_labeledAsReadonly;
140  TagTextEncoding m_encoding;
141  TagTextEncoding m_descEncoding;
142 };
143 
148  m_size(0),
149  m_type(TagDataType::Undefined),
150  m_labeledAsReadonly(false),
151  m_encoding(TagTextEncoding::Latin1),
152  m_descEncoding(TagTextEncoding::Latin1)
153 {}
154 
165 inline TagValue::TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding, TagTextEncoding convertTo) :
166  m_labeledAsReadonly(false),
167  m_descEncoding(TagTextEncoding::Latin1)
168 {
169  assignText(text, textSize, textEncoding, convertTo);
170 }
171 
181 inline TagValue::TagValue(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo) :
182  m_labeledAsReadonly(false),
183  m_descEncoding(TagTextEncoding::Latin1)
184 {
185  assignText(text, textEncoding, convertTo);
186 }
187 
191 inline TagValue::TagValue(int value) :
192  TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::Integer)
193 {}
194 
205 inline TagValue::TagValue(const char *data, size_t length, TagDataType type, TagTextEncoding encoding) :
206  m_size(length),
207  m_type(type),
208  m_labeledAsReadonly(false),
209  m_encoding(encoding),
210  m_descEncoding(TagTextEncoding::Latin1)
211 {
212  if(length) {
213  if(type == TagDataType::Text) {
214  stripBom(data, m_size, encoding);
215  }
216  m_ptr = std::make_unique<char []>(m_size);
217  std::copy(data, data + m_size, m_ptr.get());
218  }
219 }
220 
233 inline TagValue::TagValue(std::unique_ptr<char[]> &&data, size_t length, TagDataType type, TagTextEncoding encoding) :
234  m_size(length),
235  m_type(type),
236  m_labeledAsReadonly(false),
237  m_encoding(encoding),
238  m_descEncoding(TagTextEncoding::Latin1)
239 {
240  if(length) {
241  m_ptr = move(data);
242  }
243 }
244 
249 inline TagValue::TagValue(const PositionInSet &value) :
250  TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet)
251 {}
252 
257 inline bool TagValue::operator!=(const TagValue &other) const
258 {
259  return !(*this == other);
260 }
261 
271 inline void TagValue::assignText(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
272 {
273  assignText(text.data(), text.size(), textEncoding, convertTo);
274 }
275 
280 {
281  if(value.isNull()) {
283  clearData();
284  } else {
285  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet);
286  }
287 }
288 
293 {
294  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::TimeSpan);
295 }
296 
301 {
302  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::DateTime);
303 }
304 
309 {
310  return m_type;
311 }
312 
320 inline std::string TagValue::toString(TagTextEncoding encoding) const
321 {
322  std::string res;
323  toString(res, encoding);
324  return res;
325 }
326 
333 inline std::u16string TagValue::toWString(TagTextEncoding encoding) const
334 {
335  std::u16string res;
336  toWString(res, encoding);
337  return res;
338 }
339 
344 inline bool TagValue::isEmpty() const
345 {
346  return m_ptr == nullptr || m_size == 0;
347 }
348 
355 inline void TagValue::clearData()
356 {
357  m_size = 0;
358  m_ptr.reset();
359 }
360 
365 inline size_t TagValue::dataSize() const
366 {
367  return m_size;
368 }
369 
376 inline char *TagValue::dataPointer() const
377 {
378  return m_ptr.get();
379 }
380 
387 inline const std::string &TagValue::description() const
388 {
389  return m_desc;
390 }
391 
400 inline void TagValue::setDescription(const std::string &value, TagTextEncoding encoding)
401 {
402  m_desc = value;
403  m_descEncoding = encoding;
404 }
405 
411 inline const std::string &TagValue::mimeType() const
412 {
413  return m_mimeType;
414 }
415 
422 inline void TagValue::setMimeType(const std::string &value)
423 {
424  m_mimeType = value;
425 }
426 
432 inline const std::string &TagValue::language() const
433 {
434  return m_lng;
435 }
436 
443 inline void TagValue::setLanguage(const std::string &value)
444 {
445  m_lng = value;
446 }
447 
456 inline bool TagValue::isLabeledAsReadonly() const
457 {
458  return m_labeledAsReadonly;
459 }
460 
469 inline void TagValue::setReadonly(bool value)
470 {
471  m_labeledAsReadonly = value;
472 }
473 
480 {
481  return m_encoding;
482 }
483 
490 {
491  return m_descEncoding;
492 }
493 
494 }
495 
496 #endif // TAGVALUE_H
The TagValue class wraps values of different types.
Definition: tagvalue.h:64
void setDescription(const std::string &value, TagTextEncoding encoding=TagTextEncoding::Latin1)
Sets the description.
Definition: tagvalue.h:400
TAG_PARSER_EXPORT const char * language()
bool isEmpty() const
Returns an indication whether an value is assigned.
Definition: tagvalue.h:344
TagTextEncoding dataEncoding() const
Returns the data encoding.
Definition: tagvalue.h:479
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:569
char * dataPointer() const
Returns a pointer to the raw data assigned to the current instance.
Definition: tagvalue.h:376
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:333
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:22
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition: id3v2frame.h:100
constexpr bool operator!=(byte lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:33
void assignTimeSpan(ChronoUtilities::TimeSpan value)
Assigns the given TimeSpan value.
Definition: tagvalue.h:292
void assignDateTime(ChronoUtilities::DateTime value)
Assigns the given DateTime value.
Definition: tagvalue.h:300
The PositionInSet class describes the position of an element in a set which consists of a certain num...
Definition: positioninset.h:20
const std::string & language() const
Returns the language.
Definition: tagvalue.h:432
TagValue()
Constructs an empty TagValue.
Definition: tagvalue.h:147
TagDataType type() const
Returns the type of the assigned value.
Definition: tagvalue.h:308
TagTextEncoding descriptionEncoding() const
Returns the description encoding.
Definition: tagvalue.h:489
void clearData()
Clears the assigned data.
Definition: tagvalue.h:355
The Tag class is used to store, read and write tag information.
Definition: tag.h:98
bool operator!=(const TagValue &other) const
Returns whether both instances are not equal.
Definition: tagvalue.h:257
void assignPosition(PositionInSet value)
Assigns the given PositionInSet value.
Definition: tagvalue.h:279
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:648
int characterSize(TagTextEncoding encoding)
Returns the size of one character for the specified encoding in bytes.
Definition: tagvalue.h:35
TAG_PARSER_EXPORT const char * description()
constexpr bool operator==(byte lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:28
TagDataType
Specifies the data type.
Definition: tagvalue.h:51
bool isLabeledAsReadonly() const
Returns an indication whether the value is labeled as read-only.
Definition: tagvalue.h:456
Contains all classes and functions of the TagInfo library.
Definition: exceptions.h:9
void setLanguage(const std::string &value)
Sets the language.
Definition: tagvalue.h:443
void setMimeType(const std::string &value)
Sets the MIME type.
Definition: tagvalue.h:422
const std::string & mimeType() const
Returns the MIME type.
Definition: tagvalue.h:411
const std::string & description() const
Returns the description.
Definition: tagvalue.h:387
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
size_t dataSize() const
Returns the size of the assigned value in bytes.
Definition: tagvalue.h:365
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:320
void setReadonly(bool value)
Sets whether the TagValue is labeled as read-only.
Definition: tagvalue.h:469
constexpr bool isNull() const
Returns an indication whether both the element position and total element count is 0...
Definition: positioninset.h:91