AI22-0143-1

!standard A.4.11(51/3)                                    26-04-30  AI22-0143-1/05

!standard A.4.11(82/3)

!standard A.4.11(94/3)

!class presentation 25-11-24

!status Amendment 1-2022 25-11-24

!status ARG Approved  9-0-0  25-12-11

!status work item 25-11-24

!status received 25-11-21

!assigned author Randall Brukardt

!submitter Randall Brukardt

!priority Low

!difficulty Easy

!subject Make new UTF Decode functions consistent

!summary

We describe the new UTF Decode functions in the same way that existing functions are described.

!issue

AI22-0102-1 added a series of new Decode functions to two Ada.Strings.UTF_Encoding packages. However, these new functions were not added to the descriptive list of functions that follows, which looks like these were bolted on after the fact. Moreover, while some of their semantics were added to the text before the list, the rest of their semantics was not given at all.

!recommendation

(see summary.)

!wording

Delete A.4.11(51.1/6).

Add after A.4.11(82/3):

function Decode (Item         : UTF_String;
                 Input_Scheme : Encoding_Scheme;
                 Substitute   : Character) return String;

Returns the result of decoding Item, which is encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme. If the decoding of a sequence results in a code point whose value exceeds 16#FF#, the resulting character is replaced by Substitute in the result String.

function Decode (Item         : UTF_8_String;
                 Substitute   : Character) return String;

Returns the result of decoding Item, which is encoded in UTF-8. If the decoding of a sequence results in a code point whose value exceeds 16#FF#, the resulting character is replaced by Substitute in the result String.

function Decode (Item         : UTF_16_Wide_String;
                 Substitute   : Character) return String;

Returns the result of decoding Item, which is encoded in UTF-16. If the decoding of a sequence results in a code point whose value exceeds 16#FF#, the resulting character is replaced by Substitute in the result String.

Add after A.4.11(94/3):

function Decode (Item         : UTF_String;
                 Input_Scheme : Encoding_Scheme;
                 Substitute   : Wide_Character) return Wide_String;

Returns the result of decoding Item, which is encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme. If the decoding of a sequence results in a code point whose value exceeds 16#FFFF#, the resulting character is replaced by Substitute in the result Wide_String.

function Decode (Item         : UTF_8_String;
                 Substitute   : Wide_Character) return Wide_String;

Returns the result of decoding Item, which is encoded in UTF-8. If the decoding of a sequence results in a code point whose value exceeds 16#FFFF#, the resulting character is replaced by Substitute in the result Wide_String.

function Decode (Item         : UTF_16_Wide_String;
                 Substitute   : Wide_Character) return Wide_String;

Returns the result of decoding Item, which is encoded in UTF-16. If the decoding of a sequence results in a code point whose value exceeds 16#FFFF#, the resulting character is replaced by Substitute in the result Wide_String.

!discussion

Without this change, the normal operation of the new Decode functions is ill-defined. The meaning is fairly obvious, but the fact that the definition is not given makes the careful reader wonder if something special is intended.

The substitution wording was simplified, as the context makes it obvious what the meaning and type of “Substitute” is, so repeating that is not necessary.

!comment A.4.11(51/3) change is made in AI22-0102-1.

!corrigendum A.4.11(82/3)

@dinsa

@xindent{Returns the result of decoding Item, which is encoded in UTF-16.}

@dinss

@xcode{@b{function} Decode (Item         : UTF_String;
                Input_Scheme : Encoding_Scheme;
                Substitute   : Character) @b{return} String;}

@xindent{Returns the result of decoding Item, which is encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme. If the decoding of a sequence results in a code point whose value exceeds 16#FF#, the resulting character is replaced by Substitute in the result String.}

@xcode{@b{function} Decode (Item         : UTF_8_String;
                Substitute   : Character) @b{return} String;}

@xindent{Returns the result of decoding Item, which is encoded in UTF-8. If the decoding of a sequence results in a code point whose value exceeds 16#FF#, the resulting character is replaced by Substitute in the result String.}

@xcode{@b{function} Decode (Item         : UTF_16_Wide_String;
                Substitute   : Character) @b{return} String;}

@xindent{Returns the result of decoding Item, which is encoded in UTF-16. If the decoding of a sequence results in a code point whose value exceeds 16#FF#, the resulting character is replaced by Substitute in the result String.}

!corrigendum A.4.11(94/3)

@dinsa

@xindent{Returns the result of decoding Item, which is encoded in UTF-16.}

@dinss

@xcode{@b{function} Decode (Item         : UTF_String;
                Input_Scheme : Encoding_Scheme;
                Substitute   : Wide_Character) @b{return} Wide_String;}

@xindent{Returns the result of decoding Item, which is encoded in UTF-8, UTF-16LE, or UTF-16BE as specified by Input_Scheme. If the decoding of a sequence results in a code point whose value exceeds 16#FFFF#, the resulting character is replaced by Substitute in the result Wide_String.}

@xcode{@b{function} Decode (Item         : UTF_8_String;
                Substitute   : Wide_Character) @b{return} Wide_String;}

@xindent{Returns the result of decoding Item, which is encoded in UTF-8. If the decoding of a sequence results in a code point whose value exceeds 16#FFFF#, the resulting character is replaced by Substitute in the result Wide_String.}

@xcode{@b{function} Decode (Item         : UTF_16_Wide_String;
                Substitute   : Wide_Character) @b{return} Wide_String;}

@xindent{Returns the result of decoding Item, which is encoded in UTF-16. If the decoding of a sequence results in a code point whose value exceeds 16#FFFF#, the resulting character is replaced by Substitute in the result Wide_String.}

!ACATS test

See AI22-0102-1 for ACATS tests.

!appendix

From: Randy Brukardt

Sent: Thursday, April 30, 2026 9:49 PM

Brad Moore asked to make the subject of this AI more specific as part of his Editorial Review. No other changes were made.