Description
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.