Struct lofty::Tag

source ·

pub struct Tag { /* private fields */ }

Expand description

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

use lofty::{Accessor, Tag, TagType};

let tag = Tag::new(TagType::Id3v2);

// 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, Tag, TagType};

let tag = Tag::new(TagType::Id3v2);

// 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::id3::v2::Id3v2Tag;
use lofty::{Tag, TagType};

// 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§

source §

impl Tag

source

pub const fn new(tag_type: TagType) -> Self

Initialize a new tag with a certain TagType

source

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

Change the TagType, remapping all items

source

pub fn tag_type(&self) -> TagType

Returns the TagType

source

pub fn item_count(&self) -> u32

Returns the number of TagItems

source

pub fn picture_count(&self) -> u32

Returns the number of Pictures

source

pub fn items(&self) -> impl Iterator<Item = &TagItem> + Clone

Returns the stored TagItems as a slice

source

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

Returns a reference to a TagItem matching an ItemKey

source

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

Get a string value from an ItemKey

source

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

source

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

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

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

This will return true if the item was inserted.

source

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

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

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.

source

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

Append a TagItem to the tag

This will not remove any items of the same ItemKey, unlike Tag::insert

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

Multiple items of the same ItemKey are not valid in all formats, in which case the first available item will be used.

This will return true if the item was pushed.

source

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

Append a TagItem to the tag

Notes: See Tag::insert_unchecked

source

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

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

NOTE: This will replace any existing item with item_key. See Tag::insert

source

pub fn take(&mut self, key: &ItemKey) -> impl Iterator<Item = TagItem> + '_

Removes all items with the specified ItemKey, and returns them

source

pub fn take_strings( &mut self, key: &ItemKey ) -> impl Iterator<Item = String> + '_

Removes all items with the specified ItemKey, and filters them through ItemValue::into_string

source

pub fn get_items<'a>( &'a self, key: &'a ItemKey ) -> impl Iterator<Item = &'a TagItem> + Clone

Returns references to all TagItems with the specified key

source

pub fn get_strings<'a>( &'a self, key: &'a ItemKey ) -> impl Iterator<Item = &'a str> + Clone

Returns references to all texts of TagItems with the specified key, and ItemValue::Text

source

pub fn get_locators<'a>( &'a self, key: &'a ItemKey ) -> impl Iterator<Item = &'a str> + Clone

Returns references to all locators of TagItems with the specified key, and ItemValue::Locator

source

pub fn get_bytes<'a>( &'a self, key: &'a ItemKey ) -> impl Iterator<Item = &'a [u8]> + Clone

Returns references to all bytes of TagItems with the specified key, and ItemValue::Binary

source

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

Remove an item by its key

This will remove all items with this key.

source

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

Retain tag items based on the predicate

See Vec::retain

source

pub fn remove_empty(&mut self)

Remove all items with empty values

source

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

Returns the stored Pictures as a slice

source

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

Returns the first occurrence of the PictureType

source

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

Pushes a Picture to the tag

source

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

Removes all Pictures of a PictureType

source

pub fn set_picture(&mut self, index: usize, picture: Picture)

Replaces the picture at the given index

NOTE: If index is out of bounds, the picture will be appended to the list.

§Examples

use lofty::{Picture, Tag, TagType};

let mut tag = Tag::new(TagType::Id3v2);

// Add a front cover
tag.push_picture(front_cover);

assert_eq!(tag.pictures().len(), 1);
assert_eq!(tag.pictures()[0].pic_type(), PictureType::CoverFront);

// Replace the front cover with a back cover
tag.set_picture(0, back_cover);

assert_eq!(tag.pictures().len(), 1);
assert_eq!(tag.pictures()[0].pic_type(), PictureType::CoverBack);

// Use an out of bounds index
tag.set_picture(100, another_picture);

assert_eq!(tag.pictures().len(), 2);

source

pub fn remove_picture(&mut self, index: usize) -> Picture

Removes and returns the picture at the given index

§Panics

Panics if index is out of bounds.

§Examples

use lofty::{Picture, Tag, TagType};

let mut tag = Tag::new(TagType::Id3v2);
tag.push_picture(picture);

assert_eq!(tag.pictures().len(), 1);

tag.remove_picture(0);

assert_eq!(tag.pictures().len(), 0);