Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Include Strings guide with the others.
Three small changes:

1. Re-organize headers in the Strings guide so they show up correctly.
2. build the strings guide with the other docs
3. include the strings guide in the list of guides
  • Loading branch information
steveklabnik committed Jul 18, 2014
1 parent 4418664 commit 0c30e1f
Show file tree
Hide file tree
Showing 3 changed files with 8 additions and 9 deletions.
2 changes: 1 addition & 1 deletion mk/docs.mk
Expand Up @@ -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

Expand Down
14 changes: 6 additions & 8 deletions 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
Expand All @@ -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`:
Expand All @@ -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.
Expand Down Expand Up @@ -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<T>` vs. `&[T]`,
Expand All @@ -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()`...

Expand All @@ -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)
1 change: 1 addition & 0 deletions src/doc/index.md
Expand Up @@ -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)
Expand Down

5 comments on commit 0c30e1f

@bors
Copy link
Contributor

@bors bors commented on 0c30e1f Jul 19, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

saw approval from cmr
at steveklabnik@0c30e1f

@bors
Copy link
Contributor

@bors bors commented on 0c30e1f Jul 19, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

merging steveklabnik/rust/string_guide_link = 0c30e1f into auto

@bors
Copy link
Contributor

@bors bors commented on 0c30e1f Jul 19, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

steveklabnik/rust/string_guide_link = 0c30e1f merged ok, testing candidate = ab61022

@bors
Copy link
Contributor

@bors bors commented on 0c30e1f Jul 19, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fast-forwarding master to auto = ab61022

Please sign in to comment.