Struct lofty::Tag

pub struct Tag { /* private fields */ }

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

impl Tag

pub const 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) -> impl Iterator<Item = &TagItem> + Clone

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 ItemKey

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

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

Append a TagItem to the tag

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

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.

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

Append a TagItem to the tag

Notes: See Tag::insert_item_unchecked

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

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

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

Removes all items with the specified ItemKey, and returns them

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

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

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

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

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

pub fn remove_key(&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 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);

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);

Trait Implementations

impl Accessor for Tag

fn artist(&self) -> Option<Cow<'_, str>>

Returns the artist

fn set_artist(&mut self, value: String)

Sets the artist

fn remove_artist(&mut self)

Removes the artist

fn title(&self) -> Option<Cow<'_, str>>

Returns the title

fn set_title(&mut self, value: String)

Sets the title

fn remove_title(&mut self)

Removes the title

fn album(&self) -> Option<Cow<'_, str>>

Returns the album

fn set_album(&mut self, value: String)

Sets the album

fn remove_album(&mut self)

Removes the album

fn genre(&self) -> Option<Cow<'_, str>>

Returns the genre

fn set_genre(&mut self, value: String)

Sets the genre

fn remove_genre(&mut self)

Removes the genre

fn comment(&self) -> Option<Cow<'_, str>>

Returns the comment

fn set_comment(&mut self, value: String)

Sets the comment

fn remove_comment(&mut self)

Removes the comment

fn track(&self) -> Option<u32>

Returns the track

fn set_track(&mut self, value: u32)

Sets the track

fn remove_track(&mut self)

Removes the track

fn track_total(&self) -> Option<u32>

Returns the track total

fn set_track_total(&mut self, value: u32)

Sets the track total

fn remove_track_total(&mut self)

Removes the track total

fn disk(&self) -> Option<u32>

Returns the disk

fn set_disk(&mut self, value: u32)

Sets the disk

fn remove_disk(&mut self)

Removes the disk

fn disk_total(&self) -> Option<u32>

Returns the disk total

fn set_disk_total(&mut self, value: u32)

Sets the disk total

fn remove_disk_total(&mut self)

Removes the disk total

fn year(&self) -> Option<u32>

Returns the year

fn set_year(&mut self, value: u32)

Sets the year

fn remove_year(&mut self)

Removes the year

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

Converts to this type from the input type.

impl From<ApeTag> for Tag

fn from(input: ApeTag) -> Self

Converts to this type from the input type.

impl From<ID3v1Tag> for Tag

fn from(input: ID3v1Tag) -> Self

Converts to this type from the input type.

impl From<ID3v2Tag> for Tag

fn from(input: ID3v2Tag) -> Self

Converts to this type from the input type.

impl From<Ilst> for Tag

fn from(input: Ilst) -> Self

Converts to this type from the input type.

impl From<RIFFInfoList> for Tag

fn from(input: RIFFInfoList) -> Self

Converts to this type from the input type.

impl From<Tag> for AIFFTextChunks

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl From<Tag> for ApeTag

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl From<Tag> for ID3v1Tag

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl From<Tag> for ID3v2Tag

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl From<Tag> for Ilst

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl From<Tag> for RIFFInfoList

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl From<Tag> for VorbisComments

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl From<VorbisComments> for Tag

fn from(input: VorbisComments) -> Self

Converts to this type from the input type.

impl SplitAndMergeTag for Tag

fn split_tag(&mut self) -> Self

Extract and split generic contents into a Tag.

fn merge_tag(&mut self, tag: Self)

Rejoin a Tag.

impl TagExt for Tag

fn save_to_path<P: AsRef<Path>>(&self, path: P) -> Result<(), Self::Err>

Save the Tag to a path

Errors

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

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

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

fn remove_from_path<P: AsRef<Path>>(&self, path: P) -> Result<(), Self::Err>

Remove a tag from a Path

Errors

See TagType::remove_from

fn remove_from(&self, file: &mut File) -> Result<(), Self::Err>

Remove a tag from a File

Errors

See TagType::remove_from

type Err = LoftyError

The associated error which can be returned from IO operations

type RefKey<'a> = &'a ItemKey

The type of key used in the tag for non-mutating functions

fn len(&self) -> usize

Returns the number of items in the tag

fn contains<'a>(&'a self, key: Self::RefKey<'a>) -> bool

Whether the tag contains an item with the key

fn is_empty(&self) -> bool

Whether the tag has any items

fn dump_to<W: Write>(&self, writer: &mut W) -> Result<()>

Dump the tag to a writer

fn clear(&mut self)

Clear the tag, removing all items