StringMemoryPassthru

Allows the efficient conversion of strings by means of a temporary memory buffer only when necessary. Intended to be used when you have an API which populates a buffer with some string representation which is ultimately going to be stored in another representation, but where you don't want to do a conversion or create a temporary buffer for that string if it's not necessary.

Intended use:

Populates the buffer Str with StrLen characters. void SomeAPI(APICharType* Str, int32 StrLen);

void Func(DestChar* Buffer, int32 BufferSize) { Create a passthru. This takes the buffer (and its size) which will ultimately hold the string, as well as the length of the string that's being converted, which must be known in advance. An explicit template argument is also passed to indicate the character type of the source string. Buffer must be correctly typed for the destination string type. auto Passthru = StringMemoryPassthru(Buffer, BufferSize, SourceLength);

Passthru.Get() returns an APICharType buffer pointer which is guaranteed to be SourceLength characters in size. It's possible, and in fact intended, for Get() to return the same pointer as Buffer if DestChar and APICharType are compatible string types. If this is the case, SomeAPI will write directly into Buffer. If the string types are not compatible, Get() will return a pointer to some temporary memory which allocated by and owned by the passthru. SomeAPI(Passthru.Get(), SourceLength);

If the string types were not compatible, then the passthru used temporary storage, and we need to write that back to Buffer. We do that with the Apply call. If the string types were compatible, then the data was already written to Buffer directly and so Apply is a no-op. Passthru.Apply();

Now Buffer holds the data output by SomeAPI, already converted if necessary. }