Simplify header handling in HSTRING

[rylev]

This simplifies the HSTRING header and adds more safety documentation.

[kennykerr]

Let's merge #1749 first just to be sure we don't break anything. 😉

[eholk]

Looks good! I added a few comments, but they're mostly just (bad) ideas to consider for the future.

[eholk]

I'm guessing this is this way to match the way things already were in COM-land, but it's a little weird to me that buffer_start is not zero-sized.

[rylev]

Not having this as a zero-sized type caused some confusion that I was discussing with @kennykerr - namely, that we allocate std::mem::size_of::<Header> + 2 * length_of_hstring bytes we're allocating enough space for string data that fits all of the contents accounted for by length_of_hstring plus a terminating null u16 which length_of_string does not account for but that extra u16 in Header does.

Definitely something to consider...

[kennykerr]

This is just the way the HSTRING was implemented internally by the OS, so it helps to keep the header representation similar for clarity. Note that an empty, or zero-length, HSTRING is internally represented by a null pointer so there will never be a zero-length header.

[rylev]

@kennykerr this should be ready to go now.

While I have your attention, it seems we're debug asserting in Hstring::clear that we're not trying to clear a "fast pass" string. This seems wrong, since we should also not call heap_free in production when debug asserts are not enabled. What is the correct way to handle this? Should self.0 still be set to null?

[kennykerr]

It is strictly a bug in the language projection if this debug assert is true. I added it just to validate my implementation was correct when I first wrote the code but it can never happen, short of a logic bug in the HSTRING implementation.