Struct rocket::request::Request

source ·
pub struct Request<'r> { /* private fields */ }
Expand description

The type of an incoming web request.

This should be used sparingly in Rocket applications. In particular, it should likely only be used when writing FromRequest implementations. It contains all of the information for a given web request except for the body data. This includes the HTTP method, URI, cookies, headers, and more.

Implementations§

source§

impl<'r> Request<'r>

source

pub fn method(&self) -> Method

Retrieve the method from self.

§Example
use rocket::http::Method;

assert_eq!(get("/").method(), Method::Get);
assert_eq!(post("/").method(), Method::Post);
source

pub fn set_method(&mut self, method: Method)

Set the method of self to method.

§Example
use rocket::http::Method;

assert_eq!(request.method(), Method::Get);

request.set_method(Method::Post);
assert_eq!(request.method(), Method::Post);
source

pub fn uri(&self) -> &Origin<'r>

Borrow the Origin URI from self.

§Example
assert_eq!(get("/hello/rocketeer").uri().path(), "/hello/rocketeer");
assert_eq!(get("/hello").uri().query(), None);
source

pub fn set_uri(&mut self, uri: Origin<'r>)

Set the URI in self to uri.

§Example
use rocket::http::uri::Origin;

let uri = Origin::parse("/hello/Sergio?type=greeting").unwrap();
request.set_uri(uri);
assert_eq!(request.uri().path(), "/hello/Sergio");
assert_eq!(request.uri().query().unwrap(), "type=greeting");

let new_uri = request.uri().map_path(|p| format!("/foo{}", p)).unwrap();
request.set_uri(new_uri);
assert_eq!(request.uri().path(), "/foo/hello/Sergio");
assert_eq!(request.uri().query().unwrap(), "type=greeting");
source

pub fn host(&self) -> Option<&Host<'r>>

Returns the Host identified in the request, if any.

If the request is made via HTTP/1.1 (or earlier), this method returns the value in the HOST header without the deprecated user_info component. Otherwise, this method returns the contents of the :authority pseudo-header request field.

Note that this method only reflects the HOST header in the initial request and not any changes made thereafter. To change the value returned by this method, use Request::set_host().

§⚠️ DANGER ⚠️

Using the user-controlled host to construct URLs is a security hazard! Never do so without first validating the host against a whitelist. For this reason, Rocket disallows constructing host-prefixed URIs with uri!. Always use uri! to construct URIs.

§Example

Retrieve the raw host, unusable to construct safe URIs:

use rocket::http::uri::Host;

assert_eq!(request.host(), None);

request.set_host(Host::from(uri!("rocket.rs")));
let host = request.host().unwrap();
assert_eq!(host.domain(), "rocket.rs");
assert_eq!(host.port(), None);

request.set_host(Host::from(uri!("rocket.rs:2392")));
let host = request.host().unwrap();
assert_eq!(host.domain(), "rocket.rs");
assert_eq!(host.port(), Some(2392));

Retrieve the raw host, check it against a whitelist, and construct a URI:

use rocket::http::uri::Host;

// A sensitive URI we want to prefix with safe hosts.
#[get("/token?<secret>")]
fn token(secret: Token) { /* .. */ }

// Whitelist of known hosts. In a real setting, you might retrieve this
// list from config at ignite-time using tools like `AdHoc::config()`.
const WHITELIST: [Host<'static>; 3] = [
    Host::new(uri!("rocket.rs")),
    Host::new(uri!("rocket.rs:443")),
    Host::new(uri!("guide.rocket.rs:443")),
];

// A request with a host of "rocket.rs". Note the case-insensitivity.
request.set_host(Host::from(uri!("ROCKET.rs")));
let prefix = request.host().and_then(|h| h.to_absolute("https", &WHITELIST));

// `rocket.rs` is in the whitelist, so we'll get back a `Some`.
assert!(prefix.is_some());
if let Some(prefix) = prefix {
    // We can use this prefix to safely construct URIs.
    let uri = uri!(prefix, token("some-secret-token"));
    assert_eq!(uri, "https://ROCKET.rs/token?secret=some-secret-token");
}

// A request with a host of "attacker-controlled.com".
request.set_host(Host::from(uri!("attacker-controlled.com")));
let prefix = request.host().and_then(|h| h.to_absolute("https", &WHITELIST));

// `attacker-controlled.come` is _not_ on the whitelist.
assert!(prefix.is_none());
assert!(request.host().is_some());
source

pub fn set_host(&mut self, host: Host<'r>)

Sets the host of self to host.

§Example

Set the host to rocket.rs:443.

use rocket::http::uri::Host;

assert_eq!(request.host(), None);

request.set_host(Host::from(uri!("rocket.rs:443")));
let host = request.host().unwrap();
assert_eq!(host.domain(), "rocket.rs");
assert_eq!(host.port(), Some(443));
source

pub fn remote(&self) -> Option<&Endpoint>

Returns the raw address of the remote connection that initiated this request if the address is known. If the address is not known, None is returned.

Because it is common for proxies to forward connections for clients, the remote address may contain information about the proxy instead of the client. For this reason, proxies typically set a “X-Real-IP” header ip_header with the client’s true IP. To extract this IP from the request, use the real_ip() or client_ip() methods.

§Example
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use rocket::listener::Endpoint;

assert_eq!(request.remote(), None);

let localhost = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 8111);
request.set_remote(Endpoint::Tcp(localhost));
assert_eq!(request.remote().unwrap().tcp().unwrap(), localhost);
source

pub fn set_remote(&mut self, endpoint: Endpoint)

Sets the remote address of self to address.

§Example

Set the remote address to be 127.0.0.1:8111:

use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use rocket::listener::Endpoint;

assert_eq!(request.remote(), None);

let localhost = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 8111);
request.set_remote(Endpoint::Tcp(localhost));
assert_eq!(request.remote().unwrap().tcp().unwrap(), localhost);
source

