Trait TagLike 

pub trait TagLike: Sealed {
    // Provided methods
    fn get(&self, id: impl AsRef<str>) -> Option<&Frame> { ... }
    fn add_frame(&mut self, new_frame: impl Into<Frame>) -> Option<Frame> { ... }
    fn set_text(&mut self, id: impl AsRef<str>, text: impl Into<String>) { ... }
    fn set_text_values(
        &mut self,
        id: impl AsRef<str>,
        texts: impl IntoIterator<Item = impl Into<String>>,
    ) { ... }
    fn remove(&mut self, id: impl AsRef<str>) -> Vec<Frame> { ... }
    fn year(&self) -> Option<i32> { ... }
    fn set_year(&mut self, year: i32) { ... }
    fn remove_year(&mut self) { ... }
    fn date_recorded(&self) -> Option<Timestamp> { ... }
    fn set_date_recorded(&mut self, timestamp: Timestamp) { ... }
    fn remove_date_recorded(&mut self) { ... }
    fn date_released(&self) -> Option<Timestamp> { ... }
    fn set_date_released(&mut self, timestamp: Timestamp) { ... }
    fn remove_date_released(&mut self) { ... }
    fn original_date_released(&self) -> Option<Timestamp> { ... }
    fn set_original_date_released(&mut self, timestamp: Timestamp) { ... }
    fn remove_original_date_released(&mut self) { ... }
    fn artist(&self) -> Option<&str> { ... }
    fn artists(&self) -> Option<Vec<&str>> { ... }
    fn set_artist(&mut self, artist: impl Into<String>) { ... }
    fn remove_artist(&mut self) { ... }
    fn album_artist(&self) -> Option<&str> { ... }
    fn set_album_artist(&mut self, album_artist: impl Into<String>) { ... }
    fn remove_album_artist(&mut self) { ... }
    fn album(&self) -> Option<&str> { ... }
    fn set_album(&mut self, album: impl Into<String>) { ... }
    fn remove_album(&mut self) { ... }
    fn title(&self) -> Option<&str> { ... }
    fn set_title(&mut self, title: impl Into<String>) { ... }
    fn remove_title(&mut self) { ... }
    fn duration(&self) -> Option<u32> { ... }
    fn set_duration(&mut self, duration: u32) { ... }
    fn remove_duration(&mut self) { ... }
    fn genre(&self) -> Option<&str> { ... }
    fn genre_parsed(&self) -> Option<Cow<'_, str>> { ... }
    fn genres(&self) -> Option<Vec<&str>> { ... }
    fn genres_parsed(&self) -> Vec<Cow<'_, str>> { ... }
    fn set_genre(&mut self, genre: impl Into<String>) { ... }
    fn remove_genre(&mut self) { ... }
    fn disc(&self) -> Option<u32> { ... }
    fn set_disc(&mut self, disc: u32) { ... }
    fn remove_disc(&mut self) { ... }
    fn total_discs(&self) -> Option<u32> { ... }
    fn set_total_discs(&mut self, total_discs: u32) { ... }
    fn remove_total_discs(&mut self) { ... }
    fn track(&self) -> Option<u32> { ... }
    fn set_track(&mut self, track: u32) { ... }
    fn remove_track(&mut self) { ... }
    fn total_tracks(&self) -> Option<u32> { ... }
    fn set_total_tracks(&mut self, total_tracks: u32) { ... }
    fn remove_total_tracks(&mut self) { ... }
    fn add_extended_text(
        &mut self,
        description: impl Into<String>,
        value: impl Into<String>,
    ) { ... }
    fn remove_extended_text(
        &mut self,
        description: Option<&str>,
        value: Option<&str>,
    ) { ... }
    fn add_picture(&mut self, picture: Picture) { ... }
    fn remove_picture_by_type(&mut self, picture_type: PictureType) { ... }
    fn remove_all_pictures(&mut self) { ... }
    fn add_comment(&mut self, comment: Comment) { ... }
    fn remove_comment(&mut self, description: Option<&str>, text: Option<&str>) { ... }
    fn add_encapsulated_object(
        &mut self,
        description: impl Into<String>,
        mime_type: impl Into<String>,
        filename: impl Into<String>,
        data: impl Into<Vec<u8>>,
    ) { ... }
    fn remove_encapsulated_object(
        &mut self,
        description: Option<&str>,
        mime_type: Option<&str>,
        filename: Option<&str>,
        data: Option<&[u8]>,
    ) { ... }
    fn add_lyrics(&mut self, lyrics: Lyrics) { ... }
    fn remove_all_lyrics(&mut self) { ... }
    fn add_synchronised_lyrics(&mut self, lyrics: SynchronisedLyrics) { ... }
    fn remove_all_synchronised_lyrics(&mut self) { ... }
    fn remove_all_chapters(&mut self) { ... }
    fn remove_all_tables_of_contents(&mut self) { ... }
    fn remove_unique_file_identifier_by_owner_identifier(
        &mut self,
        owner_identifier: &str,
    ) { ... }
    fn remove_all_unique_file_identifiers(&mut self) { ... }
}

