Trait id3::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 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) { ... }
}

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

Object Safety

This trait is not object safe.

Implementors

impl TagLike for Chapter

impl TagLike for TableOfContents

impl TagLike for Tag