| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT RUN-TIME COMPONENTS -- |
| -- -- |
| -- A D A . C H A R A C T E R S . H A N D L I N G -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 1992-2022, Free Software Foundation, Inc. -- |
| -- -- |
| -- This specification is derived from the Ada Reference Manual for use with -- |
| -- GNAT. The copyright notice above, and the license provisions that follow -- |
| -- apply solely to the contents of the part following the private keyword. -- |
| -- -- |
| -- GNAT is free software; you can redistribute it and/or modify it under -- |
| -- terms of the GNU General Public License as published by the Free Soft- -- |
| -- ware Foundation; either version 3, or (at your option) any later ver- -- |
| -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- |
| -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- |
| -- or FITNESS FOR A PARTICULAR PURPOSE. -- |
| -- -- |
| -- As a special exception under Section 7 of GPL version 3, you are granted -- |
| -- additional permissions described in the GCC Runtime Library Exception, -- |
| -- version 3.1, as published by the Free Software Foundation. -- |
| -- -- |
| -- You should have received a copy of the GNU General Public License and -- |
| -- a copy of the GCC Runtime Library Exception along with this program; -- |
| -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- |
| -- <http://www.gnu.org/licenses/>. -- |
| -- -- |
| -- GNAT was originally developed by the GNAT team at New York University. -- |
| -- Extensive contributions were provided by Ada Core Technologies Inc. -- |
| -- -- |
| ------------------------------------------------------------------------------ |
| |
| -- Postconditions in this unit are meant for analysis only, not for run-time |
| -- checking, in order not to slow down the execution of these functions. |
| |
| pragma Assertion_Policy (Post => Ignore); |
| |
| with Ada.Characters.Latin_1; |
| |
| package Ada.Characters.Handling |
| with SPARK_Mode |
| is |
| pragma Pure; |
| -- In accordance with Ada 2005 AI-362 |
| |
| ---------------------------------------- |
| -- Character Classification Functions -- |
| ---------------------------------------- |
| |
| -- In the description below for each function that returns a Boolean |
| -- result, the effect is described in terms of the conditions under which |
| -- the value True is returned. If these conditions are not met, then the |
| -- function returns False. |
| -- |
| -- Each of the following classification functions has a formal Character |
| -- parameter, Item, and returns a Boolean result. |
| |
| function Is_Control (Item : Character) return Boolean |
| with |
| Post => Is_Control'Result = |
| (Character'Pos (Item) in 0 .. 31 | 127 .. 159); |
| -- True if Item is a control character. A control character is a character |
| -- whose position is in one of the ranges 0..31 or 127..159. |
| |
| function Is_Graphic (Item : Character) return Boolean |
| with |
| Post => Is_Graphic'Result = |
| (Character'Pos (Item) in 32 .. 126 | 160 .. 255); |
| -- True if Item is a graphic character. A graphic character is a character |
| -- whose position is in one of the ranges 32..126 or 160..255. |
| |
| function Is_Letter (Item : Character) return Boolean |
| with |
| Post => Is_Letter'Result = |
| (Item in 'A' .. 'Z' | 'a' .. 'z' |
| or else Character'Pos (Item) in 192 .. 214 | 216 .. 246 | 248 .. 255); |
| -- True if Item is a letter. A letter is a character that is in one of the |
| -- ranges 'A'..'Z' or 'a'..'z', or whose position is in one of the ranges |
| -- 192..214, 216..246, or 248..255. |
| |
| function Is_Lower (Item : Character) return Boolean |
| with |
| Post => Is_Lower'Result = |
| (Item in 'a' .. 'z' |
| or else Character'Pos (Item) in 223 .. 246 | 248 .. 255); |
| -- True if Item is a lower-case letter. A lower-case letter is a character |
| -- that is in the range 'a'..'z', or whose position is in one of the ranges |
| -- 223..246 or 248..255. |
| |
| function Is_Upper (Item : Character) return Boolean |
| with |
| Post => Is_Upper'Result = |
| (Item in 'A' .. 'Z' |
| or else Character'Pos (Item) in 192 .. 214 | 216 .. 222); |
| -- True if Item is an upper-case letter. An upper-case letter is a |
| -- character that is in the range 'A'..'Z' or whose position is in one |
| -- of the ranges 192..214 or 216..222. |
| |
| function Is_Basic (Item : Character) return Boolean |
| with |
| Post => Is_Basic'Result = |
| (Item in 'A' .. 'Z' |
| | 'a' .. 'z' |
| | Latin_1.UC_AE_Diphthong |
| | Latin_1.LC_AE_Diphthong |
| | Latin_1.UC_Icelandic_Eth |
| | Latin_1.LC_Icelandic_Eth |
| | Latin_1.UC_Icelandic_Thorn |
| | Latin_1.LC_Icelandic_Thorn |
| | Latin_1.LC_German_Sharp_S); |
| -- True if Item is a basic letter. A basic letter is a character that |
| -- is in one of the ranges 'A'..'Z' and 'a'..'z', or that is one of |
| -- the following: UC_AE_Diphthong, LC_AE_Diphthong, UC_Icelandic_Eth, |
| -- LC_Icelandic_Eth, UC_Icelandic_Thorn, LC_Icelandic_Thorn, or |
| -- LC_German_Sharp_S. |
| |
| function Is_Digit (Item : Character) return Boolean |
| with |
| Post => Is_Digit'Result = (Item in '0' .. '9'); |
| -- True if Item is a decimal digit. A decimal digit is a character in the |
| -- range '0'..'9'. |
| |
| function Is_Decimal_Digit (Item : Character) return Boolean |
| renames Is_Digit; |
| |
| function Is_Hexadecimal_Digit (Item : Character) return Boolean |
| with |
| Post => Is_Hexadecimal_Digit'Result = |
| (Is_Decimal_Digit (Item) or Item in 'A' .. 'F' | 'a' .. 'f'); |
| -- True if Item is a hexadecimal digit. A hexadecimal digit is a character |
| -- that is either a decimal digit or that is in one of the ranges 'A'..'F' |
| -- or 'a'..'f'. |
| |
| function Is_Alphanumeric (Item : Character) return Boolean |
| with |
| Post => Is_Alphanumeric'Result = |
| (Is_Letter (Item) or Is_Decimal_Digit (Item)); |
| -- True if Item is an alphanumeric character. An alphanumeric character is |
| -- a character that is either a letter or a decimal digit. |
| |
| function Is_Special (Item : Character) return Boolean |
| with |
| Post => Is_Special'Result = |
| (Is_Graphic (Item) and not Is_Alphanumeric (Item)); |
| -- True if Item is a special graphic character. A special graphic character |
| -- is a graphic character that is not alphanumeric. |
| |
| function Is_Line_Terminator (Item : Character) return Boolean |
| with |
| Post => Is_Line_Terminator'Result = |
| (Character'Pos (Item) in 10 .. 13 | 133); |
| -- True if Item is a character with position 10..13 (Line_Feed, |
| -- Line_Tabulation, Form_Feed, Carriage_Return) or 133 (Next_Line). |
| |
| function Is_Mark (Item : Character) return Boolean |
| with |
| Post => Is_Mark'Result = False; |
| -- Never True (no value of type Character has categories Mark, Non-Spacing |
| -- or Mark, Spacing Combining). |
| |
| function Is_Other_Format (Item : Character) return Boolean |
| with |
| Post => Is_Other_Format'Result = (Character'Pos (Item) = 173); |
| -- True if Item is a character with position 173 (Soft_Hyphen). |
| |
| function Is_Punctuation_Connector (Item : Character) return Boolean |
| with |
| Post => Is_Punctuation_Connector'Result = |
| (Character'Pos (Item) = 95); |
| -- True if Item is a character with position 95 ('_', known as Low_Line or |
| -- Underscore). |
| |
| function Is_Space (Item : Character) return Boolean |
| with |
| Post => Is_Space'Result = (Character'Pos (Item) in 32 | 160); |
| -- True if Item is a character with position 32 (' ') or 160 |
| -- (No_Break_Space). |
| |
| function Is_NFKC (Item : Character) return Boolean |
| with |
| Post => Is_NFKC'Result = |
| (Character'Pos (Item) not in |
| 160 | 168 | 170 | 175 | 178 | 179 | 180 |
| | 181 | 184 | 185 | 186 | 188 | 189 | 190); |
| -- True if Item could be present in a string normalized to Normalization |
| -- Form KC (as defined by Clause 21 of ISO/IEC 10646:2017); this includes |
| -- all characters except those with positions 160, 168, 170, 175, 178, 179, |
| -- 180, 181, 184, 185, 186, 188, 189, and 190. |
| |
| --------------------------------------------------- |
| -- Conversion Functions for Character and String -- |
| --------------------------------------------------- |
| |
| -- Each of the names To_Lower, To_Upper, and To_Basic refers to two |
| -- functions: one that converts from Character to Character, and |
| -- the other that converts from String to String. The result of each |
| -- Character-to-Character function is described below, in terms of |
| -- the conversion applied to Item, its formal Character parameter. The |
| -- result of each String-to-String conversion is obtained by applying |
| -- to each element of the function's String parameter the corresponding |
| -- Character-to-Character conversion; the result is the null String if the |
| -- value of the formal parameter is the null String. The lower bound of the |
| -- result String is 1. |
| |
| function To_Lower (Item : Character) return Character |
| with |
| Post => To_Lower'Result = |
| (if Is_Upper (Item) then |
| Character'Val (Character'Pos (Item) + |
| (if Item in 'A' .. 'Z' then |
| Character'Pos ('a') - Character'Pos ('A') |
| else |
| Character'Pos (Latin_1.LC_A_Grave) |
| - Character'Pos (Latin_1.UC_A_Grave))) |
| else |
| Item); |
| -- Returns the corresponding lower-case value for Item if Is_Upper(Item), |
| -- and returns Item otherwise. |
| |
| function To_Upper (Item : Character) return Character |
| with |
| Post => To_Upper'Result = |
| (if Is_Lower (Item) |
| and then Item not in Latin_1.LC_German_Sharp_S |
| | Latin_1.LC_Y_Diaeresis |
| then |
| Character'Val (Character'Pos (Item) + |
| (if Item in 'A' .. 'Z' then |
| Character'Pos ('A') - Character'Pos ('a') |
| else |
| Character'Pos (Latin_1.UC_A_Grave) |
| - Character'Pos (Latin_1.LC_A_Grave))) |
| else |
| Item); |
| -- Returns the corresponding upper-case value for Item if Is_Lower(Item) |
| -- and Item has an upper-case form, and returns Item otherwise. The lower |
| -- case letters LC_German_Sharp_S and LC_Y_Diaeresis do not have upper case |
| -- forms. |
| |
| function To_Basic (Item : Character) return Character |
| with |
| Post => To_Basic'Result = |
| (if not Is_Letter (Item) or else Is_Basic (Item) then |
| Item |
| else |
| (case Item is |
| when Latin_1.UC_A_Grave .. Latin_1.UC_A_Ring => 'A', |
| when Latin_1.UC_C_Cedilla => 'C', |
| when Latin_1.UC_E_Grave .. Latin_1.UC_E_Diaeresis => 'E', |
| when Latin_1.UC_I_Grave .. Latin_1.UC_I_Diaeresis => 'I', |
| when Latin_1.UC_N_Tilde => 'N', |
| when Latin_1.UC_O_Grave .. Latin_1.UC_O_Diaeresis => 'O', |
| when Latin_1.UC_O_Oblique_Stroke => 'O', |
| when Latin_1.UC_U_Grave .. Latin_1.UC_U_Diaeresis => 'U', |
| when Latin_1.UC_Y_Acute => 'Y', |
| when Latin_1.LC_A_Grave .. Latin_1.LC_A_Ring => 'a', |
| when Latin_1.LC_C_Cedilla => 'c', |
| when Latin_1.LC_E_Grave .. Latin_1.LC_E_Diaeresis => 'e', |
| when Latin_1.LC_I_Grave .. Latin_1.LC_I_Diaeresis => 'i', |
| when Latin_1.LC_N_Tilde => 'n', |
| when Latin_1.LC_O_Grave .. Latin_1.LC_O_Diaeresis => 'o', |
| when Latin_1.LC_O_Oblique_Stroke => 'o', |
| when Latin_1.LC_U_Grave .. Latin_1.LC_U_Diaeresis => 'u', |
| when Latin_1.LC_Y_Acute => 'y', |
| when Latin_1.LC_Y_Diaeresis => 'y', |
| when others => raise Program_Error)); |
| -- Returns the letter corresponding to Item but with no diacritical mark, |
| -- if Item is a letter but not a basic letter; returns Item otherwise. |
| |
| function To_Lower (Item : String) return String |
| with |
| Post => To_Lower'Result'First = 1 |
| and then To_Lower'Result'Length = Item'Length |
| and then |
| (for all J in To_Lower'Result'Range => |
| To_Lower'Result (J) = To_Lower (Item (Item'First + (J - 1)))); |
| |
| function To_Upper (Item : String) return String |
| with |
| Post => To_Upper'Result'First = 1 |
| and then To_Upper'Result'Length = Item'Length |
| and then |
| (for all J in To_Upper'Result'Range => |
| To_Upper'Result (J) = To_Upper (Item (Item'First + (J - 1)))); |
| |
| function To_Basic (Item : String) return String |
| with |
| Post => To_Basic'Result'First = 1 |
| and then To_Basic'Result'Length = Item'Length |
| and then |
| (for all J in To_Basic'Result'Range => |
| To_Basic'Result (J) = To_Basic (Item (Item'First + (J - 1)))); |
| |
| ---------------------------------------------------------------------- |
| -- Classifications of and Conversions Between Character and ISO 646 -- |
| ---------------------------------------------------------------------- |
| |
| -- The following set of functions test for membership in the ISO 646 |
| -- character range, or convert between ISO 646 and Character. |
| |
| subtype ISO_646 is |
| Character range Character'Val (0) .. Character'Val (127); |
| |
| function Is_ISO_646 (Item : Character) return Boolean |
| with |
| Post => Is_ISO_646'Result = (Item in ISO_646); |
| -- The function whose formal parameter, Item, is of type Character returns |
| -- True if Item is in the subtype ISO_646. |
| |
| function Is_ISO_646 (Item : String) return Boolean |
| with |
| Post => Is_ISO_646'Result = |
| (for all J in Item'Range => Is_ISO_646 (Item (J))); |
| -- The function whose formal parameter, Item, is of type String returns |
| -- True if Is_ISO_646(Item(I)) is True for each I in Item'Range. |
| |
| function To_ISO_646 |
| (Item : Character; |
| Substitute : ISO_646 := ' ') return ISO_646 |
| with |
| Post => To_ISO_646'Result = |
| (if Is_ISO_646 (Item) then Item else Substitute); |
| -- The function whose first formal parameter, Item, is of type Character |
| -- returns Item if Is_ISO_646(Item), and returns the Substitute ISO_646 |
| -- character otherwise. |
| |
| function To_ISO_646 |
| (Item : String; |
| Substitute : ISO_646 := ' ') return String |
| with |
| Post => To_ISO_646'Result'First = 1 |
| and then To_ISO_646'Result'Length = Item'Length |
| and then |
| (for all J in To_ISO_646'Result'Range => |
| To_ISO_646'Result (J) = |
| To_ISO_646 (Item (Item'First + (J - 1)), Substitute)); |
| -- The function whose first formal parameter, Item, is of type String |
| -- returns the String whose Range is 1..Item'Length and each of whose |
| -- elements is given by To_ISO_646 of the corresponding element in Item. |
| |
| ------------------------------------------------------ |
| -- Classifications of Wide_Character and Characters -- |
| ------------------------------------------------------ |
| |
| -- Ada 2005 AI 395: these functions are moved to Ada.Characters.Conversions |
| -- and are considered obsolete in Ada.Characters.Handling. However we do |
| -- not complain about this obsolescence, since in practice it is necessary |
| -- to use these routines when creating code that is intended to run in |
| -- either Ada 95 or Ada 2005 mode. |
| |
| -- We do however have to flag these if the pragma No_Obsolescent_Features |
| -- restriction is active (see Restrict.Check_Obsolescent_2005_Entity). |
| |
| function Is_Character (Item : Wide_Character) return Boolean |
| with |
| Post => Is_Character'Result = |
| (Wide_Character'Pos (Item) <= Character'Pos (Character'Last)); |
| -- Returns True if Wide_Character'Pos(Item) <= |
| -- Character'Pos(Character'Last). |
| |
| function Is_String (Item : Wide_String) return Boolean |
| with |
| Post => Is_String'Result = |
| (for all I in Item'Range => Is_Character (Item (I))); |
| -- Returns True if Is_Character(Item(I)) is True for each I in Item'Range. |
| |
| ------------------------------------------------------ |
| -- Conversions between Wide_Character and Character -- |
| ------------------------------------------------------ |
| |
| -- Ada 2005 AI 395: these functions are moved to Ada.Characters.Conversions |
| -- and are considered obsolete in Ada.Characters.Handling. However we do |
| -- not complain about this obsolescence, since in practice it is necessary |
| -- to use these routines when creating code that is intended to run in |
| -- either Ada 95 or Ada 2005 mode. |
| |
| -- We do however have to flag these if the pragma No_Obsolescent_Features |
| -- restriction is active (see Restrict.Check_Obsolescent_2005_Entity). |
| |
| function To_Character |
| (Item : Wide_Character; |
| Substitute : Character := ' ') return Character |
| with |
| Post => To_Character'Result = |
| (if Is_Character (Item) then |
| Character'Val (Wide_Character'Pos (Item)) |
| else |
| Substitute); |
| -- Returns the Character corresponding to Item if Is_Character(Item), and |
| -- returns the Substitute Character otherwise. |
| |
| function To_String |
| (Item : Wide_String; |
| Substitute : Character := ' ') return String |
| with |
| Post => To_String'Result'First = 1 |
| and then To_String'Result'Length = Item'Length |
| and then |
| (for all J in To_String'Result'Range => |
| To_String'Result (J) = |
| To_Character (Item (Item'First + (J - 1)), Substitute)); |
| -- Returns the String whose range is 1..Item'Length and each of whose |
| -- elements is given by To_Character of the corresponding element in Item. |
| |
| function To_Wide_Character |
| (Item : Character) return Wide_Character |
| with |
| Post => To_Wide_Character'Result = |
| Wide_Character'Val (Character'Pos (Item)); |
| -- Returns the Wide_Character X such that Character'Pos(Item) = |
| -- Wide_Character'Pos (X). |
| |
| function To_Wide_String |
| (Item : String) return Wide_String |
| with |
| Post => To_Wide_String'Result'First = 1 |
| and then To_Wide_String'Result'Length = Item'Length |
| and then |
| (for all J in To_Wide_String'Result'Range => |
| To_Wide_String'Result (J) = |
| To_Wide_Character (Item (Item'First + (J - 1)))); |
| -- Returns the Wide_String whose range is 1..Item'Length and each of whose |
| -- elements is given by To_Wide_Character of the corresponding element in |
| -- Item. |
| |
| private |
| pragma Inline (Is_Alphanumeric); |
| pragma Inline (Is_Basic); |
| pragma Inline (Is_Character); |
| pragma Inline (Is_Control); |
| pragma Inline (Is_Digit); |
| pragma Inline (Is_Graphic); |
| pragma Inline (Is_Hexadecimal_Digit); |
| pragma Inline (Is_ISO_646); |
| pragma Inline (Is_Letter); |
| pragma Inline (Is_Line_Terminator); |
| pragma Inline (Is_Lower); |
| pragma Inline (Is_Mark); |
| pragma Inline (Is_Other_Format); |
| pragma Inline (Is_Punctuation_Connector); |
| pragma Inline (Is_Space); |
| pragma Inline (Is_Special); |
| pragma Inline (Is_Upper); |
| pragma Inline (To_Basic); |
| pragma Inline (To_Character); |
| pragma Inline (To_Lower); |
| pragma Inline (To_Upper); |
| pragma Inline (To_Wide_Character); |
| |
| end Ada.Characters.Handling; |