TagLike is a trait that provides a set of useful default methods that make manipulation of tag frames easier.

Provided Methods

fn get(&self, id: impl AsRef<str>) -> Option<&Frame>

Returns a reference to the first frame with the specified identifier.

Example

use id3::{Tag, TagLike, Frame, Content};

let mut tag = Tag::new();

tag.add_frame(Frame::text("TIT2", "Hello"));

assert!(tag.get("TIT2").is_some());
assert!(tag.get("TCON").is_none());

fn add_frame(&mut self, new_frame: impl Into<Frame>) -> Option<Frame>

Adds the frame to the tag, replacing and returning any conflicting frame.

Example

use id3::{Tag, TagLike, Frame, Content};
use id3::frame::ExtendedText;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tag = Tag::new();

    tag.add_frame(Frame::text("TPE1", "Armin van Buuren"));
    tag.add_frame(ExtendedText{
        description: "hello".to_string(),
        value: "world".to_string(),
    });

    let removed = tag.add_frame(Frame::text("TPE1", "John 00 Fleming"))
        .ok_or("no such frame")?;
    assert_eq!(removed.content().text(), Some("Armin van Buuren"));
    Ok(())
}

fn set_text(&mut self, id: impl AsRef<str>, text: impl Into<String>)

Adds a text frame.

Example

use id3::{Tag, TagLike};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tag = Tag::new();
    tag.set_text("TRCK", "1/13");
    assert_eq!(tag.get("TRCK").ok_or("no such frame")?.content().text(), Some("1/13"));
    Ok(())
}

fn set_text_values( &mut self, id: impl AsRef<str>, texts: impl IntoIterator<Item = impl Into<String>>, )

Panics

If any of the strings contain a null byte.

Example

use id3::{Tag, TagLike};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tag = Tag::new();
    tag.set_text_values("TCON", ["Synthwave", "Cyber Punk", "Electronic"]);
    let text = tag.get("TCON").ok_or("no such frame")?.content().text();
    assert_eq!(text, Some("Synthwave\u{0}Cyber Punk\u{0}Electronic"));
    Ok(())
}

fn remove(&mut self, id: impl AsRef<str>) -> Vec<Frame>

Remove all frames with the specified identifier and return them.

Example

use id3::{Content, Frame, Tag, TagLike};

let mut tag = Tag::new();

tag.add_frame(Frame::text("TALB", ""));
tag.add_frame(Frame::text("TPE1", ""));
assert_eq!(tag.frames().count(), 2);

let removed = tag.remove("TALB");
assert_eq!(tag.frames().count(), 1);
assert_eq!(removed.len(), 1);

let removed = tag.remove("TPE1");
assert_eq!(tag.frames().count(), 0);
assert_eq!(removed.len(), 1);

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

Returns the year (TYER). Returns None if the year frame could not be found or if it could not be parsed.

Example

use id3::{Tag, TagLike, Frame};
use id3::frame::Content;

let mut tag = Tag::new();
assert!(tag.year().is_none());

tag.add_frame(Frame::text("TYER", "2014"));
assert_eq!(tag.year(), Some(2014));

tag.remove("TYER");

tag.add_frame(Frame::text("TYER", "nope"));
assert!(tag.year().is_none());

