Struct cookie::Cookie

source · [−]

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

Expand description

Representation of an HTTP 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

source

impl<'c> Cookie<'c>

source

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

Creates a new Cookie with the given name and value.

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

Creates a new Cookie with the given name and an empty value.

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

Creates a new CookieBuilder instance from the given key and value strings.

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.

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

Converts self into a Cookie with a static lifetime with as few allocations as possible.

pub fn name(&self) -> &str

Returns the name of self.

pub fn value(&self) -> &str

Returns the value of self.

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

Returns the name and value of self as a tuple of (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));

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

pub fn set_name<N: Into<Cow<'c, 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");

source

pub fn set_value<V: Into<Cow<'c, 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");

source

pub fn set_http_only<T: Into<Option<bool>>>(&mut self, value: T)

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

source

pub fn set_secure<T: Into<Option<bool>>>(&mut self, value: T)

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

source

pub fn set_same_site<T: Into<Option<SameSite>>>(&mut self, value: T)

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

source

pub fn set_max_age<D: Into<Option<Duration>>>(&mut self, value: D)

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

source

pub fn set_path<P: Into<Cow<'c, 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("/"));

source

pub fn unset_path(&mut self)

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

source

pub fn set_domain<D: Into<Cow<'c, 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"));

source

pub fn unset_domain(&mut self)

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

source

pub fn set_expires<T: Into<Expiration>>(&mut self, time: T)

Sets the expires field of self to time. If time is None, an expiration of Session is set.

Example

extern crate time;
use cookie::{Cookie, Expiration};
use time::{Duration, OffsetDateTime};

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_eq!(c.expires(), Some(Expiration::Session));

source

pub fn unset_expires(&mut self)

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

source

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

source

pub fn make_removal(&mut self)

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

extern crate time;

use cookie::Cookie;
use 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()));

source

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

source

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

source

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

source

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

source

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("/").finish();
assert_eq!(&c.stripped().to_string(), "key?=value");

Trait Implementations

source

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

source

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

Returns a copy of the value. Read more

1.0.0 · source

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

Performs copy-assignment from source. Read more

source

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

source

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

Formats the value using the given formatter. Read more

source

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

source

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

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

source

impl FromStr for Cookie<'static>

type Err = ParseError

The associated error which can be returned from parsing.

source

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

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

source

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

source

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

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

1.0.0 · source

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

This method tests for !=.

Auto Trait Implementations

impl<'c> RefUnwindSafe for Cookie<'c>

impl<'c> Send for Cookie<'c>

impl<'c> Sync for Cookie<'c>

impl<'c> Unpin for Cookie<'c>

impl<'c> UnwindSafe for Cookie<'c>

Blanket Implementations

source

impl<T> Any for T where
T: 'static + ?Sized,

source

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

source

impl<T> Borrow<T> for T where
T: ?Sized,

const: unstable · source

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

source

impl<T> BorrowMut<T> for T where
T: ?Sized,

const: unstable · source

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

source

impl<T> From<T> for T

const: unstable · source

fn from(t: T) -> T

Returns the argument unchanged.

source

impl<T, U> Into for T where
U: From<T>,

const: unstable · source

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source

impl<T> ToOwned for T where
T: Clone,

type Owned = T

The resulting type after obtaining ownership.

source

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more

source

fn clone_into(&self, target: &mut T)

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

source

impl<T> ToString for T where
T: Display + ?Sized,

source

default fn to_string(&self) -> String

Converts the given value to a String. Read more

source

impl<T, U> TryFrom for T where
U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

const: unstable · source

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Performs the conversion.

source

impl<T, U> TryInto for T where
U: TryFrom<T>,

type Error = >::Error

The type returned in the event of a conversion error.

const: unstable · source

fn try_into(self) -> Result<U, >::Error>

Performs the conversion.

Struct cookie::Cookie

Implementations

impl<'c> Cookie<'c>

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

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

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

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

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

pub fn name(&self) -> &str

pub fn value(&self) -> &str

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

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

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

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

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

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

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

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

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

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

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

pub fn set_http_only<T: Into<Option<bool>>>(&mut self, value: T)

pub fn set_secure<T: Into<Option<bool>>>(&mut self, value: T)

pub fn set_same_site<T: Into<Option<SameSite>>>(&mut self, value: T)

pub fn set_max_age<D: Into<Option<Duration>>>(&mut self, value: D)

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

pub fn unset_path(&mut self)

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

pub fn unset_domain(&mut self)

pub fn set_expires<T: Into<Expiration>>(&mut self, time: T)

pub fn unset_expires(&mut self)

pub fn make_permanent(&mut self)

pub fn make_removal(&mut self)

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

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

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

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

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

Trait Implementations

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

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

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

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

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

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

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

impl FromStr for Cookie<'static>

type Err = ParseError

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

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

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

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

Auto Trait Implementations

impl<'c> RefUnwindSafe for Cookie<'c>

impl<'c> Send for Cookie<'c>

impl<'c> Sync for Cookie<'c>

impl<'c> Unpin for Cookie<'c>

impl<'c> UnwindSafe for Cookie<'c>

Blanket Implementations

impl<T> Any for T where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for T where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for T where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for T

fn from(t: T) -> T

impl<T, U> Into<U> for T where U: From<T>,

fn into(self) -> U

impl<T> ToOwned for T where T: Clone,

type Owned = T

fn to_owned(&self) -> T

fn clone_into(&self, target: &mut T)

impl<T> ToString for T where T: Display + ?Sized,

default fn to_string(&self) -> String

impl<T, U> TryFrom<U> for T where U: Into<T>,

type Error = Infallible

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for T where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

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

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

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

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

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

impl<T> Any for T where
T: 'static + ?Sized,

impl<T> Borrow<T> for T where
T: ?Sized,

impl<T> BorrowMut<T> for T where
T: ?Sized,

impl<T, U> Into<U> for T where
U: From<T>,

impl<T> ToOwned for T where
T: Clone,

impl<T> ToString for T where
T: Display + ?Sized,

impl<T, U> TryFrom<U> for T where
U: Into<T>,

impl<T, U> TryInto<U> for T where
U: TryFrom<T>,