Notes on SIZE_HINT

[jsha]

The docs for SIZE_HINT say:

Provides a conservative estimate of the expanded length of the rendered template

It would be useful to say which way "conservative" means - I assume it means to err on the side of too low rather than too high.

Also, The Rust Performance Book suggests using eprintln! on a sample workload to print sizes in order to decide what a good pre-reserved capacity is. It might be nice to offer some handy way to do that for a given template. Maybe debug / trace logging?

By my reading of the source, SIZE_HINT only applies to calling render() on a template, not render_into, using the Display impl, or using the (blanket) ToString impl. That should probably be documented, along with the impact on sub-templates.

Also, I think Template could implement ToString to bypass the blanket ToString impl on Display items. Template's implementation could pre-reserve based on SIZE_HINT.

[Kijewski]

I don't think it's possible to override the default ToString implementation until feature(specialization) is stable.

Error[E0119]: conflicting implementations of trait `ToString` for type `test_match_ws::MatchWs`
   --> testing/tests/ws.rs:469:18
    |
469 |         #[derive(Template)]
    |                  ^^^^^^^^
...
    |
    = note: conflicting implementation in crate `alloc`:
            - impl<T> ToString for T
              where T: std::fmt::Display, T: ?Sized;
    = note: this error originates in the derive macro `Template` which comes from the expansion of the macro `test_match` (in Nightly builds, run with -Z macro-backtrace for more info)

[jsha]

Oh, right! Thanks for the clarification.

[djc]

Yeah, as far as I can tell neither a std::io::Write nor a std::fmt::Formatter expose any way to manage/extend any underlying buffers.

Would you be able to send a PR for some of the suggested documentation improvements?

[jsha]

Yep, will do!