[thirdparty/gcc.git] / gcc / ada / stringt.ads

------------------------------------------------------------------------------
--                                                                          --
--                         GNAT COMPILER COMPONENTS                         --
--                                                                          --
--                              S T R I N G T                               --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--          Copyright (C) 1992-2009, Free Software Foundation, Inc.         --
--                                                                          --
-- 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.      --
--                                                                          --
------------------------------------------------------------------------------

with System; use System;
with Types;  use Types;

package Stringt is

--  This package contains routines for handling the strings table which is
--  used to store string constants encountered in the source, and also those
--  additional string constants generated by compile time concatenation and
--  other similar processing.

--  A string constant in this table consists of a series of Char_Code values,
--  so that 16-bit character codes can be properly handled if this feature
--  is implemented in the scanner.

--  There is no guarantee that hashing is used in the implementation, although
--  it maybe. This means that the caller cannot count on having the same Id
--  value for two identical strings stored separately and also cannot count on
--  the two Id values being different.

   --------------------------------------
   -- String Table Access Subprograms --
   --------------------------------------

   procedure Initialize;
   --  Initializes the strings table for a new compilation. Note that
   --  Initialize must not be called if Tree_Read is used.

   procedure Lock;
   --  Lock internal tables before calling back end

   procedure Unlock;
   --  Unlock internal tables, in case back end needs to modify them

   procedure Start_String;
   --  Sets up for storing a new string in the table. To store a string, a
   --  call is first made to Start_String, then successive calls are
   --  made to Store_String_Character to store the characters of the string.
   --  Finally, a call to End_String terminates the entry and returns it Id.

   procedure Start_String (S : String_Id);
   --  Like Start_String with no parameter, except that the contents of the
   --  new string is initialized to be a copy of the given string. A test is
   --  made to see if S is the last created string, and if so it is shared,
   --  rather than copied, this can be particularly helpful for the case of
   --  a continued concatenation of string constants.

   procedure Store_String_Char (C : Char_Code);
   procedure Store_String_Char (C : Character);
   --  Store next character of string, see description above for Start_String

   procedure Store_String_Chars (S : String);
   procedure Store_String_Chars (S : String_Id);
   --  Store character codes of given string in sequence

   procedure Store_String_Int (N : Int);
   --  Stored decimal representation of integer with possible leading minus

   procedure Unstore_String_Char;
   --  Undoes effect of previous Store_String_Char call, used in some error
   --  situations of unterminated string constants.

   function End_String return String_Id;
   --  Terminates current string and returns its Id

   function String_Length (Id : String_Id) return Nat;
   --  Returns length of previously stored string

   function Get_String_Char (Id : String_Id; Index : Int) return Char_Code;
   pragma Inline (Get_String_Char);
   --  Obtains the specified character from a stored string. The lower bound
   --  of stored strings is always 1, so the range is 1 .. String_Length (Id).

   function String_Equal (L, R : String_Id) return Boolean;
   --  Determines if two string literals represent the same string

   procedure String_To_Name_Buffer (S : String_Id);
   --  Place characters of given string in Name_Buffer, setting Name_Len.
   --  Error if any characters are out of Character range. Does not attempt
   --  to do any encoding of any characters.

   procedure Add_String_To_Name_Buffer (S : String_Id);
   --  Append characters of given string to Name_Buffer, updating Name_Len.
   --  Error if any characters are out of Character range. Does not attempt
   --  to do any encoding of any characters.

   function String_Chars_Address return System.Address;
   --  Return address of String_Chars table (used by Back_End call to Gigi)

   function String_From_Name_Buffer return String_Id;
   --  Given a name stored in Namet.Name_Buffer (length in Namet.Name_Len),
   --  returns a string of the corresponding value. The value in Name_Buffer
   --  is unchanged, and the cases of letters are unchanged.

   function Strings_Address return System.Address;
   --  Return address of Strings table (used by Back_End call to Gigi)

   procedure Tree_Read;
   --  Initializes internal tables from current tree file using the relevant
   --  Table.Tree_Read routines. Note that Initialize should not be called if
   --  Tree_Read is used. Tree_Read includes all necessary initialization.

   procedure Tree_Write;
   --  Writes out internal tables to current tree file using the relevant
   --  Table.Tree_Write routines.

   procedure Write_Char_Code (Code : Char_Code);
   --  Procedure to write a character code value, used for debugging purposes
   --  for writing character codes. If the character code is in the range
   --  16#20# .. 16#7E#, then the single graphic character corresponding to
   --  the code is output. For any other codes in the range 16#00# .. 16#FF#,
   --  the code is output as ["hh"] where hh is the two digit hex value for
   --  the code. Codes greater than 16#FF# are output as ["hhhh"] where hhhh
   --  is the four digit hex representation of the code value (high order
   --  byte first). Hex letters are always in lower case.

   procedure Write_String_Table_Entry (Id : String_Id);
   --  Writes a string value with enclosing quotes to the current file using
   --  routines in package Output. Does not write an end of line character.
   --  This procedure is used for debug output purposes, and also for output
   --  of strings specified by pragma Linker Option to the ali file. 7-bit
   --  ASCII graphics (except for double quote) are output literally.
   --  The double quote appears as two successive double quotes.
   --  All other codes, are output as described for Write_Char_Code. For
   --  example, the string created by folding "A" & ASCII.HT & "Hello" will
   --  print as "A["09"]Hello". A No_String value prints simply as "no string"
   --  without surrounding quote marks.

