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

Protected Types

using CRTPBase = FieldMapBasedTag< ImplementationType >
 

Protected Member Functions

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

Friends

class FieldMapBasedTagTraits< ImplementationType >
 

Additional Inherited Members

- Protected Attributes inherited from TagParser::Tag
std::string m_version
 
std::uint64_t m_size
 
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 31 of file fieldbasedtag.h.

Member Typedef Documentation

◆ Compare

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

Definition at line 37 of file fieldbasedtag.h.

◆ CRTPBase

template<class ImplementationType >
using TagParser::FieldMapBasedTag< ImplementationType >::CRTPBase = FieldMapBasedTag<ImplementationType>
protected

Definition at line 68 of file fieldbasedtag.h.

◆ FieldType

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

Definition at line 35 of file fieldbasedtag.h.

◆ IdentifierType

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

Definition at line 36 of file fieldbasedtag.h.

Constructor & Destructor Documentation

◆ FieldMapBasedTag()

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

Constructs a new FieldMapBasedTag.

Definition at line 101 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.

Definition at line 442 of file fieldbasedtag.h.

◆ fieldCount()

template<class ImplementationType >
std::size_t TagParser::FieldMapBasedTag< ImplementationType >::fieldCount
virtual

Returns the number of present fields.

Implements TagParser::Tag.

Definition at line 341 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 357 of file fieldbasedtag.h.

◆ fields() [1/2]

template<class ImplementationType >
auto TagParser::FieldMapBasedTag< ImplementationType >::fields
inline

Returns the fields of the tag by providing direct access to the field map of the tag.

Definition at line 336 of file fieldbasedtag.h.

◆ fields() [2/2]

template<class ImplementationType >
auto TagParser::FieldMapBasedTag< ImplementationType >::fields
inline

Returns the fields of the tag by providing direct access to the field map of the tag.

Definition at line 328 of file fieldbasedtag.h.

◆ 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 314 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.

Definition at line 292 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
fromSpecifies the tag the fields should be inserted from.
overwriteIndicates whether existing fields should be overwritten.
Returns
Returns the number of fields that have been inserted.

Definition at line 402 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
fromSpecifies the Tag the values should be inserted from.
overwriteIndicates 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 432 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 382 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 124 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 148 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 135 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 301 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 205 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 223 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 366 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 390 of file fieldbasedtag.h.

◆ proposedDataType() [2/2]

template<class ImplementationType >
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 190 of file tag.h.

◆ proposedTextEncoding()

template<class ImplementationType >
TagTextEncoding TagParser::FieldMapBasedTag< ImplementationType >::proposedTextEncoding
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.

Definition at line 115 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 319 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 254 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 186 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 266 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 277 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.

Definition at line 371 of file fieldbasedtag.h.

◆ type()

template<class ImplementationType >
TagType TagParser::FieldMapBasedTag< ImplementationType >::type
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.

Definition at line 105 of file fieldbasedtag.h.

◆ typeName()

template<class ImplementationType >
std::string_view TagParser::FieldMapBasedTag< ImplementationType >::typeName
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.

Definition at line 110 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 162 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 167 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 176 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 181 of file fieldbasedtag.h.

Friends And Related Function Documentation

◆ FieldMapBasedTagTraits< ImplementationType >

template<class ImplementationType >
friend class FieldMapBasedTagTraits< ImplementationType >
friend

Definition at line 442 of file fieldbasedtag.h.


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