diff --git a/mk/docs.mk b/mk/docs.mk index 213565b09ac27..933a0bdc717ca 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -30,7 +30,7 @@ DOCS := index intro tutorial guide guide-ffi guide-macros guide-lifetimes \ guide-tasks guide-container guide-pointers guide-testing \ guide-runtime complement-bugreport \ complement-lang-faq complement-design-faq complement-project-faq rust \ - rustdoc guide-unsafe + rustdoc guide-unsafe guide-strings PDF_DOCS := tutorial rust diff --git a/src/doc/guide-strings.md b/src/doc/guide-strings.md index 6f301afc8498d..4fea8b8039e00 100644 --- a/src/doc/guide-strings.md +++ b/src/doc/guide-strings.md @@ -1,7 +1,5 @@ % The Strings Guide -# Strings - Strings are an important concept to master in any programming language. If you come from a managed language background, you may be surprised at the complexity of string handling in a systems programming language. Efficient access and @@ -14,7 +12,7 @@ Additionally, strings are not null-terminated and can contain null bytes. Rust has two main types of strings: `&str` and `String`. -## &str +# &str The first kind is a `&str`. This is pronounced a 'string slice.' String literals are of the type `&str`: @@ -38,7 +36,7 @@ Like vector slices, string slices are simply a pointer plus a length. This means that they're a 'view' into an already-allocated string, such as a `&'static str` or a `String`. -## String +# String A `String` is a heap-allocated string. This string is growable, and is also guaranteed to be UTF-8. @@ -73,9 +71,9 @@ let x: &[u8] = &[b'a', b'b']; let stack_str: &str = str::from_utf8(x).unwrap(); ``` -## Best Practices +# Best Practices -### `String` vs. `&str` +## `String` vs. `&str` In general, you should prefer `String` when you need ownership, and `&str` when you just need to borrow a string. This is very similar to using `Vec` vs. `&[T]`, @@ -98,7 +96,7 @@ need, and it can make your lifetimes more complex. Furthermore, you can pass either kind of string into `foo` by using `.as_slice()` on any `String` you need to pass in, so the `&str` version is more flexible. -### Comparisons +## Comparisons To compare a String to a constant string, prefer `as_slice()`... @@ -123,7 +121,7 @@ fn compare(string: String) { Converting a `String` to a `&str` is cheap, but converting the `&str` to a `String` involves an allocation. -## Other Documentation +# Other Documentation * [the `&str` API documentation](/std/str/index.html) * [the `String` API documentation](std/string/index.html) diff --git a/src/doc/index.md b/src/doc/index.md index eb8c59ac030ee..c54f4e00905de 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -13,6 +13,7 @@ li {list-style-type: none; } # Guides +* [Strings](guide-strings.html) * [Pointers](guide-pointers.html) * [References and Lifetimes](guide-lifetimes.html) * [Containers and Iterators](guide-container.html)