pub fn real_ip(&self) -> Option<IpAddr>

Returns the IP address of the configured ip_header of the request if such a header is configured, exists and contains a valid IP address.

§Example
use std::net::Ipv4Addr;
use rocket::http::Header;

assert_eq!(req.real_ip(), None);

// `ip_header` defaults to `X-Real-IP`.
let req = req.header(Header::new("X-Real-IP", "127.0.0.1"));
assert_eq!(req.real_ip(), Some(Ipv4Addr::LOCALHOST.into()));
source

pub fn proxy_proto(&self) -> Option<ProxyProto<'_>>

Returns the ProxyProto associated with the current request.

The value is determined by inspecting the header named proxy_proto_header, if configured, and parsing it case-insensitivity. If the parameter isn’t configured or the request doesn’t contain a header named as indicated, this method returns None.

§Example
use rocket::http::{Header, ProxyProto};

// By default, no `proxy_proto_header` is configured.
let req = req.header(Header::new("x-forwarded-proto", "https"));
assert_eq!(req.proxy_proto(), None);

// We can configure one by setting the `proxy_proto_header` parameter.
// Here we set it to `x-forwarded-proto`, considered de-facto standard.
let figment = figment.merge(("proxy_proto_header", "x-forwarded-proto"));
let req = req.header(Header::new("x-forwarded-proto", "https"));
assert_eq!(req.proxy_proto(), Some(ProxyProto::Https));

let req = req.header(Header::new("x-forwarded-proto", "HTTP"));
assert_eq!(req.proxy_proto(), Some(ProxyProto::Http));

let req = req.header(Header::new("x-forwarded-proto", "xproto"));
assert_eq!(req.proxy_proto(), Some(ProxyProto::Unknown("xproto".into())));
source

pub fn context_is_likely_secure(&self) -> bool

Returns whether we are likely in a secure context.

A request is in a “secure context” if it was initially sent over a secure (TLS, via HTTPS) connection. If TLS is configured and enabled, then the request is guaranteed to be in a secure context. Otherwise, if Request::proxy_proto() evaluates to Https, then we are likely to be in a secure context. We say likely because it is entirely possible for the header to indicate that the connection is being proxied via HTTPS while reality differs. As such, this value should not be trusted when 100% confidence is a necessity.

§Example
use rocket::http::{Header, ProxyProto};

// If TLS and proxy_proto are disabled, we are not in a secure context.
assert_eq!(req.context_is_likely_secure(), false);

// Configuring proxy_proto and receiving a header value of `https` is
// interpreted as likely being in a secure context.
// Here we set it to `x-forwarded-proto`, considered de-facto standard.
let figment = figment.merge(("proxy_proto_header", "x-forwarded-proto"));
let req = req.header(Header::new("x-forwarded-proto", "https"));
assert_eq!(req.context_is_likely_secure(), true);
source

pub fn client_ip(&self) -> Option<IpAddr>

Attempts to return the client’s IP address by first inspecting the ip_header and then using the remote connection’s IP address. Note that the built-in IpAddr request guard can be used to retrieve the same information in a handler:

