New Recipes

[AndyGauge]

Create an issue for each of the recipes

• Algorithms
  • [x] Sort a vector
    • with custom ordering
    • with a custom key
  • CLI
  • [x] color (ANSI)
  • Compression
  • [x] Decompress gzipped web content
  • Concurrency
  • [x] Sharing Data between threads
  • shared ownership with Arc
  • shared stack with crossbeam
  • mutable data with Mutex
  • passing messages with mspc
  • Crypto
  • [ ] Using TLS
  • … client side
  • … server side
  • [ ] Calculate a cryptographic hash using MD5
  • Database interfaces
  • [ ] Postgres
  • … querying
  • … updating
  • … transactions
  • … prepared statements
  • [ ] sqlite
  • … querying
  • … updating
  • … prepared statements
  • [ ] diesel example and link?
  • Data structures
  • [ ] Vec
  • [ ] HashMap/Set
  • [ ] BTreeMap
  • [ ] VecDeque
  • [ ] petgraph
  • Memory management
  • [ ] mmap
  • [ ] Rc
  • [ ] allocator APIs in std?
  • custom global allocator
  • [ ] arenas?
  • Network programming
  • [ ] std::net
  • [ ] show examples (or cross-ref) doing common tasks
  • SSL
  • Gzip
  • http
  • Operating systems
  • [ ] Command API
  • [ ] std::env
  • [ ] Reference: winapi, libc
  • Parsing
  • [ ] nom
  • [ ] lalrpop
  • Science aka numerics
  • [x] Numeric Types
  • BigInt (num)
  • Complex numbers (num)
  • [x] Geometry, Trigonometry, Statistics
    • A few Geometry calculations
    • Plotting a circle with trigonometry
    • Distance between 2 lat/long.
    • Statistics
  • [x] Matricies
    • various vector math recipes
    • various matrix recipes
    • serailze matrix

• Text processing
  • [ ] std string apis — pattern APIs
• Rust patterns
  • [ ] RefCell
  • [ ] Cell

These were taken from https://paper.dropbox.com/doc/Cookbook-new-recipe-list--AHhY6tZWu74Ju8uewuP5J87BAg-oRJe83bTkNE4Gk2Qmvu5V

[AndyGauge]

@budziq can you review this list? This is from when @withoutboats and @aturon were planning new recipes. I'm happy to create the issues, but before officially adopting them, I'm hoping for your input. There are also opportunities in here to expand our adopted crates so cc https://github.com/rust-lang-nursery/ecosystem-wg/issues/22

[budziq]

can you review this list

@AndyGauge Sure! It looks very cool on the first glance, but I'll need some time to give any reasonable feadback. Some assorted musings:

• As you mentioned, the first thing that we would need to establish is a list of crates to include in the next iteration of examples. In my experience it is very helpful to add such information to every example ticket. It greatly helps contributors in the initial steps.
• database interaction/ORM was on my target from day one. But do we show diesel, rusqlite, postgres or all?
• custom allocators. These are already explained at length in TRPL. Should we overlap? cc @steveklabnik (To some extent also Rc, RefCell, Cell`)
• I'm all for inclusion of nom using its API was a pleasure, can't really speak for lalrpop. But I'm guessing that the approaches are different enough to warrant showing both, although pest seams to be quite popular too.
• not sure about ndarray as there are quite a few [more popular crates for matrix operations(https://crates.io/keywords/matrix) including nalgebra. I still do all my data sciency stuff in python so I cannot really tell anything about the quality of these libs. Maybe @aturon can give us some insight why ndarray was originally chosen?
• I'd love to finaly see some XML examples but last time I checked there was no clear crate winner. But xml-rs seams to have [gained popularity] (https://crates.io/keywords/xml)
• It would be cool to to see uuid-rs and num (possibly bigint) examples
• I can't really say I follow the idea of representing libc and winapi correctly as I understand these as low level and not immediately usable to any effect that cannot be better shown by usage of std or higher level crate (even if this is something like nix). But maybe just showing that there are such interfaces will be educational enough?
• in regard of mutex,mpsc, and basic datastructures it is unclear to what granularity we would like to overlap with std docs. I guess that I'd prefer for the examples to show some self contained usable code. More towards the extreme of "generate thumbnails in parallel" than "pass a value between threads".
• edit: also how do we chose between std and a dedicated crate if there seams to exist a strictly superior alternative. see std std::sync::mpsc::channel vs crossbeam_channel

[AndyGauge]

• I like the idea of putting the crate, and I think adding the category would also benefit contributors. Now that there is an order, maintaining the order is important.
• I think we should show raw SQL adapters, and have a recipe for diesel then link to their guides. I don't want to make ORM a major part of the cookbook, but would like to see a simple recipe to spark interest in visiting the diesel page. It takes a lot of setup to get it to work, but I think a migration for one model and a query would suffice. I think rusqlite, postgres, diesel would be a good scope.
• allocators: I'd love to see a recipe that uses Box in a meaningful way, but it would need to be something that many developers could benefit from. Implementing Deref would be great, but I think having a structured recipe that does something useful is the challenge. Here's a common musing: https://users.rust-lang.org/t/when-should-i-use-box-t/4411/2 and it leads to a meaningful usecase: "for performance if T is large and is being moved around a lot, using a Box instead will avoid doing big memcpys". I wonder if getting into the Rc, RefCell, and Cell land after that is too narrow use cases for the Cookbook.
• mdbook depends on handlebars depends on pest. That seems to be where 75% of pest's usage comes from. You are right though about it being used more. I can't make a claim about PEG vs LALR vs combinators. If I knew what developers were actually interested in it would make crate inclusion easier. I think we can start with nom and consider additional parsers later.
• I'm not sure why num isn't showcased. I also don't know if science is really needed by a wide audience. We should probably just drop this and pursue https://github.com/rust-lang-nursery/rust-cookbook/issues/362
• +1 xml-rs and maybe an xmltree example
• +1 num I think uuid-rs has a small usage case and already good documentation. I figure if you need to generate a UUID, you just google uuid in rust and find the plain api. +1 Bigint
• I move to table the libc and winapi until more categories are fleshed out.
• I agree with usable code rather than just implementing the datastructures. I also agree that crossbeam_channel over std::sync::mspc::channel in the Cookbook. We already highlight crossbeam.

[budziq]

@AndyGauge :+1: Sorry for taking so long. Imho all of these are valid points. Lets go with these recipes!

[Frederik-Baetens]

Hello, I don't know if I should post this here but, I have an implementation of an algorithm for the closest pair of points problem. It is a very nice use case of a btreeset, since the data needs to be sorted, and inserted into at random points.

For each point in a vec of points sorted by x coordinate, the algorithm calculates the distance only to points that are within the square around it with a diameter of 2*(min distance so far) as shown here For the horizontal dimension, you can just use the fact that you're working in a sorted vec, but to keep track of proximity in a second dimension, a btreeset is useful. You basically insert points into the btreeset as you pass over them in your for loop. Then you will know which points are close in the x dimension based on the sorted vec, and you will know which points are close in the y direction based on the BtreeSet.

If you think this is a good idea I'd be glad to clean up my code and try to submit a pull request.