Tag Parser: TagParser::FieldMapBasedTag< ImplementationType > Class Template Reference

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

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Types | Protected Member Functions | Friends | List of all members
TagParser::FieldMapBasedTag< ImplementationType > Class Template Reference

The FieldMapBasedTag provides a generic implementation of Tag which stores the tag fields using std::multimap. More...

`#include <fieldbasedtag.h>`

Inheritance diagram for TagParser::FieldMapBasedTag< ImplementationType >:
[legend]
Collaboration diagram for TagParser::FieldMapBasedTag< ImplementationType >:
[legend]

## Public Types
using | FieldType = typename FieldMapBasedTagTraits<ImplementationType>::FieldType
using | IdentifierType = typename FieldMapBasedTagTraits<ImplementationType>::FieldType::IdentifierType
using | Compare = typename FieldMapBasedTagTraits<ImplementationType>::Compare

## Public Member Functions
| FieldMapBasedTag ()
| Constructs a new FieldMapBasedTag.
TagType | type () const
| Returns the type of the tag as TagParser::TagType.
std::string_view | typeName () const
| Returns the type name of the tag as C-style string.
TagTextEncoding | proposedTextEncoding () const
| Returns the proposed text encoding.
const TagValue & | value (const IdentifierType &id) const
| Returns the value of the field with the specified id.
const TagValue & | value (KnownField field) const
| Returns the value of the specified field.
std::vector< const TagValue * > | values (const IdentifierType &id) const
| Returns the values of the field with the specified id.
std::vector< const TagValue * > | values (KnownField field) const
| Returns the values of the specified field.
bool | setValue (const IdentifierType &id, const TagValue &value)
| Assigns the given value to the field with the specified id.
bool | setValue (KnownField field, const TagValue &value)
| Assigns the given value to the specified field.
bool | setValues (const IdentifierType &id, const std::vector< TagValue > &values)
| Assigns the given values to the field with the specified id.
bool | setValues (KnownField field, const std::vector< TagValue > &values)
| Assigns the given values to the field with the specified id.
bool | hasField (KnownField field) const
| Returns an indication whether the specified field is present.
bool | hasField (const IdentifierType &id) const
| Returns an indication whether the field with the specified id is present.
void | removeAllFields ()
| Removes all fields from the tag.
const std::multimap< IdentifierType, FieldType, Compare > & | fields () const
std::multimap< IdentifierType, FieldType, Compare > & | fields ()
std::size_t | fieldCount () const
| Returns the number of present fields.
IdentifierType | fieldId (KnownField value) const
| Returns the ID for the specified field.
KnownField | knownField (const IdentifierType &id) const
| Returns the field for the specified ID.
bool | supportsField (KnownField field) const
| Returns an indication whether the specified field is supported by the tag.
TagDataType | proposedDataType (const IdentifierType &id) const
| Returns the proposed data type for the field with the specified id.
std::size_t | insertFields (const FieldMapBasedTag< ImplementationType > &from, bool overwrite)
| Inserts all fields from another tag of the same field type and compare function.
std::size_t | insertValues (const Tag &from, bool overwrite)
| Inserts all compatible values from another Tag.
void | ensureTextValuesAreProperlyEncoded ()
| Ensures the encoding of all assigned text values is supported by the tag by converting the character set if necessary.
virtual TagDataType | proposedDataType (KnownField field) const
| Returns the proposed data type for the specified field as TagDataType.
Public Member Functions inherited from TagParser::Tag
virtual | ~Tag ()
| Destroys the Tag.
std::string | toString () const
| Returns a string representation of the tag.
virtual bool | canEncodingBeUsed (TagTextEncoding encoding) const
| Returns an indication whether the specified encoding can be used to provide string values for the tag.
const std::string & | version () const
| Returns the version of the tag as std::string.
std::uint64_t | size () const
| Returns the size the tag within the file it is parsed from in bytes.
virtual bool | supportsTarget () const
| Returns an indication whether a target is supported by the tag.
const TagTarget & | target () const
TagTarget & | target ()
| Returns the target of tag.
void | setTarget (const TagTarget &target)
| Sets the target of tag.
virtual TagTargetLevel | targetLevel () const
| Returns the name of the current tag target level.
std::string_view | targetLevelName () const
| Returns the name of the current target level.
bool | isTargetingLevel (TagTargetLevel tagTargetLevel) const
| Returns whether the tag is targeting the specified tagTargetLevel.
std::string | targetString () const
| Returns the string representation for the assigned tag target.
virtual bool | supportsDescription (KnownField field) const
| Returns an indications whether the specified field supports descriptions.
virtual bool | supportsMimeType (KnownField field) const
| Returns an indications whether the specified field supports mime types.
virtual bool | supportsMultipleValues (KnownField field) const
| Returns an indications whether the specified field supports multiple values.