use std::net::IpAddr;

#[get("/")]
fn get_ip(client_ip: IpAddr) { /* ... */ }

#[get("/")]
fn try_get_ip(client_ip: Option<IpAddr>) { /* ... */ }

If the ip_header exists and contains a valid IP address, that address is returned. Otherwise, if the address of the remote connection is known, that address is returned. Otherwise, None is returned.

§Example

// starting without an "X-Real-IP" header or remote address
assert!(request.client_ip().is_none());

// add a remote address; this is done by Rocket automatically
let localhost_9190 = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 9190);
request.set_remote(Endpoint::Tcp(localhost_9190));
assert_eq!(request.client_ip().unwrap(), Ipv4Addr::LOCALHOST);

// now with an X-Real-IP header, the default value for `ip_header`.
request.add_header(Header::new("X-Real-IP", "8.8.8.8"));
assert_eq!(request.client_ip().unwrap(), Ipv4Addr::new(8, 8, 8, 8));
source

pub fn cookies(&self) -> &CookieJar<'r>

Returns a wrapped borrow to the cookies in self.

CookieJar implements internal mutability, so this method allows you to get and add/remove cookies in self.

§Example

Add a new cookie to a request’s cookies:

use rocket::http::Cookie;

req.cookies().add(("key", "val"));
req.cookies().add(("ans", format!("life: {}", 38 + 4)));

assert_eq!(req.cookies().get_pending("key").unwrap().value(), "val");
assert_eq!(req.cookies().get_pending("ans").unwrap().value(), "life: 42");
source

pub fn headers(&self) -> &HeaderMap<'r>

Returns a HeaderMap of all of the headers in self.

§Example
use rocket::http::{Accept, ContentType};

assert!(get("/").headers().is_empty());

let req = get("/").header(Accept::HTML).header(ContentType::HTML);
assert_eq!(req.headers().len(), 2);
source

pub fn add_header<'h: 'r, H: Into<Header<'h>>>(&mut self, header: H)

Add header to self’s headers. The type of header can be any type that implements the Into<Header> trait. This includes common types such as ContentType and Accept.

§Example
use rocket::http::ContentType;

assert!(request.headers().is_empty());

request.add_header(ContentType::HTML);
assert!(request.headers().contains("Content-Type"));
assert_eq!(request.headers().len(), 1);
source

pub fn replace_header<'h: 'r, H: Into<Header<'h>>>(&mut self, header: H)

Replaces the value of the header with name header.name with header.value. If no such header exists, header is added as a header to self.

§Example
use rocket::http::ContentType;

assert!(request.headers().is_empty());

request.add_header(ContentType::Any);
assert_eq!(request.headers().get_one("Content-Type"), Some("*/*"));
assert_eq!(request.content_type(), Some(&ContentType::Any));

request.replace_header(ContentType::PNG);
assert_eq!(request.headers().get_one("Content-Type"), Some("image/png"));
assert_eq!(request.content_type(), Some(&ContentType::PNG));
source

pub fn content_type(&self) -> Option<&ContentType>

Returns the Content-Type header of self. If the header is not present, returns None.

§Example
use rocket::http::ContentType;

assert_eq!(get("/").content_type(), None);

let req = get("/").header(ContentType::JSON);
assert_eq!(req.content_type(), Some(&ContentType::JSON));
source

pub fn accept(&self) -> Option<&Accept>

Returns the Accept header of self. If the header is not present, returns None.

§Example
use rocket::http::Accept;

assert_eq!(get("/").accept(), None);
assert_eq!(get("/").header(Accept::JSON).accept(), Some(&Accept::JSON));
source

pub fn format(&self) -> Option<&MediaType>

Returns the media type “format” of the request.

The returned MediaType is derived from either the Content-Type or the Accept header of the request, based on whether the request’s method allows a body (see Method::allows_request_body()). The table below summarized this:

Method Allows BodyReturned Format
AlwaysOption<ContentType>
Maybe or NeverSome(Preferred Accept or Any)

In short, if the request’s method indicates support for a payload, the request’s Content-Type header value, if any, is returned. Otherwise the preferred Accept header value is returned, or if none is present, Accept::Any.

The media type returned from this method is used to match against the format route attribute.

§Example
use rocket::http::{Accept, ContentType, MediaType};

// Non-payload-bearing: format is accept header.
let req = get("/").header(Accept::HTML);
assert_eq!(req.format(), Some(&MediaType::HTML));

