Struct http_types::cookies::Cookie [−][src]
pub struct Cookie<'c> { /* fields omitted */ }
Expand description
Representation of an HTTP cookie.
Constructing a Cookie
To construct a cookie with only a name/value, use Cookie::new()
:
use cookie::Cookie; let cookie = Cookie::new("name", "value"); assert_eq!(&cookie.to_string(), "name=value");
To construct more elaborate cookies, use Cookie::build()
and
CookieBuilder
methods:
use cookie::Cookie; let cookie = Cookie::build("name", "value") .domain("www.rust-lang.org") .path("/") .secure(true) .http_only(true) .finish();
Implementations
Creates a new Cookie
with the given name and value.
Example
use cookie::Cookie; let cookie = Cookie::new("name", "value"); assert_eq!(cookie.name_value(), ("name", "value"));
Creates a new Cookie
with the given name and an empty value.
Example
use cookie::Cookie; let cookie = Cookie::named("name"); assert_eq!(cookie.name(), "name"); assert!(cookie.value().is_empty());
Creates a new CookieBuilder
instance from the given key and value
strings.
Example
use cookie::Cookie; let c = Cookie::build("foo", "bar").finish(); assert_eq!(c.name_value(), ("foo", "bar"));
Parses a Cookie
from the given HTTP cookie header value string. Does
not perform any percent-decoding.
Example
use cookie::Cookie; let c = Cookie::parse("foo=bar%20baz; HttpOnly").unwrap(); assert_eq!(c.name_value(), ("foo", "bar%20baz")); assert_eq!(c.http_only(), Some(true));
This is supported on crate feature percent-encode
only.
percent-encode
only.Parses a Cookie
from the given HTTP cookie header value string where
the name and value fields are percent-encoded. Percent-decodes the
name/value fields.
Example
use cookie::Cookie; let c = Cookie::parse_encoded("foo=bar%20baz; HttpOnly").unwrap(); assert_eq!(c.name_value(), ("foo", "bar baz")); assert_eq!(c.http_only(), Some(true));
This is supported on crate feature percent-encode
only.
percent-encode
only.Wraps self
in an EncodedCookie
: a cost-free wrapper around Cookie
whose Display
implementation percent-encodes the name and value of the
wrapped Cookie
.
Example
use cookie::Cookie; let mut c = Cookie::new("my name", "this; value?"); assert_eq!(&c.encoded().to_string(), "my%20name=this%3B%20value%3F");
Converts self
into a Cookie
with a static lifetime with as few
allocations as possible.
Example
use cookie::Cookie; let c = Cookie::new("a", "b"); let owned_cookie = c.into_owned(); assert_eq!(owned_cookie.name_value(), ("a", "b"));
Returns the name of self
.
Example
use cookie::Cookie; let c = Cookie::new("name", "value"); assert_eq!(c.name(), "name");
Returns the value of self
.
Example
use cookie::Cookie; let c = Cookie::new("name", "value"); assert_eq!(c.value(), "value");
Returns the name and value of self
as a tuple of (name, value)
.
Example
use cookie::Cookie; let c = Cookie::new("name", "value"); assert_eq!(c.name_value(), ("name", "value"));
Returns whether this cookie was marked HttpOnly
or not. Returns
Some(true)
when the cookie was explicitly set (manually or parsed) as
HttpOnly
, Some(false)
when http_only
was manually set to false
,
and None
otherwise.
Example
use cookie::Cookie; let c = Cookie::parse("name=value; httponly").unwrap(); assert_eq!(c.http_only(), Some(true)); let mut c = Cookie::new("name", "value"); assert_eq!(c.http_only(), None); let mut c = Cookie::new("name", "value"); assert_eq!(c.http_only(), None); // An explicitly set "false" value. c.set_http_only(false); assert_eq!(c.http_only(), Some(false)); // An explicitly set "true" value. c.set_http_only(true); assert_eq!(c.http_only(), Some(true));
Returns whether this cookie was marked Secure
or not. Returns
Some(true)
when the cookie was explicitly set (manually or parsed) as
Secure
, Some(false)
when secure
was manually set to false
, and
None
otherwise.
Example
use cookie::Cookie; let c = Cookie::parse("name=value; Secure").unwrap(); assert_eq!(c.secure(), Some(true)); let mut c = Cookie::parse("name=value").unwrap(); assert_eq!(c.secure(), None); let mut c = Cookie::new("name", "value"); assert_eq!(c.secure(), None); // An explicitly set "false" value. c.set_secure(false); assert_eq!(c.secure(), Some(false)); // An explicitly set "true" value. c.set_secure(true); assert_eq!(c.secure(), Some(true));
Returns the SameSite
attribute of this cookie if one was specified.
Example
use cookie::{Cookie, SameSite}; let c = Cookie::parse("name=value; SameSite=Lax").unwrap(); assert_eq!(c.same_site(), Some(SameSite::Lax));
Returns the specified max-age of the cookie if one was specified.
Example
use cookie::Cookie; let c = Cookie::parse("name=value").unwrap(); assert_eq!(c.max_age(), None); let c = Cookie::parse("name=value; Max-Age=3600").unwrap(); assert_eq!(c.max_age().map(|age| age.whole_hours()), Some(1));
Returns the Path
of the cookie if one was specified.
Example
use cookie::Cookie; let c = Cookie::parse("name=value").unwrap(); assert_eq!(c.path(), None); let c = Cookie::parse("name=value; Path=/").unwrap(); assert_eq!(c.path(), Some("/")); let c = Cookie::parse("name=value; path=/sub").unwrap(); assert_eq!(c.path(), Some("/sub"));
Returns the Domain
of the cookie if one was specified.
Example
use cookie::Cookie; let c = Cookie::parse("name=value").unwrap(); assert_eq!(c.domain(), None); let c = Cookie::parse("name=value; Domain=crates.io").unwrap(); assert_eq!(c.domain(), Some("crates.io"));
Returns the Expires
time of the cookie if one was specified.
Example
use cookie::Cookie; let c = Cookie::parse("name=value").unwrap(); assert_eq!(c.expires(), None); let expire_time = "Wed, 21 Oct 2017 07:28:00 GMT"; let cookie_str = format!("name=value; Expires={}", expire_time); let c = Cookie::parse(cookie_str).unwrap(); assert_eq!(c.expires().map(|t| t.year()), Some(2017));
Sets the name of self
to name
.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.name(), "name"); c.set_name("foo"); assert_eq!(c.name(), "foo");
Sets the value of self
to value
.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.value(), "value"); c.set_value("bar"); assert_eq!(c.value(), "bar");
Sets the value of http_only
in self
to value
. If value
is
None
, the field is unset.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.http_only(), None); c.set_http_only(true); assert_eq!(c.http_only(), Some(true)); c.set_http_only(false); assert_eq!(c.http_only(), Some(false)); c.set_http_only(None); assert_eq!(c.http_only(), None);
Sets the value of secure
in self
to value
. If value
is None
,
the field is unset.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.secure(), None); c.set_secure(true); assert_eq!(c.secure(), Some(true)); c.set_secure(false); assert_eq!(c.secure(), Some(false)); c.set_secure(None); assert_eq!(c.secure(), None);
Sets the value of same_site
in self
to value
. If value
is
None
, the field is unset. If value
is SameSite::None
, the “Secure”
flag will be set when the cookie is written out unless secure
is
explicitly set to false
via Cookie::set_secure()
or the equivalent
builder method.
Example
use cookie::{Cookie, SameSite}; let mut c = Cookie::new("name", "value"); assert_eq!(c.same_site(), None); c.set_same_site(SameSite::None); assert_eq!(c.same_site(), Some(SameSite::None)); assert_eq!(c.to_string(), "name=value; SameSite=None; Secure"); c.set_secure(false); assert_eq!(c.to_string(), "name=value; SameSite=None"); let mut c = Cookie::new("name", "value"); assert_eq!(c.same_site(), None); c.set_same_site(SameSite::Strict); assert_eq!(c.same_site(), Some(SameSite::Strict)); assert_eq!(c.to_string(), "name=value; SameSite=Strict"); c.set_same_site(None); assert_eq!(c.same_site(), None); assert_eq!(c.to_string(), "name=value");
Sets the value of max_age
in self
to value
. If value
is None
,
the field is unset.
Example
extern crate time; use cookie::Cookie; use time::Duration; let mut c = Cookie::new("name", "value"); assert_eq!(c.max_age(), None); c.set_max_age(Duration::hours(10)); assert_eq!(c.max_age(), Some(Duration::hours(10))); c.set_max_age(None); assert!(c.max_age().is_none());
Sets the path
of self
to path
.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.path(), None); c.set_path("/"); assert_eq!(c.path(), Some("/"));
Unsets the path
of self
.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.path(), None); c.set_path("/"); assert_eq!(c.path(), Some("/")); c.unset_path(); assert_eq!(c.path(), None);
Sets the domain
of self
to domain
.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.domain(), None); c.set_domain("rust-lang.org"); assert_eq!(c.domain(), Some("rust-lang.org"));
Unsets the domain
of self
.
Example
use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.domain(), None); c.set_domain("rust-lang.org"); assert_eq!(c.domain(), Some("rust-lang.org")); c.unset_domain(); assert_eq!(c.domain(), None);
Sets the expires field of self
to time
. If time
is None
, the
field is unset.
Example
extern crate time; use time::{Duration, OffsetDateTime}; use cookie::Cookie; let mut c = Cookie::new("name", "value"); assert_eq!(c.expires(), None); let mut now = OffsetDateTime::now(); now += Duration::weeks(52); c.set_expires(now); assert!(c.expires().is_some()); c.set_expires(None); assert!(c.expires().is_none());
Makes self
a “permanent” cookie by extending its expiration and max
age 20 years into the future.
Example
extern crate time; use cookie::Cookie; use time::Duration; let mut c = Cookie::new("foo", "bar"); assert!(c.expires().is_none()); assert!(c.max_age().is_none()); c.make_permanent(); assert!(c.expires().is_some()); assert_eq!(c.max_age(), Some(Duration::days(365 * 20)));
Returns the name of self
as a string slice of the raw string self
was originally parsed from. If self
was not originally parsed from a
raw string, returns None
.
This method differs from Cookie::name()
in that it returns a string
with the same lifetime as the originally parsed string. This lifetime
may outlive self
. If a longer lifetime is not required, or you’re
unsure if you need a longer lifetime, use Cookie::name()
.
Example
use cookie::Cookie; let cookie_string = format!("{}={}", "foo", "bar"); // `c` will be dropped at the end of the scope, but `name` will live on let name = { let c = Cookie::parse(cookie_string.as_str()).unwrap(); c.name_raw() }; assert_eq!(name, Some("foo"));
Returns the value of self
as a string slice of the raw string self
was originally parsed from. If self
was not originally parsed from a
raw string, returns None
.
This method differs from Cookie::value()
in that it returns a
string with the same lifetime as the originally parsed string. This
lifetime may outlive self
. If a longer lifetime is not required, or
you’re unsure if you need a longer lifetime, use Cookie::value()
.
Example
use cookie::Cookie; let cookie_string = format!("{}={}", "foo", "bar"); // `c` will be dropped at the end of the scope, but `value` will live on let value = { let c = Cookie::parse(cookie_string.as_str()).unwrap(); c.value_raw() }; assert_eq!(value, Some("bar"));
Returns the Path
of self
as a string slice of the raw string self
was originally parsed from. If self
was not originally parsed from a
raw string, or if self
doesn’t contain a Path
, or if the Path
has
changed since parsing, returns None
.
This method differs from Cookie::path()
in that it returns a
string with the same lifetime as the originally parsed string. This
lifetime may outlive self
. If a longer lifetime is not required, or
you’re unsure if you need a longer lifetime, use Cookie::path()
.
Example
use cookie::Cookie; let cookie_string = format!("{}={}; Path=/", "foo", "bar"); // `c` will be dropped at the end of the scope, but `path` will live on let path = { let c = Cookie::parse(cookie_string.as_str()).unwrap(); c.path_raw() }; assert_eq!(path, Some("/"));
Returns the Domain
of self
as a string slice of the raw string
self
was originally parsed from. If self
was not originally parsed
from a raw string, or if self
doesn’t contain a Domain
, or if the
Domain
has changed since parsing, returns None
.
This method differs from Cookie::domain()
in that it returns a
string with the same lifetime as the originally parsed string. This
lifetime may outlive self
struct. If a longer lifetime is not
required, or you’re unsure if you need a longer lifetime, use
Cookie::domain()
.
Example
use cookie::Cookie; let cookie_string = format!("{}={}; Domain=crates.io", "foo", "bar"); //`c` will be dropped at the end of the scope, but `domain` will live on let domain = { let c = Cookie::parse(cookie_string.as_str()).unwrap(); c.domain_raw() }; assert_eq!(domain, Some("crates.io"));
Trait Implementations
Auto Trait Implementations
impl<'c> RefUnwindSafe for Cookie<'c>
impl<'c> UnwindSafe for Cookie<'c>
Blanket Implementations
Mutably borrows from an owned value. Read more
type Output = T
type Output = T
Should always be Self