[rust.git] / doc / po / tutorial-container.md.pot

# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR The Rust Project Developers
# This file is distributed under the same license as the Rust package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Rust 0.8-pre\n"
"POT-Creation-Date: 2013-08-05 19:40+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. type: Plain text
#: doc/tutorial-container.md:2
msgid "% Containers and iterators"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:4
msgid "# Containers"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:6
msgid "The container traits are defined in the `std::container` module."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:8
msgid "## Unique and managed vectors"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:12
msgid ""
"Vectors have `O(1)` indexing and removal from the end, along with `O(1)` "
"amortized insertion. Vectors are the most common container in Rust, and are "
"flexible enough to fit many use cases."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:16
msgid ""
"Vectors can also be sorted and used as efficient lookup tables with the "
"`std::vec::bsearch` function, if all the elements are inserted at one time "
"and deletions are unnecessary."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:18
msgid "## Maps and sets"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:22
msgid ""
"Maps are collections of unique keys with corresponding values, and sets are "
"just unique keys without a corresponding value. The `Map` and `Set` traits "
"in `std::container` define the basic interface."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:24
msgid "The standard library provides three owned map/set types:"
msgstr ""

#. type: Bullet: '* '
#: doc/tutorial-container.md:30
msgid ""
"`std::hashmap::HashMap` and `std::hashmap::HashSet`, requiring the keys to "
"implement `Eq` and `Hash`"
msgstr ""

#. type: Bullet: '* '
#: doc/tutorial-container.md:30
msgid ""
"`std::trie::TrieMap` and `std::trie::TrieSet`, requiring the keys to be "
"`uint`"
msgstr ""

#. type: Bullet: '* '
#: doc/tutorial-container.md:30
msgid ""
"`extra::treemap::TreeMap` and `extra::treemap::TreeSet`, requiring the keys "
"to implement `TotalOrd`"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:34
msgid ""
"These maps do not use managed pointers so they can be sent between tasks as "
"long as the key and value types are sendable. Neither the key or value type "
"has to be copyable."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:37
msgid ""
"The `TrieMap` and `TreeMap` maps are ordered, while `HashMap` uses an "
"arbitrary order."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:42
msgid ""
"Each `HashMap` instance has a random 128-bit key to use with a keyed hash, "
"making the order of a set of keys in a given hash table randomized. Rust "
"provides a [SipHash](https://131002.net/siphash/) implementation for any "
"type implementing the `IterBytes` trait."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:44
msgid "## Double-ended queues"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:49
msgid ""
"The `extra::deque` module implements a double-ended queue with `O(1)` "
"amortized inserts and removals from both ends of the container. It also has "
"`O(1)` indexing like a vector. The contained elements are not required to be "
"copyable, and the queue will be sendable if the contained type is sendable."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:51
msgid "## Priority queues"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:55
msgid ""
"The `extra::priority_queue` module implements a queue ordered by a key.  The "
"contained elements are not required to be copyable, and the queue will be "
"sendable if the contained type is sendable."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:61
msgid ""
"Insertions have `O(log n)` time complexity and checking or popping the "
"largest element is `O(1)`. Converting a vector to a priority queue can be "
"done in-place, and has `O(n)` complexity. A priority queue can also be "
"converted to a sorted vector in-place, allowing it to be used for an `O(n "
"log n)` in-place heapsort."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:63
msgid "# Iterators"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:65
msgid "## Iteration protocol"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:69
msgid ""
"The iteration protocol is defined by the `Iterator` trait in the `std::"
"iterator` module. The minimal implementation of the trait is a `next` "
"method, yielding the next element from an iterator object:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:73
msgid "~~~ /// An infinite stream of zeroes struct ZeroStream;"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:80
#, no-wrap
msgid ""
"impl Iterator<int> for ZeroStream {\n"
"    fn next(&mut self) -> Option<int> {\n"
"        Some(0)\n"
"    }\n"
"}\n"
"~~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:83
msgid ""
"Reaching the end of the iterator is signalled by returning `None` instead of "
"`Some(item)`:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:89 doc/tutorial-container.md:262
#, no-wrap
msgid ""
"~~~\n"
"/// A stream of N zeroes\n"
"struct ZeroStream {\n"
"    priv remaining: uint\n"
"}\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:95
#, no-wrap
msgid ""
"impl ZeroStream {\n"
"    fn new(n: uint) -> ZeroStream {\n"
"        ZeroStream { remaining: n }\n"
"    }\n"
"}\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:107 doc/tutorial-container.md:284
#, no-wrap
msgid ""
"impl Iterator<int> for ZeroStream {\n"
"    fn next(&mut self) -> Option<int> {\n"
"        if self.remaining == 0 {\n"
"            None\n"
"        } else {\n"
"            self.remaining -= 1;\n"
"            Some(0)\n"
"        }\n"
"    }\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:109
msgid "## Container iterators"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:112
msgid ""
"Containers implement iteration over the contained elements by returning an "
"iterator object. For example, vector slices several iterators available:"
msgstr ""

