2016-09-11 13:41:24 -05:00
<!DOCTYPE html>
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< meta name = "generator" content = "rustdoc" >
< meta name = "description" content = "API documentation for the Rust `url` crate." >
< meta name = "keywords" content = "rust, rustlang, rust-lang, url" >
< title > url - Rust< / title >
< link rel = "stylesheet" type = "text/css" href = "../rustdoc.css" >
< link rel = "stylesheet" type = "text/css" href = "../main.css" >
< / head >
< body class = "rustdoc" >
<!-- [if lte IE 8]>
< div class = "warning" >
This old browser is unsupported and will most likely display funky
things.
< / div >
<![endif]-->
< nav class = "sidebar" >
< p class = 'location' > < / p > < script > window . sidebarCurrent = { name : 'url' , ty : 'mod' , relpath : '../' } ; < / script >
< / nav >
< nav class = "sub" >
< form class = "search-form js-only" >
< div class = "search-container" >
< input class = "search-input" name = "search"
autocomplete="off"
placeholder="Click or press ‘ ’ ‘ ’
type="search">
< / div >
< / form >
< / nav >
< section id = 'main' class = "content mod" >
< h1 class = 'fqn' > < span class = 'in-band' > Crate < a class = 'mod' href = '' > url< / a > < / span > < span class = 'out-of-band' > < span id = 'render-detail' >
< a id = "toggle-all-docs" href = "javascript:void(0)" title = "collapse all docs" >
[< span class = 'inner' > − < / span > ]
< / a >
2016-10-09 07:40:00 -05:00
< / span > < a id = 'src-0' class = 'srclink' href = '../src/url/lib.rs.html#9-1456' title = 'goto source code' > [src]< / a > < / span > < / h1 >
2016-09-11 13:41:24 -05:00
< div class = 'docblock' > < p > rust-url is an implementation of the < a href = "http://url.spec.whatwg.org/" > URL Standard< / a >
for the < a href = "http://rust-lang.org/" > Rust< / a > programming language.< / p >
< p > It builds with < a href = "http://crates.io/" > Cargo< / a > .
To use it in your project, add this to your < code > Cargo.toml< / code > file:< / p >
< pre > < code class = "language-Cargo" > [dependencies.url]
git = " https://github.com/servo/rust-url"
< / code > < / pre >
< p > Supporting encodings other than UTF-8 in query strings is an optional feature
that requires < a href = "https://github.com/lifthrasiir/rust-encoding" > rust-encoding< / a >
and is off by default.
You can enable it with
< a href = "http://doc.crates.io/manifest.html#the-%5Bfeatures%5D-section" > Cargo’ < em > features< / em > mechanism< / a > :< / p >
< pre > < code class = "language-Cargo" > [dependencies.url]
git = " https://github.com/servo/rust-url"
features = [" query_encoding" ]
< / code > < / pre >
< p > … or by passing < code > --cfg ' feature=" query_encoding" ' < / code > to rustc.< / p >
< h1 id = 'url-parsing-and-data-structures' class = 'section-header' > < a href = '#url-parsing-and-data-structures' > URL parsing and data structures< / a > < / h1 >
< p > First, URL parsing may fail for various reasons and therefore returns a < code > Result< / code > .< / p >
< pre class = 'rust rust-example-rendered' >
< span class = 'kw' > use< / span > < span class = 'ident' > url< / span > ::{< span class = 'ident' > Url< / span > , < span class = 'ident' > ParseError< / span > };
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > Url< / span > ::< span class = 'ident' > parse< / span > (< span class = 'string' > " http://[:::1]" < / span > ) < span class = 'op' > ==< / span > < span class = 'prelude-val' > Err< / span > (< span class = 'ident' > ParseError< / span > ::< span class = 'ident' > InvalidIpv6Address< / span > ))< / pre >
< p > Let’ < / p >
< pre class = 'rust rust-example-rendered' >
< span class = 'kw' > use< / span > < span class = 'ident' > url< / span > ::{< span class = 'ident' > Url< / span > , < span class = 'ident' > Host< / span > };
< span class = 'kw' > let< / span > < span class = 'ident' > issue_list_url< / span > < span class = 'op' > =< / span > < span class = 'ident' > Url< / span > ::< span class = 'ident' > parse< / span > (
< span class = 'string' > " https://github.com/rust-lang/rust/issues?labels=E-easy& state=open" < / span >
).< span class = 'ident' > unwrap< / span > ();
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > scheme< / span > () < span class = 'op' > ==< / span > < span class = 'string' > " https" < / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > username< / span > () < span class = 'op' > ==< / span > < span class = 'string' > " " < / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > password< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > None< / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > host_str< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > Some< / span > (< span class = 'string' > " github.com" < / span > ));
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > host< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > Some< / span > (< span class = 'ident' > Host< / span > ::< span class = 'ident' > Domain< / span > (< span class = 'string' > " github.com" < / span > )));
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > port< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > None< / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > path< / span > () < span class = 'op' > ==< / span > < span class = 'string' > " /rust-lang/rust/issues" < / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > path_segments< / span > ().< span class = 'ident' > map< / span > (< span class = 'op' > |< / span > < span class = 'ident' > c< / span > < span class = 'op' > |< / span > < span class = 'ident' > c< / span > .< span class = 'ident' > collect< / span > ::< span class = 'op' > < < / span > < span class = 'ident' > Vec< / span > < span class = 'op' > < < / span > _< span class = 'op' > > > < / span > ()) < span class = 'op' > ==< / span >
< span class = 'prelude-val' > Some< / span > (< span class = 'macro' > vec< / span > < span class = 'macro' > !< / span > [< span class = 'string' > " rust-lang" < / span > , < span class = 'string' > " rust" < / span > , < span class = 'string' > " issues" < / span > ]));
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > query< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > Some< / span > (< span class = 'string' > " labels=E-easy& state=open" < / span > ));
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > fragment< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > None< / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'op' > !< / span > < span class = 'ident' > issue_list_url< / span > .< span class = 'ident' > cannot_be_a_base< / span > ());< / pre >
< p > Some URLs are said to be < em > cannot-be-a-base< / em > :
they don’
and their " path" is an arbitrary string rather than slash-separated segments:< / p >
< pre class = 'rust rust-example-rendered' >
< span class = 'kw' > use< / span > < span class = 'ident' > url< / span > ::< span class = 'ident' > Url< / span > ;
< span class = 'kw' > let< / span > < span class = 'ident' > data_url< / span > < span class = 'op' > =< / span > < span class = 'ident' > Url< / span > ::< span class = 'ident' > parse< / span > (< span class = 'string' > " data:text/plain,Hello?World#" < / span > ).< span class = 'ident' > unwrap< / span > ();
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > data_url< / span > .< span class = 'ident' > cannot_be_a_base< / span > ());
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > data_url< / span > .< span class = 'ident' > scheme< / span > () < span class = 'op' > ==< / span > < span class = 'string' > " data" < / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > data_url< / span > .< span class = 'ident' > path< / span > () < span class = 'op' > ==< / span > < span class = 'string' > " text/plain,Hello" < / span > );
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > data_url< / span > .< span class = 'ident' > path_segments< / span > ().< span class = 'ident' > is_none< / span > ());
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > data_url< / span > .< span class = 'ident' > query< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > Some< / span > (< span class = 'string' > " World" < / span > ));
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > data_url< / span > .< span class = 'ident' > fragment< / span > () < span class = 'op' > ==< / span > < span class = 'prelude-val' > Some< / span > (< span class = 'string' > " " < / span > ));< / pre >
< h1 id = 'base-url' class = 'section-header' > < a href = '#base-url' > Base URL< / a > < / h1 >
< p > Many contexts allow URL < em > references< / em > that can be relative to a < em > base URL< / em > :< / p >
< pre > < code class = "language-html" > < link rel=" stylesheet" href=" ../main.css" >
< / code > < / pre >
< p > Since parsed URL are absolute, giving a base is required for parsing relative URLs:< / p >
< pre class = 'rust rust-example-rendered' >
< span class = 'kw' > use< / span > < span class = 'ident' > url< / span > ::{< span class = 'ident' > Url< / span > , < span class = 'ident' > ParseError< / span > };
< span class = 'macro' > assert< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > Url< / span > ::< span class = 'ident' > parse< / span > (< span class = 'string' > " ../main.css" < / span > ) < span class = 'op' > ==< / span > < span class = 'prelude-val' > Err< / span > (< span class = 'ident' > ParseError< / span > ::< span class = 'ident' > RelativeUrlWithoutBase< / span > ))< / pre >
< p > Use the < code > join< / code > method on an < code > Url< / code > to use it as a base URL:< / p >
< pre class = 'rust rust-example-rendered' >
< span class = 'kw' > use< / span > < span class = 'ident' > url< / span > ::< span class = 'ident' > Url< / span > ;
< span class = 'kw' > let< / span > < span class = 'ident' > this_document< / span > < span class = 'op' > =< / span > < span class = 'ident' > Url< / span > ::< span class = 'ident' > parse< / span > (< span class = 'string' > " http://servo.github.io/rust-url/url/index.html" < / span > ).< span class = 'ident' > unwrap< / span > ();
< span class = 'kw' > let< / span > < span class = 'ident' > css_url< / span > < span class = 'op' > =< / span > < span class = 'ident' > this_document< / span > .< span class = 'ident' > join< / span > (< span class = 'string' > " ../main.css" < / span > ).< span class = 'ident' > unwrap< / span > ();
< span class = 'macro' > assert_eq< / span > < span class = 'macro' > !< / span > (< span class = 'ident' > css_url< / span > .< span class = 'ident' > as_str< / span > (), < span class = 'string' > " http://servo.github.io/rust-url/main.css" < / span > )< / pre >
< / div > < h2 id = 'reexports' class = 'section-header' > < a href = "#reexports" > Reexports< / a > < / h2 >
< table > < tr > < td > < code > pub extern crate < a class = 'mod' href = '../idna/index.html' title = 'idna' > idna< / a > ;< / code > < / td > < / tr > < / table > < h2 id = 'modules' class = 'section-header' > < a href = "#modules" > Modules< / a > < / h2 >
< table >
< tr class = ' module-item' >
< td > < a class = 'mod' href = 'form_urlencoded/index.html'
title='url::form_urlencoded'>form_urlencoded< / a > < / td >
< td class = 'docblock short' >
< p > Parser and serializer for the < a href = "http://url.spec.whatwg.org/#application/x-www-form-urlencoded" > < code > application/x-www-form-urlencoded< / code > syntax< / a > ,
as used by HTML forms.< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'mod' href = 'percent_encoding/index.html'
title='url::percent_encoding'>percent_encoding< / a > < / td >
< td class = 'docblock short' >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'mod' href = 'quirks/index.html'
title='url::quirks'>quirks< / a > < / td >
< td class = 'docblock short' >
< p > Getters and setters for URL components implemented per < a href = "https://url.spec.whatwg.org/#api" > https://url.spec.whatwg.org/#api< / a > < / p >
< / td >
< / tr > < / table > < h2 id = 'macros' class = 'section-header' > < a href = "#macros" > Macros< / a > < / h2 >
< table >
< tr class = ' module-item' >
< td > < a class = 'macro' href = 'macro.define_encode_set!.html'
title='url::define_encode_set!'>define_encode_set!< / a > < / td >
< td class = 'docblock short' >
< p > Define a new struct
that implements the < a href = "percent_encoding/trait.EncodeSet.html" > < code > EncodeSet< / code > < / a > trait,
for use in < a href = "percent_encoding/fn.percent_encode.html" > < code > percent_decode()< / code > < / a >
and related functions.< / p >
< / td >
< / tr > < / table > < h2 id = 'structs' class = 'section-header' > < a href = "#structs" > Structs< / a > < / h2 >
< table >
< tr class = ' module-item' >
< td > < a class = 'struct' href = 'struct.HostAndPort.html'
title='url::HostAndPort'>HostAndPort< / a > < / td >
< td class = 'docblock short' >
< p > This mostly exists because coherence rules don’
< code > ToSocketAddrs for (Host< S> , u16)< / code > .< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'struct' href = 'struct.OpaqueOrigin.html'
title='url::OpaqueOrigin'>OpaqueOrigin< / a > < / td >
< td class = 'docblock short' >
< p > Opaque identifier for URLs that have file or other schemes< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'struct' href = 'struct.ParseOptions.html'
title='url::ParseOptions'>ParseOptions< / a > < / td >
< td class = 'docblock short' >
< p > Full configuration for the URL parser.< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'struct' href = 'struct.PathSegmentsMut.html'
title='url::PathSegmentsMut'>PathSegmentsMut< / a > < / td >
< td class = 'docblock short' >
< p > Exposes methods to manipulate the path of an URL that is not cannot-be-base.< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'struct' href = 'struct.SocketAddrs.html'
title='url::SocketAddrs'>SocketAddrs< / a > < / td >
< td class = 'docblock short' >
< p > Socket addresses for an URL.< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'struct' href = 'struct.Url.html'
title='url::Url'>Url< / a > < / td >
< td class = 'docblock short' >
< p > A parsed URL record.< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'struct' href = 'struct.UrlQuery.html'
title='url::UrlQuery'>UrlQuery< / a > < / td >
< td class = 'docblock short' >
< p > Implementation detail of < code > Url::query_pairs_mut< / code > . Typically not used directly.< / p >
< / td >
< / tr > < / table > < h2 id = 'enums' class = 'section-header' > < a href = "#enums" > Enums< / a > < / h2 >
< table >
< tr class = ' module-item' >
< td > < a class = 'enum' href = 'enum.Host.html'
title='url::Host'>Host< / a > < / td >
< td class = 'docblock short' >
< p > The host name of an URL.< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'enum' href = 'enum.Origin.html'
title='url::Origin'>Origin< / a > < / td >
< td class = 'docblock short' >
< p > The origin of an URL< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'enum' href = 'enum.ParseError.html'
title='url::ParseError'>ParseError< / a > < / td >
< td class = 'docblock short' >
< p > Errors that can occur during parsing.< / p >
< / td >
< / tr >
< tr class = ' module-item' >
< td > < a class = 'enum' href = 'enum.Position.html'
title='url::Position'>Position< / a > < / td >
< td class = 'docblock short' >
< p > Indicates a position within a URL based on its components.< / p >
< / td >
< / tr > < / table > < / section >
< section id = 'search' class = "content hidden" > < / section >
< section class = "footer" > < / section >
< aside id = "help" class = "hidden" >
< div >
< h1 class = "hidden" > Help< / h1 >
< div class = "shortcuts" >
< h2 > Keyboard Shortcuts< / h2 >
< dl >
< dt > ?< / dt >
< dd > Show this help dialog< / dd >
< dt > S< / dt >
< dd > Focus the search field< / dd >
< dt > ⇤ < / dt >
< dd > Move up in search results< / dd >
< dt > ⇥ < / dt >
< dd > Move down in search results< / dd >
< dt > ⏎ < / dt >
< dd > Go to active search result< / dd >
< dt > +< / dt >
< dd > Collapse/expand all sections< / dd >
< / dl >
< / div >
< div class = "infos" >
< h2 > Search Tricks< / h2 >
< p >
Prefix searches with a type followed by a colon (e.g.
< code > fn:< / code > ) to restrict the search to a given type.
< / p >
< p >
Accepted types are: < code > fn< / code > , < code > mod< / code > ,
< code > struct< / code > , < code > enum< / code > ,
< code > trait< / code > , < code > type< / code > , < code > macro< / code > ,
and < code > const< / code > .
< / p >
< p >
Search functions by type signature (e.g.
< code > vec -> usize< / code > or < code > * -> vec< / code > )
< / p >
< / div >
< / div >
< / aside >
< script >
window.rootPath = "../";
window.currentCrate = "url";
window.playgroundUrl = "";
< / script >
< script src = "../jquery.js" > < / script >
< script src = "../main.js" > < / script >
< script defer src = "../search-index.js" > < / script >
< / body >
< / html >