## Protected Types
using | CRTPBase = FieldMapBasedTag<ImplementationType>

## Protected Member Functions
const TagValue & | internallyGetValue (const IdentifierType &id) const
| Default implementation for value().
void | internallyGetValuesFromField (const FieldType &field, std::vector< const TagValue * > &values) const
| Default way to gather values from a field in internallyGetValues().
std::vector< const TagValue * > | internallyGetValues (const IdentifierType &id) const
| Default implementation for values().
bool | internallySetValue (const IdentifierType &id, const TagValue &value)
| Default implementation for setValue().
bool | internallySetValues (const IdentifierType &id, const std::vector< TagValue > &values)
| Default implementation for setValues().
bool | internallyHasField (const IdentifierType &id) const
| Default implementation for hasField().
TagDataType | internallyGetProposedDataType (const IdentifierType &id) const
| Default implementation for proposedDataType().
Protected Member Functions inherited from TagParser::Tag
| Tag ()
| Constructs a new Tag.

## Friends
class | FieldMapBasedTagTraits< ImplementationType >

## Additional Inherited Members
Protected Attributes inherited from TagParser::Tag
std::string | m_version
std::uint64_t | m_size
std::unique_ptr< TagPrivate > | m_p
TagTarget | m_target

## Detailed Description

template<class ImplementationType>
class TagParser::FieldMapBasedTag< ImplementationType >

The FieldMapBasedTag provides a generic implementation of Tag which stores the tag fields using std::multimap.

The FieldMapBasedTag class only provides the interface and common functionality. It is meant to be subclassed using CRTP pattern.

Remarks
  This template class is intended to be subclassed using with the "Curiously recurring template pattern".

Definition at line 30 of file fieldbasedtag.h.

## Member Typedef Documentation

## ◆ Compare

template<class ImplementationType>

using TagParser::FieldMapBasedTag< ImplementationType >::Compare = typename FieldMapBasedTagTraits<ImplementationType>::Compare

Definition at line 36 of file fieldbasedtag.h.

## ◆ CRTPBase

template<class ImplementationType>

using TagParser::FieldMapBasedTag< ImplementationType >::CRTPBase = FieldMapBasedTag<ImplementationType>
| protected

Definition at line 67 of file fieldbasedtag.h.

## ◆ FieldType

template<class ImplementationType>

using TagParser::FieldMapBasedTag< ImplementationType >::FieldType = typename FieldMapBasedTagTraits<ImplementationType>::FieldType

Definition at line 34 of file fieldbasedtag.h.

## ◆ IdentifierType

template<class ImplementationType>

using TagParser::FieldMapBasedTag< ImplementationType >::IdentifierType = typename FieldMapBasedTagTraits<ImplementationType>::FieldType::IdentifierType

Definition at line 35 of file fieldbasedtag.h.

## Constructor & Destructor Documentation

## ◆ FieldMapBasedTag()

template<class ImplementationType>

TagParser::FieldMapBasedTag< ImplementationType >::FieldMapBasedTag | ( |  | ) |

Constructs a new FieldMapBasedTag.

Definition at line 100 of file fieldbasedtag.h.

## Member Function Documentation

## ◆ ensureTextValuesAreProperlyEncoded()

template<class ImplementationType>

void TagParser::FieldMapBasedTag< ImplementationType >::ensureTextValuesAreProperlyEncoded | ( |  | ) |
| virtual

Ensures the encoding of all assigned text values is supported by the tag by converting the character set if necessary.

Implements TagParser::Tag.

Reimplemented in TagParser::Id3v2Tag.

Definition at line 441 of file fieldbasedtag.h.