private
   pragma Inline (End_String);
   pragma Inline (String_Length);

end Stringt;
Commit	Line	Data
996ae0b0 RK	1	------------------------------------------------------------------------------
	2	-- --
	3	-- GNAT COMPILER COMPONENTS --
	4	-- --
	5	-- S T R I N G T --
	6	-- --
	7	-- S p e c --
	8	-- --
748086b7	9	-- Copyright (C) 1992-2009, Free Software Foundation, Inc. --
996ae0b0 RK	10	-- --
	11	-- GNAT is free software; you can redistribute it and/or modify it under --
	12	-- terms of the GNU General Public License as published by the Free Soft- --
748086b7	13	-- ware Foundation; either version 3, or (at your option) any later ver- --
996ae0b0 RK	14	-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
996ae0b0 RK	15	-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
748086b7 JJ	16	-- or FITNESS FOR A PARTICULAR PURPOSE. --
	17	-- --
	18	-- As a special exception under Section 7 of GPL version 3, you are granted --
	19	-- additional permissions described in the GCC Runtime Library Exception, --
	20	-- version 3.1, as published by the Free Software Foundation. --
	21	-- --
	22	-- You should have received a copy of the GNU General Public License and --
	23	-- a copy of the GCC Runtime Library Exception along with this program; --
	24	-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
	25	-- <http://www.gnu.org/licenses/>. --
996ae0b0 RK	26	-- --
996ae0b0 RK	27	-- GNAT was originally developed by the GNAT team at New York University. --
71ff80dc	28	-- Extensive contributions were provided by Ada Core Technologies Inc. --
996ae0b0 RK	29	-- --
	30	------------------------------------------------------------------------------
	31
	32	with System; use System;
	33	with Types; use Types;
	34
	35	package Stringt is
	36
	37	-- This package contains routines for handling the strings table which is
	38	-- used to store string constants encountered in the source, and also those
	39	-- additional string constants generated by compile time concatenation and
	40	-- other similar processing.
	41
	42	-- A string constant in this table consists of a series of Char_Code values,
	43	-- so that 16-bit character codes can be properly handled if this feature
	44	-- is implemented in the scanner.
	45
	46	-- There is no guarantee that hashing is used in the implementation, although
	47	-- it maybe. This means that the caller cannot count on having the same Id
	48	-- value for two identical strings stored separately and also cannot count on
	49	-- the two Id values being different.
	50
	51	--------------------------------------
	52	-- String Table Access Subprograms --
	53	--------------------------------------
	54
	55	procedure Initialize;
	56	-- Initializes the strings table for a new compilation. Note that
	57	-- Initialize must not be called if Tree_Read is used.
	58
	59	procedure Lock;
	60	-- Lock internal tables before calling back end
	61
	62	procedure Unlock;
	63	-- Unlock internal tables, in case back end needs to modify them
	64
	65	procedure Start_String;
	66	-- Sets up for storing a new string in the table. To store a string, a
	67	-- call is first made to Start_String, then successive calls are
	68	-- made to Store_String_Character to store the characters of the string.
	69	-- Finally, a call to End_String terminates the entry and returns it Id.
	70
	71	procedure Start_String (S : String_Id);
	72	-- Like Start_String with no parameter, except that the contents of the
	73	-- new string is initialized to be a copy of the given string. A test is
	74	-- made to see if S is the last created string, and if so it is shared,
	75	-- rather than copied, this can be particularly helpful for the case of
