Tag Parser: TagParser::Popularity 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 | Public Attributes | List of all members
TagParser::Popularity Class Reference

The Popularity class contains a value for ID3v2's "Popularimeter" field. More...

`#include <tagvalue.h>`

Collaboration diagram for TagParser::Popularity:
[legend]

## Public Member Functions
bool | scaleTo (TagType targetScale)
| Scales the rating from the current scale to targetScale.
Popularity | scaled (TagType targetScale) const
| Same as Popularity::scaleTo() but returns a new object.
std::string | toString () const
| Returns the popularity as string in the format "rating" if only a rating is present or in the format "user|rating|play-counter" or an empty string if the popularity isEmpty().
bool | isEmpty () const
| Returns whether the Popularity is empty. The scale and zero-values don't count.
bool | operator== (const Popularity &other) const
| Returns whether two instances are equal.

## Static Public Member Functions
static Popularity | fromString (std::string_view str)
| Parses the popularity from str assuming the same format as toString() produces and sets TagType::Unspecified as scale.
static Popularity | fromString (std::string_view str, TagType scale)
| Parses the popularity from str assuming the same format as toString() produces and assigns the specified scale.

## Public Attributes
std::string | user
| The user who gave the rating / played the file, e.g. identified by e-mail address.
double | rating = 0.0
| The rating on a tag type specific scale.
std::uint64_t | playCounter = 0
| Play counter specific to the user.
TagType | scale = TagType::Unspecified
| Specifies the scale used for rating by the tag defining that scale.

## Detailed Description

The Popularity class contains a value for ID3v2's "Popularimeter" field.

Remarks
  It can also be used for other formats than ID3v2.

See also
  See documentation of TagParser::Popularity for scaling.

Definition at line 72 of file tagvalue.h.

## Member Function Documentation

## ◆ fromString() [1/2]

Popularity TagParser::Popularity::fromString | ( | std::string_view | str | ) |
| static

Parses the popularity from str assuming the same format as toString() produces and sets TagType::Unspecified as scale.

So str is expected to contain a rating within the range of 1.0 and 5.0 or 0.0 to denote there's no rating.

Exceptions

  Throws | ConversionException() if the format is invalid.

Definition at line 1515 of file tagvalue.cpp.

## ◆ fromString() [2/2]

TagParser::Popularity TagParser::Popularity::fromString | ( | std::string_view | str,
|  | TagType | scale )
| static

Parses the popularity from str assuming the same format as toString() produces and assigns the specified scale.

So str is expected to contain a rating according to the specifications of the tag format passed via scale.

Exceptions

  Throws | ConversionException() if the format is invalid.

Definition at line 1526 of file tagvalue.cpp.

## ◆ isEmpty()

bool TagParser::Popularity::isEmpty | ( |  | ) | const
| inline

Returns whether the Popularity is empty. The scale and zero-values don't count.

Definition at line 91 of file tagvalue.h.

## ◆ operator==()

bool TagParser::Popularity::operator== | ( | const Popularity & | other | ) | const
| inline

Returns whether two instances are equal.

Remarks
  Currently they must match exactly but in the future conversions between different scales might be implemented and two instances would be considered equal if the ratings are considered equal (even specified using different scales).

Definition at line 100 of file tagvalue.h.

## ◆ scaled()

Popularity TagParser::Popularity::scaled | ( | TagType | targetScale | ) | const
| inline

Same as Popularity::scaleTo() but returns a new object.

Definition at line 109 of file tagvalue.h.

## ◆ scaleTo()

bool TagParser::Popularity::scaleTo | ( | TagType | targetScale | ) |

Scales the rating from the current scale to targetScale.

Returns
  Returns whether a conversion from the current scale to targetScale was possible. If no, the object stays unchanged. Note that it is not validated whether the currently assigned rating is a valid value in the currently assigned scale.

Remarks
  - Providing TagType::Unspecified as targetScale will convert to a generic scale where the rating is number is between 1 and 5 with decimal values possible where 5 is the best possible rating and 1 the lowest. The value 0 means there's no rating.
  - If the currently assigned scale is TagType::Unspecified than the currently assigned rating is assumed to use the generic scale described in the previous point.

Definition at line 1450 of file tagvalue.cpp.

## ◆ toString()

std::string TagParser::Popularity::toString | ( |  | ) | const

Returns the popularity as string in the format "rating" if only a rating is present or in the format "user|rating|play-counter" or an empty string if the popularity isEmpty().

Definition at line 1503 of file tagvalue.cpp.

## Member Data Documentation

## ◆ playCounter

std::uint64_t TagParser::Popularity::playCounter = 0

Play counter specific to the user.

Definition at line 78 of file tagvalue.h.

## ◆ rating

double TagParser::Popularity::rating = 0.0

The rating on a tag type specific scale.

Definition at line 76 of file tagvalue.h.

## ◆ scale

TagType TagParser::Popularity::scale = TagType::Unspecified

Specifies the scale used for rating by the tag defining that scale.

Remarks
  The value TagType::Unspecified is used to denote a generic scale from 1.0 to 5.0 where 5.0 is the best and the special value 0.0 stands for "not rated".

Definition at line 82 of file tagvalue.h.

## ◆ user

std::string TagParser::Popularity::user

The user who gave the rating / played the file, e.g. identified by e-mail address.

Definition at line 74 of file tagvalue.h.

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

- tagvalue.h
- tagvalue.cpp