## ◆ fieldCount()

template<class ImplementationType>

std::size_t TagParser::FieldMapBasedTag< ImplementationType >::fieldCount | ( |  | ) | const
| virtual

Returns the number of present fields.

Implements TagParser::Tag.

Definition at line 340 of file fieldbasedtag.h.

## ◆ fieldId()

template<class ImplementationType>

FieldMapBasedTag< ImplementationType >::IdentifierType TagParser::FieldMapBasedTag< ImplementationType >::fieldId | ( | KnownField | value | ) | const
| inline

Returns the ID for the specified field.

Returns the field ID for the specified value.

Needs to be implemented when subclassing.

Remarks
  Must be implemented in internallyGetFieldId() when creating subclass.

Definition at line 356 of file fieldbasedtag.h.

## ◆ fields() [1/2]

template<class ImplementationType>

std::multimap< IdentifierType, FieldType, Compare > & TagParser::FieldMapBasedTag< ImplementationType >::fields | ( |  | ) |

## ◆ fields() [2/2]

template<class ImplementationType>

const std::multimap< IdentifierType, FieldType, Compare > & TagParser::FieldMapBasedTag< ImplementationType >::fields | ( |  | ) | const

## ◆ hasField() [1/2]

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::hasField | ( | const IdentifierType & | id | ) | const
| inline

Returns an indication whether the field with the specified id is present.

Definition at line 313 of file fieldbasedtag.h.

## ◆ hasField() [2/2]

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::hasField | ( | KnownField | field | ) | const
| inlinevirtual

Returns an indication whether the specified field is present.

See also
  value(), setValue()

Implements TagParser::Tag.

Reimplemented in TagParser::Mp4Tag.

Definition at line 291 of file fieldbasedtag.h.

## ◆ insertFields()

template<class ImplementationType>

std::size_t TagParser::FieldMapBasedTag< ImplementationType >::insertFields | ( | const FieldMapBasedTag< ImplementationType > & | from,
|  | bool | overwrite )

Inserts all fields from another tag of the same field type and compare function.

Parameters

  from | Specifies the tag the fields should be inserted from.
  overwrite | Indicates whether existing fields should be overwritten.

Returns
  Returns the number of fields that have been inserted.

Definition at line 401 of file fieldbasedtag.h.

## ◆ insertValues()

template<class ImplementationType>

std::size_t TagParser::FieldMapBasedTag< ImplementationType >::insertValues | ( | const Tag & | from,
|  | bool | overwrite )
| virtual

Inserts all compatible values from another Tag.

Parameters

  from | Specifies the Tag the values should be inserted from.
  overwrite | Indicates whether existing values should be overwritten.

Returns
  Returns the number of values that have been inserted.

Remarks
  The encoding of the inserted text values might not be supported by the tag. To fix this, call ensureTextValuesAreProperlyEncoded() after insertion.

Reimplemented from TagParser::Tag.

Definition at line 431 of file fieldbasedtag.h.

## ◆ internallyGetProposedDataType()

template<class ImplementationType>

TagDataType TagParser::FieldMapBasedTag< ImplementationType >::internallyGetProposedDataType | ( | const IdentifierType & | id | ) | const
| inlineprotected

Default implementation for proposedDataType().

Remarks
  Shadow in subclass to provide custom implementation.

Definition at line 381 of file fieldbasedtag.h.

## ◆ internallyGetValue()

template<class ImplementationType>

const TagValue & TagParser::FieldMapBasedTag< ImplementationType >::internallyGetValue | ( | const IdentifierType & | id | ) | const
| protected

Default implementation for value().

Remarks
  Shadow in subclass to provide custom implementation.

Definition at line 123 of file fieldbasedtag.h.

## ◆ internallyGetValues()

template<class ImplementationType>

std::vector< const TagValue * > TagParser::FieldMapBasedTag< ImplementationType >::internallyGetValues | ( | const IdentifierType & | id | ) | const
| protected

Default implementation for values().

Remarks
  Shadow in subclass to provide custom implementation.

Definition at line 147 of file fieldbasedtag.h.

## ◆ internallyGetValuesFromField()

template<class ImplementationType>

