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