Struct cookie::builder::CookieBuilder

pub struct CookieBuilder<'c> {
    cookie: Cookie<'c>,
}

Structure that follows the builder pattern for building Cookie structs.

To construct a cookie:

1. Call Cookie::build() to start building.
2. Use any of the builder methods to set fields in the cookie.

The resulting CookieBuilder can be passed directly into methods expecting a T: Into<Cookie>:

use cookie::{Cookie, CookieJar};

let mut jar = CookieJar::new();
jar.add(Cookie::build(("key", "value")).secure(true).path("/"));
jar.remove(Cookie::build("key").path("/"));

You can also call CookieBuilder::build() directly to get a Cookie:

use cookie::Cookie;
use cookie::time::Duration;

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

Fields

cookie: Cookie<'c>

The cookie being built.

Implementations

impl<'c> CookieBuilder<'c>

pub fn new<N, V>(name: N, value: V) -> Self

where N: Into<Cow<'c, str>>, V: Into<Cow<'c, str>>,

Creates a new CookieBuilder instance from the given name and value.

This method is typically called indirectly via Cookie::build().

Example

use cookie::Cookie;

// These two snippets are equivalent:

let c = Cookie::build(("foo", "bar"));
assert_eq!(c.inner().name_value(), ("foo", "bar"));

let c = Cookie::new("foo", "bar");
assert_eq!(c.name_value(), ("foo", "bar"));

pub fn expires<E: Into<Expiration>>(self, when: E) -> Self

Sets the expires field in the cookie being built.

See Expiration for conversions.

Example

use cookie::{Cookie, Expiration};
use cookie::time::OffsetDateTime;

let c = Cookie::build(("foo", "bar")).expires(OffsetDateTime::now_utc());
assert!(c.inner().expires().is_some());

let c = Cookie::build(("foo", "bar")).expires(None);
assert_eq!(c.inner().expires(), Some(Expiration::Session));

pub fn max_age(self, value: Duration) -> Self

Sets the max_age field in the cookie being built.

Example

use cookie::Cookie;
use cookie::time::Duration;

let c = Cookie::build(("foo", "bar")).max_age(Duration::minutes(30));
assert_eq!(c.inner().max_age(), Some(Duration::seconds(30 * 60)));

pub fn domain<D: Into<Cow<'c, str>>>(self, value: D) -> Self

Sets the domain field in the cookie being built.

Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).domain("www.rust-lang.org");
assert_eq!(c.inner().domain(), Some("www.rust-lang.org"));

pub fn path<P: Into<Cow<'c, str>>>(self, path: P) -> Self

Sets the path field in the cookie being built.

Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).path("/");
assert_eq!(c.inner().path(), Some("/"));

pub fn secure(self, value: bool) -> Self

Sets the secure field in the cookie being built.

Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).secure(true);
assert_eq!(c.inner().secure(), Some(true));

pub fn http_only(self, value: bool) -> Self

Sets the http_only field in the cookie being built.

Example

use cookie::Cookie;

let c = Cookie::build(("foo", "bar")).http_only(true);
assert_eq!(c.inner().http_only(), Some(true));

pub fn same_site(self, value: SameSite) -> Self

Sets the same_site field in the cookie being built.

Example

use cookie::{Cookie, SameSite};

let c = Cookie::build(("foo", "bar")).same_site(SameSite::Strict);
assert_eq!(c.inner().same_site(), Some(SameSite::Strict));

pub fn partitioned(self, value: bool) -> Self

Sets the partitioned field in the cookie being built.

Note: Partitioned cookies require the Secure attribute to be set. As such, Partitioned cookies are always rendered with the Secure attribute, irrespective of the Secure attribute’s setting.

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::build(("foo", "bar")).partitioned(true);
assert_eq!(c.inner().partitioned(), Some(true));
assert!(c.to_string().contains("Secure"));

pub fn permanent(self) -> Self

Makes the cookie being built ‘permanent’ by extending its expiration and max age 20 years into the future. See also Cookie::make_permanent().

Example

use cookie::Cookie;
use cookie::time::Duration;

let c = Cookie::build(("foo", "bar")).permanent();
assert_eq!(c.inner().max_age(), Some(Duration::days(365 * 20)));

pub fn removal(self) -> Self

Makes the cookie being built ‘removal’ by clearing its value, setting a max-age of 0, and setting an expiration date far in the past. See also Cookie::make_removal().

