From da20f610940d5fdcb5d07a059b63623c0bbb330e Mon Sep 17 00:00:00 2001
From: Pavel Sountsov <siege@google.com>
Date: Sat, 22 Jun 2024 12:48:48 -0700
Subject: [PATCH] Add al_ref_info to convert ALLEGRO_USTR_INFO to ALLEGRO_USTR.

---
 docs/src/refman/utf8.txt | 15 +++++++++++++--
 include/allegro5/utf8.h  |  1 +
 src/utf8.c               |  7 +++++++
 3 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/docs/src/refman/utf8.txt b/docs/src/refman/utf8.txt
index b600f024ee..58c455903f 100644
--- a/docs/src/refman/utf8.txt
+++ b/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
diff --git a/include/allegro5/utf8.h b/include/allegro5/utf8.h
index f0459dac04..cb94a77bb7 100644
--- a/include/allegro5/utf8.h
+++ b/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));
diff --git a/src/utf8.c b/src/utf8.c
index 1a6e55d83b..5007c555e7 100644
--- a/src/utf8.c
+++ b/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)