Struct lofty::Tag

pub struct Tag { /* fields omitted */ }

Represents a parsed tag

This is a tag that is loosely bound to a specific TagType. It is used for conversions and as the return type for read_from.

Compared to other formats, this gives a much higher-level view of the tag items. Rather than storing items according to their format-specific keys, ItemKeys are used.

You can easily remap this to another TagType with Tag::re_map.

Any conversion will, of course, be lossy to a varying degree.

Usage

Accessing common items

// There are multiple quick getter methods for common items

let title = tag.title();
let artist = tag.artist();
let album = tag.album();
let genre = tag.genre();

Getting an item of a known type

use lofty::ItemKey;

// If the type of an item is known, there are getter methods
// to prevent having to match against the value

tag.get_string(&ItemKey::TrackTitle);
tag.get_binary(&ItemKey::TrackTitle, false);

Converting between formats

use lofty::{Tag, TagType};
use lofty::id3::v2::Id3v2Tag;

// Converting between formats is as simple as an `into` call.
// However, such conversions can potentially be *very* lossy.

let tag = Tag::new(TagType::Id3v2);
let id3v2_tag: Id3v2Tag = tag.into();

Implementations

impl Tag

pub fn new(tag_type: TagType) -> Self

Initialize a new tag with a certain TagType

pub fn re_map(&mut self, tag_type: TagType)

Change the TagType, remapping all items

pub fn tag_type(&self) -> &TagType

Returns the TagType

pub fn item_count(&self) -> u32

Returns the number of TagItems

pub fn picture_count(&self) -> u32

Returns the number of Pictures

pub fn items(&self) -> &[TagItem]

Returns the stored TagItems as a slice

pub fn get_item_ref(&self, item_key: &ItemKey) -> Option<&TagItem>

Returns a reference to a TagItem matching an ItemKey

pub fn get_string(&self, item_key: &ItemKey) -> Option<&str>

Get a string value from an ItemKey

pub fn get_binary(&self, item_key: &ItemKey, convert: bool) -> Option<&[u8]>

Gets a byte slice from an ItemKey

Use convert to convert ItemValue::Text and ItemValue::Locator to byte slices

pub fn insert_item(&mut self, item: TagItem) -> bool

Insert a TagItem, replacing any existing one of the same type

NOTE: This will verify an ItemKey mapping exists for the target TagType

This will return true if the item was inserted.

pub fn insert_item_unchecked(&mut self, item: TagItem)

Insert a TagItem, replacing any existing one of the same type

Notes:

• This will not verify an ItemKey mapping exists
• This will not allow writing item keys that are out of spec (keys are verified before writing)

This is only necessary if dealing with ItemKey::Unknown.

pub fn insert_text(&mut self, item_key: ItemKey, text: String) -> bool

An alias for Tag::insert_item that doesn’t require the user to create a TagItem

pub fn remove_item(&mut self, key: &ItemKey)

Remove an item by its key

This will remove all items with this key.

pub fn retain_items<F>(&mut self, f: F) where
    F: FnMut(&TagItem) -> bool, 

Retain tag items based on the predicate

See Vec::retain

pub fn pictures(&self) -> &[Picture]

Returns the stored Pictures as a slice

pub fn get_picture_type(&self, picture_type: PictureType) -> Option<&Picture>

Returns the first occurrence of the PictureType

pub fn push_picture(&mut self, picture: Picture)

Pushes a Picture to the tag

pub fn remove_picture_type(&mut self, picture_type: PictureType)

Removes all Pictures of a PictureType

pub fn save_to_path(&self, path: impl AsRef<Path>) -> Result<()>

Save the Tag to a path

Errors

• Path doesn’t exist
• Path is not writable
• See Tag::save_to

pub fn save_to(&self, file: &mut File) -> Result<()>

Save the Tag to a File

Errors

• A FileType couldn’t be determined from the File
• Attempting to write a tag to a format that does not support it. See FileType::supports_tag_type

pub fn remove_from_path(&self, path: impl AsRef<Path>) -> bool

Same as TagType::remove_from_path

pub fn remove_from(&self, file: &mut File) -> bool

Same as TagType::remove_from

Trait Implementations

impl Accessor for Tag

fn artist(&self) -> Option<&str>

Gets the artist

fn set_artist(&mut self, value: String)

Sets the artist

fn remove_artist(&mut self)

Removes the artist

fn title(&self) -> Option<&str>

Gets the title

fn set_title(&mut self, value: String)

Sets the title

fn remove_title(&mut self)

Removes the title

fn album(&self) -> Option<&str>

Gets the album

fn set_album(&mut self, value: String)

Sets the album

fn remove_album(&mut self)

Removes the album

fn genre(&self) -> Option<&str>

Gets the genre

fn set_genre(&mut self, value: String)

Sets the genre

fn remove_genre(&mut self)

Removes the genre

impl Clone for Tag

fn clone(&self) -> Tag

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl From<AiffTextChunks> for Tag

fn from(input: AiffTextChunks) -> Self

Performs the conversion.

impl From<ApeTag> for Tag

fn from(input: ApeTag) -> Self

Performs the conversion.

impl From<Id3v1Tag> for Tag

fn from(input: Id3v1Tag) -> Self

Performs the conversion.

impl From<Id3v2Tag> for Tag

fn from(input: Id3v2Tag) -> Self

Performs the conversion.

impl From<Ilst> for Tag

fn from(input: Ilst) -> Self

Performs the conversion.

impl From<RiffInfoList> for Tag

fn from(input: RiffInfoList) -> Self

Performs the conversion.

impl From<Tag> for ApeTag

fn from(input: Tag) -> Self

Performs the conversion.

impl From<Tag> for Id3v1Tag

fn from(input: Tag) -> Self

Performs the conversion.

impl From<Tag> for Id3v2Tag

fn from(input: Tag) -> Self

Performs the conversion.

impl From<Tag> for AiffTextChunks

fn from(input: Tag) -> Self

Performs the conversion.

impl From<Tag> for RiffInfoList

fn from(input: Tag) -> Self

Performs the conversion.

impl From<Tag> for Ilst

fn from(input: Tag) -> Self

Performs the conversion.

impl From<Tag> for VorbisComments

fn from(input: Tag) -> Self

Performs the conversion.

impl From<VorbisComments> for Tag

fn from(input: VorbisComments) -> Self

Performs the conversion.

impl IntoIterator for Tag

type Item = TagItem

The type of the elements being iterated over.

type IntoIter = IntoIter<Self::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.