feat(library): add experimental string ASC overloads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

6 files changed, 35 insertions, 0 deletions

diff --git a/pseudocode-lib/README.md b/pseudocode-lib/README.md
index bd646ee..665e2ed 100644
--- a/pseudocode-lib/README.md
+++ b/pseudocode-lib/README.md
@@ -28,3 +28,5 @@ The library provides `&`, `_EXP_STRING_NUM_TO_STR` (INTEGER/REAL), `_EXP_STRING_
 `_EXP_STRING_LCASE(S : _EXP_STRING)` returns a new `_EXP_STRING` with letters converted to lower case. Its `(Ch : CHAR)` overload returns CHAR, following guide section 5.5. Nonletters and embedded NUL bytes are preserved; the source is unchanged. Use ASCII for predictable case conversion.
 
 `_EXP_STRING_UCASE(S : _EXP_STRING)` returns a new `_EXP_STRING` with letters converted to upper case. Its `(Ch : CHAR)` overload returns CHAR, following guide section 5.5. Nonletters and embedded NUL bytes are preserved; the source is unchanged. Use ASCII for predictable case conversion.
+
+`_EXP_STRING_ASC(S : _EXP_STRING)` returns the unsigned code of the first byte as INTEGER, or 0 for an empty string. Its `(Ch : CHAR)` overload returns the unsigned byte code of Ch. For ASCII characters this is the ASCII code.
diff --git a/pseudocode-lib/_exp_string.cc b/pseudocode-lib/_exp_string.cc
index bd476b8..6a17f74 100644
--- a/pseudocode-lib/_exp_string.cc
+++ b/pseudocode-lib/_exp_string.cc
@@ -113,6 +113,15 @@ char _exp_string_impl_ucase_char(char Ch) {
         return static_cast<char>(std::toupper(static_cast<unsigned char>(Ch)));
     });
 }
+long long _exp_string_impl_asc(void *Handle) {
+    return checked([&]() -> long long {
+        const auto &Source = text(Handle);
+        return Source.empty() ? 0 : static_cast<unsigned char>(Source.front());
+    });
+}
+long long _exp_string_impl_asc_char(char Ch) {
+    return checked([&]() -> long long { return static_cast<unsigned char>(Ch); });
+}
 void _exp_string_impl_output(void *Handle) {
     checked([&] {
         const auto &Text = text(Handle);
diff --git a/pseudocode-lib/_exp_string.cps b/pseudocode-lib/_exp_string.cps
index a56ed04..a4d95d6 100644
--- a/pseudocode-lib/_exp_string.cps
+++ b/pseudocode-lib/_exp_string.cps
@@ -21,6 +21,8 @@ EXTERN "C" EXTERN_PROCEDURE _exp_string_impl_lcase(_EXP_STRING_HANDLE, _EXP_STRI
 EXTERN "C" EXTERN_FUNCTION _exp_string_impl_lcase_char(C_CHAR) RETURNS C_CHAR
 EXTERN "C" EXTERN_PROCEDURE _exp_string_impl_ucase(_EXP_STRING_HANDLE, _EXP_STRING_HANDLE)
 EXTERN "C" EXTERN_FUNCTION _exp_string_impl_ucase_char(C_CHAR) RETURNS C_CHAR
+EXTERN "C" EXTERN_FUNCTION _exp_string_impl_asc(_EXP_STRING_HANDLE) RETURNS _EXP_STRING_C_INTEGER
+EXTERN "C" EXTERN_FUNCTION _exp_string_impl_asc_char(C_CHAR) RETURNS _EXP_STRING_C_INTEGER
 EXTERN "C" EXTERN_PROCEDURE _exp_string_impl_output(_EXP_STRING_HANDLE)
 
 CLASS _EXP_STRING
@@ -103,3 +105,9 @@ ENDFUNCTION
 OVERLOAD FUNCTION _EXP_STRING_UCASE(Ch : CHAR) RETURNS CHAR
     RETURN (CHAR)_exp_string_impl_ucase_char((C_CHAR)Ch)
 ENDFUNCTION
+OVERLOAD FUNCTION _EXP_STRING_ASC(S : _EXP_STRING) RETURNS INTEGER
+    RETURN (INTEGER)_exp_string_impl_asc(S._HANDLE)
+ENDFUNCTION
+OVERLOAD FUNCTION _EXP_STRING_ASC(Ch : CHAR) RETURNS INTEGER
+    RETURN (INTEGER)_exp_string_impl_asc_char((C_CHAR)Ch)
+ENDFUNCTION
diff --git a/tests/library/exp-string/expected.txt b/tests/library/exp-string/expected.txt
index b7e35f6..88c9a2f 100644
--- a/tests/library/exp-string/expected.txt
+++ b/tests/library/exp-string/expected.txt
@@ -32,3 +32,6 @@ AbC@19
 H:H:@
 0:8
 ABC
+65:65
+0:0:0
+255
diff --git a/tests/library/exp-string/notes.md b/tests/library/exp-string/notes.md
index d365dfc..f360410 100644
--- a/tests/library/exp-string/notes.md
+++ b/tests/library/exp-string/notes.md
@@ -15,3 +15,5 @@ MID positions 2..4 give BCD. The minimum INTEGER start clamps to 1 and gives AB;
 LCASE converts AbC@19 to abc@19 without modifying the source. Its CHAR overload returns CHAR w for W or w and preserves @, as in guide section 5.5. Empty length stays zero; two leading NULs survive conversion and letters after them still become abc.
 
 UCASE converts AbC@19 to ABC@19 without modifying the source. Its CHAR overload returns CHAR H for h or H and preserves @, as in guide section 5.5. Empty length stays zero; two leading NULs survive conversion and letters after them still become ABC.
+
+ASC returns 65 for CHAR A and the first byte of ABCDEFGH, zero for empty strings or NUL, and 255 for a byte with all eight bits set. These byte-code functions are compiler/library extensions.
diff --git a/tests/library/exp-string/program.cps b/tests/library/exp-string/program.cps
index 61a915c..dfa5b47 100644
--- a/tests/library/exp-string/program.cps
+++ b/tests/library/exp-string/program.cps
@@ -44,6 +44,7 @@ CALL CheckRight()
 CALL CheckMid()
 CALL CheckLCase()
 CALL CheckUCase()
+CALL CheckAsc()
 
 PROCEDURE CheckLeft()
     DECLARE Letters : _EXP_STRING((C_STRING)"ABCDEFGH")
@@ -104,3 +105,13 @@ PROCEDURE CheckUCase()
     OUTPUT _EXP_STRING_LENGTH(_EXP_STRING_UCASE(Empty)), ":", _EXP_STRING_LENGTH(_EXP_STRING_UCASE(Nuls & Mixed))
     CALL _EXP_STRING_OUTPUT(_EXP_STRING_MID(_EXP_STRING_UCASE(Nuls & Mixed), 3, 3))
 ENDPROCEDURE
+
+PROCEDURE CheckAsc()
+    DECLARE Letters : _EXP_STRING((C_STRING)"ABCDEFGH")
+    DECLARE Empty : _EXP_STRING
+    DECLARE Nuls : _EXP_STRING(2, (C_CHAR)'\0')
+    DECLARE High : _EXP_STRING(1, (C_CHAR)255)
+    OUTPUT _EXP_STRING_ASC('A'), ":", _EXP_STRING_ASC(Letters)
+    OUTPUT _EXP_STRING_ASC(Empty), ":", _EXP_STRING_ASC(Nuls), ":", _EXP_STRING_ASC('\0')
+    OUTPUT _EXP_STRING_ASC(High)
+ENDPROCEDURE