fn set_year(&mut self, year: i32)

Sets the year (TYER).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_year(2014);
assert_eq!(tag.year(), Some(2014));

fn remove_year(&mut self)

Removes the year (TYER).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_year(2014);
assert!(tag.year().is_some());

tag.remove_year();
assert!(tag.year().is_none());

fn date_recorded(&self) -> Option<Timestamp>

Return the content of the TDRC frame, if any

Example

use id3::{Tag, TagLike};
use id3::Timestamp;

let mut tag = Tag::new();
tag.set_date_recorded(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert_eq!(tag.date_recorded().map(|t| t.year), Some(2014));

fn set_date_recorded(&mut self, timestamp: Timestamp)

Sets the content of the TDRC frame

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_date_recorded(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert_eq!(tag.date_recorded().map(|t| t.year), Some(2014));

fn remove_date_recorded(&mut self)

Remove the content of the TDRC frame

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_date_recorded(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert!(tag.date_recorded().is_some());

tag.remove_date_recorded();
assert!(tag.date_recorded().is_none());

fn date_released(&self) -> Option<Timestamp>

Return the content of the TDRL frame, if any

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_date_released(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert_eq!(tag.date_released().map(|t| t.year), Some(2014));

fn set_date_released(&mut self, timestamp: Timestamp)

Sets the content of the TDRL frame

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_date_released(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert_eq!(tag.date_released().map(|t| t.year), Some(2014));

fn remove_date_released(&mut self)

Remove the content of the TDRL frame

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_date_released(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert!(tag.date_released().is_some());

tag.remove_date_released();
assert!(tag.date_released().is_none());

fn original_date_released(&self) -> Option<Timestamp>

Return the content of the TDOR frame, if any

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_original_date_released(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert_eq!(tag.original_date_released().map(|t| t.year), Some(2014));

fn set_original_date_released(&mut self, timestamp: Timestamp)

Sets the content of the TDOR frame

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_original_date_released(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert_eq!(tag.original_date_released().map(|t| t.year), Some(2014));

fn remove_original_date_released(&mut self)

Remove the content of the TDOR frame

Example

use id3::{Tag, TagLike, Timestamp};

let mut tag = Tag::new();
tag.set_original_date_released(Timestamp{ year: 2014, month: None, day: None, hour: None, minute: None, second: None });
assert!(tag.original_date_released().is_some());

tag.remove_original_date_released();
assert!(tag.original_date_released().is_none());

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

Returns the artist (TPE1).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
tag.add_frame(Frame::text("TPE1", "artist"));
assert_eq!(tag.artist(), Some("artist"));

fn artists(&self) -> Option<Vec<&str>>

Returns the (potential) multiple artists (TPE1).

fn set_artist(&mut self, artist: impl Into<String>)

Sets the artist (TPE1).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_artist("artist");
assert_eq!(tag.artist(), Some("artist"));

fn remove_artist(&mut self)

Removes the artist (TPE1).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_artist("artist");
assert!(tag.artist().is_some());

tag.remove_artist();
assert!(tag.artist().is_none());

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

Sets the album artist (TPE2).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
tag.add_frame(Frame::text("TPE2", "artist"));
assert_eq!(tag.album_artist(), Some("artist"));

fn set_album_artist(&mut self, album_artist: impl Into<String>)

Sets the album artist (TPE2).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_album_artist("artist");
assert_eq!(tag.album_artist(), Some("artist"));

fn remove_album_artist(&mut self)

Removes the album artist (TPE2).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_album_artist("artist");
assert!(tag.album_artist().is_some());

tag.remove_album_artist();
assert!(tag.album_artist().is_none());

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

Returns the album (TALB).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
tag.add_frame(Frame::text("TALB", "album"));
assert_eq!(tag.album(), Some("album"));

fn set_album(&mut self, album: impl Into<String>)

Sets the album (TALB).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_album("album");
assert_eq!(tag.album(), Some("album"));

fn remove_album(&mut self)

Removes the album (TALB).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_album("album");
assert!(tag.album().is_some());

tag.remove_album();
assert!(tag.album().is_none());

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

Returns the title (TIT2).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
tag.add_frame(Frame::text("TIT2", "title"));
assert_eq!(tag.title(), Some("title"));

fn set_title(&mut self, title: impl Into<String>)

Sets the title (TIT2).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_title("title");
assert_eq!(tag.title(), Some("title"));

fn remove_title(&mut self)

Removes the title (TIT2).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_title("title");
assert!(tag.title().is_some());

tag.remove_title();
assert!(tag.title().is_none());

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

Returns the duration (TLEN).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();

tag.add_frame(Frame::text("TLEN", "350"));
assert_eq!(tag.duration(), Some(350));

fn set_duration(&mut self, duration: u32)

Sets the duration (TLEN).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_duration(350);
assert_eq!(tag.duration(), Some(350));

fn remove_duration(&mut self)

Removes the duration (TLEN).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_duration(350);
assert!(tag.duration().is_some());

tag.remove_duration();
assert!(tag.duration().is_none());

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

Returns the plain genre (TCON) text.

Please be aware that ID3v2 specifies that this frame is permitted to refer to a predetermined set of ID3v1 genres by index. To handle such frames, use genre_parsed instead.

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
tag.add_frame(Frame::text("TCON", "genre"));
assert_eq!(tag.genre(), Some("genre"));
tag.set_genre("(31)");
assert_eq!(tag.genre(), Some("(31)"));

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

Returns the genre (TCON) with ID3v1 genre indices resolved.

Example

use id3::frame::Content;
use id3::{Frame, Tag, TagLike};
use std::borrow::Cow;

let mut tag = Tag::new();
tag.add_frame(Frame::text("TCON", "genre"));
assert_eq!(tag.genre_parsed(), Some(Cow::Borrowed("genre")));
tag.set_genre("(31)");
assert_eq!(tag.genre_parsed(), Some(Cow::Owned("Trance".to_string())));

fn genres(&self) -> Option<Vec<&str>>

Returns the (potential) multiple plain genres (TCON).

fn genres_parsed(&self) -> Vec<Cow<'_, str>>

Returns the genre (TCON) with ID3v1 genre indices resolved.

Example

use id3::frame::Content;
use id3::{Frame, Tag, TagLike};
use std::borrow::Cow;

let mut tag = Tag::new();
tag.add_frame(Frame::text("TCON", "genre"));
assert_eq!(tag.genres_parsed(), vec!["genre"]);
tag.add_frame(Frame::text("TCON", "21\x00Eurodance"));
assert_eq!(tag.genres_parsed(), vec!["Ska", "Eurodance"]);

fn set_genre(&mut self, genre: impl Into<String>)

Sets the plain genre (TCON).

No attempt is made to interpret and convert ID3v1 indices.

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_genre("genre");
assert_eq!(tag.genre(), Some("genre"));

fn remove_genre(&mut self)

Removes the genre (TCON).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_genre("genre");
assert!(tag.genre().is_some());

tag.remove_genre();
assert!(tag.genre().is_none());

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

Returns the disc number (TPOS).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
assert!(tag.disc().is_none());

tag.add_frame(Frame::text("TPOS", "4"));
assert_eq!(tag.disc(), Some(4));

tag.remove("TPOS");

tag.add_frame(Frame::text("TPOS", "nope"));
assert!(tag.disc().is_none());

fn set_disc(&mut self, disc: u32)

Sets the disc (TPOS).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_disc(2);
assert_eq!(tag.disc(), Some(2));

fn remove_disc(&mut self)

Removes the disc number (TPOS).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_disc(3);
assert!(tag.disc().is_some());

tag.remove_disc();
assert!(tag.disc().is_none());

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

Returns the total number of discs (TPOS).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
assert!(tag.disc().is_none());

tag.add_frame(Frame::text("TPOS", "4/10"));
assert_eq!(tag.total_discs(), Some(10));

tag.remove("TPOS");

tag.add_frame(Frame::text("TPOS", "4/nope"));
assert!(tag.total_discs().is_none());

fn set_total_discs(&mut self, total_discs: u32)

Sets the total number of discs (TPOS).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_total_discs(10);
assert_eq!(tag.total_discs(), Some(10));

fn remove_total_discs(&mut self)

Removes the total number of discs (TPOS).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_total_discs(10);
assert!(tag.total_discs().is_some());

tag.remove_total_discs();
assert!(tag.total_discs().is_none());

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

Returns the track number (TRCK).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
assert!(tag.track().is_none());

tag.add_frame(Frame::text("TRCK", "4"));
assert_eq!(tag.track(), Some(4));

tag.remove("TRCK");

tag.add_frame(Frame::text("TRCK", "nope"));
assert!(tag.track().is_none());

fn set_track(&mut self, track: u32)

Sets the track (TRCK).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_track(10);
assert_eq!(tag.track(), Some(10));

fn remove_track(&mut self)

Removes the track number (TRCK).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_track(10);
assert!(tag.track().is_some());

tag.remove_track();
assert!(tag.track().is_none());

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

Returns the total number of tracks (TRCK).

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::Content;

let mut tag = Tag::new();
assert!(tag.total_tracks().is_none());

tag.add_frame(Frame::text("TRCK", "4/10"));
assert_eq!(tag.total_tracks(), Some(10));

tag.remove("TRCK");

tag.add_frame(Frame::text("TRCK", "4/nope"));
assert!(tag.total_tracks().is_none());

fn set_total_tracks(&mut self, total_tracks: u32)

Sets the total number of tracks (TRCK).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_total_tracks(10);
assert_eq!(tag.total_tracks(), Some(10));

fn remove_total_tracks(&mut self)

Removes the total number of tracks (TCON).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();
tag.set_total_tracks(10);
assert!(tag.total_tracks().is_some());

tag.remove_total_tracks();
assert!(tag.total_tracks().is_none());

fn add_extended_text( &mut self, description: impl Into<String>, value: impl Into<String>, )

👎Deprecated: Use add_frame(frame::ExtendedText{ .. })

Adds a user defined text frame (TXXX).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();

tag.add_extended_text("key1", "value1");
tag.add_extended_text("key2", "value2");

assert_eq!(tag.extended_texts().count(), 2);
assert!(tag.extended_texts().any(|t| t.description == "key1" && t.value == "value1"));
assert!(tag.extended_texts().any(|t| t.description == "key2" && t.value == "value2"));

fn remove_extended_text( &mut self, description: Option<&str>, value: Option<&str>, )

Removes the user defined text frame (TXXX) with the specified key and value.

A key or value may be None to specify a wildcard value.

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();

tag.add_extended_text("key1", "value1");
tag.add_extended_text("key2", "value2");
tag.add_extended_text("key3", "value2");
tag.add_extended_text("key4", "value3");
tag.add_extended_text("key5", "value4");
assert_eq!(tag.extended_texts().count(), 5);

tag.remove_extended_text(Some("key1"), None);
assert_eq!(tag.extended_texts().count(), 4);

tag.remove_extended_text(None, Some("value2"));
assert_eq!(tag.extended_texts().count(), 2);

tag.remove_extended_text(Some("key4"), Some("value3"));
assert_eq!(tag.extended_texts().count(), 1);

tag.remove_extended_text(None, None);
assert_eq!(tag.extended_texts().count(), 0);

fn add_picture(&mut self, picture: Picture)

👎Deprecated: Use add_frame(frame::Picture{ .. })

Adds a picture frame (APIC). Any other pictures with the same type will be removed from the tag.

Example

use id3::{Tag, TagLike};
use id3::frame::{Picture, PictureType};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tag = Tag::new();
    tag.add_picture(Picture {
        mime_type: "image/jpeg".to_string(),
        picture_type: PictureType::Other,
        description: "some image".to_string(),
        data: vec![],
    });
    tag.add_picture(Picture {
        mime_type: "image/png".to_string(),
        picture_type: PictureType::Other,
        description: "some other image".to_string(),
        data: vec![],
    });
    assert_eq!(tag.pictures().count(), 1);
    assert_eq!(&tag.pictures().nth(0).ok_or("no such picture")?.mime_type[..], "image/png");
    Ok(())
}

fn remove_picture_by_type(&mut self, picture_type: PictureType)

Removes all pictures of the specified type.

Example

use id3::{Tag, TagLike};
use id3::frame::{Picture, PictureType};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tag = Tag::new();
    tag.add_picture(Picture {
        mime_type: "image/jpeg".to_string(),
        picture_type: PictureType::Other,
        description: "some image".to_string(),
        data: vec![],
    });
    tag.add_picture(Picture {
        mime_type: "image/png".to_string(),
        picture_type: PictureType::CoverFront,
        description: "some other image".to_string(),
        data: vec![],
    });

    assert_eq!(tag.pictures().count(), 2);
    tag.remove_picture_by_type(PictureType::CoverFront);
    assert_eq!(tag.pictures().count(), 1);
    assert_eq!(tag.pictures().nth(0).ok_or("no such picture")?.picture_type, PictureType::Other);
    Ok(())
}

fn remove_all_pictures(&mut self)

Removes all pictures.

Example

use id3::{Tag, TagLike};
use id3::frame::{Picture, PictureType};

let mut tag = Tag::new();
tag.add_picture(Picture {
    mime_type: "image/jpeg".to_string(),
    picture_type: PictureType::Other,
    description: "some image".to_string(),
    data: vec![],
});
tag.add_picture(Picture {
    mime_type: "image/png".to_string(),
    picture_type: PictureType::CoverFront,
    description: "some other image".to_string(),
    data: vec![],
});

assert_eq!(tag.pictures().count(), 2);
tag.remove_all_pictures();
assert_eq!(tag.pictures().count(), 0);

fn add_comment(&mut self, comment: Comment)

👎Deprecated: Use add_frame(frame::Comment{ .. })

Adds a comment (COMM).

Example

use id3::{Tag, TagLike};
use id3::frame::Comment;

let mut tag = Tag::new();

let com1 = Comment {
    lang: "eng".to_string(),
    description: "key1".to_string(),
    text: "value1".to_string(),
};
let com2 = Comment {
    lang: "eng".to_string(),
    description: "key2".to_string(),
    text: "value2".to_string(),
};
tag.add_comment(com1.clone());
tag.add_comment(com2.clone());

assert_eq!(tag.comments().count(), 2);
assert_ne!(None, tag.comments().position(|c| *c == com1));
assert_ne!(None, tag.comments().position(|c| *c == com2));

fn remove_comment(&mut self, description: Option<&str>, text: Option<&str>)

Removes the comment (COMM) with the specified key and value.

A key or value may be None to specify a wildcard value.

Example

use id3::{Tag, TagLike};
use id3::frame::Comment;

let mut tag = Tag::new();

tag.add_comment(Comment {
    lang: "eng".to_string(),
    description: "key1".to_string(),
    text: "value1".to_string(),
});
tag.add_comment(Comment {
    lang: "eng".to_string(),
    description: "key2".to_string(),
    text: "value2".to_string(),
});
assert_eq!(tag.comments().count(), 2);

tag.remove_comment(Some("key1"), None);
assert_eq!(tag.comments().count(), 1);

tag.remove_comment(None, Some("value2"));
assert_eq!(tag.comments().count(), 0);

fn add_encapsulated_object( &mut self, description: impl Into<String>, mime_type: impl Into<String>, filename: impl Into<String>, data: impl Into<Vec<u8>>, )

👎Deprecated: Use add_frame(frame::EncapsulatedObject{ .. })

Adds an encapsulated object frame (GEOB).

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();

tag.add_encapsulated_object("key1", "application/octet-stream", "", &b"\x00\x01\xAB"[..]);
tag.add_encapsulated_object("key2", "application/json", "foo.json", &b"{ \"value\" }"[..]);

assert_eq!(tag.encapsulated_objects().count(), 2);
assert!(tag.encapsulated_objects().any(|t| t.description == "key1" && t.mime_type == "application/octet-stream" && t.filename == "" && t.data == b"\x00\x01\xAB"));
assert!(tag.encapsulated_objects().any(|t| t.description == "key2" && t.mime_type == "application/json" && t.filename == "foo.json" && t.data == b"{ \"value\" }"));

fn remove_encapsulated_object( &mut self, description: Option<&str>, mime_type: Option<&str>, filename: Option<&str>, data: Option<&[u8]>, )

Removes the encapsulated object frame (GEOB) with the specified key, MIME type, filename and data.

A key or value may be None to specify a wildcard value.

Example

use id3::{Tag, TagLike};

let mut tag = Tag::new();

tag.add_encapsulated_object("key1", "application/octet-stream", "filename1", &b"value1"[..]);
tag.add_encapsulated_object("key2", "text/plain", "filename2", &b"value2"[..]);
tag.add_encapsulated_object("key3", "text/plain", "filename3", &b"value2"[..]);
tag.add_encapsulated_object("key4", "application/octet-stream", "filename4", &b"value3"[..]);
tag.add_encapsulated_object("key5", "application/octet-stream", "filename4", &b"value4"[..]);
tag.add_encapsulated_object("key6", "application/octet-stream", "filename5", &b"value5"[..]);
tag.add_encapsulated_object("key7", "application/octet-stream", "filename6", &b"value6"[..]);
tag.add_encapsulated_object("key8", "application/octet-stream", "filename7", &b"value7"[..]);
assert_eq!(tag.encapsulated_objects().count(), 8);

tag.remove_encapsulated_object(Some("key1"), None, None, None);
assert_eq!(tag.encapsulated_objects().count(), 7);

tag.remove_encapsulated_object(None, Some("text/plain"), None, None);
assert_eq!(tag.encapsulated_objects().count(), 5);

tag.remove_encapsulated_object(None, None, Some("filename4"), None);
assert_eq!(tag.encapsulated_objects().count(), 3);

tag.remove_encapsulated_object(None, None, None, Some(&b"value5"[..]));
assert_eq!(tag.encapsulated_objects().count(), 2);

tag.remove_encapsulated_object(Some("key7"), None, Some("filename6"), None);
assert_eq!(tag.encapsulated_objects().count(), 1);

tag.remove_encapsulated_object(None, None, None, None);
assert_eq!(tag.encapsulated_objects().count(), 0);

fn add_lyrics(&mut self, lyrics: Lyrics)

👎Deprecated: Use add_frame(frame::Lyrics{ .. })

Sets the lyrics (USLT).

Example

use id3::{Tag, TagLike};
use id3::frame::Lyrics;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tag = Tag::new();
    tag.add_lyrics(Lyrics {
        lang: "eng".to_string(),
        description: "".to_string(),
        text: "The lyrics".to_string(),
    });
    assert_eq!(tag.lyrics().nth(0).ok_or("no such lyrics")?.text, "The lyrics");
    Ok(())
}

fn remove_all_lyrics(&mut self)

Removes the lyrics text (USLT) from the tag.

Example

use id3::{Tag, TagLike};
use id3::frame::Lyrics;

let mut tag = Tag::new();
tag.add_lyrics(Lyrics {
    lang: "eng".to_string(),
    description: "".to_string(),
    text: "The lyrics".to_string(),
});
assert_eq!(1, tag.lyrics().count());
tag.remove_all_lyrics();
assert_eq!(0, tag.lyrics().count());

fn add_synchronised_lyrics(&mut self, lyrics: SynchronisedLyrics)

👎Deprecated: Use add_frame(frame::SynchronisedLyrics{ .. })

Adds a synchronised lyrics frame (SYLT).

Example

use id3::{Tag, TagLike};
use id3::frame::{SynchronisedLyrics, SynchronisedLyricsType, TimestampFormat};

let mut tag = Tag::new();
tag.add_synchronised_lyrics(SynchronisedLyrics {
    lang: "eng".to_string(),
    timestamp_format: TimestampFormat::Ms,
    content_type: SynchronisedLyricsType::Lyrics,
    content: vec![
        (1000, "he".to_string()),
        (1100, "llo".to_string()),
        (1200, "world".to_string()),
    ],
    description: "description".to_string()
});
assert_eq!(1, tag.synchronised_lyrics().count());

fn remove_all_synchronised_lyrics(&mut self)

Removes all synchronised lyrics (SYLT) frames from the tag.

Example

use id3::{Tag, TagLike};
use id3::frame::{SynchronisedLyrics, SynchronisedLyricsType, TimestampFormat};

let mut tag = Tag::new();
tag.add_synchronised_lyrics(SynchronisedLyrics {
    lang: "eng".to_string(),
    timestamp_format: TimestampFormat::Ms,
    content_type: SynchronisedLyricsType::Lyrics,
    content: vec![
        (1000, "he".to_string()),
        (1100, "llo".to_string()),
        (1200, "world".to_string()),
    ],
    description: "description".to_string()
});
assert_eq!(1, tag.synchronised_lyrics().count());
tag.remove_all_synchronised_lyrics();
assert_eq!(0, tag.synchronised_lyrics().count());

fn remove_all_chapters(&mut self)

/// Removes all chapters (CHAP) frames from the tag.

Example

use id3::{Tag, TagLike};
use id3::frame::{Chapter, Content, Frame};

let mut tag = Tag::new();
tag.add_frame(Chapter{
    element_id: "01".to_string(),
    start_time: 1000,
    end_time: 2000,
    start_offset: 0xff,
    end_offset: 0xff,
    frames: Vec::new(),
});
assert_eq!(1, tag.chapters().count());
tag.remove_all_chapters();
assert_eq!(0, tag.chapters().count());

fn remove_all_tables_of_contents(&mut self)

/// Removes all tables of contents (CTOC) frames from the tag.

Example

use id3::{Tag, TagLike};
use id3::frame::{Chapter, TableOfContents, Content, Frame};

let mut tag = Tag::new();
tag.add_frame(Chapter{
    element_id: "chap01".to_string(),
    start_time: 1000,
    end_time: 2000,
    start_offset: 0xff,
    end_offset: 0xff,
    frames: Vec::new(),
});
tag.add_frame(TableOfContents{
    element_id: "01".to_string(),
    top_level: true,
    ordered: true,
    elements: vec!["chap01".to_string()],
    frames: Vec::new(),
});
assert_eq!(1, tag.tables_of_contents().count());
tag.remove_all_tables_of_contents();
assert_eq!(0, tag.tables_of_contents().count());

fn remove_unique_file_identifier_by_owner_identifier( &mut self, owner_identifier: &str, )

Removes all Unique File Identifiers with the specified owner_identifier.

Example

use id3::{Tag, TagLike};
use id3::frame::{UniqueFileIdentifier};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tag = Tag::new();
    tag.add_frame(UniqueFileIdentifier {
        owner_identifier: "https://example.com".to_string(),
        identifier: "09FxXfNTQsCgzkPmCeFwlr".into(),
    });
    tag.add_frame(UniqueFileIdentifier {
        owner_identifier: "http://www.id3.org/dummy/ufid.html".to_string(),
        identifier: "7FZo5fMqyG5Ys1dm8F1FHa".into(),
    });

    assert_eq!(tag.unique_file_identifiers().count(), 2);
    tag.remove_unique_file_identifier_by_owner_identifier("http://www.id3.org/dummy/ufid.html");
    assert_eq!(tag.unique_file_identifiers().count(), 1);
    assert_eq!(tag.unique_file_identifiers().nth(0).ok_or("no such ufid owner")?.owner_identifier, "https://example.com");
    Ok(())
}

fn remove_all_unique_file_identifiers(&mut self)

Removes all unique file identifiers.

Example

use id3::{Tag, TagLike};
use id3::frame::{UniqueFileIdentifier};

let mut tag = Tag::new();
    tag.add_frame(UniqueFileIdentifier {
        owner_identifier: "https://example.com".to_string(),
        identifier: "09FxXfNTQsCgzkPmCeFwlr".into(),
    });
    tag.add_frame(UniqueFileIdentifier {
        owner_identifier: "http://www.id3.org/dummy/ufid.html".to_string(),
        identifier: "7FZo5fMqyG5Ys1dm8F1FHa".into(),
    });

assert_eq!(tag.unique_file_identifiers().count(), 2);
tag.remove_all_unique_file_identifiers();
assert_eq!(tag.unique_file_identifiers().count(), 0);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl TagLike for Chapter

impl TagLike for TableOfContents

impl TagLike for Tag