with System;

Package C_String_Pkg is
-- ****************************************************************************
-- Package C_String_Pkg provides routines for working with strings between the
-- C language format and the Ada character and string types.
-- ****************************************************************************

  -- /// The pointer to the C string
  -- /// (Analogous to an "unsigned char *" or "char *" type)
  type C_String is access character;

  -- /// The pointer to the corresponding Ada string
  type Ada_String is access string;


function C_String_Length(
  C_Str              : in C_String;
  Include_Terminator : in boolean := FALSE) return natural;
-- ****************************************************************************
-- This function returns the length of the C string
-- ****************************************************************************

function C_to_Ada_String(
  C_Str              : in C_String;
  Include_Terminator : in boolean := FALSE) return Ada_String;
-- ****************************************************************************
-- This function will make a copy of the C_String by dynamically allocating
-- just enough memory to hold the string in Ada_String.
-- If the C_Str has a length of zero (as returned from C_String_Length), this
-- returns NULL.
-- ****************************************************************************

procedure C_to_Ada_String(
  C_Str        : in     C_String;
  The_String   :    out string;
  Include_Term : in     boolean := FALSE);
-- ****************************************************************************
-- This procedure copies a C-style string to an Ada-style string, including the
-- null terminator, if desired. If the C_Str is longer than The_String, the
-- C_Str is 'truncated' to fit.  This routine requires that any variable NOT
-- declared as a simple string (i.e. NOT: SomeVar : string(1..x);) MUST be
-- tyecast to a string in the parameter list when called.
-- ****************************************************************************

function Get_Char(
  C_Str    : in C_String;
  Position : in natural) return character;
-- ****************************************************************************
-- This function allows one to fetch the character from the C string at the
-- given position in the string. If the position is past the end of the
-- string, the resulting character returned is Ascii.NUL.
-- ****************************************************************************

function Fetch_Char is new System.Fetch_From_Address(TARGET => character);
-- ****************************************************************************
-- This function allows one to fetch the character from the given address.
--
-- Usage:  The_Char := Fetch_Char(Variable'ADDRESS + [OFFSET(Count)]);
-- ****************************************************************************

end C_String_Pkg;