Struct cookie::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));
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 Expiration
of the cookie if one was specified.
Example
use cookie::{Cookie, Expiration}; let c = Cookie::parse("name=value").unwrap(); assert_eq!(c.expires(), None); // Here, `cookie.expires_datetime()` returns `None`. let c = Cookie::build("name", "value").expires(None).finish(); assert_eq!(c.expires(), Some(Expiration::Session)); 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().and_then(|e| e.datetime()).map(|t| t.year()), Some(2017));
Returns the expiration date-time of the cookie if one was specified.
Example
use cookie::Cookie; let c = Cookie::parse("name=value").unwrap(); assert_eq!(c.expires_datetime(), None); // Here, `cookie.expires()` returns `Some`. let c = Cookie::build("name", "value").expires(None).finish(); assert_eq!(c.expires_datetime(), 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_datetime().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
use cookie::Cookie; use cookie::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
, an
expiration of Session
is set.
Example
use cookie::{Cookie, Expiration}; use cookie::time::{Duration, OffsetDateTime}; let mut c = Cookie::new("name", "value"); assert_eq!(c.expires(), None); let mut now = OffsetDateTime::now_utc(); now += Duration::weeks(52); c.set_expires(now); assert!(c.expires().is_some()); c.set_expires(None); assert_eq!(c.expires(), Some(Expiration::Session));
Unsets the expires
of self
.
Example
use cookie::{Cookie, Expiration}; let mut c = Cookie::new("name", "value"); assert_eq!(c.expires(), None); c.set_expires(None); assert_eq!(c.expires(), Some(Expiration::Session)); c.unset_expires(); assert_eq!(c.expires(), None);
Makes self
a “permanent” cookie by extending its expiration and max
age 20 years into the future.
Example
use cookie::Cookie; use cookie::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)));
Make self
a “removal” cookie by clearing its value, setting a max-age
of 0
, and setting an expiration date far in the past.
Example
use cookie::Cookie; use cookie::time::Duration; let mut c = Cookie::new("foo", "bar"); c.make_permanent(); assert_eq!(c.max_age(), Some(Duration::days(365 * 20))); assert_eq!(c.value(), "bar"); c.make_removal(); assert_eq!(c.value(), ""); assert_eq!(c.max_age(), Some(Duration::ZERO));
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"));
This is supported on crate feature percent-encode
only.
percent-encode
only.Wraps self
in an encoded Display
: a cost-free wrapper around
Cookie
whose fmt::Display
implementation percent-encodes the name
and value of the wrapped Cookie
.
The returned structure can be chained with Display::stripped()
to
display only the name and value.
Example
use cookie::Cookie; let mut c = Cookie::build("my name", "this; value?").secure(true).finish(); assert_eq!(&c.encoded().to_string(), "my%20name=this%3B%20value%3F; Secure"); assert_eq!(&c.encoded().stripped().to_string(), "my%20name=this%3B%20value%3F");
Wraps self
in a stripped Display
]: a cost-free wrapper around
Cookie
whose fmt::Display
implementation prints only the name
and value
of the wrapped Cookie
.
The returned structure can be chained with Display::encoded()
to
encode the name and value.
Example
use cookie::Cookie; let mut c = Cookie::build("key?", "value").secure(true).path("/").finish(); assert_eq!(&c.stripped().to_string(), "key?=value"); // Note: `encoded()` is only available when `percent-encode` is enabled. assert_eq!(&c.stripped().encoded().to_string(), "key%3F=value");
Trait Implementations
Formats the cookie self
as a Set-Cookie
header value.
Does not percent-encode any values. To percent-encode, use
Cookie::encoded()
.
Example
use cookie::Cookie; let mut cookie = Cookie::build("foo", "bar") .path("/") .finish(); assert_eq!(&cookie.to_string(), "foo=bar; Path=/");
type Err = ParseError
type Err = ParseError
The associated error which can be returned from parsing.
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