diff --git a/exercises/practice/accumulate/.docs/instructions.append.md b/exercises/practice/accumulate/.docs/hints.md similarity index 98% rename from exercises/practice/accumulate/.docs/instructions.append.md rename to exercises/practice/accumulate/.docs/hints.md index 3d79940ff..082f60c16 100644 --- a/exercises/practice/accumulate/.docs/instructions.append.md +++ b/exercises/practice/accumulate/.docs/hints.md @@ -1,4 +1,4 @@ -# Hints +## General It may help to look at the Fn\* traits: [Fn](https://doc.rust-lang.org/std/ops/trait.Fn.html), diff --git a/exercises/practice/binary-search/.docs/hints.md b/exercises/practice/binary-search/.docs/hints.md new file mode 100644 index 000000000..ed2f8ee3c --- /dev/null +++ b/exercises/practice/binary-search/.docs/hints.md @@ -0,0 +1,16 @@ +## General + +[Slices](https://doc.rust-lang.org/book/2018-edition/ch04-03-slices.html) have additionally to +the normal element access via indexing (slice[index]) many useful functions like +[split_at](https://doc.rust-lang.org/std/primitive.slice.html#method.split_at) or [getting +subslices](https://doc.rust-lang.org/std/primitive.slice.html#method.get) (slice[start..end]). + +You can solve this exercise by just using boring old element access via indexing, but maybe the +other provided functions can make your code cleaner and safer. + +## For Bonus Points + +- To get your function working with all kind of elements which can be ordered, + have a look at the [Ord Trait](https://doc.rust-lang.org/std/cmp/trait.Ord.html). +- To get your function working directly on Vec and Array, you can use the + [AsRef Trait](https://doc.rust-lang.org/std/convert/trait.AsRef.html) diff --git a/exercises/practice/binary-search/.docs/instructions.append.md b/exercises/practice/binary-search/.docs/instructions.append.md index f958a0db5..f2afbf7cb 100644 --- a/exercises/practice/binary-search/.docs/instructions.append.md +++ b/exercises/practice/binary-search/.docs/instructions.append.md @@ -6,16 +6,6 @@ Rust provides in its standard library already a [binary search function](https://doc.rust-lang.org/std/primitive.slice.html#method.binary_search). For this exercise you should not use this function but just other basic tools instead. -## Hints - -[Slices](https://doc.rust-lang.org/book/2018-edition/ch04-03-slices.html) have additionally to -the normal element access via indexing (slice[index]) many useful functions like -[split_at](https://doc.rust-lang.org/std/primitive.slice.html#method.split_at) or [getting -subslices](https://doc.rust-lang.org/std/primitive.slice.html#method.get) (slice[start..end]). - -You can solve this exercise by just using boring old element access via indexing, but maybe the -other provided functions can make your code cleaner and safer. - ## For bonus points Did you get the tests passing and the code clean? If you want to, there @@ -36,10 +26,3 @@ $ cargo test --features generic Then please share your thoughts in a comment on the submission. Did this experiment make the code better? Worse? Did you learn anything from it? - -### Hints for Bonus Points - -- To get your function working with all kind of elements which can be ordered, - have a look at the [Ord Trait](https://doc.rust-lang.org/std/cmp/trait.Ord.html). -- To get your function working directly on Vec and Array, you can use the - [AsRef Trait](https://doc.rust-lang.org/std/convert/trait.AsRef.html) diff --git a/exercises/practice/clock/.docs/instructions.append.md b/exercises/practice/clock/.docs/instructions.append.md index 6ceff1140..1e3a35101 100644 --- a/exercises/practice/clock/.docs/instructions.append.md +++ b/exercises/practice/clock/.docs/instructions.append.md @@ -1,4 +1,6 @@ -# Rust Traits for `.to_string()` +# Instructions append + +## Rust Traits for `.to_string()` You will also need to implement `.to_string()` for the `Clock` struct. We will be using this to display the Clock's state. diff --git a/exercises/practice/decimal/.docs/hints.md b/exercises/practice/decimal/.docs/hints.md new file mode 100644 index 000000000..40831648e --- /dev/null +++ b/exercises/practice/decimal/.docs/hints.md @@ -0,0 +1,5 @@ +## General + +- Instead of implementing arbitrary-precision arithmetic from scratch, consider building your type on top of the [num_bigint](https://crates.io/crates/num-bigint) crate. +- You might be able to [derive](https://doc.rust-lang.org/book/2018-edition/appendix-03-derivable-traits.html) some of the required traits. +- `Decimal` is assumed to be a signed type. You do not have to create a separate unsigned type, though you may do so as an implementation detail if you so choose. diff --git a/exercises/practice/decimal/.docs/instructions.md b/exercises/practice/decimal/.docs/instructions.md index 2ec586381..d954595df 100644 --- a/exercises/practice/decimal/.docs/instructions.md +++ b/exercises/practice/decimal/.docs/instructions.md @@ -13,9 +13,3 @@ In Rust, the way to get these operations on custom types is to implement the rel # Note It would be very easy to implement this exercise by using the [bigdecimal](https://crates.io/crates/bigdecimal) crate. Don't do that; implement this yourself. - -# Hints - -- Instead of implementing arbitrary-precision arithmetic from scratch, consider building your type on top of the [num_bigint](https://crates.io/crates/num-bigint) crate. -- You might be able to [derive](https://doc.rust-lang.org/book/2018-edition/appendix-03-derivable-traits.html) some of the required traits. -- `Decimal` is assumed to be a signed type. You do not have to create a separate unsigned type, though you may do so as an implementation detail if you so choose. diff --git a/exercises/practice/dot-dsl/.docs/instructions.append.md b/exercises/practice/dot-dsl/.docs/instructions.append.md index 33fd9f817..c9aabe67c 100644 --- a/exercises/practice/dot-dsl/.docs/instructions.append.md +++ b/exercises/practice/dot-dsl/.docs/instructions.append.md @@ -1,4 +1,6 @@ -# Builder pattern +# Instructions append + +## Builder pattern This exercise expects you to build several structs using `builder pattern`. In short, this pattern allows you to split the construction function of your struct, that contains a lot of arguments, into diff --git a/exercises/practice/doubly-linked-list/.docs/instructions.append.md b/exercises/practice/doubly-linked-list/.docs/hints.md similarity index 97% rename from exercises/practice/doubly-linked-list/.docs/instructions.append.md rename to exercises/practice/doubly-linked-list/.docs/hints.md index d2a6ef54e..afe765081 100644 --- a/exercises/practice/doubly-linked-list/.docs/instructions.append.md +++ b/exercises/practice/doubly-linked-list/.docs/hints.md @@ -1,4 +1,4 @@ -# Hints +## General * A doubly linked does not have a clear ownership hierarchy, which is why it requires either the use of unsafe or abstractions for shared ownership like `Rc`. The latter has some overhead that is unnecessary diff --git a/exercises/practice/forth/.docs/instructions.append.md b/exercises/practice/forth/.docs/instructions.append.md index 42b8ccdf0..947eed8e1 100644 --- a/exercises/practice/forth/.docs/instructions.append.md +++ b/exercises/practice/forth/.docs/instructions.append.md @@ -1,3 +1,5 @@ +# Instructions append + Note the additional test case in `tests/alloc-attack.rs`. It tests against algorithmically inefficient implementations. Because of that, it usually times out online instead of outright failing, leading to a less helpful error message. diff --git a/exercises/practice/hello-world/.docs/instructions.append.md b/exercises/practice/hello-world/.docs/instructions.append.md index 9c894cfaa..d14290126 100644 --- a/exercises/practice/hello-world/.docs/instructions.append.md +++ b/exercises/practice/hello-world/.docs/instructions.append.md @@ -1 +1,3 @@ +# Instructions append + In the Rust track, tests are run using the command `cargo test`. diff --git a/exercises/practice/high-scores/.docs/instructions.append.md b/exercises/practice/high-scores/.docs/hints.md similarity index 92% rename from exercises/practice/high-scores/.docs/instructions.append.md rename to exercises/practice/high-scores/.docs/hints.md index 20863a371..228e4850d 100644 --- a/exercises/practice/high-scores/.docs/instructions.append.md +++ b/exercises/practice/high-scores/.docs/hints.md @@ -1,4 +1,4 @@ -# Hints +## General Consider retaining a reference to `scores` in the struct - copying is not necessary. You will require some lifetime annotations, though. diff --git a/exercises/practice/largest-series-product/.docs/instructions.append.md b/exercises/practice/largest-series-product/.docs/hints.md similarity index 87% rename from exercises/practice/largest-series-product/.docs/instructions.append.md rename to exercises/practice/largest-series-product/.docs/hints.md index f91157776..7344c2e28 100644 --- a/exercises/practice/largest-series-product/.docs/instructions.append.md +++ b/exercises/practice/largest-series-product/.docs/hints.md @@ -1,4 +1,4 @@ -# Largest Series Product in Rust +## General These iterators may be useful, depending on your approach diff --git a/exercises/practice/macros/.docs/instructions.append.md b/exercises/practice/macros/.docs/instructions.append.md deleted file mode 100644 index 4c02cfac6..000000000 --- a/exercises/practice/macros/.docs/instructions.append.md +++ /dev/null @@ -1,3 +0,0 @@ -# Compatibility - -Note that this exercise requires Rust 1.36 or later. diff --git a/exercises/practice/paasio/.docs/instructions.append.md b/exercises/practice/paasio/.docs/instructions.append.md index 8fc197892..10428370d 100644 --- a/exercises/practice/paasio/.docs/instructions.append.md +++ b/exercises/practice/paasio/.docs/instructions.append.md @@ -1,4 +1,6 @@ -# Abstraction over Networks and Files +# Instructions append + +## Abstraction over Networks and Files Network and file operations are implemented in terms of the [`io::Read`][read] and [`io::Write`][write] traits. It will therefore be necessary to implement those traits for your types. diff --git a/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md b/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md index b858dd6c3..309eaba05 100644 --- a/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md +++ b/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md @@ -1,4 +1,6 @@ -# Parallel Letter Frequency in Rust +# Instructions append + +## Parallel Letter Frequency in Rust Learn more about concurrency in Rust here: diff --git a/exercises/practice/poker/.docs/instructions.append.md b/exercises/practice/poker/.docs/hints.md similarity index 98% rename from exercises/practice/poker/.docs/instructions.append.md rename to exercises/practice/poker/.docs/hints.md index fb531d554..0312531cc 100644 --- a/exercises/practice/poker/.docs/instructions.append.md +++ b/exercises/practice/poker/.docs/hints.md @@ -1,4 +1,4 @@ -# Hints +## General - Ranking a list of poker hands can be considered a sorting problem. - Rust provides the [sort](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort) method for `Vec where T: Ord`. diff --git a/exercises/practice/reverse-string/.docs/instructions.append.md b/exercises/practice/reverse-string/.docs/instructions.append.md index e13803cd4..f28f72c0a 100644 --- a/exercises/practice/reverse-string/.docs/instructions.append.md +++ b/exercises/practice/reverse-string/.docs/instructions.append.md @@ -1,4 +1,7 @@ -# Bonus +# Instructions append + +## Bonus + Test your function on this string: `uüu` and see what happens. Try to write a function that properly reverses this string. Hint: grapheme clusters diff --git a/exercises/practice/rna-transcription/.docs/instructions.append.md b/exercises/practice/rna-transcription/.docs/instructions.append.md index 25fc579e1..1273336ec 100644 --- a/exercises/practice/rna-transcription/.docs/instructions.append.md +++ b/exercises/practice/rna-transcription/.docs/instructions.append.md @@ -1,4 +1,6 @@ -# Notes on Rust implementation +# Instructions append + +## Notes on Rust implementation By using private fields in structs with public `new` functions returning `Option` or `Result` (as here with `DNA::new` & `RNA::new`), we can guarantee diff --git a/exercises/practice/say/.docs/instructions.append.md b/exercises/practice/say/.docs/instructions.append.md index 37260b9bf..41400ee83 100644 --- a/exercises/practice/say/.docs/instructions.append.md +++ b/exercises/practice/say/.docs/instructions.append.md @@ -1,3 +1,4 @@ +# Instructions append ## Rust Specific Exercise Notes @@ -14,6 +15,6 @@ Adding 'and' into number text has not been implemented in test cases. ### Extension -Add capability of converting up to the max value for u64: 18,446,744,073,709,551,615. +Add capability of converting up to the max value for u64: `18_446_744_073_709_551_615`. For hints at the output this should have, look at the last test case. diff --git a/exercises/practice/simple-linked-list/.docs/instructions.append.md b/exercises/practice/simple-linked-list/.docs/hints.md similarity index 97% rename from exercises/practice/simple-linked-list/.docs/instructions.append.md rename to exercises/practice/simple-linked-list/.docs/hints.md index 8803c5703..b9520d6d2 100644 --- a/exercises/practice/simple-linked-list/.docs/instructions.append.md +++ b/exercises/practice/simple-linked-list/.docs/hints.md @@ -1,4 +1,4 @@ -# Implementation Hints +## General Do not implement the struct `SimpleLinkedList` as a wrapper around a `Vec`. Instead, allocate nodes on the heap. diff --git a/exercises/practice/space-age/.docs/instructions.append.md b/exercises/practice/space-age/.docs/instructions.append.md index 3702e9904..1443ddea2 100644 --- a/exercises/practice/space-age/.docs/instructions.append.md +++ b/exercises/practice/space-age/.docs/instructions.append.md @@ -1,4 +1,6 @@ -# Topics +# Instructions append + +## Topics Some Rust topics you may want to read about while solving this problem: diff --git a/exercises/practice/triangle/.docs/instructions.append.md b/exercises/practice/triangle/.docs/instructions.append.md index deb679100..7ae558d39 100644 --- a/exercises/practice/triangle/.docs/instructions.append.md +++ b/exercises/practice/triangle/.docs/instructions.append.md @@ -1,4 +1,4 @@ -# Triangle in Rust +# Instructions append - [Result](https://doc.rust-lang.org/std/result/index.html) diff --git a/exercises/practice/xorcism/.docs/instructions.append.md b/exercises/practice/xorcism/.docs/instructions.append.md index c7bd1f3bf..7b90b0f4e 100644 --- a/exercises/practice/xorcism/.docs/instructions.append.md +++ b/exercises/practice/xorcism/.docs/instructions.append.md @@ -1,4 +1,6 @@ -# Lifetime of `munge` return value +# Instructions append + +## Lifetime of `munge` return value Due to the usage of the `impl Trait` feature, lifetime management may be a bit tricky when implementing the `munge` method. You may find it easier to write diff --git a/rust-tooling/ci-tests/tests/docs_are_valid.rs b/rust-tooling/ci-tests/tests/docs_are_valid.rs new file mode 100644 index 000000000..37d814d8a --- /dev/null +++ b/rust-tooling/ci-tests/tests/docs_are_valid.rs @@ -0,0 +1,32 @@ +use glob::glob; +use utils::fs::cd_into_repo_root; + +// https://exercism.org/docs/building/tracks/practice-exercises#h-file-docs-hints-md +#[test] +fn hints_have_correct_heading() { + cd_into_repo_root(); + for entry in glob("exercises/practice/*/.docs/hints.md").unwrap() { + let path = entry.unwrap(); + let content = std::fs::read_to_string(&path).unwrap(); + assert!( + content.starts_with("## General"), + "incorrect heading in {}", + path.display() + ) + } +} + +// https://exercism.org/docs/building/tracks/practice-exercises#h-file-docs-introduction-append-md +#[test] +fn instructions_append_have_correct_heading() { + cd_into_repo_root(); + for entry in glob("exercises/*/*/.docs/instructions.append.md").unwrap() { + let path = entry.unwrap(); + let content = std::fs::read_to_string(&path).unwrap(); + assert!( + content.starts_with("# Instructions append"), + "incorrect heading in {}", + path.display() + ) + } +}