let req = get("/").header(ContentType::JSON).header(Accept::HTML);
assert_eq!(req.format(), Some(&MediaType::HTML));

// Payload: format is content-type header.
let req = post("/").header(ContentType::HTML);
assert_eq!(req.format(), Some(&MediaType::HTML));

let req = post("/").header(ContentType::JSON).header(Accept::HTML);
assert_eq!(req.format(), Some(&MediaType::JSON));

// Non-payload-bearing method and no accept header: `Any`.
assert_eq!(get("/").format(), Some(&MediaType::Any));
source

pub fn rocket(&self) -> &'r Rocket<Orbit>

Returns the Rocket instance that is handling this request.

§Example
// Retrieve the application config via `Rocket::config()`.
let config = request.rocket().config();

// Retrieve managed state via `Rocket::state()`.
let state = request.rocket().state::<Pool>();

// Get a list of all of the registered routes and catchers.
let routes = request.rocket().routes();
let catchers = request.rocket().catchers();
source

pub fn limits(&self) -> &'r Limits

Returns the configured application data limits.

This is convenience function equivalent to:

&request.rocket().config().limits
§Example
use rocket::data::ToByteUnit;

// This is the default `form` limit.
assert_eq!(request.limits().get("form"), Some(32.kibibytes()));

// Retrieve the limit for files with extension `.pdf`; etails to 1MiB.
assert_eq!(request.limits().get("file/pdf"), Some(1.mebibytes()));
source

pub fn route(&self) -> Option<&'r Route>

Get the presently matched route, if any.

This method returns Some any time a handler or its guards are being invoked. This method returns None before routing has commenced; this includes during request fairing callbacks.

§Example
let route = request.route();
source

pub fn guard<'z, 'a, T>(&'a self) -> BoxFuture<'z, Outcome<T, T::Error>>
where T: FromRequest<'a> + 'z, 'a: 'z, 'r: 'z,

Invokes the request guard implementation for T, returning its outcome.

§Example

Assuming a User request guard exists, invoke it:

let outcome = request.guard::<User>().await;
source

pub fn local_cache<T, F>(&self, f: F) -> &T
where F: FnOnce() -> T, T: Send + Sync + 'static,

Retrieves the cached value for type T from the request-local cached state of self. If no such value has previously been cached for this request, f is called to produce the value which is subsequently returned.

Different values of the same type cannot be cached without using a proxy, wrapper type. To avoid the need to write these manually, or for libraries wishing to store values of public types, use the local_cache! or local_cache_once! macros to generate a locally anonymous wrapper type, store, and retrieve the wrapped value from request-local cache.

§Example
// The first store into local cache for a given type wins.
let value = request.local_cache(|| "hello");
assert_eq!(*request.local_cache(|| "hello"), "hello");

// The following return the cached, previously stored value for the type.
assert_eq!(*request.local_cache(|| "goodbye"), "hello");
source

pub async fn local_cache_async<'a, T, F>(&'a self, fut: F) -> &'a T
where F: Future<Output = T>, T: Send + Sync + 'static,

Retrieves the cached value for type T from the request-local cached state of self. If no such value has previously been cached for this request, fut is awaited to produce the value which is subsequently returned.

§Example
async fn current_user<'r>(request: &Request<'r>) -> User {
    // validate request for a given user, load from database, etc
}

let current_user = request.local_cache_async(async {
    current_user(&request).await
}).await;
source

pub fn param<'a, T>(&'a self, n: usize) -> Option<Result<T, T::Error>>
where T: FromParam<'a>,

Retrieves and parses into T the 0-indexed nth non-empty segment from the routed request, that is, the nth segment after the mount point. If the request has not been routed, then this is simply the nth non-empty request URI segment.

Returns None if n is greater than the number of non-empty segments. Returns Some(Err(T::Error)) if the parameter type T failed to be parsed from the nth dynamic parameter.

This method exists only to be used by manual routing. To retrieve parameters from a request, use Rocket’s code generation facilities.

§Example
use rocket::error::Empty;

assert_eq!(get("/a/b/c").param(0), Some(Ok("a")));
assert_eq!(get("/a/b/c").param(1), Some(Ok("b")));
assert_eq!(get("/a/b/c").param(2), Some(Ok("c")));
assert_eq!(get("/a/b/c").param::<&str>(3), None);

assert_eq!(get("/1/b/3").param(0), Some(Ok(1)));
assert!(get("/1/b/3").param::<usize>(1).unwrap().is_err());
assert_eq!(get("/1/b/3").param(2), Some(Ok(3)));