3354f96d	76	-- a continued concatenation of string constants.
996ae0b0 RK	77
	78	procedure Store_String_Char (C : Char_Code);
	79	procedure Store_String_Char (C : Character);
	80	-- Store next character of string, see description above for Start_String
	81
	82	procedure Store_String_Chars (S : String);
	83	procedure Store_String_Chars (S : String_Id);
	84	-- Store character codes of given string in sequence
	85
	86	procedure Store_String_Int (N : Int);
	87	-- Stored decimal representation of integer with possible leading minus
	88
	89	procedure Unstore_String_Char;
	90	-- Undoes effect of previous Store_String_Char call, used in some error
	91	-- situations of unterminated string constants.
	92
	93	function End_String return String_Id;
	94	-- Terminates current string and returns its Id
	95
	96	function String_Length (Id : String_Id) return Nat;
	97	-- Returns length of previously stored string
	98
	99	function Get_String_Char (Id : String_Id; Index : Int) return Char_Code;
fbf5a39b	100	pragma Inline (Get_String_Char);
996ae0b0 RK	101	-- Obtains the specified character from a stored string. The lower bound
	102	-- of stored strings is always 1, so the range is 1 .. String_Length (Id).
	103
	104	function String_Equal (L, R : String_Id) return Boolean;
	105	-- Determines if two string literals represent the same string
	106
	107	procedure String_To_Name_Buffer (S : String_Id);
07fc65c4 GB	108	-- Place characters of given string in Name_Buffer, setting Name_Len.
	109	-- Error if any characters are out of Character range. Does not attempt
	110	-- to do any encoding of any characters.
996ae0b0 RK	111
996ae0b0 RK	112	procedure Add_String_To_Name_Buffer (S : String_Id);
07fc65c4 GB	113	-- Append characters of given string to Name_Buffer, updating Name_Len.
	114	-- Error if any characters are out of Character range. Does not attempt
	115	-- to do any encoding of any characters.
996ae0b0 RK	116
	117	function String_Chars_Address return System.Address;
	118	-- Return address of String_Chars table (used by Back_End call to Gigi)
	119
	120	function String_From_Name_Buffer return String_Id;
	121	-- Given a name stored in Namet.Name_Buffer (length in Namet.Name_Len),
	122	-- returns a string of the corresponding value. The value in Name_Buffer
	123	-- is unchanged, and the cases of letters are unchanged.
	124
	125	function Strings_Address return System.Address;
	126	-- Return address of Strings table (used by Back_End call to Gigi)
	127
	128	procedure Tree_Read;
87b3f81f AC	129	-- Initializes internal tables from current tree file using the relevant
	130	-- Table.Tree_Read routines. Note that Initialize should not be called if
	131	-- Tree_Read is used. Tree_Read includes all necessary initialization.
996ae0b0 RK	132
996ae0b0 RK	133	procedure Tree_Write;
87b3f81f AC	134	-- Writes out internal tables to current tree file using the relevant
87b3f81f AC	135	-- Table.Tree_Write routines.
996ae0b0 RK	136
	137	procedure Write_Char_Code (Code : Char_Code);
	138	-- Procedure to write a character code value, used for debugging purposes
	139	-- for writing character codes. If the character code is in the range
	140	-- 16#20# .. 16#7E#, then the single graphic character corresponding to
	141	-- the code is output. For any other codes in the range 16#00# .. 16#FF#,
	142	-- the code is output as ["hh"] where hh is the two digit hex value for
	143	-- the code. Codes greater than 16#FF# are output as ["hhhh"] where hhhh
	144	-- is the four digit hex representation of the code value (high order
07fc65c4	145	-- byte first). Hex letters are always in lower case.
996ae0b0 RK	146
	147	procedure Write_String_Table_Entry (Id : String_Id);
	148	-- Writes a string value with enclosing quotes to the current file using
	149	-- routines in package Output. Does not write an end of line character.
	150	-- This procedure is used for debug output purposes, and also for output
	151	-- of strings specified by pragma Linker Option to the ali file. 7-bit
07fc65c4 GB	152	-- ASCII graphics (except for double quote) are output literally.
07fc65c4 GB	153	-- The double quote appears as two successive double quotes.
996ae0b0	154	-- All other codes, are output as described for Write_Char_Code. For
82c80734 RD	155	-- example, the string created by folding "A" & ASCII.HT & "Hello" will
82c80734 RD	156	-- print as "A["09"]Hello". A No_String value prints simply as "no string"
996ae0b0 RK	157	-- without surrounding quote marks.
	158
	159	private
	160	pragma Inline (End_String);
	161	pragma Inline (String_Length);
	162
	163	end Stringt;