void TagParser::FieldMapBasedTag< ImplementationType >::internallyGetValuesFromField | ( | const FieldType & | field,
|  | std::vector< const TagValue * > & | values ) const
| protected

Default way to gather values from a field in internallyGetValues().

Remarks
  Shadow in subclass to provide custom implementation.

Definition at line 134 of file fieldbasedtag.h.

## ◆ internallyHasField()

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::internallyHasField | ( | const IdentifierType & | id | ) | const
| protected

Default implementation for hasField().

Remarks
  Shadow in subclass to provide custom implementation.

Definition at line 300 of file fieldbasedtag.h.

## ◆ internallySetValue()

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::internallySetValue | ( | const IdentifierType & | id,
|  | const TagValue & | value )
| protected

Default implementation for setValue().

Remarks
  Shadow in subclass to provide custom implementation.

Definition at line 204 of file fieldbasedtag.h.

## ◆ internallySetValues()

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::internallySetValues | ( | const IdentifierType & | id,
|  | const std::vector< TagValue > & | values )
| protected

Default implementation for setValues().

Remarks
  Shadow in subclass to provide custom implementation.

Definition at line 222 of file fieldbasedtag.h.

## ◆ knownField()

template<class ImplementationType>

KnownField TagParser::FieldMapBasedTag< ImplementationType >::knownField | ( | const IdentifierType & | id | ) | const
| inline

Returns the field for the specified ID.

Returns the KnownField for the specified id.

Needs to be implemented when subclassing.

Remarks
  Must be implemented in internallyGetKnownField() when creating subclass.

Definition at line 365 of file fieldbasedtag.h.

## ◆ proposedDataType() [1/2]

template<class ImplementationType>

TagDataType TagParser::FieldMapBasedTag< ImplementationType >::proposedDataType | ( | const IdentifierType & | id | ) | const
| inline

Returns the proposed data type for the field with the specified id.

Definition at line 389 of file fieldbasedtag.h.

## ◆ proposedDataType() [2/2]

template<class ImplementationType>

TagDataType TagParser::Tag::proposedDataType | ( | KnownField | field | ) | const
| inlinevirtual

Returns the proposed data type for the specified field as TagDataType.

Most values need to be provided as string (see proposedTextEncoding() and canEncodingBeUsed()). Other values need to be provided as integer or an other TagDataType. This method helps to determine which type is required for a particular field.

Remarks
  - The tag class and its subclasses try to convert the provided values. So using exactly the proposed type is not neccassary. Nevertheless it can help to detect conversion errors early. A GUI application could use this method to determine which widget should be used.
  - The default implementation returns a data type which is most commonly used for the specified field. The default implementation might be overwritten when subclassing.

Reimplemented from TagParser::Tag.

Definition at line 206 of file tag.h.

## ◆ proposedTextEncoding()

template<class ImplementationType>

TagTextEncoding TagParser::FieldMapBasedTag< ImplementationType >::proposedTextEncoding | ( |  | ) | const
| virtual

Returns the proposed text encoding.

This is TagTextEncoding::Latin1 by default an might be overwritten when subclassing.

The tag class and its subclasses do not perform any conversions. You have to provide all string values using an encoding which is appropriate for the specific tag type. This method returns such an encoding.

See also
  canEncodingBeUsed()

Reimplemented from TagParser::Tag.

Reimplemented in TagParser::Id3v2Tag.

Definition at line 114 of file fieldbasedtag.h.

## ◆ removeAllFields()

template<class ImplementationType>

void TagParser::FieldMapBasedTag< ImplementationType >::removeAllFields | ( |  | ) |
| inlinevirtual

Removes all fields from the tag.

Implements TagParser::Tag.

Definition at line 318 of file fieldbasedtag.h.

## ◆ setValue() [1/2]

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::setValue | ( | const IdentifierType & | id,
|  | const TagValue & | value )

Assigns the given value to the field with the specified id.

See also
  Tag::setValue()

Definition at line 253 of file fieldbasedtag.h.

## ◆ setValue() [2/2]

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::setValue | ( | KnownField | field,
|  | const TagValue & | value )
| inlinevirtual

Assigns the given value to the specified field.

Remarks
  - If an empty value is given, the field will be be removed.
  - Some tags support more than just one value per field. This method will only alter the first value.

