Tag Parser  6.5.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Member Functions | Static Public Member Functions | Friends | List of all members
Media::TagValue Class Reference

The TagValue class wraps values of different types. More...

#include <tagvalue.h>

Public Member Functions

 TagValue ()
 Constructs an empty TagValue. More...
 
 TagValue (const char *text, std::size_t textSize, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
 Constructs a new TagValue holding a copy of the given text. More...
 
 TagValue (const std::string &text, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
 Constructs a new TagValue holding a copy of the given text. More...
 
 TagValue (int value)
 Constructs a new TagValue holding the given integer value. More...
 
 TagValue (const char *data, size_t length, TagDataType type=TagDataType::Undefined, TagTextEncoding encoding=TagTextEncoding::Latin1)
 Constructs a new TagValue with a copy of the given data. More...
 
 TagValue (std::unique_ptr< char[]> &&data, size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
 Constructs a new TagValue holding with the given data. More...
 
 TagValue (const PositionInSet &value)
 Constructs a new TagValue holding a copy of the given PositionInSet value. More...
 
 TagValue (const TagValue &other)
 Constructs a new TagValue holding a copy of the given TagValue instance. More...
 
 TagValue (TagValue &&other)=default
 
 ~TagValue ()
 Destroys the TagValue. More...
 
TagValueoperator= (const TagValue &other)
 Assigns the value of another TagValue to the current instance. More...
 
TagValueoperator= (TagValue &&other)=default
 
bool operator== (const TagValue &other) const
 Returns whether both instances are equal. More...
 
bool operator!= (const TagValue &other) const
 Returns whether both instances are not equal. More...
 
bool isEmpty () const
 Returns an indication whether an value is assigned. More...
 
void clearData ()
 Clears the assigned data. More...
 
void clearMetadata ()
 Wipes assigned meta data. More...
 
void clearDataAndMetadata ()
 Wipes assigned data including meta data. More...
 
TagDataType type () const
 Returns the type of the assigned value. More...
 
std::string toString (TagTextEncoding encoding=TagTextEncoding::Unspecified) const
 Converts the value of the current TagValue object to its equivalent std::string representation. More...
 
void toString (std::string &result, TagTextEncoding encoding=TagTextEncoding::Unspecified) const
 Converts the value of the current TagValue object to its equivalent std::string representation. More...
 
std::u16string toWString (TagTextEncoding encoding=TagTextEncoding::Unspecified) const
 Converts the value of the current TagValue object to its equivalent std::wstring representation. More...
 
void toWString (std::u16string &result, TagTextEncoding encoding=TagTextEncoding::Unspecified) const
 Converts the value of the current TagValue object to its equivalent std::u16string representation. More...
 
int32 toInteger () const
 Converts the value of the current TagValue object to its equivalent integer representation. More...
 
int toStandardGenreIndex () const
 Converts the value of the current TagValue object to its equivalent standard genre index. More...
 
PositionInSet toPositionInSet () const
 Converts the value of the current TagValue object to its equivalent PositionInSet representation. More...
 
ChronoUtilities::TimeSpan toTimeSpan () const
 Converts the value of the current TagValue object to its equivalent TimeSpan representation. More...
 
ChronoUtilities::DateTime toDateTime () const
 Converts the value of the current TagValue object to its equivalent DateTime representation. More...
 
size_t dataSize () const
 Returns the size of the assigned value in bytes. More...
 
char * dataPointer () const
 Returns a pointer to the raw data assigned to the current instance. More...
 
const std::string & description () const
 Returns the description. More...
 
void setDescription (const std::string &value, TagTextEncoding encoding=TagTextEncoding::Latin1)
 Sets the description. More...
 
const std::string & mimeType () const
 Returns the MIME type. More...
 
void setMimeType (const std::string &value)
 Sets the MIME type. More...
 
const std::string & language () const
 Returns the language. More...
 
void setLanguage (const std::string &value)
 Sets the language. More...
 
bool isLabeledAsReadonly () const
 Returns an indication whether the value is labeled as read-only. More...
 
void setReadonly (bool value)
 Sets whether the TagValue is labeled as read-only. More...
 
TagTextEncoding dataEncoding () const
 Returns the data encoding. More...
 
void convertDataEncoding (TagTextEncoding encoding)
 Converts the currently assigned text value to the specified encoding. More...
 
void convertDataEncodingForTag (const Tag *tag)
 Ensures the encoding of the currently assigned text value is supported by the specified tag. More...
 
TagTextEncoding descriptionEncoding () const
 Returns the description encoding. More...
 
void assignText (const char *text, std::size_t textSize, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
 Assigns a copy of the given text. More...
 
void assignText (const std::string &text, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
 Assigns a copy of the given text. More...
 
void assignInteger (int value)
 Assigns the given integer value. More...
 
void assignStandardGenreIndex (int index)
 Assigns the given standard genre index to be assigned. More...
 
void assignData (const char *data, size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
 Assigns a copy of the given data. More...
 
void assignData (std::unique_ptr< char[]> &&data, size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
 Assigns the given data. More...
 
void assignPosition (PositionInSet value)
 Assigns the given PositionInSet value. More...
 
void assignTimeSpan (ChronoUtilities::TimeSpan value)
 Assigns the given TimeSpan value. More...
 
void assignDateTime (ChronoUtilities::DateTime value)
 Assigns the given DateTime value. More...
 

Static Public Member Functions

static const TagValueempty ()
 Returns an empty TagValue. More...
 

Friends

class Id3v2Frame
 

Detailed Description

The TagValue class wraps values of different types.

It is meant to be assigned to a tag field.

For a list of supported types see Media::TagDataType.

Definition at line 64 of file tagvalue.h.

Constructor & Destructor Documentation

◆ TagValue() [1/9]

Media::TagValue::TagValue ( )
inline

Constructs an empty TagValue.

Definition at line 147 of file tagvalue.h.

◆ TagValue() [2/9]

Media::TagValue::TagValue ( const char *  text,
std::size_t  textSize,
TagTextEncoding  textEncoding = TagTextEncoding::Latin1,
TagTextEncoding  convertTo = TagTextEncoding::Unspecified 
)
inline

Constructs a new TagValue holding a copy of the given text.

Parameters
textSpecifies the text to be assigned.
textSizeSpecifies the size of text. (The actual number of bytes, not the number of characters.)
textEncodingSpecifies the encoding of the given text.
convertToSpecifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.
Exceptions
Throwsa ConversionException if the conversion the specified character set fails.
Remarks
Strips the BOM of the specified text.

Definition at line 165 of file tagvalue.h.

◆ TagValue() [3/9]

Media::TagValue::TagValue ( const std::string &  text,
TagTextEncoding  textEncoding = TagTextEncoding::Latin1,
TagTextEncoding  convertTo = TagTextEncoding::Unspecified 
)
inline

Constructs a new TagValue holding a copy of the given text.

Parameters
textSpecifies the text to be assigned.
textEncodingSpecifies the encoding of the given text.
convertToSpecifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.
Exceptions
Throwsa ConversionException if the conversion the specified character set fails.
Remarks
Strips the BOM of the specified text.

Definition at line 181 of file tagvalue.h.

◆ TagValue() [4/9]

Media::TagValue::TagValue ( int  value)
inline

Constructs a new TagValue holding the given integer value.

Definition at line 191 of file tagvalue.h.

◆ TagValue() [5/9]

Media::TagValue::TagValue ( const char *  data,
size_t  length,
TagDataType  type = TagDataType::Undefined,
TagTextEncoding  encoding = TagTextEncoding::Latin1 
)
inline

Constructs a new TagValue with a copy of the given data.

Parameters
dataSpecifies a pointer to the data.
lengthSpecifies the length of the data.
typeSpecifies the type of the data as TagDataType.
encodingSpecifies the encoding of the data as TagTextEncoding. The encoding will only be considered if a text is assigned.
Remarks
Strips the BOM of the specified data if type is TagDataType::Text.

Definition at line 205 of file tagvalue.h.

◆ TagValue() [6/9]

Media::TagValue::TagValue ( std::unique_ptr< char[]> &&  data,
size_t  length,
TagDataType  type = TagDataType::Binary,
TagTextEncoding  encoding = TagTextEncoding::Latin1 
)
inline

Constructs a new TagValue holding with the given data.

The data is not copied. It is moved.

Parameters
dataSpecifies a pointer to the data.
lengthSpecifies the length of the data.
typeSpecifies the type of the data as TagDataType.
encodingSpecifies the encoding of the data as TagTextEncoding. The encoding will only be considered if a text is assigned.
Remarks
Does not strip the BOM so for consistency the caller must ensure there is no BOM present.

Definition at line 233 of file tagvalue.h.

◆ TagValue() [7/9]

Media::TagValue::TagValue ( const PositionInSet value)
inline

Constructs a new TagValue holding a copy of the given PositionInSet value.

Parameters
valueSpecifies the PositionInSet.

Definition at line 249 of file tagvalue.h.

◆ TagValue() [8/9]

Media::TagValue::TagValue ( const TagValue other)

Constructs a new TagValue holding a copy of the given TagValue instance.

Parameters
otherSpecifies another TagValue instance.

Definition at line 31 of file tagvalue.cpp.

◆ TagValue() [9/9]

Media::TagValue::TagValue ( TagValue &&  other)
default

◆ ~TagValue()

Media::TagValue::~TagValue ( )

Destroys the TagValue.

Definition at line 128 of file tagvalue.cpp.

Member Function Documentation

◆ assignData() [1/2]

void Media::TagValue::assignData ( const char *  data,
size_t  length,
TagDataType  type = TagDataType::Binary,
TagTextEncoding  encoding = TagTextEncoding::Latin1 
)

Assigns a copy of the given data.

Parameters
dataSpecifies the data to be assigned.
lengthSpecifies the length of the data.
typeSpecifies the type of the data as TagDataType.
encodingSpecifies the encoding of the data as TagTextEncoding. The encoding will only be considered if a text is assigned.

Definition at line 648 of file tagvalue.cpp.

◆ assignData() [2/2]

void Media::TagValue::assignData ( std::unique_ptr< char[]> &&  data,
size_t  length,
TagDataType  type = TagDataType::Binary,
TagTextEncoding  encoding = TagTextEncoding::Latin1 
)

Assigns the given data.

Takes ownership.

The specified data is not copied. It is moved.

Parameters
dataSpecifies the data to be assigned.
lengthSpecifies the length of the data.
typeSpecifies the type of the data as TagDataType.
encodingSpecifies the encoding of the data as TagTextEncoding. The encoding will only be considered if a text is assigned.
Remarks
Does not strip the BOM so for consistency the caller must ensure there is no BOM present.

Definition at line 678 of file tagvalue.cpp.

◆ assignDateTime()

void Media::TagValue::assignDateTime ( ChronoUtilities::DateTime  value)
inline

Assigns the given DateTime value.

Definition at line 300 of file tagvalue.h.

◆ assignInteger()

void Media::TagValue::assignInteger ( int  value)

Assigns the given integer value.

Parameters
valueSpecifies the integer to be assigned.

Definition at line 620 of file tagvalue.cpp.

◆ assignPosition()

void Media::TagValue::assignPosition ( PositionInSet  value)
inline

Assigns the given PositionInSet value.

Definition at line 279 of file tagvalue.h.

◆ assignStandardGenreIndex()

void Media::TagValue::assignStandardGenreIndex ( int  index)

Assigns the given standard genre index to be assigned.

Parameters
indexSpecifies the index to be assigned.
See also
List of genres - Wikipedia

Definition at line 634 of file tagvalue.cpp.

◆ assignText() [1/2]

void Media::TagValue::assignText ( const char *  text,
std::size_t  textSize,
TagTextEncoding  textEncoding = TagTextEncoding::Latin1,
TagTextEncoding  convertTo = TagTextEncoding::Unspecified 
)

Assigns a copy of the given text.

Parameters
textSpecifies the text to be assigned.
textSizeSpecifies the size of text. (The actual number of bytes, not the number of characters.)
textEncodingSpecifies the encoding of the given text.
convertToSpecifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.
Exceptions
Throwsa ConversionException if the conversion the specified character set fails.
Remarks
Strips the BOM of the specified text.

Definition at line 569 of file tagvalue.cpp.

◆ assignText() [2/2]

void Media::TagValue::assignText ( const std::string &  text,
TagTextEncoding  textEncoding = TagTextEncoding::Latin1,
TagTextEncoding  convertTo = TagTextEncoding::Unspecified 
)
inline

Assigns a copy of the given text.

Parameters
textSpecifies the text to be assigned.
textEncodingSpecifies the encoding of the given text.
convertToSpecifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.
Exceptions
Throwsa ConversionException if the conversion the specified character set fails.
Remarks
Strips the BOM of the specified text.

Definition at line 271 of file tagvalue.h.

◆ assignTimeSpan()

void Media::TagValue::assignTimeSpan ( ChronoUtilities::TimeSpan  value)
inline

Assigns the given TimeSpan value.

Definition at line 292 of file tagvalue.h.

◆ clearData()

void Media::TagValue::clearData ( )
inline

Clears the assigned data.

Remarks
Meta data such as description and MIME type remains unaffected.
See also
clearMetadata()
clearDataAndMetadata()

Definition at line 355 of file tagvalue.h.

◆ clearDataAndMetadata()

void Media::TagValue::clearDataAndMetadata ( )

Wipes assigned data including meta data.

See also
clearData()
clearMetadata()

Definition at line 153 of file tagvalue.cpp.

◆ clearMetadata()

void Media::TagValue::clearMetadata ( )

Wipes assigned meta data.

Definition at line 138 of file tagvalue.cpp.

◆ convertDataEncoding()

void Media::TagValue::convertDataEncoding ( TagTextEncoding  encoding)

Converts the currently assigned text value to the specified encoding.

Exceptions
ThrowsConversionUtilities::ConversionException() if the conversion fails.
Remarks
See also
convertDataEncodingForTag()

Definition at line 359 of file tagvalue.cpp.

◆ convertDataEncodingForTag()

void Media::TagValue::convertDataEncodingForTag ( const Tag tag)

Ensures the encoding of the currently assigned text value is supported by the specified tag.

See also
This is a convenience method for convertDataEncoding().

Definition at line 400 of file tagvalue.cpp.

◆ dataEncoding()

TagTextEncoding Media::TagValue::dataEncoding ( ) const
inline

Returns the data encoding.

Remarks
This value is only relevant if type() equals TagDataType::Text.
See also
assignText()

Definition at line 479 of file tagvalue.h.

◆ dataPointer()

char * Media::TagValue::dataPointer ( ) const
inline

Returns a pointer to the raw data assigned to the current instance.

Remarks
The instance keeps ownership over the data which will be invalidated when the it gets destroyed or an other value is assigned.
The raw data is not null terminated. See dataSize().

Definition at line 376 of file tagvalue.h.

◆ dataSize()

size_t Media::TagValue::dataSize ( ) const
inline

Returns the size of the assigned value in bytes.

Remarks
Meta data such as description and MIME type is not considered as part of the assigned value.

Definition at line 365 of file tagvalue.h.

◆ description()

const std::string & Media::TagValue::description ( ) const
inline

Returns the description.

Remarks
The usage of this meta information depends on the tag implementation.
See also
descriptionEncoding()
setDescription()

Definition at line 387 of file tagvalue.h.

◆ descriptionEncoding()

TagTextEncoding Media::TagValue::descriptionEncoding ( ) const
inline

Returns the description encoding.

Remarks
This value is only relevant if a description is assigned.
See also
description(), setDescription()

Definition at line 489 of file tagvalue.h.

◆ empty()

const TagValue & Media::TagValue::empty ( )
static

Returns an empty TagValue.

Definition at line 739 of file tagvalue.cpp.

◆ isEmpty()

bool Media::TagValue::isEmpty ( ) const
inline

Returns an indication whether an value is assigned.

Remarks
Meta data such as description and MIME type is not considered as an assigned value.

Definition at line 344 of file tagvalue.h.

◆ isLabeledAsReadonly()

bool Media::TagValue::isLabeledAsReadonly ( ) const
inline

Returns an indication whether the value is labeled as read-only.

Remarks
The usage of this meta information depends on the tag implementation.
This is just an additional information. It has no effect on the behavior of the TagValue thus assignments can still be performed (to prohibit assignments simply use the "const" keyword).
See also
setReadonly()

Definition at line 456 of file tagvalue.h.

◆ language()

const std::string & Media::TagValue::language ( ) const
inline

Returns the language.

Remarks
The usage of this meta information depends on the tag implementation.
See also
setLanguage()

Definition at line 432 of file tagvalue.h.

◆ mimeType()

const std::string & Media::TagValue::mimeType ( ) const
inline

Returns the MIME type.

Remarks
The usage of this meta information depends on the tag implementation.
See also
setMimeType()

Definition at line 411 of file tagvalue.h.

◆ operator!=()

bool Media::TagValue::operator!= ( const TagValue other) const
inline

Returns whether both instances are not equal.

Remarks
Simply the negation of operator==() so check there for details.

Definition at line 257 of file tagvalue.h.

◆ operator=() [1/2]

TagValue & Media::TagValue::operator= ( const TagValue other)

Assigns the value of another TagValue to the current instance.

Definition at line 50 of file tagvalue.cpp.

◆ operator=() [2/2]

TagValue& Media::TagValue::operator= ( TagValue &&  other)
default

◆ operator==()

bool Media::TagValue::operator== ( const TagValue other) const

Returns whether both instances are equal.

If the data types are not equal, two instances are still considered equal if the string representation is identical. The encoding and meta data must be equal as well if relevant for the data type.

See also
TagValueTests::testEqualityOperator()

Definition at line 79 of file tagvalue.cpp.

◆ setDescription()

void Media::TagValue::setDescription ( const std::string &  value,
TagTextEncoding  encoding = TagTextEncoding::Latin1 
)
inline

Sets the description.

Parameters
valueSpecifies the description.
encodingSpecifies the encoding used to provide the description.
Remarks
The usage of this meta information depends on the tag implementation.
See also
description()
descriptionEncoding()

Definition at line 400 of file tagvalue.h.

◆ setLanguage()

void Media::TagValue::setLanguage ( const std::string &  value)
inline

Sets the language.

Parameters
valueSpecifies the language.
Remarks
The usage of this meta information depends on the tag implementation.
See also
language()

Definition at line 443 of file tagvalue.h.

◆ setMimeType()

void Media::TagValue::setMimeType ( const std::string &  value)
inline

Sets the MIME type.

Parameters
valueSpecifies the mime type.
Remarks
The usage of this meta information depends on the tag implementation.
See also
mimeType()

Definition at line 422 of file tagvalue.h.

◆ setReadonly()

void Media::TagValue::setReadonly ( bool  value)
inline

Sets whether the TagValue is labeled as read-only.

Remarks
The usage of this meta information depends on the tag implementation.
This is just an additional information. It has no effect on the behavior of the TagValue thus assignments can still be performed (to prohibit assignments simply use the "const" keyword).
See also
isLabeledAsReadonly()

Definition at line 469 of file tagvalue.h.

◆ toDateTime()

DateTime Media::TagValue::toDateTime ( ) const

Converts the value of the current TagValue object to its equivalent DateTime representation.

Exceptions
ThrowsConversionException on failure.

Definition at line 309 of file tagvalue.cpp.

◆ toInteger()

int32 Media::TagValue::toInteger ( ) const

Converts the value of the current TagValue object to its equivalent integer representation.

Exceptions
ThrowsConversionException on failure.

Definition at line 164 of file tagvalue.cpp.

◆ toPositionInSet()

PositionInSet Media::TagValue::toPositionInSet ( ) const

Converts the value of the current TagValue object to its equivalent PositionInSet representation.

Exceptions
ThrowsConversionException on failure.

Definition at line 243 of file tagvalue.cpp.

◆ toStandardGenreIndex()

int Media::TagValue::toStandardGenreIndex ( ) const

Converts the value of the current TagValue object to its equivalent standard genre index.

Exceptions
ThrowsConversionException on failure.

Definition at line 200 of file tagvalue.cpp.

◆ toString() [1/2]

std::string Media::TagValue::toString ( TagTextEncoding  encoding = TagTextEncoding::Unspecified) const
inline

Converts the value of the current TagValue object to its equivalent std::string representation.

Parameters
encodingSpecifies the encoding to to be used; set to TagTextEncoding::Unspecified to use the present encoding without any character set conversion.
Exceptions
ThrowsConversionException on failure.

Definition at line 320 of file tagvalue.h.

◆ toString() [2/2]

void Media::TagValue::toString ( std::string &  result,
TagTextEncoding  encoding = TagTextEncoding::Unspecified 
) const

Converts the value of the current TagValue object to its equivalent std::string representation.

Parameters
resultSpecifies the string to store the result.
encodingSpecifies the encoding to to be used; set to TagTextEncoding::Unspecified to use the present encoding without any character set conversion.
Remarks
If UTF-16 is the desired output encoding, it makes sense to use the toWString() method instead.
Exceptions
ThrowsConversionException on failure.

Definition at line 416 of file tagvalue.cpp.

◆ toTimeSpan()

TimeSpan Media::TagValue::toTimeSpan ( ) const

Converts the value of the current TagValue object to its equivalent TimeSpan representation.

Exceptions
ThrowsConversionException on failure.

Definition at line 281 of file tagvalue.cpp.

◆ toWString() [1/2]

std::u16string Media::TagValue::toWString ( TagTextEncoding  encoding = TagTextEncoding::Unspecified) const
inline

Converts the value of the current TagValue object to its equivalent std::wstring representation.

Exceptions
ThrowsConversionException on failure.
Remarks
Use this only, if encoding is an UTF-16 encoding.

Definition at line 333 of file tagvalue.h.

◆ toWString() [2/2]

void Media::TagValue::toWString ( std::u16string &  result,
TagTextEncoding  encoding = TagTextEncoding::Unspecified 
) const

Converts the value of the current TagValue object to its equivalent std::u16string representation.

Exceptions
ThrowsConversionException on failure.
Remarks
Use this only, if encoding is an UTF-16 encoding.
See also
toString()

Definition at line 492 of file tagvalue.cpp.

◆ type()

TagDataType Media::TagValue::type ( ) const
inline

Returns the type of the assigned value.

Definition at line 308 of file tagvalue.h.

Friends And Related Function Documentation

◆ Id3v2Frame

friend class Id3v2Frame
friend

Definition at line 66 of file tagvalue.h.


The documentation for this class was generated from the following files: