4.2.2. GNATCOLL.Buffer

package GNATCOLL.Buffer is

   package UTF8 renames Ada.Strings.UTF_Encoding;
   package FS renames GNATCOLL.OS.FS;
   package Mmap renames GNATCOLL.Mmap;

   use all type FS.File_Descriptor;

   type Reader is tagged limited private;
   --  Object used to read character-by-character a file, stream or string

   function Open (FD : FS.File_Descriptor) return Reader;
   --  Open a Reader base on a file descriptor.

   function Open (Path : UTF8.UTF_8_String) return Reader;
   --  Open a Reader on the content of file located at Path.

   function Open_String (Str : UTF8.UTF_8_String) return Reader;
   --  Create Reader object based on UTF-8 string

   function Next (Self : in out Reader'Class; C : out Character) return Boolean
      with Inline_Always => True;
   --  Increment buffer position and get the next character. If no character
   --  is available return False. Otherwise return True and set C to the next
   --  character value.

   function Current_Char (Self : Reader'Class) return Character
      with Inline_Always => True;
   --  Get the current character in the buffer. Call to that function is only
   --  valid if Is_End_Of_Data returns False.

   function Is_End_Of_Data (Self : Reader'Class) return Boolean
      with Inline_Always => True;
   --  Return True if the end of the buffer has been reached.

   function Check (Self : in out Reader'Class; Str : String) return Boolean
      with Inline_Always => True;
   --  Check whether the next characters in the buffer are equal to Str. If
   --  Str is found Check return True and buffer position updated to the
   --  latest character of Str. If False is returned then buffer position is
   --  not updated.

   function Token
      (Self : Reader'Class; First, Last : Long_Long_Integer) return String
      with Inline_Always => True;
   --  Return slice of the buffer between First and Last.

   function Current_Position (Self : Reader'Class) return Long_Long_Integer
      with Inline_Always => True;
   --  Return absolute position in the stream

   procedure Current_Text_Position
      (Self   : Reader'Class;
       Line   : out Integer;
       Column : out Integer);
   --  Get Current text position. For large file (>2GB) or for file opened from
   --  a file descriptor, line is not tracked. Instead the function set Line
   --  and Column to 0.

   procedure Current_Text_Position
      (Self   : Reader'Class;
       Offset : Integer;
       Line   : out Integer;
       Column : out Integer);
   --  Get text position at a given offset

   procedure Release (Self : in out Reader'Class)
      with Inline_Always => True;
   --  Release buffer before the current position. Effect is not immediate.

   function Window_Offset (Self : Reader'Class) return Integer
      with Inline_Always => True;
   --  Get the current offset in the internal buffer

   procedure Set_Window_Offset (Self : in out Reader'Class; Offset : Integer)
      with Inline_Always => True;
   --  Set the curent offset in the internal buffer

   function Next
      (Self   : in out Reader'Class;
       C      : out Character;
       Offset : in out Integer)
      return Boolean with Inline_Always => True;
   --  Same as previous Next function except that Offset is updated instead of
   --  the internal position. This version of Next can be used to speed the
   --  iteration on the stream by using a local variable for the offset.

   procedure Finalize (Self : in out Reader);
   --  Finalize Reader object

end GNATCOLL.Buffer;