Example

use cookie::Cookie;
use cookie::time::Duration;

let mut builder = Cookie::build("foo").removal();
assert_eq!(builder.inner().max_age(), Some(Duration::ZERO));

let mut builder = Cookie::build(("name", "value")).removal();
assert_eq!(builder.inner().value(), "");
assert_eq!(builder.inner().max_age(), Some(Duration::ZERO));

pub fn inner(&self) -> &Cookie<'c>

Returns a borrow to the cookie currently being built.

Example

use cookie::Cookie;

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

assert_eq!(builder.inner().name_value(), ("name", "value"));
assert_eq!(builder.inner().domain(), Some("www.rust-lang.org"));
assert_eq!(builder.inner().path(), Some("/"));
assert_eq!(builder.inner().http_only(), Some(true));
assert_eq!(builder.inner().secure(), None);

pub fn inner_mut(&mut self) -> &mut Cookie<'c>

Returns a mutable borrow to the cookie currently being built.

Example

use cookie::Cookie;

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

assert_eq!(builder.inner().http_only(), Some(true));

builder.inner_mut().set_http_only(false);
assert_eq!(builder.inner().http_only(), Some(false));

pub fn build(self) -> Cookie<'c>

Finishes building and returns the built Cookie.

This method usually does not need to be called directly. This is because CookieBuilder implements Into<Cookie>, so a value of CookieBuilder can be passed directly into any method that expects a C: Into<Cookie>.

Example

use cookie::{Cookie, CookieJar};

// We don't usually need to use `build()`. Inspect with `inner()`, and
// pass the builder directly into methods expecting `T: Into<Cookie>`.
let c = Cookie::build(("foo", "bar"))
    .domain("crates.io")
    .path("/");

// Use `inner()` and inspect the cookie.
assert_eq!(c.inner().name_value(), ("foo", "bar"));
assert_eq!(c.inner().domain(), Some("crates.io"));
assert_eq!(c.inner().path(), Some("/"));

// Add the cookie to a jar. Note the automatic conversion.
CookieJar::new().add(c);

// We could use `build()` to get a `Cookie` when needed.
let c = Cookie::build(("foo", "bar"))
    .domain("crates.io")
    .path("/")
    .build();

// Inspect the built cookie.
assert_eq!(c.name_value(), ("foo", "bar"));
assert_eq!(c.domain(), Some("crates.io"));
assert_eq!(c.path(), Some("/"));

// Add the cookie to a jar.
CookieJar::new().add(c);

pub fn finish(self) -> Cookie<'c>

👎Deprecated since 0.18.0: CookieBuilder can be passed in to methods expecting a Cookie; for other cases, use CookieBuilder::build()

Deprecated. Convert self into a Cookie.

Instead of using this method, pass a CookieBuilder directly into methods expecting a T: Into<Cookie>. For other cases, use CookieBuilder::build().

Trait Implementations

impl<'a> AsMut<Cookie<'a>> for CookieBuilder<'a>

fn as_mut(&mut self) -> &mut Cookie<'a>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<'a> AsRef<Cookie<'a>> for CookieBuilder<'a>

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

Converts this type into a shared reference of the (usually inferred) input type.

impl<'a> Borrow<Cookie<'a>> for CookieBuilder<'a>

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

Immutably borrows from an owned value.

impl<'a> BorrowMut<Cookie<'a>> for CookieBuilder<'a>

fn borrow_mut(&mut self) -> &mut Cookie<'a>

Mutably borrows from an owned value.

impl<'c> Clone for CookieBuilder<'c>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'c> Debug for CookieBuilder<'c>

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

Formats the value using the given formatter.

impl Display for CookieBuilder<'_>

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

Formats the value using the given formatter.

impl<'c> From<Cookie<'c>> for CookieBuilder<'c>

fn from(cookie: Cookie<'c>) -> Self

Converts to this type from the input type.

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

fn from(builder: CookieBuilder<'a>) -> Self

Converts to this type from the input type.

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

fn eq(&self, other: &Cookie<'b>) -> 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, 'b> PartialEq<CookieBuilder<'b>> for Cookie<'a>

fn eq(&self, other: &CookieBuilder<'b>) -> 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<'c> PartialEq for CookieBuilder<'c>

fn eq(&self, other: &CookieBuilder<'c>) -> 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<'c> StructuralPartialEq for CookieBuilder<'c>