File : g-encstr.ads
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 -- --
19 -- --
20 -- --
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
55 with System.WCh_Con;
56
57 generic
58 Encoding_Method : System.WCh_Con.WC_Encoding_Method;
59
60 package 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
109 end GNAT.Encode_String;