feat: implement require macros and fix log docs

[austinabell]

Basically want to provide macros to mimic similar behaviour to the rust assert! macros without it adding extra rust details and file information about the assertion.

Built on #492 to avoid conflicts and use the correct method signature, but can switch if we want this and not that PR.

Optional which opinions would be appreciated:

• Should the no message call panic() syscall directly? I assumed not because it seems like a micro-optimization that would be hard to debug by default. Pinpointing that it's a require statement might help developers

[mikedotexe]

cool, seems like these will be less costly on CPU cycles than asserts, is that right?

[austinabell]

I don't think that will necessarily be the case, but it should reduce the code size from not including file/line numbers of where the assert is. This also depends on the use case, though.

[austinabell]

@matklad would love a quick opinion on this if you think this is a good direction for having this type of assertion available without the Rust internals.

[matklad]

Couple of thoughts:

• I wonder if we should just call this assert. The require name doesn't really point to the difference
• You probably don't need _eq/_neq versions -- they exist solely to provide better assertion messages. we don't allow assertion message, assert!(x == y) is enough.
• Would be cool to get some specific numbers on code saving here: I know that fmt is heavy in principle, but I don't have a gut feeling for how much.

Overall seems like a good idea!

[matklad]

Not entirely sure, but it seems that built-in format uses &$message rather than $message.as_ref()

• https://github.com/rust-lang/rust/blob/d59b80d588368cdcfcc1d54e119374a3d78169ff/compiler/rustc_builtin_macros/src/format.rs#L797
• https://github.com/rust-lang/rust/blob/d59b80d588368cdcfcc1d54e119374a3d78169ff/compiler/rustc_expand/src/build.rs#L232-L235
• https://github.com/rust-lang/rust/blob/d59b80d588368cdcfcc1d54e119374a3d78169ff/compiler/rustc_ast/src/ast.rs#L1362-L1364

[austinabell]

So the rationale was that I wanted the ability to supply something that wasn't just a static string or if keeping expr then forcing the user to pass in a &str, in place of not having the formatting machinery.

I was thinking it would be used as the log! macro where it allows String, &str, or anything that implements AsRef<str>. I suppose all we want here is to allow owned or str references, so I think I will take this suggestion because it's unlikely someone will assert with the message being a single struct

[austinabell]

Couple of thoughts:

• I wonder if we should just call this assert. The require name doesn't really point to the difference

I personally think that keeping it named require to avoid collision with the std prelude and making it clear that it performs a different function is good rather than having unexpected side effects if someone does/doesn't import the near_sdk::assert, do you have a strong opinion on naming it assert?

• You probably don't need _eq/_neq versions -- they exist solely to provide better assertion messages. we don't allow assertion message, assert!(x == y) is enough.

Good point! I'll remove those for now. My rationale was that it would be easier for migration to these from the assert variants, but can always just add later if we want

• Would be cool to get some specific numbers on code saving here: I know that fmt is heavy in principle, but I don't have a gut feeling for how much.

So it's hard to tell, since most of fmt is still pulled in for all contracts using the sdk, but roughly can see the contract size changes in #514 (since now we are tying the example builds with docker to the CI checks)

[austinabell]

Just in case of ambiguity, I'm assuming your approval as invalid @mikedotexe because I've made changes since your approval.

[willemneal]

Looks good to me. I tried to think of why require wouldn't be a good name (since it's overloaded with node's old way of importing modules), but given that they are moving away from that to import * from * I think it's good.