<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Strings - The Rust Programming Language</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<base href="">
<link rel="stylesheet" href="book.css">
<link href='https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<style>
.page-wrapper.has-warning > .nav-chapters {
/* add height for warning content & margin */
top: 120px;
}
p.warning {
background-color: rgb(242, 222, 222);
border-bottom-color: rgb(238, 211, 215);
border-bottom-left-radius: 4px;
border-bottom-right-radius: 4px;
border-bottom-style: solid;
border-bottom-width: 0.666667px;
border-image-outset: 0 0 0 0;
border-image-repeat: stretch stretch;
border-image-slice: 100% 100% 100% 100%;
border-image-source: none;
border-image-width: 1 1 1 1;
border-left-color: rgb(238, 211, 215);
border-left-style: solid;
border-left-width: 0.666667px;
border-right-color: rgb(238, 211, 215);
border-right-style: solid;
border-right-width: 0.666667px;
border-top-color: rgb(238, 211, 215);
border-top-left-radius: 4px;
border-top-right-radius: 4px;
border-top-style: solid;
border-top-width: 0.666667px;
color: rgb(185, 74, 72);
margin-bottom: 0px;
margin-left: 0px;
margin-right: 0px;
margin-top: 30px;
padding-bottom: 8px;
padding-left: 14px;
padding-right: 35px;
padding-top: 8px;
}
p.warning strong {
color: rgb(185, 74, 72)
}
p.warning a {
color: rgb(0, 136, 204)
}
</style>
<!-- MathJax -->
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<!-- Fetch JQuery from CDN but have a local fallback -->
<script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>
<script>
if (typeof jQuery == 'undefined') {
document.write(unescape("%3Cscript src='jquery.js'%3E%3C/script%3E"));
}
</script>
</head>
<body class="light">
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme = localStorage.getItem('theme');
if (theme == null) { theme = 'light'; }
$('body').removeClass().addClass(theme);
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var sidebar = localStorage.getItem('sidebar');
if (sidebar === "hidden") { $("html").addClass("sidebar-hidden") }
else if (sidebar === "visible") { $("html").addClass("sidebar-visible") }
</script>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="ch01-00-introduction.html"><strong>1.</strong> Introduction</a></li><li><ul class="section"><li><a href="ch01-01-installation.html"><strong>1.1.</strong> Installation</a></li><li><a href="ch01-02-hello-world.html"><strong>1.2.</strong> Hello, World!</a></li></ul></li><li><a href="ch02-00-guessing-game-tutorial.html"><strong>2.</strong> Guessing Game Tutorial</a></li><li><a href="ch03-00-common-programming-concepts.html"><strong>3.</strong> Common Programming Concepts</a></li><li><ul class="section"><li><a href="ch03-01-variables-and-mutability.html"><strong>3.1.</strong> Variables and Mutability</a></li><li><a href="ch03-02-data-types.html"><strong>3.2.</strong> Data Types</a></li><li><a href="ch03-03-how-functions-work.html"><strong>3.3.</strong> How Functions Work</a></li><li><a href="ch03-04-comments.html"><strong>3.4.</strong> Comments</a></li><li><a href="ch03-05-control-flow.html"><strong>3.5.</strong> Control Flow</a></li></ul></li><li><a href="ch04-00-understanding-ownership.html"><strong>4.</strong> Understanding Ownership</a></li><li><ul class="section"><li><a href="ch04-01-what-is-ownership.html"><strong>4.1.</strong> What is Ownership?</a></li><li><a href="ch04-02-references-and-borrowing.html"><strong>4.2.</strong> References & Borrowing</a></li><li><a href="ch04-03-slices.html"><strong>4.3.</strong> Slices</a></li></ul></li><li><a href="ch05-00-structs.html"><strong>5.</strong> Using Structs to Structure Related Data</a></li><li><ul class="section"><li><a href="ch05-01-defining-structs.html"><strong>5.1.</strong> Defining and Instantiating Structs</a></li><li><a href="ch05-02-example-structs.html"><strong>5.2.</strong> An Example Program Using Structs</a></li><li><a href="ch05-03-method-syntax.html"><strong>5.3.</strong> Method Syntax</a></li></ul></li><li><a href="ch06-00-enums.html"><strong>6.</strong> Enums and Pattern Matching</a></li><li><ul class="section"><li><a href="ch06-01-defining-an-enum.html"><strong>6.1.</strong> Defining an Enum</a></li><li><a href="ch06-02-match.html"><strong>6.2.</strong> The <code>match</code> Control Flow Operator</a></li><li><a href="ch06-03-if-let.html"><strong>6.3.</strong> Concise Control Flow with <code>if let</code></a></li></ul></li><li><a href="ch07-00-modules.html"><strong>7.</strong> Modules</a></li><li><ul class="section"><li><a href="ch07-01-mod-and-the-filesystem.html"><strong>7.1.</strong> <code>mod</code> and the Filesystem</a></li><li><a href="ch07-02-controlling-visibility-with-pub.html"><strong>7.2.</strong> Controlling Visibility with <code>pub</code></a></li><li><a href="ch07-03-importing-names-with-use.html"><strong>7.3.</strong> Importing Names with <code>use</code></a></li></ul></li><li><a href="ch08-00-common-collections.html"><strong>8.</strong> Common Collections</a></li><li><ul class="section"><li><a href="ch08-01-vectors.html"><strong>8.1.</strong> Vectors</a></li><li><a href="ch08-02-strings.html" class="active"><strong>8.2.</strong> Strings</a></li><li><a href="ch08-03-hash-maps.html"><strong>8.3.</strong> Hash Maps</a></li></ul></li><li><a href="ch09-00-error-handling.html"><strong>9.</strong> Error Handling</a></li><li><ul class="section"><li><a href="ch09-01-unrecoverable-errors-with-panic.html"><strong>9.1.</strong> Unrecoverable Errors with <code>panic!</code></a></li><li><a href="ch09-02-recoverable-errors-with-result.html"><strong>9.2.</strong> Recoverable Errors with <code>Result</code></a></li><li><a href="ch09-03-to-panic-or-not-to-panic.html"><strong>9.3.</strong> To <code>panic!</code> or Not To <code>panic!</code></a></li></ul></li><li><a href="ch10-00-generics.html"><strong>10.</strong> Generic Types, Traits, and Lifetimes</a></li><li><ul class="section"><li><a href="ch10-01-syntax.html"><strong>10.1.</strong> Generic Data Types</a></li><li><a href="ch10-02-traits.html"><strong>10.2.</strong> Traits: Defining Shared Behavior</a></li><li><a href="ch10-03-lifetime-syntax.html"><strong>10.3.</strong> Validating References with Lifetimes</a></li></ul></li><li><a href="ch11-00-testing.html"><strong>11.</strong> Testing</a></li><li><ul class="section"><li><a href="ch11-01-writing-tests.html"><strong>11.1.</strong> Writing tests</a></li><li><a href="ch11-02-running-tests.html"><strong>11.2.</strong> Running tests</a></li><li><a href="ch11-03-test-organization.html"><strong>11.3.</strong> Test Organization</a></li></ul></li><li><a href="ch12-00-an-io-project.html"><strong>12.</strong> An I/O Project</a></li><li><ul class="section"><li><a href="ch12-01-accepting-command-line-arguments.html"><strong>12.1.</strong> Accepting Command Line Arguments</a></li><li><a href="ch12-02-reading-a-file.html"><strong>12.2.</strong> Reading a File</a></li><li><a href="ch12-03-improving-error-handling-and-modularity.html"><strong>12.3.</strong> Improving Error Handling and Modularity</a></li><li><a href="ch12-04-testing-the-librarys-functionality.html"><strong>12.4.</strong> Testing the Library's Functionality</a></li><li><a href="ch12-05-working-with-environment-variables.html"><strong>12.5.</strong> Working with Environment Variables</a></li><li><a href="ch12-06-writing-to-stderr-instead-of-stdout.html"><strong>12.6.</strong> Writing to <code>stderr</code> instead of <code>stdout</code></a></li></ul></li><li><a href="ch13-00-functional-features.html"><strong>13.</strong> Functional Language Features in Rust</a></li><li><ul class="section"><li><a href="ch13-01-closures.html"><strong>13.1.</strong> Closures</a></li><li><a href="ch13-02-iterators.html"><strong>13.2.</strong> Iterators</a></li><li><a href="ch13-03-improving-our-io-project.html"><strong>13.3.</strong> Improving our I/O Project</a></li><li><a href="ch13-04-performance.html"><strong>13.4.</strong> Performance</a></li></ul></li><li><a href="ch14-00-more-about-cargo.html"><strong>14.</strong> More about Cargo and Crates.io</a></li><li><ul class="section"><li><a href="ch14-01-release-profiles.html"><strong>14.1.</strong> Release Profiles</a></li><li><a href="ch14-02-publishing-to-crates-io.html"><strong>14.2.</strong> Publishing a Crate to Crates.io</a></li><li><a href="ch14-03-cargo-workspaces.html"><strong>14.3.</strong> Cargo Workspaces</a></li><li><a href="ch14-04-installing-binaries.html"><strong>14.4.</strong> Installing Binaries from Crates.io with <code>cargo install</code></a></li><li><a href="ch14-05-extending-cargo.html"><strong>14.5.</strong> Extending Cargo with Custom Commands</a></li></ul></li><li><a href="ch15-00-smart-pointers.html"><strong>15.</strong> Smart Pointers</a></li><li><ul class="section"><li><a href="ch15-01-box.html"><strong>15.1.</strong> <code>Box<T></code> Points to Data on the Heap and Has a Known Size</a></li><li><a href="ch15-02-deref.html"><strong>15.2.</strong> The <code>Deref</code> Trait Allows Access to the Data Through a Reference</a></li><li><a href="ch15-03-drop.html"><strong>15.3.</strong> The <code>Drop</code> Trait Runs Code on Cleanup</a></li><li><a href="ch15-04-rc.html"><strong>15.4.</strong> <code>Rc<T></code>, the Reference Counted Smart Pointer</a></li><li><a href="ch15-05-interior-mutability.html"><strong>15.5.</strong> <code>RefCell<T></code> and the Interior Mutability Pattern</a></li><li><a href="ch15-06-reference-cycles.html"><strong>15.6.</strong> Creating Reference Cycles and Leaking Memory is Safe</a></li></ul></li><li><a href="ch16-00-concurrency.html"><strong>16.</strong> Fearless Concurrency</a></li><li><ul class="section"><li><a href="ch16-01-threads.html"><strong>16.1.</strong> Threads</a></li><li><a href="ch16-02-message-passing.html"><strong>16.2.</strong> Message Passing</a></li><li><a href="ch16-03-shared-state.html"><strong>16.3.</strong> Shared State</a></li><li><a href="ch16-04-extensible-concurrency-sync-and-send.html"><strong>16.4.</strong> Extensible Concurrency: <code>Sync</code> and <code>Send</code></a></li></ul></li><li><a href="ch17-00-oop.html"><strong>17.</strong> Is Rust an Object-Oriented Programming Language?</a></li><li><ul class="section"><li><a href="ch17-01-what-is-oo.html"><strong>17.1.</strong> What Does Object-Oriented Mean?</a></li><li><a href="ch17-02-trait-objects.html"><strong>17.2.</strong> Trait Objects for Using Values of Different Types</a></li><li><a href="ch17-03-oo-design-patterns.html"><strong>17.3.</strong> Object-Oriented Design Pattern Implementations</a></li></ul></li><li><a href="ch18-00-patterns.html"><strong>18.</strong> Patterns Match the Structure of Values</a></li><li><ul class="section"><li><a href="ch18-01-all-the-places-for-patterns.html"><strong>18.1.</strong> All the Places Patterns May be Used</a></li><li><a href="ch18-02-refutability.html"><strong>18.2.</strong> Refutability: Whether a Pattern Might Fail to Match</a></li><li><a href="ch18-03-pattern-syntax.html"><strong>18.3.</strong> All the Pattern Syntax</a></li></ul></li><li><a href="ch19-00-advanced-features.html"><strong>19.</strong> Advanced Features</a></li><li><ul class="section"><li><a href="ch19-01-unsafe-rust.html"><strong>19.1.</strong> Unsafe Rust</a></li><li><a href="ch19-02-advanced-lifetimes.html"><strong>19.2.</strong> Advanced Lifetimes</a></li><li><a href="ch19-03-advanced-traits.html"><strong>19.3.</strong> Advanced Traits</a></li><li><a href="ch19-04-advanced-types.html"><strong>19.4.</strong> Advanced Types</a></li><li><a href="ch19-05-advanced-functions-and-closures.html"><strong>19.5.</strong> Advanced Functions & Closures</a></li></ul></li><li><a href="ch20-00-final-project-a-web-server.html"><strong>20.</strong> Final Project: Building a Multithreaded Web Server</a></li><li><ul class="section"><li><a href="ch20-01-single-threaded.html"><strong>20.1.</strong> A Single Threaded Web Server</a></li><li><a href="ch20-02-slow-requests.html"><strong>20.2.</strong> How Slow Requests Affect Throughput</a></li><li><a href="ch20-03-designing-the-interface.html"><strong>20.3.</strong> Designing the Thread Pool Interface</a></li><li><a href="ch20-04-storing-threads.html"><strong>20.4.</strong> Creating the Thread Pool and Storing Threads</a></li><li><a href="ch20-05-sending-requests-via-channels.html"><strong>20.5.</strong> Sending Requests to Threads Via Channels</a></li><li><a href="ch20-06-graceful-shutdown-and-cleanup.html"><strong>20.6.</strong> Graceful Shutdown and Cleanup</a></li></ul></li><li><a href="appendix-00.html"><strong>21.</strong> Appendix</a></li><li><ul class="section"><li><a href="appendix-01-keywords.html"><strong>21.1.</strong> A - Keywords</a></li><li><a href="appendix-02-operators.html"><strong>21.2.</strong> B - Operators</a></li><li><strong>21.3.</strong> C - Derivable Traits</li><li><strong>21.4.</strong> D - Nightly Rust</li><li><strong>21.5.</strong> E - Macros</li><li><strong>21.6.</strong> F - Translations</li><li><a href="appendix-07-newest-features.html"><strong>21.7.</strong> G - Newest Features</a></li></ul></li></ul>
</div>
<div id="page-wrapper" class="page-wrapper has-warning">
<div class="page">
<header><p class="warning">You are reading a <strong>draft</strong> of the next edition of TRPL. For more, go <a href="../index.html">here</a>.</p></header>
<div id="menu-bar" class="menu-bar">
<div class="left-buttons">
<i id="sidebar-toggle" class="fa fa-bars"></i>
<i id="theme-toggle" class="fa fa-paint-brush"></i>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<i id="print-button" class="fa fa-print" title="Print this book"></i>
</div>
</div>
<div id="content" class="content">
<a class="header" href="ch08-02-strings.html#strings" id="strings"><h2>Strings</h2></a>
<p>We’ve already talked about strings a bunch in Chapter 4, but let’s take a more
in-depth look at them now. Strings are an area that new Rustaceans commonly get
stuck on. This is due to a combination of three things: Rust’s propensity for
making sure to expose possible errors, strings being a more complicated data
structure than many programmers give them credit for, and UTF-8. These things
combine in a way that can seem difficult when coming from other languages.</p>
<p>The reason strings are in the collections chapter is that strings are
implemented as a collection of bytes plus some methods to provide useful
functionality when those bytes are interpreted as text. In this section, we’ll
talk about the operations on <code>String</code> that every collection type has, like
creating, updating, and reading. We’ll also discuss the ways in which <code>String</code>
is different than the other collections, namely how indexing into a <code>String</code> is
complicated by the differences in which people and computers interpret <code>String</code>
data.</p>
<a class="header" href="ch08-02-strings.html#what-is-a-string" id="what-is-a-string"><h3>What is a String?</h3></a>
<p>Before we can dig into those aspects, we need to talk about what exactly we
mean by the term <em>string</em>. Rust actually only has one string type in the core
language itself: <code>str</code>, the string slice, which is usually seen in its borrowed
form, <code>&str</code>. We talked about <em>string slices</em> in Chapter 4: these are a
reference to some UTF-8 encoded string data stored elsewhere. String literals,
for example, are stored in the binary output of the program, and are therefore
string slices.</p>
<p>The type called <code>String</code> is provided in Rust’s standard library rather than
coded into the core language, and is a growable, mutable, owned, UTF-8 encoded
string type. When Rustaceans talk about “strings” in Rust, they usually mean
both the <code>String</code> and the string slice <code>&str</code> types, not just one of those.
This section is largely about <code>String</code>, but both these types are used heavily
in Rust’s standard library. Both <code>String</code> and string slices are UTF-8 encoded.</p>
<p>Rust’s standard library also includes a number of other string types, such as
<code>OsString</code>, <code>OsStr</code>, <code>CString</code>, and <code>CStr</code>. Library crates may provide even
more options for storing string data. Similar to the <code>*String</code>/<code>*Str</code> naming,
they often provide an owned and borrowed variant, just like <code>String</code>/<code>&str</code>.
These string types may store different encodings or be represented in memory in
a different way, for example. We won’t be talking about these other string
types in this chapter; see their API documentation for more about how to use
them and when each is appropriate.</p>
<a class="header" href="ch08-02-strings.html#creating-a-new-string" id="creating-a-new-string"><h3>Creating a New String</h3></a>
<p>Many of the same operations available with <code>Vec</code> are available with <code>String</code> as
well, starting with the <code>new</code> function to create a string, like so:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let mut s = String::new();
#}</code></pre></pre>
<p>This creates a new empty string called <code>s</code> that we can then load data into.</p>
<p>Often, we’ll have some initial data that we’d like to start the string off
with. For that, we use the <code>to_string</code> method, which is available on any type
that implements the <code>Display</code> trait, which string literals do:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let data = "initial contents";
let s = data.to_string();
// the method also works on a literal directly:
let s = "initial contents".to_string();
#}</code></pre></pre>
<p>This creates a string containing <code>initial contents</code>.</p>
<p>We can also use the function <code>String::from</code> to create a <code>String</code> from a string
literal. This is equivalent to using <code>to_string</code>:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let s = String::from("initial contents");
#}</code></pre></pre>
<p>Because strings are used for so many things, there are many different generic
APIs that can be used for strings, so there are a lot of options. Some of them
can feel redundant, but they all have their place! In this case, <code>String::from</code>
and <code>.to_string</code> end up doing the exact same thing, so which you choose is a
matter of style.</p>
<p>Remember that strings are UTF-8 encoded, so we can include any properly encoded
data in them:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let hello = "السلام عليكم";
let hello = "Dobrý den";
let hello = "Hello";
let hello = "שָׁלוֹם";
let hello = "नमस्ते";
let hello = "こんにちは";
let hello = "안녕하세요";
let hello = "你好";
let hello = "Olá";
let hello = "Здравствуйте";
let hello = "Hola";
#}</code></pre></pre>
<a class="header" href="ch08-02-strings.html#updating-a-string" id="updating-a-string"><h3>Updating a String</h3></a>
<p>A <code>String</code> can grow in size and its contents can change just like the contents
of a <code>Vec</code>, by pushing more data into it. In addition, <code>String</code> has
concatenation operations implemented with the <code>+</code> operator for convenience.</p>
<a class="header" href="ch08-02-strings.html#appending-to-a-string-with-push" id="appending-to-a-string-with-push"><h4>Appending to a String with Push</h4></a>
<p>We can grow a <code>String</code> by using the <code>push_str</code> method to append a string slice:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let mut s = String::from("foo");
s.push_str("bar");
#}</code></pre></pre>
<p><code>s</code> will contain “foobar” after these two lines. The <code>push_str</code> method takes a
string slice because we don’t necessarily want to take ownership of the
parameter. For example, it would be unfortunate if we weren’t able to use <code>s2</code>
after appending its contents to <code>s1</code>:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let mut s1 = String::from("foo");
let s2 = String::from("bar");
s1.push_str(&s2);
#}</code></pre></pre>
<p>The <code>push</code> method is defined to have a single character as a parameter and add
it to the <code>String</code>:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let mut s = String::from("lo");
s.push('l');
#}</code></pre></pre>
<p>After this, <code>s</code> will contain “lol”.</p>
<a class="header" href="ch08-02-strings.html#concatenation-with-the--operator-or-the-format-macro" id="concatenation-with-the--operator-or-the-format-macro"><h4>Concatenation with the + Operator or the <code>format!</code> Macro</h4></a>
<p>Often, we’ll want to combine two existing strings together. One way is to use
the <code>+</code> operator like this:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let s1 = String::from("Hello, ");
let s2 = String::from("world!");
let s3 = s1 + &s2; // Note that s1 has been moved here and can no longer be used
#}</code></pre></pre>
<p>After this code the String <code>s3</code> will contain <code>Hello, world!</code>. The reason that
<code>s1</code> is no longer valid after the addition and the reason that we used a
reference to <code>s2</code> has to do with the signature of the method that gets called
when we use the <code>+</code> operator. The <code>+</code> operator uses the <code>add</code> method, whose
signature looks something like this:</p>
<pre><code class="language-rust ignore">fn add(self, s: &str) -> String {
</code></pre>
<p>This isn’t the exact signature that’s in the standard library; there <code>add</code> is
defined using generics. Here, we’re looking at the signature of <code>add</code> with
concrete types substituted for the generic ones, which is what happens when we
call this method with <code>String</code> values. We'll be discussing generics in
Chapter 10. This signature gives us the clues we need to understand the tricky
bits of the <code>+</code> operator.</p>
<p>First of all, <code>s2</code> has an <code>&</code>, meaning that we are adding a <em>reference</em> of the
second string to the first string. This is because of the <code>s</code> parameter in the
<code>add</code> function: we can only add a <code>&str</code> to a <code>String</code>, we can't add two
<code>String</code> values together. But wait - the type of <code>&s2</code> is <code>&String</code>, not
<code>&str</code>, as specified in the second parameter to <code>add</code>. Why does our example
compile? We are able to use <code>&s2</code> in the call to <code>add</code> because a <code>&String</code>
argument can be <em>coerced</em> into a <code>&str</code> - when the <code>add</code> function is called,
Rust uses something called a <em>deref coercion</em>, which you could think of here as
turning <code>&s2</code> into <code>&s2[..]</code> for use in the <code>add</code> function. We'll discuss deref
coercion in more depth in Chapter 15. Because <code>add</code> does not take ownership of
the parameter, <code>s2</code> will still be a valid <code>String</code> after this operation.</p>
<p>Second, we can see in the signature that <code>add</code> takes ownership of <code>self</code>,
because <code>self</code> does <em>not</em> have an <code>&</code>. This means <code>s1</code> in the above example
will be moved into the <code>add</code> call and no longer be valid after that. So while
<code>let s3 = s1 + &s2;</code> looks like it will copy both strings and create a new one,
this statement actually takes ownership of <code>s1</code>, appends a copy of the contents
of <code>s2</code>, then returns ownership of the result. In other words, it looks like
it’s making a lot of copies, but isn’t: the implementation is more efficient
than copying.</p>
<p>If we need to concatenate multiple strings, the behavior of <code>+</code> gets unwieldy:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let s1 = String::from("tic");
let s2 = String::from("tac");
let s3 = String::from("toe");
let s = s1 + "-" + &s2 + "-" + &s3;
#}</code></pre></pre>
<p><code>s</code> will be “tic-tac-toe” at this point. With all of the <code>+</code> and <code>"</code>
characters, it gets hard to see what’s going on. For more complicated string
combining, we can use the <code>format!</code> macro:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let s1 = String::from("tic");
let s2 = String::from("tac");
let s3 = String::from("toe");
let s = format!("{}-{}-{}", s1, s2, s3);
#}</code></pre></pre>
<p>This code will also set <code>s</code> to “tic-tac-toe”. The <code>format!</code> macro works in the
same way as <code>println!</code>, but instead of printing the output to the screen, it
returns a <code>String</code> with the contents. This version is much easier to read, and
also does not take ownership of any of its parameters.</p>
<a class="header" href="ch08-02-strings.html#indexing-into-strings" id="indexing-into-strings"><h3>Indexing into Strings</h3></a>
<p>In many other languages, accessing individual characters in a string by
referencing them by index is a valid and common operation. In Rust, however, if
we try to access parts of a <code>String</code> using indexing syntax, we’ll get an error.
That is, this code:</p>
<pre><code class="language-rust ignore">let s1 = String::from("hello");
let h = s1[0];
</code></pre>
<p>will result in this error:</p>
<pre><code class="language-text">error: the trait bound `std::string::String: std::ops::Index<_>` is not
satisfied [--explain E0277]
|>
|> let h = s1[0];
|> ^^^^^
note: the type `std::string::String` cannot be indexed by `_`
</code></pre>
<p>The error and the note tell the story: Rust strings don’t support indexing. So
the follow-up question is, why not? In order to answer that, we have to talk a
bit about how Rust stores strings in memory.</p>
<a class="header" href="ch08-02-strings.html#internal-representation" id="internal-representation"><h4>Internal Representation</h4></a>
<p>A <code>String</code> is a wrapper over a <code>Vec<u8></code>. Let’s take a look at some of our
properly-encoded UTF-8 example strings from before. First, this one:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let len = String::from("Hola").len();
#}</code></pre></pre>
<p>In this case, <code>len</code> will be four, which means the <code>Vec</code> storing the string
“Hola” is four bytes long: each of these letters takes one byte when encoded in
UTF-8. What about this example, though?</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let len = String::from("Здравствуйте").len();
#}</code></pre></pre>
<p>A person asked how long the string is might say 12. However, Rust’s answer
is 24. This is the number of bytes that it takes to encode “Здравствуйте” in
UTF-8, since each Unicode scalar value takes two bytes of storage. Therefore,
an index into the string’s bytes will not always correlate to a valid Unicode
scalar value.</p>
<p>To demonstrate, consider this invalid Rust code:</p>
<pre><code class="language-rust ignore">let hello = "Здравствуйте";
let answer = &hello[0];
</code></pre>
<p>What should the value of <code>answer</code> be? Should it be <code>З</code>, the first letter? When
encoded in UTF-8, the first byte of <code>З</code> is <code>208</code>, and the second is <code>151</code>, so
<code>answer</code> should in fact be <code>208</code>, but <code>208</code> is not a valid character on its
own. Returning <code>208</code> is likely not what a person would want if they asked for
the first letter of this string, but that’s the only data that Rust has at byte
index 0. Returning the byte value is probably not what people want, even with
only Latin letters: <code>&"hello"[0]</code> would return <code>104</code>, not <code>h</code>. To avoid
returning an unexpected value and causing bugs that might not be discovered
immediately, Rust chooses to not compile this code at all and prevent
misunderstandings earlier.</p>
<a class="header" href="ch08-02-strings.html#bytes-and-scalar-values-and-grapheme-clusters-oh-my" id="bytes-and-scalar-values-and-grapheme-clusters-oh-my"><h4>Bytes and Scalar Values and Grapheme Clusters! Oh my!</h4></a>
<p>This leads to another point about UTF-8: there are really three relevant ways
to look at strings, from Rust’s perspective: as bytes, scalar values, and
grapheme clusters (the closest thing to what people would call <em>letters</em>).</p>
<p>If we look at the Hindi word “नमस्ते” written in the Devanagari script, it is
ultimately stored as a <code>Vec</code> of <code>u8</code> values that looks like this:</p>
<pre><code class="language-text">[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]
</code></pre>
<p>That’s 18 bytes, and is how computers ultimately store this data. If we look at
them as Unicode scalar values, which are what Rust’s <code>char</code> type is, those
bytes look like this:</p>
<pre><code class="language-text">['न', 'म', 'स', '्', 'त', 'े']
</code></pre>
<p>There are six <code>char</code> values here, but the fourth and sixth are not letters,
they’re diacritics that don’t make sense on their own. Finally, if we look at
them as grapheme clusters, we’d get what a person would call the four letters
that make up this word:</p>
<pre><code class="language-text">["न", "म", "स्", "ते"]
</code></pre>
<p>Rust provides different ways of interpreting the raw string data that computers
store so that each program can choose the interpretation it needs, no matter
what human language the data is in.</p>
<p>A final reason Rust does not allow you to index into a <code>String</code> to get a
character is that indexing operations are expected to always take constant time
(O(1)). It isn’t possible to guarantee that performance with a <code>String</code>,
though, since Rust would have to walk through the contents from the beginning
to the index to determine how many valid characters there were.</p>
<a class="header" href="ch08-02-strings.html#slicing-strings" id="slicing-strings"><h3>Slicing Strings</h3></a>
<p>Because it's not clear what the return type of string indexing should be, and
it is often a bad idea to index into a string, Rust dissuades you from doing so
by asking you to be more specific if you really need it. The way you can be
more specific than indexing using <code>[]</code> with a single number is using <code>[]</code> with
a range to create a string slice containing particular bytes:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
let hello = "Здравствуйте";
let s = &hello[0..4];
#}</code></pre></pre>
<p>Here, <code>s</code> will be a <code>&str</code> that contains the first four bytes of the string.
Earlier, we mentioned that each of these characters was two bytes, so that
means that <code>s</code> will be “Зд”.</p>
<p>What would happen if we did <code>&hello[0..1]</code>? The answer: it will panic at
runtime, in the same way that accessing an invalid index in a vector does:</p>
<pre><code class="language-text">thread 'main' panicked at 'index 0 and/or 1 in `Здравствуйте` do not lie on
character boundary', ../src/libcore/str/mod.rs:1694
</code></pre>
<p>You should use this with caution, since it can cause your program to crash.</p>
<a class="header" href="ch08-02-strings.html#methods-for-iterating-over-strings" id="methods-for-iterating-over-strings"><h3>Methods for Iterating Over Strings</h3></a>
<p>Luckily, there are other ways we can access elements in a String.</p>
<p>If we need to perform operations on individual Unicode scalar values, the best
way to do so is to use the <code>chars</code> method. Calling <code>chars</code> on “नमस्ते”
separates out and returns six values of type <code>char</code>, and you can iterate over
the result in order to access each element:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
for c in "नमस्ते".chars() {
println!("{}", c);
}
#}</code></pre></pre>
<p>This code will print:</p>
<pre><code class="language-text">न
म
स
्
त
े
</code></pre>
<p>The <code>bytes</code> method returns each raw byte, which might be appropriate for your
domain:</p>
<pre><pre class="playpen"><code class="language-rust"># #![allow(unused_variables)]
#fn main() {
for b in "नमस्ते".bytes() {
println!("{}", b);
}
#}</code></pre></pre>
<p>This code will print the 18 bytes that make up this <code>String</code>, starting with:</p>
<pre><code class="language-text">224
164
168
224
// ... etc
</code></pre>
<p>But make sure to remember that valid Unicode scalar values may be made up of
more than one byte.</p>
<p>Getting grapheme clusters from strings is complex, so this functionality is not
provided by the standard library. There are crates available on crates.io if
this is the functionality you need.</p>
<a class="header" href="ch08-02-strings.html#strings-are-not-so-simple" id="strings-are-not-so-simple"><h3>Strings are Not so Simple</h3></a>
<p>To summarize, strings are complicated. Different programming languages make
different choices about how to present this complexity to the programmer. Rust
has chosen to make the correct handling of <code>String</code> data the default behavior
for all Rust programs, which does mean programmers have to put more thought
into handling UTF-8 data upfront. This tradeoff exposes more of the complexity
of strings than other programming languages do, but this will prevent you from
having to handle errors involving non-ASCII characters later in your
development lifecycle.</p>
<p>Let’s switch to something a bit less complex: hash map!</p>
</div>
<!-- Mobile navigation buttons -->
<a href="ch08-01-vectors.html" class="mobile-nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
<a href="ch08-03-hash-maps.html" class="mobile-nav-chapters next">
<i class="fa fa-angle-right"></i>
</a>
</div>
<a href="ch08-01-vectors.html" class="nav-chapters previous" title="You can navigate through the chapters using the arrow keys">
<i class="fa fa-angle-left"></i>
</a>
<a href="ch08-03-hash-maps.html" class="nav-chapters next" title="You can navigate through the chapters using the arrow keys">
<i class="fa fa-angle-right"></i>
</a>
</div>
<!-- Local fallback for Font Awesome -->
<script>
if ($(".fa").css("font-family") !== "FontAwesome") {
$('<link rel="stylesheet" type="text/css" href="_FontAwesome/css/font-awesome.css">').prependTo('head');
}
</script>
<!-- Livereload script (if served using the cli tool) -->
<script src="highlight.js"></script>
<script src="book.js"></script>
</body>
</html>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
878cdd00a13d17a73c6619a777ef5d74
>
files
>
253
