4.2.59. GNATCOLL.WString_Builders

package GNATCOLL.WString_Builders is

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

   type WString_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 WString_Builder should be finalized by calling Deallocate
   --  procedure.

   procedure Append (Self : in out WString_Builder; Str : UTF8.UTF_8_String);
   --  Append Str to Self

   procedure Append (Self : in out WString_Builder; Char : Wide_Character);
   --  Append Char to Self

   procedure Set (Self : in out WString_Builder; Str : UTF8.UTF_8_String);
   --  Reset content of Self to Str

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

   function Length (Self : WString_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 : WString_Builder) return Wide_String
      with Inline;
   --  Return an Ada String (without the trailing ASCII.NUL)

   function As_UTF8_String (Self : WString_Builder) return UTF8.UTF_8_String
      with Inline;
   --  Return an Ada String (without the trailing ASCII.NUL)

   function As_C_WString
      (Self          : WString_Builder;
       Null_If_Empty : Boolean := False)
      return OS.C_WString
      with Inline;
   --  Return a wchar* pointing to the beginning of Self content

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

   type Static_WString_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_WString_Builder;
       Str  : UTF8.UTF_8_String)
      with Inline;
   --  Append Str to Self

   procedure Append
      (Self : in out Static_WString_Builder;
       Char : Wide_Character)
      with Inline;
   --  Append Char to Self

   procedure Set
      (Self : in out Static_WString_Builder;
       Str  : UTF8.UTF_8_String)
      with Inline;
   --  Reset content of Self to Str

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

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

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

   function As_UTF8_String
      (Self : Static_WString_Builder)
      return UTF8.UTF_8_String
      with Inline;
   --  Return an Ada String (without the trailing ASCII.NUL)

   function As_C_WString
      (Self          : Static_WString_Builder;
       Null_If_Empty : Boolean := False)
      return OS.C_WString
      with Inline;
   --  Return a wchar* pointing to the beginning of Self content

end GNATCOLL.WString_Builders;