Guide macros and unsafe

[steveklabnik]

The last two sections of the guide, and a small conclusion. I suck at conclusions.

I also realized I never covered strings, so I'm going to put that section up before we're actually 'done.'

[ghost]

s/is is/is its

[steveklabnik]

dammmit, thank you

[steveklabnik]

@jakub- see if the extra words i added fixes your issue about the mutex.

[parir]

Missing *.

[steveklabnik]

thanks

[steveklabnik]

@jakub- thanks, fixed!

[mdinger]

I think this is supposed to showcase the power of the macro system but it doesn't seem that way to me. It just looks like regex is implemented with macros rather than functions. With functions you could something like this where the returned structure has a function called is_match to test with.

let date_matcher = regex(r"^\d{4}-\d{2}-\d{2}$");
println!("{}", date_matcher.is_match("2014-01-01"));

Is it easy to show why it is much better implemented as a macro than a function? If so, this seems like a good place for it. Otherwise, the conclusion might be that it's another variant of a function but why should we care.

[steveklabnik]

My point is mostly to show that macros exist, but it is true that it would be good to mention why it is implemented this way.

[huonw]

Discussing println! might be a good example? It does relatively complicated computation (compared to a C-like macro anyway), e.g. parsing & processing "{foo:<5.8t} {0:03d}", x, foo = y, and results in something that has a clear benefit: compile-time-checked flexible format strings.

[steveklabnik]

That's a good idea, especially since it's the macro we've been using already, and doesn't assume knowledge of something else, like regular expressions.

[mdinger]

Is assert! simple? It might be another alternative.

[steveklabnik]

That is an alternative, but it's not often used. At least, maybe assert_eq! or something would be better.

[steveklabnik]

I've updated this PR to talk about println! instead of regexes. I like it better, but I'm unsure as to how much of a good idea it is to show the expanded output. I kinda like the shock-and-awe effect, heh.

[mdinger]

s/numer/number/

[steveklabnik]

i really, really, really need to figure out how to get my spell checker to not throw errors in code blocks, it's how i keep missing things like this

[mdinger]

Much better macro intro.
Before - it was: "Macros do cool things but I'm not gonna show any of them to you"
Now - it's: "Macros are cool. Check this out!"

[steveklabnik]

@mdinger awesome 😄

[steveklabnik]

@huonw do you have anything to say here? You reviewed the initial draft.

[huonw]

I'll try to look over it again in the next day or so.

[steveklabnik]

@brson : I reabased this to fix the merge error.