yume/juniper
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
juniper/url/index.html
Juniper Documentation Builder cb596a6b6b Update documentation for Juniper
2016-10-09 12:40:00 +00:00

320 lines
No EOL
20 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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 ‘S’ to search, ‘?’ for more options…"
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'>&#x2212;</span>]
</a>
</span><a id='src-0' class='srclink' href='../src/url/lib.rs.html#9-1456' title='goto source code'>[src]</a></span></h1>
<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 = &quot;https://github.com/servo/rust-url&quot;
</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’s <em>features</em> mechanism</a>:</p>
<pre><code class="language-Cargo">[dependencies.url]
git = &quot;https://github.com/servo/rust-url&quot;
features = [&quot;query_encoding&quot;]
</code></pre>
<p>… or by passing <code>--cfg &#39;feature=&quot;query_encoding&quot;&#39;</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'>&quot;http://[:::1]&quot;</span>) <span class='op'>==</span> <span class='prelude-val'>Err</span>(<span class='ident'>ParseError</span>::<span class='ident'>InvalidIpv6Address</span>))</pre>
<p>Let’s parse a valid URL and look at its components.</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'>&quot;https://github.com/rust-lang/rust/issues?labels=E-easy&amp;state=open&quot;</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'>&quot;https&quot;</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'>&quot;&quot;</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'>&quot;github.com&quot;</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'>&quot;github.com&quot;</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'>&quot;/rust-lang/rust/issues&quot;</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'>&lt;</span><span class='ident'>Vec</span><span class='op'>&lt;</span>_<span class='op'>&gt;&gt;</span>()) <span class='op'>==</span>
<span class='prelude-val'>Some</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>&quot;rust-lang&quot;</span>, <span class='string'>&quot;rust&quot;</span>, <span class='string'>&quot;issues&quot;</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'>&quot;labels=E-easy&amp;state=open&quot;</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’t have a username, password, host, or port,
and their &quot;path&quot; 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'>&quot;data:text/plain,Hello?World#&quot;</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'>&quot;data&quot;</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'>&quot;text/plain,Hello&quot;</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'>&quot;World&quot;</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'>&quot;&quot;</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">&lt;link rel=&quot;stylesheet&quot; href=&quot;../main.css&quot;&gt;
</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'>&quot;../main.css&quot;</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'>&quot;http://servo.github.io/rust-url/url/index.html&quot;</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'>&quot;../main.css&quot;</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'>&quot;http://servo.github.io/rust-url/main.css&quot;</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’t allow us to implement
<code>ToSocketAddrs for (Host&lt;S&gt;, 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>&larrb;</dt>
<dd>Move up in search results</dd>
<dt>&rarrb;</dt>
<dd>Move down in search results</dd>
<dt>&#9166;</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>
Reference in a new issue View git blame Copy permalink