1------------------------------------------------------------------------------ 2-- -- 3-- GNAT RUN-TIME COMPONENTS -- 4-- -- 5-- G N A T . E N C O D E _ S T R I N G -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 2007-2010, AdaCore -- 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- -- 13-- ware Foundation; either version 3, or (at your option) any later ver- -- 14-- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- 15-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- 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/>. -- 26-- -- 27-- GNAT was originally developed by the GNAT team at New York University. -- 28-- Extensive contributions were provided by Ada Core Technologies Inc. -- 29-- -- 30------------------------------------------------------------------------------ 31 32-- This generic package provides utility routines for converting from 33-- Wide_String or Wide_Wide_String to encoded String using a specified 34-- encoding convention, which is supplied as the generic parameter. If 35-- this parameter is a known at compile time constant (e.g. a constant 36-- defined in System.WCh_Con), the instantiation is specialized so that 37-- it applies only to this specified coding. 38 39-- Note: this package is only about encoding sequences of 16- or 32-bit 40-- characters into a sequence of 8-bit codes. It knows nothing at all about 41-- the character encodings being used for the input Wide_Character and 42-- Wide_Wide_Character values, although some of the encoding methods (notably 43-- JIS and EUC) have built in assumptions about the range of possible input 44-- code values. Most often the input will be Unicode/ISO-10646 as specified by 45-- the Ada RM, but this package does not make any assumptions about the 46-- character coding, and in the case of UTF-8 all possible code values can be 47-- encoded. See also the packages Ada.Wide_[Wide_]Characters.Unicode for 48-- unicode specific functions. 49 50-- Note on brackets encoding (WCEM_Brackets). On input, upper half characters 51-- can be represented as ["hh"] but the routines in this package will only use 52-- brackets encodings for codes higher than 16#FF#, so upper half characters 53-- will be output as single Character values. 54 55with System.WCh_Con; 56 57generic 58 Encoding_Method : System.WCh_Con.WC_Encoding_Method; 59 60package GNAT.Encode_String is 61 pragma Pure; 62 63 function Encode_Wide_String (S : Wide_String) return String; 64 pragma Inline (Encode_Wide_String); 65 -- Encode the given Wide_String, returning a String encoded using the 66 -- given encoding method. Constraint_Error will be raised if the encoding 67 -- method cannot accommodate the input data. 68 69 procedure Encode_Wide_String 70 (S : Wide_String; 71 Result : out String; 72 Length : out Natural); 73 -- Encode the given Wide_String, storing the encoded string in Result, 74 -- with Length being set to the length of the encoded string. The caller 75 -- must ensure that Result is long enough (see useful constants defined 76 -- in System.WCh_Con: WC_Longest_Sequence, WC_Longest_Sequences). If the 77 -- length of Result is insufficient Constraint_Error will be raised. 78 -- Constraint_Error will also be raised if the encoding method cannot 79 -- accommodate the input data. 80 81 function Encode_Wide_Wide_String (S : Wide_Wide_String) return String; 82 pragma Inline (Encode_Wide_Wide_String); 83 -- Same as above function but for Wide_Wide_String input 84 85 procedure Encode_Wide_Wide_String 86 (S : Wide_Wide_String; 87 Result : out String; 88 Length : out Natural); 89 -- Same as above procedure, but for Wide_Wide_String input 90 91 procedure Encode_Wide_Character 92 (Char : Wide_Character; 93 Result : in out String; 94 Ptr : in out Natural); 95 pragma Inline (Encode_Wide_Character); 96 -- This is a lower level procedure that encodes the single character Char. 97 -- The output is stored in Result starting at Result (Ptr), and Ptr is 98 -- updated past the stored value. Constraint_Error is raised if Result 99 -- is not long enough to accommodate the result, or if the encoding method 100 -- specified does not accommodate the input character value, or if Ptr is 101 -- outside the bounds of the Result string. 102 103 procedure Encode_Wide_Wide_Character 104 (Char : Wide_Wide_Character; 105 Result : in out String; 106 Ptr : in out Natural); 107 -- Same as above procedure but with Wide_Wide_Character input 108 109end GNAT.Encode_String; 110