Module rspotify_model::idtypes

This module makes it possible to represent Spotify IDs and URIs with type safety and almost no overhead.

Concrete IDs

The trait Id is the central element of this module. It’s implemented by all kinds of ID, and includes the main functionality to use them. Remember that you will need to import this trait to access its methods. The easiest way is to add use rspotify::prelude::*.

• Type::Artist => ArtistId
• Type::Album => AlbumId
• Type::Track => TrackId
• Type::Playlist => PlaylistId
• Type::User => UserId
• Type::Show => ShowId
• Type::Episode => EpisodeId

Every kind of ID defines its own validity function, i.e., what characters it can be made up of, such as alphanumeric or any.

These types are just wrappers for Cow<str>, so their usage should be quite similar overall.

Examples

If an endpoint requires a TrackId, you may pass it as:

fn pause_track(id: TrackId<'_>) { /* ... */ }

let id = TrackId::from_id("4iV5W9uYEdYUVa79Axb7Rh").unwrap();
pause_track(id);

Notice how this way it’s type safe; the following example would fail at compile-time:

fn pause_track(id: TrackId<'_>) { /* ... */ }

let id = EpisodeId::from_id("4iV5W9uYEdYUVa79Axb7Rh").unwrap();
pause_track(id);

And this would panic because it’s a TrackId but its URI string specifies it’s an album (spotify:album:xxxx).

fn pause_track(id: TrackId<'_>) { /* ... */ }

let id = TrackId::from_uri("spotify:album:6akEvsycLGftJxYudPjmqK").unwrap();
pause_track(id);

A more complex example where an endpoint takes a vector of IDs of different types:

use rspotify_model::{TrackId, EpisodeId, PlayableId};

fn track(id: TrackId<'_>) { /* ... */ }
fn episode(id: EpisodeId<'_>) { /* ... */ }
fn add_to_queue(id: &[PlayableId<'_>]) { /* ... */ }

let tracks = [
    TrackId::from_uri("spotify:track:4iV5W9uYEdYUVa79Axb7Rh").unwrap(),
    TrackId::from_uri("spotify:track:5iKndSu1XI74U2OZePzP8L").unwrap(),
];
let episodes = [
    EpisodeId::from_id("0lbiy3LKzIY2fnyjioC11p").unwrap(),
    EpisodeId::from_id("4zugY5eJisugQj9rj8TYuh").unwrap(),
];

// First we get some info about the tracks and episodes
let track_info = tracks.iter().map(|id| track(id.as_ref())).collect::<Vec<_>>();
let ep_info = episodes.iter().map(|id| episode(id.as_ref())).collect::<Vec<_>>();
println!("Track info: {:?}", track_info);
println!("Episode info: {:?}", ep_info);

// And then we add both the tracks and episodes to the queue
let playable = tracks
    .into_iter()
    .map(|t| t.as_ref().into())
    .chain(
        episodes.into_iter().map(|e| e.as_ref().into())
    )
    .collect::<Vec<PlayableId>>();
add_to_queue(&playable);

Structs

• AlbumId
  ID of type Type::Album. The validity of its characters is defined by the closure |id| id.chars().all(|ch| ch.is_ascii_alphanumeric()).
• ArtistId
  ID of type Type::Artist. The validity of its characters is defined by the closure |id| id.chars().all(|ch| ch.is_ascii_alphanumeric()).
• EpisodeId
  ID of type Type::Episode. The validity of its characters is defined by the closure |id| id.chars().all(|ch| ch.is_ascii_alphanumeric()).
• PlaylistId
  ID of type Type::Playlist. The validity of its characters is defined by the closure |id| id.chars().all(|ch| ch.is_ascii_alphanumeric()).
• ShowId
  ID of type Type::Show. The validity of its characters is defined by the closure |id| id.chars().all(|ch| ch.is_ascii_alphanumeric()).
• TrackId
  ID of type Type::Track. The validity of its characters is defined by the closure |id| id.chars().all(|ch| ch.is_ascii_alphanumeric()).
• UserId
  ID of type Type::User. The validity of its characters is defined by the closure |_| true.

Enums

• IdError
  Spotify ID or URI parsing error
• PlayContextId
  Grouping up multiple kinds of IDs to treat them generically. This also implements Id, and From to instantiate it.
• PlayableId
  Grouping up multiple kinds of IDs to treat them generically. This also implements Id and From to instantiate it.

Traits

• Id
  The main interface for an ID.

Functions

• parse_uri
  A lower level function to parse a URI into both its type and its actual ID. Note that this function doesn’t check the validity of the returned ID (e.g., whether it’s alphanumeric; that should be done in Id::from_id).