Tag Parser 11.3.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Member Functions | Static Public Member Functions | List of all members
TagParser::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 char *text, 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 (std::string_view 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 (std::uint64_t value)
 Constructs a new TagValue holding the given unsigned integer value. More...
 
 TagValue (const char *data, std::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, std::size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
 Constructs a new TagValue holding with the given data. More...
 
 TagValue (PositionInSet value)
 Constructs a new TagValue holding a copy of the given PositionInSet value. More...
 
 TagValue (CppUtilities::DateTime value)
 Constructs a new TagValue holding a copy of the given DateTime value. More...
 
 TagValue (CppUtilities::TimeSpan value)
 Constructs a new TagValue holding a copy of the given TimeSpan value. More...
 
 TagValue (const Popularity &value)
 Constructs a new TagValue holding a copy of the given Popularity 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...
 
 operator bool () const
 Returns whether the value is not empty. More...
 
bool isNull () const
 Returns whether no value is assigned at all. More...
 
bool isEmpty () const
 Returns whether no or an empty 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...
 
std::string toDisplayString () const
 Returns a "display string" for the specified value. 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...
 
std::int32_t toInteger () const
 Converts the value of the current TagValue object to its equivalent integer representation. More...
 
std::uint64_t toUnsignedInteger () const
 
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...
 
CppUtilities::TimeSpan toTimeSpan () const
 Converts the value of the current TagValue object to its equivalent TimeSpan representation. More...
 
CppUtilities::DateTime toDateTime () const
 Converts the value of the current TagValue object to its equivalent DateTime representation. More...
 
Popularity toPopularity () const
 Converts the value of the current TagValue object to its equivalent Popularity representation. More...
 
std::size_t dataSize () const
 Returns the size of the assigned value in bytes. More...
 
char * dataPointer ()
 Returns a pointer to the raw data assigned to the current instance. More...
 
const char * dataPointer () const
 
std::string_view data () const
 Returns the currently assigned raw data. More...
 
const std::string & description () const
 Returns the description. More...
 
void setDescription (std::string_view value, TagTextEncoding encoding=TagTextEncoding::Latin1)
 Sets the description. More...
 
const std::string & mimeType () const
 Returns the MIME type. More...
 
void setMimeType (std::string_view mimeType)
 Sets the MIME type. More...
 
const Localelocale () const
 Returns the locale. More...
 
Localelocale ()
 Returns the locale. More...
 
void setLocale (const Locale &locale)
 Sets the setLocale. More...
 
TagValueFlags flags () const
 Returns the flags. More...
 
void setFlags (TagValueFlags flags)
 Sets the flags. More...
 
bool isLabeledAsReadonly () const
 Returns an indication whether the value is labeled as read-only. More...
 
void setReadonly (bool readOnly)
 Sets whether the TagValue is labeled as read-only. More...
 
const std::unordered_map< std::string, std::string > & nativeData () const
 Holds tag format specific meta-data for that field which does not fit into any of the other meta-data properties. More...
 
std::unordered_map< std::string, std::string > & nativeData ()
 Holds tag format specific meta-data for that field which does not fit into any of the other meta-data properties. 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 convertDescriptionEncoding (TagTextEncoding encoding)
 Converts the assigned description to use the specified 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 assignText (std::string_view 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 assignUnsignedInteger (std::uint64_t value)
 Assigns the given unsigned integer value. More...
 
void assignStandardGenreIndex (int index)
 Assigns the given standard genre index to be assigned. More...
 
void assignData (const char *data, std::size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
 
void assignData (std::unique_ptr< char[]> &&data, std::size_t length, TagDataType type=TagDataType::Binary, TagTextEncoding encoding=TagTextEncoding::Latin1)
 
void assignPosition (PositionInSet value)
 Assigns the given PositionInSet value. More...
 
void assignTimeSpan (CppUtilities::TimeSpan value)
 Assigns the given TimeSpan value. More...
 
void assignDateTime (CppUtilities::DateTime value)
 Assigns the given DateTime value. More...
 
void assignPopularity (const Popularity &value)
 Assigns the specified popularity value. More...
 
bool compareTo (const TagValue &other, TagValueComparisionFlags options=TagValueComparisionFlags::None) const
 Returns whether both instances are equal. More...
 
bool compareData (const TagValue &other, bool ignoreCase=false) const
 Returns whether the raw data of the current instance equals the raw data of other. More...
 

Static Public Member Functions

static const TagValueempty ()
 Returns a default-constructed TagValue where TagValue::isNull() and TagValue::isEmpty() both return true. More...
 
static void stripBom (const char *&text, std::size_t &length, TagTextEncoding encoding)
 Strips the byte order mask from the specified text. More...
 
static void ensureHostByteOrder (std::u16string &u16str, TagTextEncoding currentEncoding)
 Ensures the byte-order of the specified UTF-16 string matches the byte-order of the machine. More...
 
template<typename ContainerType , CppUtilities::Traits::EnableIf< CppUtilities::Traits::IsIteratable< ContainerType >, std::is_same< typename std::add_const< typename std::remove_pointer< typename ContainerType::value_type >::type >::type, const TagValue > > * = nullptr>
static std::vector< std::string > toStrings (const ContainerType &values, TagTextEncoding encoding=TagTextEncoding::Utf8)
 Converts the specified values to string using the specified encoding. More...
 
static bool compareData (const std::string &data1, const std::string &data2, bool ignoreCase=false)
 Returns whether 2 data buffers are equal. More...
 
static bool compareData (const char *data1, std::size_t size1, const char *data2, std::size_t size2, bool ignoreCase=false)
 Returns whether 2 data buffers are equal. More...
 

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 TagParser::TagDataType.

When constructing a TagValue choose the type which suites the value you want to store best. If the tag format uses a different type the serializer will take care of the neccassary conversion (eg. convert an integer to a string).

When consuming a TagValue read from a tag one should not expect that a particular type is used. The type depends on what the particular tag format uses. However, the conversion functions provided by the TagValue class take care of neccassary conversions, eg. TagValue::toInteger() will attempt to convert a string to a number (an possibly throw a ConversionException on failure).

Values of the type TagDataType::Text can be differently encoded. See TagParser::TagTextEncoding for a list of supported encodings. Be sure to use an encoding which is supported by the tag implementation. To ensure that, the functions Tag::canEncodingBeUsed(), Tag::proposedTextEncoding() and Tag::ensureTextValuesAreProperlyEncoded() can be used.

Values of the type TagDataType::Text are not supposed to contain Byte-Order-Marks. Before assigning text which might be prepended by a Byte-Order-Mark the helper function TagValue::stripBom() can be used.

Definition at line 130 of file tagvalue.h.

Constructor & Destructor Documentation

◆ TagValue() [1/15]

TagParser::TagValue::TagValue ( )
inlineexplicit

Constructs an empty TagValue.

Definition at line 251 of file tagvalue.h.

◆ TagValue() [2/15]

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

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 277 of file tagvalue.h.

◆ TagValue() [3/15]

TagParser::TagValue::TagValue ( const char *  text,
TagTextEncoding  textEncoding = TagTextEncoding::Latin1,
TagTextEncoding  convertTo = TagTextEncoding::Unspecified 
)
inlineexplicit

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

Parameters
textSpecifies the text to be assigned. This string must be null-terminated.
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 293 of file tagvalue.h.

◆ TagValue() [4/15]

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

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 307 of file tagvalue.h.

◆ TagValue() [5/15]

TagParser::TagValue::TagValue ( std::string_view  text,
TagTextEncoding  textEncoding = TagTextEncoding::Latin1,
TagTextEncoding  convertTo = TagTextEncoding::Unspecified 
)
inlineexplicit

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 323 of file tagvalue.h.

◆ TagValue() [6/15]

TagParser::TagValue::TagValue ( int  value)
inlineexplicit

Constructs a new TagValue holding the given integer value.

Definition at line 333 of file tagvalue.h.

◆ TagValue() [7/15]

TagParser::TagValue::TagValue ( std::uint64_t  value)
inlineexplicit

Constructs a new TagValue holding the given unsigned integer value.

Definition at line 341 of file tagvalue.h.

◆ TagValue() [8/15]

TagParser::TagValue::TagValue ( const char *  data,
std::size_t  length,
TagDataType  type = TagDataType::Undefined,
TagTextEncoding  encoding = TagTextEncoding::Latin1 
)
inlineexplicit

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 356 of file tagvalue.h.

◆ TagValue() [9/15]

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

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 384 of file tagvalue.h.

◆ TagValue() [10/15]

TagParser::TagValue::TagValue ( PositionInSet  value)
inlineexplicit

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

Definition at line 399 of file tagvalue.h.

◆ TagValue() [11/15]

TagParser::TagValue::TagValue ( CppUtilities::DateTime  value)
inlineexplicit

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

Definition at line 407 of file tagvalue.h.

◆ TagValue() [12/15]

TagParser::TagValue::TagValue ( CppUtilities::TimeSpan  value)
inlineexplicit

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

Definition at line 415 of file tagvalue.h.

◆ TagValue() [13/15]

TagParser::TagValue::TagValue ( const Popularity value)
inlineexplicit

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

Definition at line 423 of file tagvalue.h.

◆ TagValue() [14/15]

TagParser::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 103 of file tagvalue.cpp.

◆ TagValue() [15/15]

TagParser::TagValue::TagValue ( TagValue &&  other)
default

◆ ~TagValue()

TagParser::TagValue::~TagValue ( )
inline

Destroys the TagValue.

Definition at line 263 of file tagvalue.h.

Member Function Documentation

◆ assignData() [1/2]

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

◆ assignData() [2/2]

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

◆ assignDateTime()

void TagParser::TagValue::assignDateTime ( CppUtilities::DateTime  value)
inline

Assigns the given DateTime value.

Definition at line 508 of file tagvalue.h.

◆ assignInteger()

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

Assigns the given integer value.

Parameters
valueSpecifies the integer to be assigned.

Definition at line 1006 of file tagvalue.cpp.

◆ assignPopularity()

void TagParser::TagValue::assignPopularity ( const Popularity value)

Assigns the specified popularity value.

Definition at line 1077 of file tagvalue.cpp.

◆ assignPosition()

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

Assigns the given PositionInSet value.

Definition at line 487 of file tagvalue.h.

◆ assignStandardGenreIndex()

void TagParser::TagValue::assignStandardGenreIndex ( int  index)
inline

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 518 of file tagvalue.h.

◆ assignText() [1/3]

void TagParser::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 955 of file tagvalue.cpp.

◆ assignText() [2/3]

void TagParser::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 465 of file tagvalue.h.

◆ assignText() [3/3]

void TagParser::TagValue::assignText ( std::string_view  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 479 of file tagvalue.h.

◆ assignTimeSpan()

void TagParser::TagValue::assignTimeSpan ( CppUtilities::TimeSpan  value)
inline

Assigns the given TimeSpan value.

Definition at line 500 of file tagvalue.h.

◆ assignUnsignedInteger()

void TagParser::TagValue::assignUnsignedInteger ( std::uint64_t  value)

Assigns the given unsigned integer value.

Parameters
valueSpecifies the unsigned integer to be assigned.

Definition at line 1019 of file tagvalue.cpp.

◆ clearData()

void TagParser::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 595 of file tagvalue.h.

◆ clearDataAndMetadata()

void TagParser::TagValue::clearDataAndMetadata ( )
inline

Wipes assigned data including meta data.

See also
clearData()
clearMetadata()

Definition at line 606 of file tagvalue.h.

◆ clearMetadata()

void TagParser::TagValue::clearMetadata ( )

Wipes assigned meta data.

Definition at line 331 of file tagvalue.cpp.

◆ compareData() [1/3]

bool TagParser::TagValue::compareData ( const char *  data1,
std::size_t  size1,
const char *  data2,
std::size_t  size2,
bool  ignoreCase = false 
)
static

Returns whether 2 data buffers are equal.

In case one of the sizes is zero, no pointer is dereferenced.

Definition at line 1148 of file tagvalue.cpp.

◆ compareData() [2/3]

bool TagParser::TagValue::compareData ( const std::string &  data1,
const std::string &  data2,
bool  ignoreCase = false 
)
inlinestatic

Returns whether 2 data buffers are equal.

Definition at line 856 of file tagvalue.h.

◆ compareData() [3/3]

bool TagParser::TagValue::compareData ( const TagValue other,
bool  ignoreCase = false 
) const
inline

Returns whether the raw data of the current instance equals the raw data of other.

Definition at line 848 of file tagvalue.h.

◆ compareTo()

bool TagParser::TagValue::compareTo ( const TagValue other,
TagValueComparisionFlags  options = TagValueComparisionFlags::None 
) const

Returns whether both instances are equal.

Meta-data like description and MIME-type is taken into account as well.

  • other Specifies the other instance.
  • options Specifies options to alter the behavior. See TagValueComparisionFlags for details.
    Remarks
    • If the data types are not equal, two instances are still considered equal if the string representation is identical. For instance the text "2" is considered equal to the integer 2. This also means that an empty TagValue and the integer 0 are not considered equal.
    • The choice to allow implicit conversions was made because different tag formats use different types and usually one does not care about those internals when comparing values.
    • If any of the differently typed values can not be converted to a string (eg. it is binary data) the values are not considered equal. So the text "foo" and the binary value "foo" are not considered equal although the raw data is identical.
    • In fact, values of the types TagDataType::DateTime, TagDataType::TimeSpan, TagDataType::Picture, TagDataType::Binary and TagDataType::Unspecified will never be considered equal with a value of another type.
    • If the type is TagDataType::Text and the encoding differs values might still be considered equal if they represent the same characters. The same counts for the description.
    • This might be a costly operation due to possible conversions.
    See also

Definition at line 188 of file tagvalue.cpp.

◆ convertDataEncoding()

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

Converts the currently assigned text value to the specified encoding.

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

Definition at line 674 of file tagvalue.cpp.

◆ convertDataEncodingForTag()

void TagParser::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 716 of file tagvalue.cpp.

◆ convertDescriptionEncoding()

void TagParser::TagValue::convertDescriptionEncoding ( TagTextEncoding  encoding)

Converts the assigned description to use the specified encoding.

Definition at line 726 of file tagvalue.cpp.

◆ data()

std::string_view TagParser::TagValue::data ( ) const
inline

Returns the currently assigned raw data.

Definition at line 640 of file tagvalue.h.

◆ dataEncoding()

TagTextEncoding TagParser::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 812 of file tagvalue.h.

◆ dataPointer() [1/2]

char * TagParser::TagValue::dataPointer ( )
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 TagValue gets destroyed or another value is assigned.
The raw data is not null terminated. See dataSize().

Definition at line 627 of file tagvalue.h.

◆ dataPointer() [2/2]

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

Definition at line 632 of file tagvalue.h.

◆ dataSize()

std::size_t TagParser::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 616 of file tagvalue.h.

◆ description()

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

Returns the description.

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
See also

Definition at line 655 of file tagvalue.h.

◆ descriptionEncoding()

TagTextEncoding TagParser::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 822 of file tagvalue.h.

◆ empty()

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

Returns a default-constructed TagValue where TagValue::isNull() and TagValue::isEmpty() both return true.

Remarks
This is useful if one wants to return a const reference to a TagValue and a null-value is needed to indicate that the field does not exist at all.

Definition at line 1178 of file tagvalue.cpp.

◆ ensureHostByteOrder()

void TagParser::TagValue::ensureHostByteOrder ( std::u16string &  u16str,
TagTextEncoding  currentEncoding 
)
static

Ensures the byte-order of the specified UTF-16 string matches the byte-order of the machine.

Remarks
Does nothing if currentEncoding already matches the byte-order of the machine.

Definition at line 1128 of file tagvalue.cpp.

◆ flags()

TagValueFlags TagParser::TagValue::flags ( ) const
inline

Returns the flags.

See also
TagValueFlags

Definition at line 747 of file tagvalue.h.

◆ isEmpty()

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

Returns whether no or an empty value is assigned.

Remarks
  • An empty string and empty binary or picture data counts as empty so this function will return true for those. However, the integer 0, a TimeSpan of zero length, ... are not considered empty and this function will return false.
  • Meta-data such as description and MIME-type is not considered as an assigned value.

Definition at line 584 of file tagvalue.h.

◆ isLabeledAsReadonly()

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

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

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
  • 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 770 of file tagvalue.h.

◆ isNull()

bool TagParser::TagValue::isNull ( ) const
inline

Returns whether no value is assigned at all.

Remarks
  • Returns only true for default constructed instances or cleared instances (using TagValue::clearData()). So for empty strings, the integer 0, a TimeSpan of zero length, ... this function returns false.
  • Meta-data such as description and MIME-type is not considered as an assigned value.

Definition at line 571 of file tagvalue.h.

◆ locale() [1/2]

Locale & TagParser::TagValue::locale ( )
inline

Returns the locale.

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
  • The format of the locale is specific to the tag format. The implementation of the tag format might store the value without further validation.
See also
setLocale()

Definition at line 724 of file tagvalue.h.

◆ locale() [2/2]

const Locale & TagParser::TagValue::locale ( ) const
inline

Returns the locale.

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
  • The format of the locale is specific to the tag format. The implementation of the tag format might store the value without further validation.
See also
setLocale()

Definition at line 710 of file tagvalue.h.

◆ mimeType()

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

Returns the MIME type.

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
See also
setMimeType()

Definition at line 684 of file tagvalue.h.

◆ nativeData() [1/2]

std::unordered_map< std::string, std::string > & TagParser::TagValue::nativeData ( )
inline

Holds tag format specific meta-data for that field which does not fit into any of the other meta-data properties.

Definition at line 802 of file tagvalue.h.

◆ nativeData() [2/2]

const std::unordered_map< std::string, std::string > & TagParser::TagValue::nativeData ( ) const
inline

Holds tag format specific meta-data for that field which does not fit into any of the other meta-data properties.

Definition at line 793 of file tagvalue.h.

◆ operator bool()

TagParser::TagValue::operator bool ( ) const
inline

Returns whether the value is not empty.

See also
See TagValue::isEmpty() for a definition on what is considered empty.

Definition at line 451 of file tagvalue.h.

◆ operator!=()

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

Returns whether both instances are not equal.

See also
The negation of TagValue::compareTo() with TagValueComparisionOption::None so see TagValue::compareTo() for details.

Definition at line 442 of file tagvalue.h.

◆ operator=() [1/2]

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

Assigns the value of another TagValue to the current instance.

Definition at line 122 of file tagvalue.cpp.

◆ operator=() [2/2]

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

◆ operator==()

bool TagParser::TagValue::operator== ( const TagValue other) const
inline

Returns whether both instances are equal.

See also
The same as TagValue::compareTo() with TagValueComparisionOption::None so see TagValue::compareTo() for details.

Definition at line 433 of file tagvalue.h.

◆ setDescription()

void TagParser::TagValue::setDescription ( std::string_view  value,
TagTextEncoding  encoding = TagTextEncoding::Latin1 
)
inline

Sets the description.

Parameters
valueSpecifies the description.
encodingSpecifies the encoding used to provide the description.
Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
See also

Definition at line 671 of file tagvalue.h.

◆ setFlags()

void TagParser::TagValue::setFlags ( TagValueFlags  flags)
inline

Sets the flags.

See also
TagValueFlags

Definition at line 756 of file tagvalue.h.

◆ setLocale()

void TagParser::TagValue::setLocale ( const Locale locale)
inline

Sets the setLocale.

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
  • The format of the locale is specific to the tag format. The implementation of the tag format might store the value without further validation.
See also
locale()

Definition at line 738 of file tagvalue.h.

◆ setMimeType()

void TagParser::TagValue::setMimeType ( std::string_view  mimeType)
inline

Sets the MIME type.

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
See also
mimeType()

Definition at line 696 of file tagvalue.h.

◆ setReadonly()

void TagParser::TagValue::setReadonly ( bool  readOnly)
inline

Sets whether the TagValue is labeled as read-only.

Remarks
  • Whether this additional meta-data is available and can be used depends on the tag format. It will be ignored by the implementation of the tag format if not supported.
  • 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 784 of file tagvalue.h.

◆ stripBom()

void TagParser::TagValue::stripBom ( const char *&  text,
std::size_t &  length,
TagTextEncoding  encoding 
)
static

Strips the byte order mask from the specified text.

Definition at line 1099 of file tagvalue.cpp.

◆ toDateTime()

DateTime TagParser::TagValue::toDateTime ( ) const

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

Exceptions
ThrowsConversionException on failure.

Definition at line 594 of file tagvalue.cpp.

◆ toDisplayString()

std::string TagParser::TagValue::toDisplayString ( ) const

Returns a "display string" for the specified value.

Returns
  • Returns the just the type if no displayable string can be made of it, eg. "picture", otherwise returns the string representation.
  • Returns "invalid …" if a conversion error returned when making the string representation but never throws a ConversionException (unlike toString()).

Definition at line 350 of file tagvalue.cpp.

◆ toInteger()

std::int32_t TagParser::TagValue::toInteger ( ) const

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

Exceptions
ThrowsConversionException on failure.

Definition at line 371 of file tagvalue.cpp.

◆ toPopularity()

Popularity TagParser::TagValue::toPopularity ( ) const

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

Exceptions
ThrowsConversionException on failure.

Definition at line 628 of file tagvalue.cpp.

◆ toPositionInSet()

PositionInSet TagParser::TagValue::toPositionInSet ( ) const

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

Exceptions
ThrowsConversionException on failure.

Definition at line 506 of file tagvalue.cpp.

◆ toStandardGenreIndex()

int TagParser::TagValue::toStandardGenreIndex ( ) const

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

Exceptions
ThrowsConversionException on failure.

Definition at line 456 of file tagvalue.cpp.

◆ toString() [1/2]

void TagParser::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
Exceptions
ThrowsConversionException on failure.

Definition at line 776 of file tagvalue.cpp.

◆ toString() [2/2]

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

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
Exceptions
ThrowsConversionException on failure.

Definition at line 544 of file tagvalue.h.

◆ toStrings()

template<typename ContainerType , CppUtilities::Traits::EnableIf< CppUtilities::Traits::IsIteratable< ContainerType >, std::is_same< typename std::add_const< typename std::remove_pointer< typename ContainerType::value_type >::type >::type, const TagValue > > * >
std::vector< std::string > TagParser::TagValue::toStrings ( const ContainerType &  values,
TagTextEncoding  encoding = TagTextEncoding::Utf8 
)
static

Converts the specified values to string using the specified encoding.

Exceptions
ThrowsConversionException on failure.
See also
toString()

Definition at line 835 of file tagvalue.h.

◆ toTimeSpan()

TimeSpan TagParser::TagValue::toTimeSpan ( ) const

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

Exceptions
ThrowsConversionException on failure.

Definition at line 555 of file tagvalue.cpp.

◆ toUnsignedInteger()

std::uint64_t TagParser::TagValue::toUnsignedInteger ( ) const

Definition at line 413 of file tagvalue.cpp.

◆ toWString() [1/2]

void TagParser::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
  • Not all types can be converted to a string, eg. TagDataType::Picture, TagDataType::Binary and TagDataType::Unspecified will always fail to convert.
  • Use this only, if encoding is an UTF-16 encoding.
See also
toString()

Definition at line 865 of file tagvalue.cpp.

◆ toWString() [2/2]

std::u16string TagParser::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 557 of file tagvalue.h.

◆ type()

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

Returns the type of the assigned value.

Definition at line 527 of file tagvalue.h.


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