#. type: Bullet: '* '
#: doc/tutorial-container.md:116
msgid "`iter()` and `rev_iter()`, for immutable references to the elements"
msgstr ""

#. type: Bullet: '* '
#: doc/tutorial-container.md:116
msgid ""
"`mut_iter()` and `mut_rev_iter()`, for mutable references to the elements"
msgstr ""

#. type: Bullet: '* '
#: doc/tutorial-container.md:116
msgid ""
"`consume_iter()` and `consume_rev_iter`, to move the elements out by-value"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:119
msgid ""
"A typical mutable container will implement at least `iter()`, `mut_iter()` "
"and `consume_iter()` along with the reverse variants if it maintains an "
"order."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:121
msgid "### Freezing"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:125
msgid ""
"Unlike most other languages with external iterators, Rust has no *iterator "
"invalidation*. As long an iterator is still in scope, the compiler will "
"prevent modification of the container through another handle."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:130
#, no-wrap
msgid ""
"~~~\n"
"let mut xs = [1, 2, 3];\n"
"{\n"
"    let _it = xs.iter();\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:136
#, no-wrap
msgid ""
"    // the vector is frozen for this scope, the compiler will statically\n"
"    // prevent modification\n"
"}\n"
"// the vector becomes unfrozen again at the end of the scope\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:139
msgid ""
"These semantics are due to most container iterators being implemented with "
"`&` and `&mut`."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:141
msgid "## Iterator adaptors"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:145
msgid ""
"The `IteratorUtil` trait implements common algorithms as methods extending "
"every `Iterator` implementation. For example, the `fold` method will "
"accumulate the items yielded by an `Iterator` into a single value:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:151
msgid ""
"~~~ let xs = [1, 9, 2, 3, 14, 12]; let result = xs.iter().fold(0, |"
"accumulator, item| accumulator - *item); assert_eq!(result, -41); ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:153
msgid ""
"Some adaptors return an adaptor object implementing the `Iterator` trait "
"itself:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:160
msgid ""
"~~~ let xs = [1, 9, 2, 3, 14, 12]; let ys = [5, 2, 1, 8]; let sum = xs."
"iter().chain_(ys.iter()).fold(0, |a, b| a + *b); assert_eq!(sum, 57); ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:164
msgid ""
"Note that some adaptors like the `chain_` method above use a trailing "
"underscore to work around an issue with method resolve. The underscores will "
"be dropped when they become unnecessary."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:166
msgid "## For loops"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:168
msgid ""
"The `for` keyword can be used as sugar for iterating through any iterator:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:171
msgid "~~~ let xs = [2, 3, 5, 7, 11, 13, 17];"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:176
#, no-wrap
msgid ""
"// print out all the elements in the vector\n"
"for x in xs.iter() {\n"
"    println(x.to_str())\n"
"}\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:182
#, no-wrap
msgid ""
"// print out all but the first 3 elements in the vector\n"
"for x in xs.iter().skip(3) {\n"
"    println(x.to_str())\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:185
msgid ""
"For loops are *often* used with a temporary iterator object, as above. They "
"can also advance the state of an iterator in a mutable location:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:189
msgid ""
"~~~ let xs = [1, 2, 3, 4, 5]; let ys = [\"foo\", \"bar\", \"baz\", \"foobar"
"\"];"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:192
msgid ""
"// create an iterator yielding tuples of elements from both vectors let mut "
"it = xs.iter().zip(ys.iter());"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:196
#, no-wrap
msgid ""
"// print out the pairs of elements up to (&3, &\"baz\")\n"
"for (x, y) in it {\n"
"    printfln!(\"%d %s\", *x, *y);\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:201
#, no-wrap
msgid ""
"    if *x == 3 {\n"
"        break;\n"
"    }\n"
"}\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:204
msgid ""
"// yield and print the last pair from the iterator printfln!(\"last: %?\", "
"it.next());"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:208
msgid "// the iterator is now fully consumed assert!(it.next().is_none()); ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:210
msgid "## Conversion"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:212
msgid ""
"Iterators offer generic conversion to containers with the `collect` adaptor:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:218
msgid ""
"~~~ let xs = [0, 1, 1, 2, 3, 5, 8]; let ys = xs.rev_iter().skip(1)."
"transform(|&x| x * 2).collect::<~[int]>(); assert_eq!(ys, ~[10, 6, 4, 2, 2, "
"0]); ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:221
msgid ""
"The method requires a type hint for the container type, if the surrounding "
"code does not provide sufficient information."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:225
msgid ""
"Containers can provide conversion from iterators through `collect` by "
"implementing the `FromIterator` trait. For example, the implementation for "
"vectors is as follows:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:238
#, no-wrap
msgid ""
"~~~\n"
"impl<A> FromIterator<A> for ~[A] {\n"
"    pub fn from_iterator<T: Iterator<A>>(iterator: &mut T) -> ~[A] {\n"
"        let (lower, _) = iterator.size_hint();\n"
"        let mut xs = with_capacity(lower);\n"
"        for x in iterator {\n"
"            xs.push(x);\n"
"        }\n"
"        xs\n"
"    }\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:240
msgid "### Size hints"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:243
msgid ""
"The `Iterator` trait provides a `size_hint` default method, returning a "
"lower bound and optionally on upper bound on the length of the iterator:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:247
msgid "~~~ fn size_hint(&self) -> (uint, Option<uint>) { (0, None) } ~~~"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:251
msgid ""
"The vector implementation of `FromIterator` from above uses the lower bound "
"to pre-allocate enough space to hold the minimum number of elements the "
"iterator will yield."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:254
msgid ""
"The default implementation is always correct, but it should be overridden if "
"the iterator can provide better information."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:256
msgid ""
"The `ZeroStream` from earlier can provide an exact lower and upper bound:"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:267
#, no-wrap
msgid ""
"impl ZeroStream {\n"
"    fn new(n: uint) -> ZeroStream {\n"
"        ZeroStream { remaining: n }\n"
"    }\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:272
#, no-wrap
msgid ""
"    fn size_hint(&self) -> (uint, Option<uint>) {\n"
"        (self.remaining, Some(self.remaining))\n"
"    }\n"
"}\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:286
msgid "## Double-ended iterators"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:290
msgid ""
"The `DoubleEndedIterator` trait represents an iterator able to yield "
"elements from either end of a range. It inherits from the `Iterator` trait "
"and extends it with the `next_back` function."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:293
msgid ""
"A `DoubleEndedIterator` can be flipped with the `invert` adaptor, returning "
"another `DoubleEndedIterator` with `next` and `next_back` exchanged."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:300
msgid ""
"~~~ let xs = [1, 2, 3, 4, 5, 6]; let mut it = xs.iter(); printfln!(\"%?\", "
"it.next()); // prints `Some(&1)` printfln!(\"%?\", it.next()); // prints "
"`Some(&2)` printfln!(\"%?\", it.next_back()); // prints `Some(&6)`"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:306
#, no-wrap
msgid ""
"// prints `5`, `4` and `3`\n"
"for &x in it.invert() {\n"
"    printfln!(\"%?\", x)\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:309
msgid ""
"The `rev_iter` and `mut_rev_iter` methods on vectors just return an inverted "
"version of the standard immutable and mutable vector iterators."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:312
msgid ""
"The `chain_`, `transform`, `filter`, `filter_map` and `peek` adaptors are "
"`DoubleEndedIterator` implementations if the underlying iterators are."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:317
msgid ""
"~~~ let xs = [1, 2, 3, 4]; let ys = [5, 6, 7, 8]; let mut it = xs.iter()."
"chain_(ys.iter()).transform(|&x| x * 2);"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:319
msgid "printfln!(\"%?\", it.next()); // prints `Some(2)`"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:325
#, no-wrap
msgid ""
"// prints `16`, `14`, `12`, `10`, `8`, `6`, `4`\n"
"for x in it.invert() {\n"
"    printfln!(\"%?\", x);\n"
"}\n"
"~~~\n"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:327
msgid "## Random-access iterators"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:331
msgid ""
"The `RandomAccessIterator` trait represents an iterator offering random "
"access to the whole range. The `indexable` method retrieves the number of "
"elements accessible with the `idx` method."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:334
msgid ""
"The `chain_` adaptor is an implementation of `RandomAccessIterator` if the "
"underlying iterators are."
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:343
msgid ""
"~~~ let xs = [1, 2, 3, 4, 5]; let ys = ~[7, 9, 11]; let mut it = xs.iter()."
"chain_(ys.iter()); printfln!(\"%?\", it.idx(0)); // prints `Some(&1)` "
"printfln!(\"%?\", it.idx(5)); // prints `Some(&7)` printfln!(\"%?\", it."
"idx(7)); // prints `Some(&11)` printfln!(\"%?\", it.idx(8)); // prints `None`"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:348
msgid ""
"// yield two elements from the beginning, and one from the end it.next(); it."
"next(); it.next_back();"
msgstr ""

#. type: Plain text
#: doc/tutorial-container.md:352
msgid ""
"printfln!(\"%?\", it.idx(0)); // prints `Some(&3)` printfln!(\"%?\", it."
"idx(4)); // prints `Some(&9)` printfln!(\"%?\", it.idx(6)); // prints `None` "
"~~~"
msgstr ""