Tag Parser: TagParser::TagValue Class Reference

Tag Parser 12.5.3 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
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.
| 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.
| TagValue (const char *text, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
| Constructs a new TagValue holding a copy of the given text.
| TagValue (const std::string &text, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
| Constructs a new TagValue holding a copy of the given text.
| TagValue (std::string_view text, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
| Constructs a new TagValue holding a copy of the given text.
| TagValue (int value)
| Constructs a new TagValue holding the given integer value.
| TagValue (std::uint64_t value)
| Constructs a new TagValue holding the given unsigned integer value.
| 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.
| 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.
| TagValue (PositionInSet value)
| Constructs a new TagValue holding a copy of the given PositionInSet value.
| TagValue (CppUtilities::DateTime value)
| Constructs a new TagValue holding a copy of the given DateTime value.
| TagValue (const CppUtilities::DateTimeExpression &value)
| Constructs a new TagValue holding a copy of the given DateTimeExpression value.
| TagValue (CppUtilities::TimeSpan value)
| Constructs a new TagValue holding a copy of the given TimeSpan value.
| TagValue (const Popularity &value)
| Constructs a new TagValue holding a copy of the given Popularity value.
| TagValue (const TagValue &other)
| Constructs a new TagValue holding a copy of the given TagValue instance.
| TagValue (TagValue &&other)
| ~TagValue ()
| Destroys the TagValue.
TagValue & | operator= (const TagValue &other)
| Assigns the value of another TagValue to the current instance.
TagValue & | operator= (TagValue &&other)
bool | operator== (const TagValue &other) const
| Returns whether both instances are equal.
bool | operator!= (const TagValue &other) const
| Returns whether both instances are not equal.
| operator bool () const
| Returns whether the value is not empty.
bool | isNull () const
| Returns whether no value is assigned at all.
bool | isEmpty () const
| Returns whether no or an empty value is assigned.
void | clearData ()
| Clears the assigned data.
void | clearMetadata ()
| Wipes assigned meta data.
void | clearDataAndMetadata ()
| Wipes assigned data including meta data.
TagDataType | type () const
| Returns the type of the assigned value.
std::string | toString (TagTextEncoding encoding=TagTextEncoding::Unspecified) const
| Converts the value of the current TagValue object to its equivalent std::string representation.
std::string | toDisplayString () const
| Returns a "display string" for the specified value.
void | toString (std::string &result, TagTextEncoding encoding=TagTextEncoding::Unspecified) const
| Converts the value of the current TagValue object to its equivalent std::string representation.
std::u16string | toWString (TagTextEncoding encoding=TagTextEncoding::Unspecified) const
| Converts the value of the current TagValue object to its equivalent std::wstring representation.
void | toWString (std::u16string &result, TagTextEncoding encoding=TagTextEncoding::Unspecified) const
| Converts the value of the current TagValue object to its equivalent std::u16string representation.
std::int32_t | toInteger () const
| Converts the value of the current TagValue object to its equivalent integer representation.
std::uint64_t | toUnsignedInteger () const
int | toStandardGenreIndex () const
| Converts the value of the current TagValue object to its equivalent standard genre index.
PositionInSet | toPositionInSet () const
| Converts the value of the current TagValue object to its equivalent PositionInSet representation.
CppUtilities::TimeSpan | toTimeSpan () const
| Converts the value of the current TagValue object to its equivalent TimeSpan representation.
CppUtilities::DateTime | toDateTime () const
| Converts the value of the current TagValue object to its equivalent DateTime representation (using the UTC timezone).
CppUtilities::DateTimeExpression | toDateTimeExpression () const
| Converts the value of the current TagValue object to its equivalent DateTimeExpression representation.
Popularity | toPopularity () const
| Converts the value of the current TagValue object to its equivalent Popularity representation.
Popularity | toScaledPopularity (TagType scale=TagType::Unspecified) const
| Converts the value of the current TagValue object to its equivalent Popularity representation using the specified scale.
std::size_t | dataSize () const
| Returns the size of the assigned value in bytes.
char * | dataPointer ()
| Returns a pointer to the raw data assigned to the current instance.
const char * | dataPointer () const
std::string_view | data () const
| Returns the currently assigned raw data.
const std::string & | description () const
| Returns the description.
void | setDescription (std::string_view value, TagTextEncoding encoding=TagTextEncoding::Latin1)
| Sets the description.
const std::string & | mimeType () const
| Returns the MIME type.
void | setMimeType (std::string_view mimeType)
| Sets the MIME type.
const Locale & | locale () const
| Returns the locale.
Locale & | locale ()
| Returns the locale.
void | setLocale (const Locale &locale)
| Sets the setLocale.
TagValueFlags | flags () const
| Returns the flags.
void | setFlags (TagValueFlags flags)
| Sets the flags.
bool | isLabeledAsReadonly () const
| Returns an indication whether the value is labeled as read-only.
void | setReadonly (bool readOnly)
| Sets whether the TagValue is labeled as read-only.
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.
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.
TagTextEncoding | dataEncoding () const
| Returns the data encoding.
void | convertDataEncoding (TagTextEncoding encoding)
| Converts the currently assigned text value to the specified encoding.
void | convertDataEncodingForTag (const Tag *tag)
| Ensures the encoding of the currently assigned text value is supported by the specified tag.
TagTextEncoding | descriptionEncoding () const
| Returns the description encoding.
void | convertDescriptionEncoding (TagTextEncoding encoding)
| Converts the assigned description to use the specified encoding.
void | assignText (const char *text, std::size_t textSize, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
| Assigns a copy of the given text.
void | assignText (const std::string &text, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
| Assigns a copy of the given text.
void | assignText (std::string_view text, TagTextEncoding textEncoding=TagTextEncoding::Latin1, TagTextEncoding convertTo=TagTextEncoding::Unspecified)
| Assigns a copy of the given text.
void | assignInteger (int value)
| Assigns the given integer value.
void | assignUnsignedInteger (std::uint64_t value)
| Assigns the given unsigned integer value.
void | assignStandardGenreIndex (int index)
| Assigns the given standard genre index to be assigned.
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.
void | assignTimeSpan (CppUtilities::TimeSpan value)
| Assigns the given TimeSpan value.
void | assignDateTime (CppUtilities::DateTime value)
| Assigns the given DateTime value.
void | assignDateTimeExpression (const CppUtilities::DateTimeExpression &value)
| Assigns the given DateTimeExpression value.
void | assignPopularity (const Popularity &value)
| Assigns the specified popularity value.
bool | compareTo (const TagValue &other, TagValueComparisionFlags options=TagValueComparisionFlags::None) const
| Returns whether both instances are equal.
bool | compareData (const TagValue &other, bool ignoreCase=false) const
| Returns whether the raw data of the current instance equals the raw data of other.

## Static Public Member Functions
static const TagValue & | empty ()
| Returns a default-constructed TagValue where TagValue::isNull() and TagValue::isEmpty() both return true.
static void | stripBom (const char *&text, std::size_t &length, TagTextEncoding encoding)
| Strips the byte order mask from the specified text.
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.
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.
static bool | compareData (const std::string &data1, const std::string &data2, bool ignoreCase=false)
| Returns whether 2 data buffers are equal.
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.

## 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 encodings supported by this library.
- Tag formats usually only support a subset of these encodings. The serializers for the various tag formats provided by this library will keep the encoding if possible and otherwise convert the assigned text to an encoding supported by the tag format on the fly. Note that ID3v1 does not specify which encodings are supported (or unsupported) so the serializer will just write text data as-is.
- The deserializers will store text data in the encoding that is used in the tag.
- The functions Tag::canEncodingBeUsed() and Tag::proposedTextEncoding() can be used to check whether an encoding can be used by a certain tag format to avoid any unnecessary character set conversions.
- There's also the function Tag::ensureTextValuesAreProperlyEncoded() which can be used to convert all text values currently assigned to a tag to the encoding which is deemed best for the current tag format. This function is a bit more agressive than the implict conversions, e.g. it ensures no UTF-16 encoded text ends up in ID3v1 tags.
- If you want to use UTF-8 everywhere, simply always assign UTF-8 text and use TagValue::toString(TagTextEncoding::Utf8) when reading text.

Values of the type TagDataType::Popularity might use different rating scales depending on the tag format.

- You can assign a Popularity object of any scale. Tag implementations will convert it accordingly.
- You can use TagValue::toScaledPopularity() to retrieve a Popularity object of the desired scale.
- When just working with text data (via TagValue::toString() and TagValue::assignText()), no scaling of internally assigned Popularity objects is done; so you're working with raw rating values in this case.

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

## Constructor & Destructor Documentation

## ◆ TagValue() [1/16]

TagParser::TagValue::TagValue | ( |  | ) |
| explicit

Constructs an empty TagValue.

Definition at line 156 of file tagvalue.cpp.

## ◆ TagValue() [2/16]

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

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

Parameters

  text | Specifies the text to be assigned.
  textSize | Specifies the size of text. (The actual number of bytes, not the number of characters.)
  textEncoding | Specifies the encoding of the given text.
  convertTo | Specifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.

Exceptions

  Throws | a ConversionException if the conversion the specified character set fails.

Remarks
  Strips the BOM of the specified text.

Definition at line 175 of file tagvalue.cpp.

## ◆ TagValue() [3/16]

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

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

Parameters

  text | Specifies the text to be assigned. This string must be null-terminated.
  textEncoding | Specifies the encoding of the given text.
  convertTo | Specifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.

Exceptions

  Throws | a ConversionException if the conversion the specified character set fails.

Remarks
  Strips the BOM of the specified text.

Definition at line 191 of file tagvalue.cpp.

## ◆ TagValue() [4/16]

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

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

Parameters

  text | Specifies the text to be assigned.
  textEncoding | Specifies the encoding of the given text.
  convertTo | Specifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.

Exceptions

  Throws | a ConversionException if the conversion the specified character set fails.

Remarks
  Strips the BOM of the specified text.

Definition at line 205 of file tagvalue.cpp.

## ◆ TagValue() [5/16]

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

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

Parameters

  text | Specifies the text to be assigned.
  textEncoding | Specifies the encoding of the given text.
  convertTo | Specifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.

Exceptions

  Throws | a ConversionException if the conversion the specified character set fails.

Remarks
  Strips the BOM of the specified text.

Definition at line 221 of file tagvalue.cpp.

## ◆ TagValue() [6/16]

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

Constructs a new TagValue holding the given integer value.

Definition at line 273 of file tagvalue.h.

## ◆ TagValue() [7/16]

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

Constructs a new TagValue holding the given unsigned integer value.

Definition at line 281 of file tagvalue.h.

## ◆ TagValue() [8/16]

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

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

Parameters

  data | Specifies a pointer to the data.
  length | Specifies the length of the data.
  type | Specifies the type of the data as TagDataType.
  encoding | Specifies 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 245 of file tagvalue.cpp.

## ◆ TagValue() [9/16]

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

Constructs a new TagValue holding with the given data.

The data is not copied. It is moved.

Parameters

  data | Specifies a pointer to the data.
  length | Specifies the length of the data.
  type | Specifies the type of the data as TagDataType.
  encoding | Specifies 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 273 of file tagvalue.cpp.

## ◆ TagValue() [10/16]

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

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

Definition at line 289 of file tagvalue.h.

## ◆ TagValue() [11/16]

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

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

Definition at line 297 of file tagvalue.h.

## ◆ TagValue() [12/16]

TagParser::TagValue::TagValue | ( | const CppUtilities::DateTimeExpression & | value | ) |
| inlineexplicit

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

Definition at line 305 of file tagvalue.h.

## ◆ TagValue() [13/16]

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

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

Definition at line 313 of file tagvalue.h.

## ◆ TagValue() [14/16]

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

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

Definition at line 321 of file tagvalue.h.

## ◆ TagValue() [15/16]

TagParser::TagValue::TagValue | ( | const TagValue & | other | ) |

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

Parameters

  other | Specifies another TagValue instance.

Definition at line 135 of file tagvalue.cpp.

## ◆ TagValue() [16/16]

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

## ◆ ~TagValue()

TagParser::TagValue::~TagValue | ( |  | ) |

Destroys the TagValue.

Definition at line 231 of file tagvalue.cpp.

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

## ◆ assignDateTimeExpression()

void TagParser::TagValue::assignDateTimeExpression | ( | const CppUtilities::DateTimeExpression & | value | ) |
| inline

Assigns the given DateTimeExpression value.

Definition at line 414 of file tagvalue.h.

## ◆ assignInteger()

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

Assigns the given integer value.

Parameters

  value | Specifies the integer to be assigned.

Definition at line 1260 of file tagvalue.cpp.

## ◆ assignPopularity()

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

Assigns the specified popularity value.

Definition at line 1331 of file tagvalue.cpp.

## ◆ assignPosition()

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

Assigns the given PositionInSet value.

Definition at line 385 of file tagvalue.h.

## ◆ assignStandardGenreIndex()

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

Assigns the given standard genre index to be assigned.

Parameters

  index | Specifies the index to be assigned.

See also
  List of genres - Wikipedia

Definition at line 424 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

  text | Specifies the text to be assigned.
  textSize | Specifies the size of text. (The actual number of bytes, not the number of characters.)
  textEncoding | Specifies the encoding of the given text.
  convertTo | Specifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.

Exceptions

  Throws | a ConversionException if the conversion the specified character set fails.

Remarks
  Strips the BOM of the specified text.

Definition at line 1209 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

  text | Specifies the text to be assigned.
  textEncoding | Specifies the encoding of the given text.
  convertTo | Specifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.

Exceptions

  Throws | a ConversionException if the conversion the specified character set fails.

Remarks
  Strips the BOM of the specified text.

Definition at line 363 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

  text | Specifies the text to be assigned.
  textEncoding | Specifies the encoding of the given text.
  convertTo | Specifies the encoding to convert text to; set to TagTextEncoding::Unspecified to use textEncoding without any character set conversions.

Exceptions

  Throws | a ConversionException if the conversion the specified character set fails.

Remarks
  Strips the BOM of the specified text.

Definition at line 377 of file tagvalue.h.

## ◆ assignTimeSpan()

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

Assigns the given TimeSpan value.

Definition at line 398 of file tagvalue.h.

## ◆ assignUnsignedInteger()

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

Assigns the given unsigned integer value.

Parameters

  value | Specifies the unsigned integer to be assigned.

Definition at line 1273 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 501 of file tagvalue.h.

## ◆ clearDataAndMetadata()

void TagParser::TagValue::clearDataAndMetadata | ( |  | ) |
| inline

Wipes assigned data including meta data.

See also
  clearData()
  clearMetadata()

Definition at line 512 of file tagvalue.h.

## ◆ clearMetadata()

void TagParser::TagValue::clearMetadata | ( |  | ) |

Wipes assigned meta data.

- Clears description, mime type, language and flags.
- Resets the encoding to TagTextEncoding::Latin1.
- Resets the data type to TagDataType::Undefined.

Definition at line 500 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 1402 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 762 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 754 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.
    - 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
    - TagValue::compareData() to compare raw data without any conversions
    - TagValueTests::testEqualityOperator() for examples

Definition at line 354 of file tagvalue.cpp.

## ◆ convertDataEncoding()

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

Converts the currently assigned text value to the specified encoding.

Exceptions

  Throws | CppUtilities::ConversionException() if the conversion fails.

Remarks
  - Does nothing if dataEncoding() equals encoding.
  - Sets dataEncoding() to the specified encoding if the conversion succeeds.
  - Does not do any conversion if the current type() is not TagDataType::Text.

See also
  convertDataEncodingForTag()

Definition at line 921 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 963 of file tagvalue.cpp.

## ◆ convertDescriptionEncoding()

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

Converts the assigned description to use the specified encoding.

Definition at line 973 of file tagvalue.cpp.

## ◆ data()

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

Returns the currently assigned raw data.

Definition at line 546 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 718 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 533 of file tagvalue.h.

## ◆ dataPointer() [2/2]

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

Definition at line 538 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 522 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
  - descriptionEncoding() for the encoding of the returned string
  - convertDescriptionEncoding() to change the encoding of the description
  - setDescription() for setting the description

Definition at line 561 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 728 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 1432 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 1382 of file tagvalue.cpp.

## ◆ flags()

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

Returns the flags.

See also
  TagValueFlags

Definition at line 653 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 490 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 676 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 477 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 630 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 616 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 590 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 708 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 699 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 349 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 340 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 288 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 331 of file tagvalue.h.

## ◆ setDescription()

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

Sets the description.

Parameters

  value | Specifies the description.
  encoding | Specifies 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
  - description() and descriptionEncoding()
  - convertDescriptionEncoding() to change the description encoding after assignment

Definition at line 577 of file tagvalue.h.

## ◆ setFlags()

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

Sets the flags.

See also
  TagValueFlags

Definition at line 662 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 644 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 602 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 690 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 1353 of file tagvalue.cpp.

## ◆ toDateTime()

DateTime TagParser::TagValue::toDateTime | ( |  | ) | const

Converts the value of the current TagValue object to its equivalent DateTime representation (using the UTC timezone).

Exceptions

  Throws | ConversionException on failure.

Definition at line 763 of file tagvalue.cpp.

## ◆ toDateTimeExpression()

CppUtilities::DateTimeExpression TagParser::TagValue::toDateTimeExpression | ( |  | ) | const

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

Exceptions

  Throws | ConversionException on failure.

Definition at line 799 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 519 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

  Throws | ConversionException on failure.

Definition at line 540 of file tagvalue.cpp.

## ◆ toPopularity()

Popularity TagParser::TagValue::toPopularity | ( |  | ) | const

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

Exceptions

  Throws | ConversionException on failure.

Remarks
  - If text is assigned, the returned popularity's scale will always be TagType::Unspecified as the text representation does not preserve the scale. Assign the correct scale if needed manually. Note that tag field implementations provided by this library take care to assign a popularity (and not just text) when parsing the popularity/rating fields to preserve the scale information.
  - Use TagValue::toScaledPopularity() if you want to convert the rating to a certain scale (to use that scale consistently without having to deal with multiple scales yourself).

Definition at line 841 of file tagvalue.cpp.

## ◆ toPositionInSet()

PositionInSet TagParser::TagValue::toPositionInSet | ( |  | ) | const

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

Exceptions

  Throws | ConversionException on failure.

Definition at line 675 of file tagvalue.cpp.

## ◆ toScaledPopularity()

Popularity TagParser::TagValue::toScaledPopularity | ( | TagType | scale = TagType::Unspecified | ) | const

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

Exceptions

  Throws | ConversionException on failure, e.g. when Popularity::scaleTo() fails.

Remarks
  1. See Popularity::scaleTo() for details about scaling.
  2. If text is assigned, it is converted like with TagValue::toPopularity(). However, the specified a scale is assigned as the popularity's scale assuming that the text representation already contains a rating with the desired scale. That means if you assign text to a TagValue, the tag implementations (which use this function internally) will use that text as-is when serializing the popularity/rating field.
  3. Since TagValue::toString() also does not do any scaling the previous point means that if you only ever use TagValue::assignText() (or equivalent c'tors) and TagValue::toString() you will always work with raw rating values consistently.
  4. Since tag implementations provided by this library always take care to assign the popularity/rating as such (and not just as text) you do not need to care about point 2. if you want to use a certain scale consistently. Just call this function with the desired scal when reading and assign a popularity object with that scale before saving changes.

Definition at line 901 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

  Throws | ConversionException on failure.

Definition at line 625 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

  result | Specifies the string to store the result.
  encoding | Specifies the encoding to to be used; set to TagTextEncoding::Unspecified to use the present encoding without any character set conversion.

Remarks
  - Not all types can be converted to a string, eg. TagDataType::Picture, TagDataType::Binary and TagDataType::Unspecified will always fail to convert.
  - If UTF-16 is the desired output encoding, it makes sense to use TagValue::toWString() instead.
  - If a popularity is assigned, its string representation is returned without further scaling.

Exceptions

  Throws | ConversionException on failure.

Definition at line 1024 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

  result | Specifies the string to store the result.
  encoding | Specifies the encoding to to be used; set to TagTextEncoding::Unspecified to use the present encoding without any character set conversion.

Remarks
  - Not all types can be converted to a string, eg. TagDataType::Picture, TagDataType::Binary and TagDataType::Unspecified will always fail to convert.
  - If UTF-16 is the desired output encoding, it makes sense to use the toWString() method instead.

Exceptions

  Throws | ConversionException on failure.

Definition at line 450 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

  Throws | ConversionException on failure.

See also
  toString()

Definition at line 741 of file tagvalue.h.

## ◆ toTimeSpan()

TimeSpan TagParser::TagValue::toTimeSpan | ( |  | ) | const

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

Exceptions

  Throws | ConversionException on failure.

Definition at line 724 of file tagvalue.cpp.

## ◆ toUnsignedInteger()

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

Definition at line 582 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

  Throws | ConversionException 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 1116 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

  Throws | ConversionException on failure.

Remarks
  Use this only, if encoding is an UTF-16 encoding.

Definition at line 463 of file tagvalue.h.

## ◆ type()

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

Returns the type of the assigned value.

Definition at line 433 of file tagvalue.h.

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

- tagvalue.h
- tagvalue.cpp