assert_eq!(get("/").param::<&str>(0), Some(Err(Empty)));
source

pub fn segments<'a, T>(&'a self, n: RangeFrom<usize>) -> Result<T, T::Error>
where T: FromSegments<'a>,

Retrieves and parses into T all of the path segments in the request URI beginning and including the 0-indexed nth non-empty segment after the mount point.,that is, the nth segment after the mount point. If the request has not been routed, then this is simply the nth non-empty request URI segment.

T must implement FromSegments, which is used to parse the segments. If there are no non-empty segments, the Segments iterator will be empty.

This method exists only to be used by manual routing. To retrieve segments from a request, use Rocket’s code generation facilities.

§Example
use std::path::PathBuf;

assert_eq!(get("/").segments(0..), Ok(PathBuf::new()));
assert_eq!(get("/").segments(2..), Ok(PathBuf::new()));

// Empty segments are skipped.
assert_eq!(get("///").segments(2..), Ok(PathBuf::new()));
assert_eq!(get("/a/b/c").segments(0..), Ok(PathBuf::from("a/b/c")));
assert_eq!(get("/a/b/c").segments(1..), Ok(PathBuf::from("b/c")));
assert_eq!(get("/a/b/c").segments(2..), Ok(PathBuf::from("c")));
assert_eq!(get("/a/b/c").segments(3..), Ok(PathBuf::new()));
assert_eq!(get("/a/b/c").segments(4..), Ok(PathBuf::new()));
source

pub fn query_value<'a, T>(&'a self, name: &str) -> Option<Result<'a, T>>
where T: FromForm<'a>,

Retrieves and parses into T the query value with field name name. T must implement FromForm, which is used to parse the query’s value. Key matching is performed case-sensitively.

§Warning

This method exists only to be used by manual routing and should never be used in a regular Rocket application. It is much more expensive to use this method than to retrieve query parameters via Rocket’s codegen. To retrieve query values from a request, always prefer to use Rocket’s code generation facilities.

§Error

If a query segment with name name isn’t present, returns None. If parsing the value fails, returns Some(Err(_)).

§Example
use rocket::form::FromForm;

#[derive(Debug, PartialEq, FromForm)]
struct Dog<'r> {
    name: &'r str,
    age: usize
}

let req = get("/?a=apple&z=zebra&a=aardvark");
assert_eq!(req.query_value::<&str>("a").unwrap(), Ok("apple"));
assert_eq!(req.query_value::<&str>("z").unwrap(), Ok("zebra"));
assert_eq!(req.query_value::<&str>("b"), None);

let a_seq = req.query_value::<Vec<&str>>("a");
assert_eq!(a_seq.unwrap().unwrap(), ["apple", "aardvark"]);

let req = get("/?dog.name=Max+Fido&dog.age=3");
let dog = req.query_value::<Dog>("dog");
assert_eq!(dog.unwrap().unwrap(), Dog { name: "Max Fido", age: 3 });

Trait Implementations§

source§

impl<'r> Clone for Request<'r>

source§

fn clone(&self) -> Request<'r>

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 Debug for Request<'_>

source§

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

Formats the value using the given formatter. Read more
source§

impl Trace for Request<'_>

Auto Trait Implementations§

§

impl<'r> !Freeze for Request<'r>

§

impl<'r> !RefUnwindSafe for Request<'r>

§

impl<'r> Send for Request<'r>

§

impl<'r> Sync for Request<'r>

§

impl<'r> Unpin for Request<'r>

§

impl<'r> !UnwindSafe for Request<'r>

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<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

source§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self, E>

source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

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

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> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

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

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

§Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

§Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

§Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

§Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

§Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

§Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

§Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

§Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

§Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

§Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

§Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

§Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

§Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

§Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

§Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

§Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

§Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

§Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

§Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

§Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

§Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

§Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

§Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

§Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

§Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

§Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

§Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

§Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

§Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

§Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

§Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

§Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

§Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

§Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

§Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

§Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

§Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

§Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

§Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

§Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

§Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

§Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

§Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

§Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

§Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

§Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

§Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

§Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

§Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

§Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear(). The clear() method will be removed in a future release.

Returns self with the quirk() set to Quirk::Clear.

§Example
println!("{}", value.clear());
source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Resetting.

§Example
println!("{}", value.resetting());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

§Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

§Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
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)

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

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

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

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

§

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

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> Upcast<T> for U
where T: UpcastFrom<U>,

source§

fn upcast(self) -> T

source§

impl<T, B> UpcastFrom<Counter<T, B>> for T

source§

fn upcast_from(value: Counter<T, B>) -> T

source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more