rocket/serde/
uuid.rs

Help
1//! UUID path/query parameter and form value parsing support.
2//!
3//! # Enabling
4//!
5//! This module is only available when the `uuid` feature is enabled. Enable it
6//! in `Cargo.toml` as follows:
7//!
8//! ```toml
9//! [dependencies.rocket]
10//! version = "0.5.1"
11//! features = ["uuid"]
12//! ```
13//!
14//! # Usage
15//!
16//! `Uuid` implements [`FromParam`] and [`FromFormField`] (i.e,
17//! [`FromForm`](crate::form::FromForm)), allowing UUID values to be accepted
18//! directly in paths, queries, and forms. You can use the `Uuid` type directly
19//! as a target of a dynamic parameter:
20//!
21//! ```rust
22//! # #[macro_use] extern crate rocket;
23//! use rocket::serde::uuid::Uuid;
24//!
25//! #[get("/users/<id>")]
26//! fn user(id: Uuid) -> String {
27//!     format!("We found: {}", id)
28//! }
29//! ```
30//!
31//! You can also use the `Uuid` as a form value, including in query strings:
32//!
33//! ```rust
34//! # #[macro_use] extern crate rocket;
35//! use rocket::serde::uuid::Uuid;
36//!
37//! #[get("/user?<id>")]
38//! fn user(id: Uuid) -> String {
39//!     format!("User ID: {}", id)
40//! }
41//! ```
42//!
43//! Additionally, `Uuid` implements `UriDisplay<P>` for all `P`. As such, route
44//! URIs including `Uuid`s can be generated in a type-safe manner:
45//!
46//! ```rust
47//! # #[macro_use] extern crate rocket;
48//! use rocket::serde::uuid::Uuid;
49//! use rocket::response::Redirect;
50//!
51//! #[get("/user/<id>")]
52//! fn user(id: Uuid) -> String {
53//!     format!("User ID: {}", id)
54//! }
55//!
56//! #[get("/user?<id>")]
57//! fn old_user_path(id: Uuid) -> Redirect {
58//!     # let _ = Redirect::to(uri!(user(&id)));
59//!     # let _ = Redirect::to(uri!(old_user_path(id)));
60//!     # let _ = Redirect::to(uri!(old_user_path(&id)));
61//!     Redirect::to(uri!(user(id)))
62//! }
63//! ```
64//!
65//! # Extra Features
66//!
67//! The [`uuid`](https://docs.rs/uuid/1) crate exposes extra `v{n}` features
68//! for generating UUIDs which are not enabled by Rocket. To enable these
69//! features, depend on `uuid` directly. The extra functionality can be accessed
70//! via both `rocket::serde::uuid::Uuid` or the direct `uuid::Uuid`; the types
71//! are one and the same.
72//!
73//! ```toml
74//! [dependencies.uuid]
75//! version = "1"
76//! features = ["v1", "v4"]
77//! ```
78
79use crate::request::FromParam;
80use crate::form::{self, FromFormField, ValueField};
81
82/// Error returned on [`FromParam`] or [`FromFormField`] failures.
83///
84pub use uuid_::Error;
85
86pub use uuid_::{Uuid, Builder, Variant, Version, Bytes, uuid, fmt};
87
88impl<'a> FromParam<'a> for Uuid {
89    type Error = Error;
90
91    /// A value is successfully parsed if `param` is a properly formatted Uuid.
92    /// Otherwise, an error is returned.
93    #[inline(always)]
94    fn from_param(param: &'a str) -> Result<Uuid, Self::Error> {
95        param.parse()
96    }
97}
98
99impl<'v> FromFormField<'v> for Uuid {
100    #[inline]
101    fn from_value(field: ValueField<'v>) -> form::Result<'v, Self> {
102        Ok(field.value.parse().map_err(form::error::Error::custom)?)
103    }
104}
105
106#[cfg(test)]
107mod test {
108    use super::{Uuid, FromParam};
109
110    #[test]
111    fn test_from_param() {
112        let uuid_str = "c1aa1e3b-9614-4895-9ebd-705255fa5bc2";
113        let uuid = Uuid::from_param(uuid_str).unwrap();
114        assert_eq!(uuid_str, uuid.to_string());
115    }
116
117    #[test]
118    fn test_from_param_invalid() {
119        let uuid_str = "c1aa1e3b-9614-4895-9ebd-705255fa5bc2p";
120        assert!(Uuid::from_param(uuid_str).is_err());
121    }
122}
rocket/serde/uuid.rs

rocket/serde/
uuid.rs
