Struct saphir::CookiesMut

pub struct CookiesMut<'a> { /* fields omitted */ }

A Mutable Wrapper around the CookieJar Struct

Methods from Deref<Target = CookieJar>

pub fn get(&self, name: &str) -> Option<&Cookie<'static>>

Returns a reference to the Cookie inside this jar with the name name. If no such cookie exists, returns None.

Example

use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
assert!(jar.get("name").is_none());

jar.add(Cookie::new("name", "value"));
assert_eq!(jar.get("name").map(|c| c.value()), Some("value"));

pub fn add_original(&mut self, cookie: Cookie<'static>)

Adds an "original" cookie to this jar. If an original cookie with the same name already exists, it is replaced with cookie. Cookies added with add take precedence and are not replaced by this method.

Adding an original cookie does not affect the delta computation. This method is intended to be used to seed the cookie jar with cookies received from a client's HTTP message.

For accurate delta computations, this method should not be called after calling remove.

Example

use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("second", "two"));

assert_eq!(jar.get("name").map(|c| c.value()), Some("value"));
assert_eq!(jar.get("second").map(|c| c.value()), Some("two"));
assert_eq!(jar.iter().count(), 2);
assert_eq!(jar.delta().count(), 0);

pub fn add(&mut self, cookie: Cookie<'static>)

Adds cookie to this jar. If a cookie with the same name already exists, it is replaced with cookie.

Example

use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add(Cookie::new("name", "value"));
jar.add(Cookie::new("second", "two"));

assert_eq!(jar.get("name").map(|c| c.value()), Some("value"));
assert_eq!(jar.get("second").map(|c| c.value()), Some("two"));
assert_eq!(jar.iter().count(), 2);
assert_eq!(jar.delta().count(), 2);

pub fn remove(&mut self, cookie: Cookie<'static>)

Removes cookie from this jar. If an original cookie with the same name as cookie is present in the jar, a removal cookie will be present in the delta computation. To properly generate the removal cookie, cookie must contain the same path and domain as the cookie that was initially set.

A "removal" cookie is a cookie that has the same name as the original cookie but has an empty value, a max-age of 0, and an expiration date far in the past.

Example

Removing an original cookie results in a removal cookie:

extern crate time;

use cookie::{CookieJar, Cookie};
use time::Duration;

let mut jar = CookieJar::new();

// Assume this cookie originally had a path of "/" and domain of "a.b".
jar.add_original(Cookie::new("name", "value"));

// If the path and domain were set, they must be provided to `remove`.
jar.remove(Cookie::build("name", "").path("/").domain("a.b").finish());

// The delta will contain the removal cookie.
let delta: Vec<_> = jar.delta().collect();
assert_eq!(delta.len(), 1);
assert_eq!(delta[0].name(), "name");
assert_eq!(delta[0].max_age(), Some(Duration::seconds(0)));

Removing a new cookie does not result in a removal cookie:

use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add(Cookie::new("name", "value"));
assert_eq!(jar.delta().count(), 1);

jar.remove(Cookie::named("name"));
assert_eq!(jar.delta().count(), 0);

pub fn force_remove(&mut self, cookie: Cookie<'a>)

Removes cookie from this jar completely. This method differs from remove in that no delta cookie is created under any condition. Neither the delta nor iter methods will return a cookie that is removed using this method.

Example

Removing an original cookie; no removal cookie is generated:

extern crate time;

use cookie::{CookieJar, Cookie};
use time::Duration;

let mut jar = CookieJar::new();

// Add an original cookie and a new cookie.
jar.add_original(Cookie::new("name", "value"));
jar.add(Cookie::new("key", "value"));
assert_eq!(jar.delta().count(), 1);
assert_eq!(jar.iter().count(), 2);

// Now force remove the original cookie.
jar.force_remove(Cookie::new("name", "value"));
assert_eq!(jar.delta().count(), 1);
assert_eq!(jar.iter().count(), 1);

// Now force remove the new cookie.
jar.force_remove(Cookie::new("key", "value"));
assert_eq!(jar.delta().count(), 0);
assert_eq!(jar.iter().count(), 0);

pub fn clear(&mut self)

Deprecated since 0.7.0:

calling this method may not remove all cookies since the path and domain are not specified; use remove instead

Removes all cookies from this cookie jar.

pub fn delta(&self) -> Delta

Returns an iterator over cookies that represent the changes to this jar over time. These cookies can be rendered directly as Set-Cookie header values to affect the changes made to this jar on the client.

Example

use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();
jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("second", "two"));

// Add new cookies.
jar.add(Cookie::new("new", "third"));
jar.add(Cookie::new("another", "fourth"));
jar.add(Cookie::new("yac", "fifth"));

// Remove some cookies.
jar.remove(Cookie::named("name"));
jar.remove(Cookie::named("another"));

// Delta contains two new cookies ("new", "yac") and a removal ("name").
assert_eq!(jar.delta().count(), 3);

pub fn iter(&self) -> Iter

Returns an iterator over all of the cookies present in this jar.

Example

use cookie::{CookieJar, Cookie};

let mut jar = CookieJar::new();

jar.add_original(Cookie::new("name", "value"));
jar.add_original(Cookie::new("second", "two"));

jar.add(Cookie::new("new", "third"));
jar.add(Cookie::new("another", "fourth"));
jar.add(Cookie::new("yac", "fifth"));

jar.remove(Cookie::named("name"));
jar.remove(Cookie::named("another"));

// There are three cookies in the jar: "second", "new", and "yac".
for cookie in jar.iter() {
    match cookie.name() {
        "second" => assert_eq!(cookie.value(), "two"),
        "new" => assert_eq!(cookie.value(), "third"),
        "yac" => assert_eq!(cookie.value(), "fifth"),
        _ => unreachable!("there are only three cookies in the jar")
    }
}

Trait Implementations

impl<'a> Deref for CookiesMut<'a>

type Target = CookieJar

The resulting type after dereferencing.

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

Dereferences the value.

impl<'a> DerefMut for CookiesMut<'a>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.