Support multiple field values (e.g. multiple artists)

[UgnilJoZ]

Summary

Ogg Vorbis I format specification mentions multiple possible values per field name:

Field names are not required to be unique (occur once) within a comment header. As an example, assume a track was recorded by three well know artists; the following is permissible, and encouraged:

ARTIST=Dizzy Gillespie 
ARTIST=Sonny Rollins
ARTIST=Sonny Stitt 

The Accessor trait handles the artist as String and &str, which is a single value, or sometimes possibly a string that represents a list using a separator.

It seems to be currently impossible to get a list of the artists embedded in Vorbis Comments.

API design

impl Accessor {
    pub fn artists(&self) -> impl Iterator<Item=&str>;
    /// Replace the list of artists
    pub fn set_artists(&mut self, values: impl Iterator<Item=&str>);
}

[Serial-ATA]

This is possible when using Tag, with either get_strings or take_strings. I did miss this on VorbisComments though 😄.

[open-schnick]

Hi,
i just got it to work using get_items for reading and push for writing the tags but needless to say it was tiresome to find out how to do that because its not very intuitive.
Are there any plans to adapt the api to reflect the fact that artist can be more than a single one?
If that is not the case i would like to add this "special" case to the docs of the set and get artist functions

[Serial-ATA]

@open-schnick

Are there any plans to adapt the api to reflect the fact that artist can be more than a single one?

I don't really think it's an API issue.

Note that technically any item can appear multiple times. And I don't think changing the API to just return all items would be a great idea, since most users only care about the first item anyway.

Tag already has methods for both getting the first item (most common case) and getting all items (get/get_items, get_string/get_strings, etc.).

If that is not the case i would like to add this "special" case to the docs of the set and get artist functions

I agree that the docs for anything outside of the simplest cases are lacking. Feel free to make a PR improving them and/or adding some examples, that'd be great :)

[open-schnick]

@Serial-ATA sounds reasonable.
Imo it would make more sense to have additional functions in the accessor trait like artists() additional to artist() but no pressure i can impl whatever seems like the better way to do it

[Serial-ATA]

The issues are:

• I'm usually hesitant to add things to Accessor, since it's intended to only have methods for items that all tag formats support. Only some of the tags actually support multiple of the same field.
• There isn't a single way to store multiple artists. In Vorbis Comments in this case, even though the spec says otherwise, ARTIST is typically only used for the full artist string (e.g. "Foo feat. Bar"). Then each artist name is stored in individual ARTISTS/ALBUMARTISTS fields (See ItemKey: Add ItemKey::TrackArtists #454). So then comes the question: Would artists() follow the spec or common convention?

[open-schnick]

Makes sense, thanks for explaining and the crate :)
I added some lines of docs to the accessor trait in #554