Merge pull request #161 from kstep/uri-type

Initial id type proposal

CHANGELOG.md

@@ -13,6 +13,7 @@ If we missed any change or there's something you'd like to discuss about this ve
   + Remove `itertools` dependency by using the standard library.
   + Remove `rand` in place of `getrandom` to [reduce total dependencies and compile times](https://github.com/ramsayleung/rspotify/issues/108#issuecomment-673587185).
   + Cleanup, reduced repetitive code and boilerplate internally in several places ([#117](https://github.com/ramsayleung/rspotify/pull/117), [#113](https://github.com/ramsayleung/rspotify/pull/113), [#107](https://github.com/ramsayleung/rspotify/pull/107), [#106](https://github.com/ramsayleung/rspotify/pull/106)).
+  + Added internal zero-copy type for Spotify ids, reduced number of allocations/clones ([#161](https://github.com/ramsayleung/rspotify/pull/161)).
   + Updated dependencies to the latest versions, integrated Dependabot to keep track of them ([#105](https://github.com/ramsayleung/rspotify/pull/105), [#111](https://github.com/ramsayleung/rspotify/pull/111)).
 - ([#145](https://github.com/ramsayleung/rspotify/pull/145)) Mark `SimplifiedEpisode.language` as deprecated.
 - ([#145](https://github.com/ramsayleung/rspotify/pull/145)) Derive `PartialEq` and `Eq` for models:
@@ -106,15 +107,15 @@ If we missed any change or there's something you'd like to discuss about this ve
     + The `ClientError::CLI` variant, for whenever user interaction goes wrong
 - Fix typo in `user_playlist_remove_specific_occurrenes_of_tracks`, now it's `user_playlist_remove_specific_occurrences_of_tracks`.
 - ([#123](https://github.com/ramsayleung/rspotify/pull/123))All fallible calls in the client return a `ClientError` rather than using `failure`.
-- ([#128](https://github.com/ramsayleung/rspotify/pull/128)) Endpoints take `Vec<String>/&[String]` as parameter have changed to `impl IntoIterator<Item = &str>`, which is backward compatibility.
-  + The endpoints which changes parameter from `Vec<String>` to `impl IntoIterator<Item = &str>`:
+- ([#161](https://github.com/ramsayleung/rspotify/pull/161)) Endpoints taking `Vec<String>/&[String]` as parameter have changed to `impl IntoIterator<Item = &Id<Type>>`.
+  + The endpoints which changes parameter from `Vec<String>` to `impl IntoIterator<Item = &Id<Type>>`:
 	- `artists`
 	- `albums`
 	- `save_shows`
 	- `get_several_episodes`
 	- `check_users_saved_shows`
 	- `remove_users_saved_shows`
-  + The endpoints which changes parameter from `&[String]` to `impl IntoIterator<Item = &str>`:
+  + The endpoints which changes parameter from `&[String]` to `impl IntoIterator<Item = &Id<Type>>`:
 	- `user_playlist_add_tracks`
 	- `user_playlist_replace_tracks`
 	- `user_playlist_remove_all_occurrences_of_tracks`
@@ -130,6 +131,13 @@ If we missed any change or there's something you'd like to discuss about this ve
 	- `user_follow_users`
 	- `user_unfollow_users`
 	- `audios_features`
+  + The endpoints which changes parameter from `String` to `&Id<Type>`:
+        - `get_a_show`
+        - `get_an_episode`
+        - `get_shows_episodes`
+  + The endpoint which changes parameter from `Vec<Map<String, Value>>` to `Vec<TrackPositions>`:
+        - `playlist_remove_specific_occurrences_of_tracks`
+- The `Offset` type is now an enum to match API logic, `Offset::Position` is `u32` now (it's not a position in time, it's a position in a playlist, and you can't have both `position` and `uri` fields at the same time).
 - ([#128](https://github.com/ramsayleung/rspotify/pull/128)) Rename endpoints with more fitting name:
   + `audio_analysis` -> `track_analysis`
   + `audio_features` -> `track_features`
@@ -158,6 +166,7 @@ If we missed any change or there's something you'd like to discuss about this ve
   + Change `{FullArtist, FullPlaylist, PublicUser, PrivateUser}::followers` from `HashMap<String, Option<Value>>` to struct `Followers`
   + Replace `Actions::disallows` with a `Vec<DisallowKey>` by removing all entires whose value is false, which will result in a simpler API
   + Replace `{FullAlbum, SimplifiedEpisode, FullEpisode}::release_date_precision` from `String` to `DatePrecision` enum, makes it easier to use.
+  + Id and URI parameters are type-safe now everywhere, `Id<Type>` and `IdBuf<Type>` types for ids/URIs added (non-owning and owning structs).
 - ([#157](https://github.com/ramsayleung/rspotify/pull/157))Keep polishing models to make it easier to use:
   + Constrain visibility of `FullArtists` struct with `pub (in crate)`, make `artists` and `artist_related_artists` endpoints return a `Vec<FullArtist>` instead.
   + Constrain visibility of `FullTracks` struct with `pub (in crate)`, make `tracks` and `artist_top_tracks` endpoints return a `Vec<FullTrack>` instead.

examples/album.rs

@@ -1,4 +1,5 @@
 use rspotify::client::SpotifyBuilder;
+use rspotify::model::Id;
 use rspotify::oauth2::CredentialsBuilder;
 
 #[tokio::main]
@@ -34,7 +35,7 @@ async fn main() {
     spotify.request_client_token().await.unwrap();
 
     // Running the requests
-    let birdy_uri = "spotify:album:0sNOF9WDwhWunNAHPD3Baj";
+    let birdy_uri = Id::from_uri("spotify:album:0sNOF9WDwhWunNAHPD3Baj").unwrap();
     let albums = spotify.album(birdy_uri).await;
 
     println!("Response: {:#?}", albums);

examples/track.rs

@@ -1,4 +1,5 @@
 use rspotify::client::SpotifyBuilder;
+use rspotify::model::Id;
 use rspotify::oauth2::CredentialsBuilder;
 
 #[tokio::main]
@@ -34,7 +35,7 @@ async fn main() {
     spotify.request_client_token().await.unwrap();
 
     // Running the requests
-    let birdy_uri = "spotify:track:6rqhFgbbKwnb9MLmUQDhG6";
+    let birdy_uri = Id::from_uri("spotify:track:6rqhFgbbKwnb9MLmUQDhG6").unwrap();
     let track = spotify.track(birdy_uri).await;
 
     println!("Response: {:#?}", track);

examples/tracks.rs

@@ -1,4 +1,5 @@
 use rspotify::client::SpotifyBuilder;
+use rspotify::model::Id;
 use rspotify::oauth2::CredentialsBuilder;
 
 #[tokio::main]
@@ -33,8 +34,8 @@ async fn main() {
     // so `...` is used instead of `prompt_for_user_token`.
     spotify.request_client_token().await.unwrap();
 
-    let birdy_uri1 = "spotify:track:3n3Ppam7vgaVa1iaRUc9Lp";
-    let birdy_uri2 = "spotify:track:3twNvmDtFQtAd5gMKedhLD";
+    let birdy_uri1 = Id::from_uri("spotify:track:3n3Ppam7vgaVa1iaRUc9Lp").unwrap();
+    let birdy_uri2 = Id::from_uri("spotify:track:3twNvmDtFQtAd5gMKedhLD").unwrap();
     let track_uris = vec![birdy_uri1, birdy_uri2];
     let tracks = spotify.tracks(track_uris, None).await;
     println!("Response: {:?}", tracks);

examples/with_refresh_token.rs

@@ -16,15 +16,16 @@
 //! so in the case of Spotify it doesn't seem to revoke them at all.
 
 use rspotify::client::{Spotify, SpotifyBuilder};
+use rspotify::model::Id;
 use rspotify::oauth2::{CredentialsBuilder, OAuthBuilder};
 
 // Sample request that will follow some artists, print the user's
 // followed artists, and then unfollow the artists.
 async fn do_things(spotify: Spotify) {
     let artists = vec![
-        "3RGLhK1IP9jnYFH4BRFJBS", // The Clash
-        "0yNLKJebCb8Aueb54LYya3", // New Order
-        "2jzc5TC5TVFLXQlBNiIUzE", // a-ha
+        Id::from_id("3RGLhK1IP9jnYFH4BRFJBS").unwrap(), // The Clash
+        Id::from_id("0yNLKJebCb8Aueb54LYya3").unwrap(), // New Order
+        Id::from_id("2jzc5TC5TVFLXQlBNiIUzE").unwrap(), // a-ha
     ];
     spotify
         .user_follow_artists(artists.clone())