Struct cookie::Cookie

pub struct Cookie<'c> { /* fields omitted */ }

Representation of an HTTP cookie.

Constructing a Cookie

To construct a cookie with only a name/value, use the new method:

use cookie::Cookie;

let cookie = Cookie::new("name", "value");
assert_eq!(&cookie.to_string(), "name=value");

To construct more elaborate cookies, use the build method and CookieBuilder methods:

use cookie::Cookie;

let cookie = Cookie::build("name", "value")
    .domain("www.rust-lang.org")
    .path("/")
    .secure(true)
    .http_only(true)
    .finish();

Methods

impl Cookie<'static>

pub fn new<N, V>(name: N, value: V) -> Cookie<'static> where     N: Into<Cow<'static, str>>,     V: Into<Cow<'static, str>>,

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

pub fn named<N>(name: N) -> Cookie<'static> where     N: Into<Cow<'static, str>>,

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

pub fn build<N, V>(name: N, value: V) -> CookieBuilder where     N: Into<Cow<'static, str>>,     V: Into<Cow<'static, str>>,

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

impl<'c> Cookie<'c>

pub fn parse<S>(s: S) -> Result<Cookie<'c>, ParseError> where     S: Into<Cow<'c, str>>,

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(), true);

pub fn parse_encoded<S>(s: S) -> Result<Cookie<'c>, ParseError> where     S: Into<Cow<'c, str>>,

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.

This API requires the percent-encode feature to be enabled on this crate.

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(), true);

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

Wraps self in an EncodedCookie: a cost-free wrapper around Cookie whose Display implementation percent-encodes the name and value of the wrapped Cookie.

This method is only available when the percent-encode feature is enabled.

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

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

Converts self into a Cookie with a static lifetime. This method results in at most one allocation.

Example

use cookie::Cookie;

let c = Cookie::new("a", "b");
let owned_cookie = c.into_owned();
assert_eq!(owned_cookie.name_value(), ("a", "b"));

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.

Example

use cookie::Cookie;

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

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 http_only(&self) -> bool

Returns whether this cookie was marked HttpOnly or not.

Example

use cookie::Cookie;

let c = Cookie::parse("name=value; httponly").unwrap();
assert_eq!(c.http_only(), true);

pub fn secure(&self) -> bool

Returns whether this cookie was marked Secure or not.

Example

use cookie::Cookie;

let c = Cookie::parse("name=value; Secure").unwrap();
assert_eq!(c.secure(), 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 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.num_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.

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

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

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.tm_year), Some(117));

pub fn set_name<N: Into<Cow<'static, str>>>(&mut self, name: N)

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

pub fn set_value<V: Into<Cow<'static, str>>>(&mut self, value: V)

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

pub fn set_http_only(&mut self, value: bool)

Sets the value of http_only in self to value.

Example

use cookie::Cookie;

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

c.set_http_only(true);
assert_eq!(c.http_only(), true);

pub fn set_secure(&mut self, value: bool)

Sets the value of secure in self to value.

Example

use cookie::Cookie;

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

c.set_secure(true);
assert_eq!(c.secure(), true);

pub fn set_same_site(&mut self, value: SameSite)

Sets the value of same_site in self to value.

Example

use cookie::{Cookie, SameSite};

let mut c = Cookie::new("name", "value");
assert!(c.same_site().is_none());

c.set_same_site(SameSite::Strict);
assert_eq!(c.same_site(), Some(SameSite::Strict));

pub fn set_max_age(&mut self, value: Duration)

Sets the value of max_age in self to value.

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

pub fn set_path<P: Into<Cow<'static, str>>>(&mut self, path: P)

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

pub fn set_domain<D: Into<Cow<'static, str>>>(&mut self, domain: D)

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

pub fn set_expires(&mut self, time: Tm)

Sets the expires field of self to time.

Example

extern crate time;

use cookie::Cookie;

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

let mut now = time::now();
now.tm_year += 1;

c.set_expires(now);
assert!(c.expires().is_some())

pub fn make_permanent(&mut self)

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

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 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 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 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 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 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 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.

This method differs from 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 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

impl<'c> Debug for Cookie<'c>

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

Formats the value using the given formatter.

impl<'c> Clone for Cookie<'c>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'c> Display for Cookie<'c>

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

Formats the cookie self as a Set-Cookie header value.

Example

use cookie::Cookie;

let mut cookie = Cookie::build("foo", "bar")
    .path("/")
    .finish();

assert_eq!(&cookie.to_string(), "foo=bar; Path=/");

impl FromStr for Cookie<'static>

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Cookie<'static>, ParseError>

Parses a string s to return a value of this type.

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.