Struct Cookie

pub struct Cookie<'a> {
    pub path: CookiePath,
    pub domain: CookieDomain,
    pub expires: CookieExpiration,
    /* private fields */
}

A cookie conforming more closely to IETF RFC6265

Fields

path: CookiePath

The Path attribute from a Set-Cookie header or the default-path as determined from the request-uri

domain: CookieDomain

The Domain attribute from a Set-Cookie header, or a HostOnly variant if no non-empty Domain attribute found

expires: CookieExpiration

For a persistent Cookie (see IETF RFC6265 Section 5.3), the expiration time as defined by the Max-Age or Expires attribute, otherwise SessionEnd, indicating a non-persistent Cookie that should expire at the end of the session

Implementations

impl<'a> Cookie<'a>

pub fn matches(&self, request_url: &Url) -> bool

Whether this Cookie should be included for request_url

pub fn is_persistent(&self) -> bool

Should this Cookie be persisted across sessions?

pub fn expire(&mut self)

Expire this cookie

pub fn is_expired(&self) -> bool

Return whether the Cookie is expired now

pub fn expires_by(&self, utc_tm: &OffsetDateTime) -> bool

Indicates if the Cookie expires as of utc_tm.

pub fn parse<S>(cookie_str: S, request_url: &Url) -> CookieResult<'a>

where S: Into<Cow<'a, str>>,

Parses a new cookie_store::Cookie from cookie_str.

pub fn try_from_raw_cookie( raw_cookie: &RawCookie<'a>, request_url: &Url, ) -> CookieResult<'a>

Create a new cookie_store::Cookie from a cookie::Cookie (from the cookie crate) received from request_url.

pub fn into_owned(self) -> Cookie<'static>

Methods from Deref<Target = RawCookie<'a>>

pub fn name(&self) -> &str

Returns the name of self.

Example

use cookie::Cookie;

let c = Cookie::new("name", "value");
assert_eq!(c.name(), "name");

pub fn value(&self) -> &str

Returns the value of self.

Does not strip surrounding quotes. See Cookie::value_trimmed() for a version that does.

Example

use cookie::Cookie;

let c = Cookie::new("name", "value");
assert_eq!(c.value(), "value");

let c = Cookie::new("name", "\"value\"");
assert_eq!(c.value(), "\"value\"");

pub fn value_trimmed(&self) -> &str

Returns the value of self with surrounding double-quotes trimmed.

This is not the value of the cookie (that is Cookie::value()). Instead, this is the value with a surrounding pair of double-quotes, if any, trimmed away. Quotes are only trimmed when they form a pair and never otherwise. The trimmed value is never used for other operations, such as equality checking, on self.

Example

use cookie::Cookie;
let c0 = Cookie::new("name", "value");
assert_eq!(c0.value_trimmed(), "value");

let c = Cookie::new("name", "\"value\"");
assert_eq!(c.value_trimmed(), "value");
assert!(c != c0);

let c = Cookie::new("name", "\"value");
assert_eq!(c.value(), "\"value");
assert_eq!(c.value_trimmed(), "\"value");
assert!(c != c0);

let c = Cookie::new("name", "\"value\"\"");
assert_eq!(c.value(), "\"value\"\"");
assert_eq!(c.value_trimmed(), "value\"");
assert!(c != c0);

pub fn name_value(&self) -> (&str, &str)

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"));

pub fn name_value_trimmed(&self) -> (&str, &str)

Returns the name and trimmed value of self as a tuple of (name, trimmed_value).

Example

use cookie::Cookie;

let c = Cookie::new("name", "\"value\"");
assert_eq!(c.name_value_trimmed(), ("name", "value"));

pub fn http_only(&self) -> Option<bool>

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));

pub fn secure(&self) -> Option<bool>

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));

pub fn same_site(&self) -> Option<SameSite>

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));

pub fn partitioned(&self) -> Option<bool>

Returns whether this cookie was marked Partitioned or not. Returns Some(true) when the cookie was explicitly set (manually or parsed) as Partitioned, Some(false) when partitioned was manually set to false, and None otherwise.

Note: This cookie attribute is an HTTP draft! Its meaning and definition are not standardized and therefore subject to change.

Example

use cookie::Cookie;

let c = Cookie::parse("name=value; Partitioned").unwrap();
assert_eq!(c.partitioned(), Some(true));

let mut c = Cookie::parse("name=value").unwrap();
assert_eq!(c.partitioned(), None);

let mut c = Cookie::new("name", "value");
assert_eq!(c.partitioned(), None);

// An explicitly set "false" value.
c.set_partitioned(false);
assert_eq!(c.partitioned(), Some(false));

// An explicitly set "true" value.
c.set_partitioned(true);
assert_eq!(c.partitioned(), Some(true));

pub fn max_age(&self) -> Option<Duration>

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));

pub fn path(&self) -> Option<&str>

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"));

pub fn domain(&self) -> Option<&str>

Returns the Domain of the cookie if one was specified.

This does not consider whether the Domain is valid; validation is left to higher-level libraries, as needed. However, if the Domain starts with a leading ., the leading . is stripped.

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"));

let c = Cookie::parse("name=value; Domain=.crates.io").unwrap();
assert_eq!(c.domain(), Some("crates.io"));

// Note that `..crates.io` is not a valid domain.
let c = Cookie::parse("name=value; Domain=..crates.io").unwrap();
assert_eq!(c.domain(), Some(".crates.io"));

pub fn expires(&self) -> Option<Expiration>

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).build();
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));

pub fn expires_datetime(&self) -> Option<OffsetDateTime>

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).build();
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));

pub fn name_raw(&self) -> Option<&'c str>

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"));

pub fn value_raw(&self) -> Option<&'c str>

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"));

pub fn path_raw(&self) -> Option<&'c str>

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("/"));

pub fn domain_raw(&self) -> Option<&'c str>

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.

Like Cookie::domain(), this does not consider whether Domain is valid; validation is left to higher-level libraries, as needed. However, if Domain starts with a leading ., the leading . is stripped.

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"));

pub fn encoded<'a>(&'a self) -> Display<'a, 'c>

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).build();
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");

pub fn stripped<'a>(&'a self) -> Display<'a, 'c>

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("/").build();
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

impl<'a> Clone for Cookie<'a>

fn clone(&self) -> Cookie<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Cookie<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Deref for Cookie<'a>

type Target = Cookie<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de, 'a> Deserialize<'de> for Cookie<'a>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a> From<Cookie<'a>> for Cookie<'a>

fn from(cookie: Cookie<'a>) -> RawCookie<'static>

Converts to this type from the input type.

impl<'a> PartialEq for Cookie<'a>

fn eq(&self, other: &Cookie<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Serialize for Cookie<'a>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> StructuralPartialEq for Cookie<'a>