al_ref_cstr, al_ref_buffer and al_ref_ustr document their return value lifetimes incorrectly

[tehsausage]

The documentation for al_ref_cstr claims the following:

The [returned] string is valid until the underlying C string disappears.

However, the returned string also becomes invalid once the ALLEGRO_USTR_INFO struct passed to it becomes invalid.

Test-case: https://gist.github.com/tehsausage/5a834aa308aaa052a87719a0645b2636

In this example, the documentation for al_ref_cstr implies "Hello cstr", "Hello ustr", and "Goodbye ustr" would all be printed without issue. Instead, undefined behavior is invoked, and "Goodbye ustr" is not printed, or the program crashes.

The documentation for al_ref_cstr and al_ref_ustr (but not al_ref_buffer) also includes the following text:

The information about the string (e.g. its size) is stored in the structure pointed to by the info parameter. The string will not have any other storage allocated of its own, so if you allocate the info structure on the stack then no explicit “free” operation is required.

However, its not mentioned that the lifetime of the returned ALLEGRO_USTR object is tied to the lifetime of the passed-in ALLEGRO_USTR_INFO object.

---

al_ref_buffer and al_ref_ustr make similarly incorrect claims:

The [returned] string is valid while the underlying memory buffer is valid.

The [returned] string is valid until the underlying string is modified or destroyed.

Both are also invalidated by the lifetime of the associated ALLEGRO_USTR_INFO object ending.

[rmbeer]

I have already made a pull request, although I have no way to bring it to this thread other than a link. I hope that it would be useful to someone.

https://github.com/liballeg/allegro5/pull/1205

I also commented that it is possible to adjust the code and make it return -1 to the string size to indicate that the original string was removed.