____ | Up | Next | Back | Forward
TOC -- / --.-- / --.--.-- | Index | Search | Syntax | Help


B.3.1 The Package Interfaces.C.Strings

(1)
The package Interfaces.C.Strings declares types and subprograms allowing an Ada program to allocate, reference, update, and free C-style strings. In particular, the private type chars_ptr corresponds to a common use of ``char *'' in C programs, and an object of this type can be passed to a subprogram to which pragma Import(C,...) has been applied, and for which ``char *'' is the type of the argument of the C function.
Static Semantics
(2)
The library package Interfaces.C.Strings has the following declaration:
(3)
       package Interfaces.C.Strings is
          pragma Preelaborate(Strings);
(4)
          type char_array_access is access all char_array;
(5)
          type chars_ptr is private;
(6)
          type chars_ptr_array is array (size_t range <>) of chars_ptr;
(7)
          Null_Ptr : constant chars_ptr;
(8)
          function To_Chars_Ptr (Item      : in char_array_access;
                                 Nul_Check : in Boolean := False)
             return chars_ptr;
(9)
          function New_Char_Array (Chars   : in char_array) return chars_ptr;
(10)
          function New_String (Str : in String) return chars_ptr;
(11)
          procedure Free (Item : in out chars_ptr);
(12)
          Dereference_Error : exception;
(13)
          function Value (Item : in chars_ptr) return char_array;
(14)
          function Value (Item : in chars_ptr; Length : in size_t)
             return char_array;
(15)
          function Value (Item : in chars_ptr) return String;
(16)
          function Value (Item : in chars_ptr; Length : in size_t)
             return String;
(17)
          function Strlen (Item : in chars_ptr) return size_t;
(18)
          procedure Update (Item   : in chars_ptr;
                            Offset : in size_t;
                            Chars  : in char_array;
                            Check  : in Boolean := True);
(19)
          procedure Update (Item   : in chars_ptr;
                            Offset : in size_t;
                            Str    : in String;
                            Check  : in Boolean := True);
(20)
          Update_Error : exception;
(21)
       private
          ... -- not specified by the language
       end Interfaces.C.Strings;
(22)
The type chars_ptr is C-compatible and corresponds to the use of C's ``char *'' for a pointer to the first char in a char array terminated by nul. When an object of type chars_ptr is declared, its value is by default set to Null_Ptr, unless the object is imported (see B.1).
(23)
       function To_Chars_Ptr (Item      : in char_array_access;
                              Nul_Check : in Boolean := False)
          return chars_ptr;
(24)
(25)
       function New_Char_Array (Chars   : in char_array) return chars_ptr;
(26)
(27)
(28)

(29)
       function New_String (Str : in String) return chars_ptr;
(30)
(31)
       procedure Free (Item : in out chars_ptr);
(32)
(33)
       function Value (Item : in chars_ptr) return char_array;
(34)
(35)
       function Value (Item : in chars_ptr; Length : in size_t)
          return char_array;
(36)
(37)
       function Value (Item : in chars_ptr) return String;
(38)
(39)
       function Value (Item : in chars_ptr; Length : in size_t)
          return String;
(40)
(41)
       function Strlen (Item : in chars_ptr) return size_t;
(42)
(43)
       procedure Update (Item   : in chars_ptr;
                         Offset : in size_t;
                         Chars  : in char_array;
                         Check  : Boolean := True);
(44)
(45)
(46)
(47)
(48)
(49)
       procedure Update (Item   : in chars_ptr;
                         Offset : in size_t;
                         Str    : in String;
                         Check  : in Boolean := True);
(50)
Erroneous Execution
(51)
Execution of any of the following is erroneous if the Item parameter is not null_ptr and Item does not point to a nul-terminated array of chars.
(52)
(53)
(54)
(55)
Execution of Free(X) is also erroneous if the chars_ptr X was not returned by New_Char_Array or New_String.
(56)
Reading or updating a freed char_array is erroneous.
(57)
Execution of Update is erroneous if Check is False and a call with Check equal to True would have propagated Update_Error.

(58)
(59)
(60)

____ | Up | Next | Back | Forward
TOC -- / --.-- / --.--.-- | Index | Search | Syntax | Help

Ada WWW Home -- Email comments, additions, corrections, gripes, kudos, etc. to:

Magnus Kempe -- Magnus.Kempe@di.epfl.ch
Copyright statement
Page last generated: 95-03-12