Add al_ref_info to convert ALLEGRO_USTR_INFO to ALLEGRO_USTR.

docs/src/refman/utf8.txt

@@ -97,9 +97,10 @@ NULs.
 ### API: ALLEGRO_USTR_INFO
 
 A type that holds additional information for an [ALLEGRO_USTR] that references
-an external memory buffer.
+an external memory buffer. You can convert it back to [ALLEGRO_USTR] via
+[al_ref_info].
 
-See also: [al_ref_cstr], [al_ref_buffer] and [al_ref_ustr].
+See also: [al_ref_cstr], [al_ref_buffer], [al_ref_info] and [al_ref_ustr].
 
 
 ## Creating and destroying strings
@@ -269,6 +270,16 @@ to find the byte offsets.
 See also: [al_ref_cstr], [al_ref_buffer]
 
 
+### API: al_ref_info
+
+Create a read-only string that references the storage of another [ALLEGRO_USTR]
+string that has already been stored in the [ALLEGRO_USTR_INFO] structure.
+
+The string is valid until the underlying string is modified or destroyed.
+
+See also: [al_ref_cstr], [al_ref_buffer], [al_ref_ustr]
+
+
 ## Sizes and offsets
 
 ### API: al_ustr_size

include/allegro5/utf8.h

@@ -45,6 +45,7 @@ AL_FUNC(const ALLEGRO_USTR *, al_ref_buffer, (ALLEGRO_USTR_INFO *info, const cha
       size_t size));
 AL_FUNC(const ALLEGRO_USTR *, al_ref_ustr, (ALLEGRO_USTR_INFO *info,
       const ALLEGRO_USTR *us, int start_pos, int end_pos));
+AL_FUNC(const ALLEGRO_USTR *, al_ref_info, (const ALLEGRO_USTR_INFO *info));
 
 /* Sizes and offsets */
 AL_FUNC(size_t, al_ustr_size, (const ALLEGRO_USTR *us));

src/utf8.c

@@ -192,6 +192,13 @@ const ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_INFO *info, const ALLEGRO_USTR *us,
 }
 
 
+/* Function: al_ref_info
+ */
+const ALLEGRO_USTR *al_ref_info(const ALLEGRO_USTR_INFO *info)
+{
+   return info;
+}
+
 /* Function: al_ustr_size
  */
 size_t al_ustr_size(const ALLEGRO_USTR *us)