4.2.47. GNATCOLL.String_Builders

package GNATCOLL.String_Builders is

   package OS renames GNATCOLL.OS;

   type String_Builder is limited private;
   --  String_Builder is an efficient unbounded structure to create String
   --  object by aggregation. The structure also maintains a null character at
   --  the end of the String allowing export to C without reallocation.
   --  Instances of String_Builder should be finalized by calling Deallocate
   --  procedure.

   procedure Append (Self : in out String_Builder; Str : String);
   --  Append Str to Self

   procedure Append (Self : in out String_Builder; Char : Character);
   --  Append Char to Self

   procedure Set (Self : in out String_Builder; Str : String);
   --  Reset content of Self to Str

   function Element (Self : String_Builder; N : Positive) return Character
      with Inline;
   --  Return the Nth character of Self

   function Length (Self : String_Builder) return Natural
      with Inline;
   --  Return the length of Self (the size does not take into account
   --  the trailing ASCII.NUL character maintained by the structure).

   function As_String (Self : String_Builder) return String
      with Inline;
   --  Return an Ada String (without the trailing ASCII.NUL)

   function As_C_String (Self : String_Builder) return OS.C_String
      with Inline;
   --  Return a char* pointing to the beginning of Self content

   procedure Deallocate (Self : in out String_Builder)
      with Inline;
   --  Free heap memory associated with Self

   type Static_String_Builder (Size_With_NUL : Natural) is limited private;
   --  Behave the same way as String_Builder except that the maximum
   --  size if known in advance. The structure does not allocate memory
   --  on the heap. Size passed as discriminant should be the maximum size
   --  of the string plus one character for the trailing NUL char.

   procedure Append (Self : in out Static_String_Builder; Str : String)
      with Inline;
   --  Append Str to Self

   procedure Append (Self : in out Static_String_Builder; Char : Character)
      with Inline;
   --  Append Char to Self

   procedure Set (Self : in out Static_String_Builder; Str : String)
      with Inline;
   --  Reset content of Self to Str

   function Element
      (Self : Static_String_Builder; N : Positive)
      return Character
      with Inline;
   --  Return the Nth character of Self

   function Length (Self : Static_String_Builder) return Natural
      with Inline;
   --  Return the length of Self (the size does not take into account
   --  the trailing ASCII.NUL character maintained by the structure).

   function As_String (Self : Static_String_Builder) return String
      with Inline;
   --  Return an Ada String (without the trailing ASCII.NUL)

   function As_C_String (Self : Static_String_Builder) return OS.C_String
      with Inline;
   --  Return a char* pointing to the beginning of Self content

end GNATCOLL.String_Builders;