1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --                Copyright (C) 2001-2003 ACT-Europe                 -- 
  5. --                                                                   -- 
  6. -- This library is free software; you can redistribute it and/or     -- 
  7. -- modify it under the terms of the GNU General Public               -- 
  8. -- License as published by the Free Software Foundation; either      -- 
  9. -- version 2 of the License, or (at your option) any later version.  -- 
  10. --                                                                   -- 
  11. -- This library is distributed in the hope that it will be useful,   -- 
  12. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  13. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  14. -- General Public License for more details.                          -- 
  15. --                                                                   -- 
  16. -- You should have received a copy of the GNU General Public         -- 
  17. -- License along with this library; if not, write to the             -- 
  18. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  19. -- Boston, MA 02111-1307, USA.                                       -- 
  20. --                                                                   -- 
  21. -- As a special exception, if other files instantiate generics from  -- 
  22. -- this unit, or you link this unit with other files to produce an   -- 
  23. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  24. -- executable to be covered by the GNU General Public License. This  -- 
  25. -- exception does not however invalidate any other reasons why the   -- 
  26. -- executable file  might be covered by the  GNU Public License.     -- 
  27. ----------------------------------------------------------------------- 
  28.  
  29. --  <description> 
  30. -- 
  31. --  This package provides definitions for string conversions and i18n. 
  32. --  See also Glib.Unicode. 
  33. -- 
  34. --  </description> 
  35. --  <c_version>1.3.11</c_version> 
  36. --  <group>Glib, the general-purpose library</group> 
  37.  
  38. with Glib.Error; use Glib.Error; 
  39. with Interfaces.C.Strings; use Interfaces.C.Strings; 
  40.  
  41. package Glib.Convert is 
  42.    pragma Preelaborate; 
  43.  
  44.    --  Convert_Error domain for GErrors: 
  45.  
  46.    No_Conversion     : constant := 0; 
  47.    Illegal_Sequence  : constant := 1; 
  48.    Failed            : constant := 2; 
  49.    Partial_Input     : constant := 3; 
  50.    Bad_URI           : constant := 4; 
  51.    Not_Absolute_Path : constant := 5; 
  52.  
  53.    function Convert_Error_Domain return GQuark; 
  54.    --  Return the error domain associated with Glib.Convert. 
  55.  
  56.    procedure Convert 
  57.      (Str           : String; 
  58.       To_Codeset    : String; 
  59.       From_Codeset  : String; 
  60.       Bytes_Read    : out Natural; 
  61.       Bytes_Written : out Natural; 
  62.       Error         : GError_Access := null; 
  63.       Result        : out String); 
  64.    --  Convert a string from one character set to another. 
  65.    -- 
  66.    --  Str:           String to convert 
  67.    --  Result:        String converted, if no error. 
  68.    --  To_Codeset:    Name of character set into which to convert Str 
  69.    --  From_Codeset:  Character set of Str. 
  70.    --  Bytes_Read:    Number of bytes in the input string that were 
  71.    --                 successfully converted. 
  72.    --                 Even if the conversion was successful, this may be 
  73.    --                 less than Len if there were partial characters 
  74.    --                 at the end of the input. If the error 
  75.    --                 Illegal_Sequence occurs, the value 
  76.    --                 stored will the byte offset after the last valid 
  77.    --                 input sequence. 
  78.    --  Bytes_Written: Number of bytes stored in the output buffer. 
  79.    --  Error:         Location to store the error occuring, ignored if null. 
  80.    --                 Any of the errors in Convert_Error_Domain may occur. 
  81.  
  82.    function Convert 
  83.      (Str           : String; 
  84.       To_Codeset    : String; 
  85.       From_Codeset  : String; 
  86.       Error         : GError_Access := null) return String; 
  87.    --  Same as above, but return a String directly. 
  88.  
  89.    procedure Convert 
  90.      (Str           : chars_ptr; 
  91.       Len           : Natural; 
  92.       To_Codeset    : String; 
  93.       From_Codeset  : String; 
  94.       Bytes_Read    : out Natural; 
  95.       Bytes_Written : out Natural; 
  96.       Error         : GError_Access := null; 
  97.       Result        : out String); 
  98.    --  Same as Convert procedure, but take a C string as input. 
  99.  
  100.    function Convert 
  101.      (Str           : String; 
  102.       To_Codeset    : String; 
  103.       From_Codeset  : String; 
  104.       Bytes_Read    : access Natural; 
  105.       Bytes_Written : access Natural; 
  106.       Error         : GError_Access := null) return chars_ptr; 
  107.    --  Same as Convert procedure, but return the result as a C string. 
  108.  
  109.    function Convert 
  110.      (Str           : chars_ptr; 
  111.       Len           : Natural; 
  112.       To_Codeset    : String; 
  113.       From_Codeset  : String; 
  114.       Bytes_Read    : access Natural; 
  115.       Bytes_Written : access Natural; 
  116.       Error         : GError_Access := null) return chars_ptr; 
  117.    --  Same as Convert procedure, but take and return the result as a C string. 
  118.  
  119.    procedure Locale_To_UTF8 
  120.      (OS_String     : String; 
  121.       Bytes_Read    : out Natural; 
  122.       Bytes_Written : out Natural; 
  123.       Error         : GError_Access := null; 
  124.       Result        : out String); 
  125.    --  Convert a string which is in the encoding used for strings by 
  126.    --  the C runtime (usually the same as that used by the operating 
  127.    --  system) in the current locale into a UTF-8 string. 
  128.    -- 
  129.    --  OS_String:     A string in the encoding of the current locale 
  130.    --  Bytes_Read:    Number of bytes in the input string that were 
  131.    --                 successfully converted. 
  132.    --                 Even if the conversion was successful, this may be 
  133.    --                 less than Len if there were partial characters 
  134.    --                 at the end of the input. If the error 
  135.    --                 Illegal_Sequence occurs, the value 
  136.    --                 stored will the byte offset after the last valid 
  137.    --                 input sequence. 
  138.    --  Bytes_Written: Number of bytes stored in Result. 
  139.    --  Error:         Location to store the error occuring, ignored if null. 
  140.    --                 Any of the errors in Convert_Error_Domain may occur. 
  141.  
  142.    function Locale_To_UTF8 
  143.      (OS_String     : String; 
  144.       Bytes_Read    : access Natural; 
  145.       Bytes_Written : access Natural; 
  146.       Error         : GError_Access := null) return chars_ptr; 
  147.    --  Same as procedure Locale_To_UTF8, but return the raw C string for 
  148.    --  efficiency. The caller is responsible for freeing the resulting string. 
  149.  
  150.    function Locale_To_UTF8 (OS_String : String) return String; 
  151.    --  Same as procedure Locale_To_UTF8, but return only the String. 
  152.  
  153.    procedure Locale_From_UTF8 
  154.      (UTF8_String   : String; 
  155.       Bytes_Read    : out Natural; 
  156.       Bytes_Written : out Natural; 
  157.       Error         : GError_Access := null; 
  158.       Result        : out String); 
  159.    --  Convert a string from UTF-8 to the encoding used for strings by 
  160.    --  the C runtime (usually the same as that used by the operating 
  161.    --  system) in the current locale. 
  162.    -- 
  163.    --  UTF8_String:   A UTF-8 encoded string 
  164.    --  Bytes_Read:    Number of bytes in the input string that were 
  165.    --                 successfully converted. 
  166.    --                 Even if the conversion was successful, this may be 
  167.    --                 less than Len if there were partial characters 
  168.    --                 at the end of the input. If the error 
  169.    --                 Illegal_Sequence occurs, the value 
  170.    --                 stored will the byte offset after the last valid 
  171.    --                 input sequence. 
  172.    --  Bytes_Written: Number of bytes stored in the output buffer. 
  173.    --  Error:         Location to store the error occuring, ignored if null. 
  174.    --                 Any of the errors in Convert_Error_Domain may occur. 
  175.  
  176.    function Locale_From_UTF8 
  177.      (UTF8_String   : String; 
  178.       Bytes_Read    : access Natural; 
  179.       Bytes_Written : access Natural; 
  180.       Error         : GError_Access := null) return chars_ptr; 
  181.    --  Same as procedure Locale_From_UTF8, but return the raw C string for 
  182.    --  efficiency. The caller is responsible for freeing the resulting string. 
  183.    --  Use the C "free" function to free this. 
  184.  
  185.    function Locale_From_UTF8 (UTF8_String : String) return String; 
  186.    --  Same as procedure Locale_From_UTF8, but return only the String. 
  187.  
  188.    function Filename_To_UTF8 
  189.      (OS_String : String; 
  190.       Error     : GError_Access := null) return String; 
  191.    --  Convert a string which is in the encoding used for filenames 
  192.    --  into a UTF-8 string. 
  193.  
  194.    function Filename_From_UTF8 
  195.      (UTF8_String : String; 
  196.       Error       : GError_Access := null) return String; 
  197.    --  Convert a string from UTF-8 to the encoding used for filenames. 
  198.  
  199.    function Filename_From_URI 
  200.      (URI      : String; 
  201.       Hostname : access chars_ptr; 
  202.       Error    : GError_Access := null) return String; 
  203.    --  Convert an escaped UTF-8 encoded URI to a local filename in the 
  204.    --  encoding used for filenames. 
  205.    -- 
  206.    --  URI:      A uri describing a filename (escaped, encoded in UTF-8). 
  207.    --  Hostname: Location to store hostname for the URI. 
  208.    --            If there is no hostname in the URI, null will be 
  209.    --            stored in this location. 
  210.    --  Error:    Location to store the error occuring, ignored if null. 
  211.    --            Any of the errors in Convert_Error_Domain may occur. 
  212.  
  213.    function Filename_To_URI 
  214.      (Filename : String; 
  215.       Hostname : String := ""; 
  216.       Error    : GError_Access := null) return String; 
  217.    --  Convert an absolute filename to an escaped UTF-8 encoded URI. 
  218.    -- 
  219.    --  Filename: An absolute filename specified in the encoding 
  220.    --            used for filenames by the operating system. 
  221.    --  Hostname: A UTF-8 encoded hostname, or "" for none. 
  222.    --  Error:    Location to store the error occuring, ignored if null. 
  223.    --            Any of the errors in Convert_Error may occur. 
  224.  
  225.    function Escape_Text (S : String) return String; 
  226.    --  Escape the text so that it is interpreted as-is by the Pango markup 
  227.    --  language 
  228.  
  229. private 
  230.  
  231.    pragma Import (C, Convert_Error_Domain, "g_convert_error_quark"); 
  232.  
  233. end Glib.Convert;