Tag Parser  6.2.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 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 
21 enum class TagTextEncoding : unsigned int
22 {
23  Latin1,
24  Utf8,
28 };
29 
34 inline int characterSize(TagTextEncoding encoding) {
35  switch(encoding) {
38  return 1;
41  return 2;
42  default:
43  return 0;
44  }
45 }
46 
50 enum class TagDataType : unsigned int
51 {
52  Text,
53  Integer,
56  TimeSpan,
57  DateTime,
58  Picture,
59  Binary,
60  Undefined
61 };
62 
64 {
65 public:
66  // constructor, destructor
67  TagValue();
68  TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
69  TagValue(const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
70  TagValue(int value);
71  TagValue(const char *data, size_t length, TagDataType type = TagDataType::Undefined, TagTextEncoding encoding = TagTextEncoding::Latin1);
72  TagValue(std::unique_ptr<char[]> &&data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
73  TagValue(const PositionInSet &value);
74  TagValue(const TagValue &other);
75  TagValue(TagValue &&other) = default;
76  ~TagValue();
77 
78  // operators
79  TagValue &operator=(const TagValue &other);
80  TagValue &operator=(TagValue &&other) = default;
81  bool operator==(const TagValue &other) const;
82  bool operator!=(const TagValue &other) const;
83 
84  // methods
85  bool isEmpty() const;
86  void clearData();
87  void clearMetadata();
88  void clearDataAndMetadata();
89  TagDataType type() const;
90  std::string toString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
91  void toString(std::string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
92  std::u16string toWString(TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
93  void toWString(std::u16string &result, TagTextEncoding encoding = TagTextEncoding::Unspecified) const;
94  int32 toInteger() const;
95  int toStandardGenreIndex() const;
96  PositionInSet toPositionInSet() const;
97  ChronoUtilities::TimeSpan toTimeSpan() const;
98  ChronoUtilities::DateTime toDateTime() const;
99  size_t dataSize() const;
100  char *dataPointer() const;
101  const std::string &description() const;
102  void setDescription(const std::string &value, TagTextEncoding encoding = TagTextEncoding::Latin1);
103  const std::string &mimeType() const;
104  void setMimeType(const std::string &value);
105  const std::string &language() const;
106  void setLanguage(const std::string &value);
107  bool isLabeledAsReadonly() const;
108  void setReadonly(bool value);
109  TagTextEncoding dataEncoding() const;
110  void convertDataEncoding(TagTextEncoding encoding);
111  void convertDataEncodingForTag(const Tag *tag);
112  TagTextEncoding descriptionEncoding() const;
113  static const TagValue &empty();
114 
115  void assignText(const char *text, std::size_t textSize, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
116  void assignText(const std::string &text, TagTextEncoding textEncoding = TagTextEncoding::Latin1, TagTextEncoding convertTo = TagTextEncoding::Unspecified);
117  void assignInteger(int value);
118  void assignStandardGenreIndex(int index);
119  void assignData(const char *data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
120  void assignData(std::unique_ptr<char[]> &&data, size_t length, TagDataType type = TagDataType::Binary, TagTextEncoding encoding = TagTextEncoding::Latin1);
121  void assignPosition(PositionInSet value);
122  void assignTimeSpan(ChronoUtilities::TimeSpan value);
123  void assignDateTime(ChronoUtilities::DateTime value);
124 
125 
126 private:
127  void stripBom(const char *&text, size_t &length, TagTextEncoding encoding);
128 
129  std::unique_ptr<char[]> m_ptr;
130  std::string::size_type m_size;
131  TagDataType m_type;
132  std::string m_desc;
133  std::string m_mimeType;
134  std::string m_lng;
135  bool m_labeledAsReadonly;
136  TagTextEncoding m_encoding;
137  TagTextEncoding m_descEncoding;
138 };
139 
144  m_size(0),
145  m_type(TagDataType::Undefined),
146  m_labeledAsReadonly(false),
147  m_encoding(TagTextEncoding::Latin1),
148  m_descEncoding(TagTextEncoding::Latin1)
149 {}
150 
161 inline TagValue::TagValue(const char *text, std::size_t textSize, TagTextEncoding textEncoding, TagTextEncoding convertTo) :
162  m_labeledAsReadonly(false),
163  m_descEncoding(TagTextEncoding::Latin1)
164 {
165  assignText(text, textSize, textEncoding, convertTo);
166 }
167 
177 inline TagValue::TagValue(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo) :
178  m_labeledAsReadonly(false),
179  m_descEncoding(TagTextEncoding::Latin1)
180 {
181  assignText(text, textEncoding, convertTo);
182 }
183 
187 inline TagValue::TagValue(int value) :
188  TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::Integer)
189 {}
190 
201 inline TagValue::TagValue(const char *data, size_t length, TagDataType type, TagTextEncoding encoding) :
202  m_size(length),
203  m_type(type),
204  m_labeledAsReadonly(false),
205  m_encoding(encoding),
206  m_descEncoding(TagTextEncoding::Latin1)
207 {
208  if(length) {
209  if(type == TagDataType::Text) {
210  stripBom(data, m_size, encoding);
211  }
212  m_ptr = std::make_unique<char []>(m_size);
213  std::copy(data, data + m_size, m_ptr.get());
214  }
215 }
216 
229 inline TagValue::TagValue(std::unique_ptr<char[]> &&data, size_t length, TagDataType type, TagTextEncoding encoding) :
230  m_size(length),
231  m_type(type),
232  m_labeledAsReadonly(false),
233  m_encoding(encoding),
234  m_descEncoding(TagTextEncoding::Latin1)
235 {
236  if(length) {
237  m_ptr = move(data);
238  }
239 }
240 
245 inline TagValue::TagValue(const PositionInSet &value) :
246  TagValue(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet)
247 {}
248 
253 inline bool TagValue::operator!=(const TagValue &other) const
254 {
255  return !(*this == other);
256 }
257 
267 inline void TagValue::assignText(const std::string &text, TagTextEncoding textEncoding, TagTextEncoding convertTo)
268 {
269  assignText(text.data(), text.size(), textEncoding, convertTo);
270 }
271 
276 {
277  if(value.isNull()) {
279  clearData();
280  } else {
281  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::PositionInSet);
282  }
283 }
284 
289 {
290  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::TimeSpan);
291 }
292 
297 {
298  assignData(reinterpret_cast<const char *>(&value), sizeof(value), TagDataType::DateTime);
299 }
300 
305 {
306  return m_type;
307 }
308 
316 inline std::string TagValue::toString(TagTextEncoding encoding) const
317 {
318  std::string res;
319  toString(res, encoding);
320  return res;
321 }
322 
329 inline std::u16string TagValue::toWString(TagTextEncoding encoding) const
330 {
331  std::u16string res;
332  toWString(res, encoding);
333  return res;
334 }
335 
340 inline bool TagValue::isEmpty() const
341 {
342  return m_ptr == nullptr || m_size == 0;
343 }
344 
351 inline void TagValue::clearData()
352 {
353  m_size = 0;
354  m_ptr.reset();
355 }
356 
361 inline size_t TagValue::dataSize() const
362 {
363  return m_size;
364 }
365 
372 inline char *TagValue::dataPointer() const
373 {
374  return m_ptr.get();
375 }
376 
383 inline const std::string &TagValue::description() const
384 {
385  return m_desc;
386 }
387 
396 inline void TagValue::setDescription(const std::string &value, TagTextEncoding encoding)
397 {
398  m_desc = value;
399  m_descEncoding = encoding;
400 }
401 
407 inline const std::string &TagValue::mimeType() const
408 {
409  return m_mimeType;
410 }
411 
418 inline void TagValue::setMimeType(const std::string &value)
419 {
420  m_mimeType = value;
421 }
422 
428 inline const std::string &TagValue::language() const
429 {
430  return m_lng;
431 }
432 
439 inline void TagValue::setLanguage(const std::string &value)
440 {
441  m_lng = value;
442 }
443 
452 inline bool TagValue::isLabeledAsReadonly() const
453 {
454  return m_labeledAsReadonly;
455 }
456 
465 inline void TagValue::setReadonly(bool value)
466 {
467  m_labeledAsReadonly = value;
468 }
469 
476 {
477  return m_encoding;
478 }
479 
486 {
487  return m_descEncoding;
488 }
489 
490 }
491 
492 #endif // TAGVALUE_H
The TagValue class wraps values of different types.
Definition: tagvalue.h:63
void setDescription(const std::string &value, TagTextEncoding encoding=TagTextEncoding::Latin1)
Sets the description.
Definition: tagvalue.h:396
TAG_PARSER_EXPORT const char * language()
bool isEmpty() const
Returns an indication whether an value is assigned.
Definition: tagvalue.h:340
TagTextEncoding dataEncoding() const
Returns the data encoding.
Definition: tagvalue.h:475
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:550
char * dataPointer() const
Returns a pointer to the raw data assigned to the current instance.
Definition: tagvalue.h:372
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:329
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:21
constexpr bool operator!=(byte lhs, FlacMetaDataBlockType type)
Definition: flacmetadata.h:33
void assignTimeSpan(ChronoUtilities::TimeSpan value)
Assigns the given TimeSpan value.
Definition: tagvalue.h:288
void assignDateTime(ChronoUtilities::DateTime value)
Assigns the given DateTime value.
Definition: tagvalue.h:296
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:428
TagValue()
Constructs an empty TagValue.
Definition: tagvalue.h:143
TagDataType type() const
Returns the type of the assigned value.
Definition: tagvalue.h:304
TagTextEncoding descriptionEncoding() const
Returns the description encoding.
Definition: tagvalue.h:485
void clearData()
Clears the assigned data.
Definition: tagvalue.h:351
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:253
void assignPosition(PositionInSet value)
Assigns the given PositionInSet value.
Definition: tagvalue.h:275
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:629
int characterSize(TagTextEncoding encoding)
Returns the size of one character for the specified encoding in bytes.
Definition: tagvalue.h:34
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:50
bool isLabeledAsReadonly() const
Returns an indication whether the value is labeled as read-only.
Definition: tagvalue.h:452
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:439
void setMimeType(const std::string &value)
Sets the MIME type.
Definition: tagvalue.h:418
const std::string & mimeType() const
Returns the MIME type.
Definition: tagvalue.h:407
const std::string & description() const
Returns the description.
Definition: tagvalue.h:383
#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:361
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:316
void setReadonly(bool value)
Sets whether the TagValue is labeled as read-only.
Definition: tagvalue.h:465
constexpr bool isNull() const
Returns an indication whether both the element position and total element count is 0...
Definition: positioninset.h:91