See also
  value(), hasField()

Implements TagParser::Tag.

Definition at line 185 of file fieldbasedtag.h.

## ◆ setValues() [1/2]

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::setValues | ( | const IdentifierType & | id,
|  | const std::vector< TagValue > & | values )

Assigns the given values to the field with the specified id.

Remarks
  There might me more than one value assigned to an id. Whereas setValue() only alters the first value, this method will replace all currently assigned values with the specified values.

See also
  Tag::setValues()

Definition at line 265 of file fieldbasedtag.h.

## ◆ setValues() [2/2]

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::setValues | ( | KnownField | field,
|  | const std::vector< TagValue > & | values )
| virtual

Assigns the given values to the field with the specified id.

Remarks
  There might me more than one value assigned to a field. Whereas setValue() only alters the first value, this method will replace all currently assigned values with the specified values.

See also
  Tag::setValues()

Reimplemented from TagParser::Tag.

Definition at line 276 of file fieldbasedtag.h.

## ◆ supportsField()

template<class ImplementationType>

bool TagParser::FieldMapBasedTag< ImplementationType >::supportsField | ( | KnownField | field | ) | const
| inlinevirtual

Returns an indication whether the specified field is supported by the tag.

Implements TagParser::Tag.

Reimplemented in TagParser::Mp4Tag.

Definition at line 370 of file fieldbasedtag.h.

## ◆ type()

template<class ImplementationType>

TagType TagParser::FieldMapBasedTag< ImplementationType >::type | ( |  | ) | const
| virtual

Returns the type of the tag as TagParser::TagType.

This is TagType::Unspecified by default and might be overwritten when subclassing.

Reimplemented from TagParser::Tag.

Reimplemented in TagParser::OggVorbisComment.

Definition at line 104 of file fieldbasedtag.h.

## ◆ typeName()

template<class ImplementationType>

std::string_view TagParser::FieldMapBasedTag< ImplementationType >::typeName | ( |  | ) | const
| virtual

Returns the type name of the tag as C-style string.

This is "unspecified" by default and might be overwritten when subclassing.

Reimplemented from TagParser::Tag.

Reimplemented in TagParser::OggVorbisComment.

Definition at line 109 of file fieldbasedtag.h.

## ◆ value() [1/2]

template<class ImplementationType>

const TagValue & TagParser::FieldMapBasedTag< ImplementationType >::value | ( | const IdentifierType & | id | ) | const
| inline

Returns the value of the field with the specified id.

See also
  Tag::value()

Definition at line 161 of file fieldbasedtag.h.

## ◆ value() [2/2]

template<class ImplementationType>

const TagValue & TagParser::FieldMapBasedTag< ImplementationType >::value | ( | KnownField | field | ) | const
| inlinevirtual

Returns the value of the specified field.

Remarks
  - If the specified field is not present an empty TagValue will be returned.
  - Some tags support more than just one value per field. If there are multiple values this method just returns the first one.

See also
  setValue(), hasField()

Implements TagParser::Tag.

Definition at line 166 of file fieldbasedtag.h.

## ◆ values() [1/2]

template<class ImplementationType>

std::vector< const TagValue * > TagParser::FieldMapBasedTag< ImplementationType >::values | ( | const IdentifierType & | id | ) | const
| inline

Returns the values of the field with the specified id.

See also
  Tag::values()

Definition at line 175 of file fieldbasedtag.h.

## ◆ values() [2/2]

template<class ImplementationType>

std::vector< const TagValue * > TagParser::FieldMapBasedTag< ImplementationType >::values | ( | KnownField | field | ) | const
| inlinevirtual

Returns the values of the specified field.

Remarks
  - There might me more than one value assigned to a field. Whereas value() returns only the first value, this method returns all values.
  - However, the default implementation just returns the first value assuming multiple values per field are not supported by the tag.

Reimplemented from TagParser::Tag.

Definition at line 180 of file fieldbasedtag.h.

## Friends And Related Symbol Documentation

## ◆ FieldMapBasedTagTraits< ImplementationType >

template<class ImplementationType>

friend class FieldMapBasedTagTraits< ImplementationType >
| friend

Definition at line 441 of file fieldbasedtag.h.

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

- fieldbasedtag.h