Ada Programming/Libraries/Ada.Strings.Unbounded

Computing » Computer Science » Computer Programming » Ada Programming

---

This language feature is available from Ada 95 on.

Ada.Strings.Unbounded is a unit of the Predefined Language Environment since Ada 95.

This package defines the operations for unbounded string handling.

Usage

Ada.Strings.Unbounded is used in several places. Here some relevant extracts. As always you can follow the download links to see the full examples.

Conversion between unbounded and bounded strings:

File: show_commandline_4.adb (view, plain text, download page, browse all)

with Ada.Strings.Unbounded;

   package SU   renames Ada.Strings.Unbounded;

   X :  SU.Unbounded_String 
     := SU.To_Unbounded_String (CL.Argument (1));

   T_IO.Put_Line (SU.To_String (X));

   X := SU.To_Unbounded_String (CL.Argument (2));

   T_IO.Put_Line (SU.To_String (X));

Another example:

with
  Ada.Text_IO,
  Ada.Integer_Text_IO,
  Ada.Strings.Unbounded,
  Ada.Text_IO.Unbounded_IO;

procedure User_Input2 is
   S : Ada.Strings.Unbounded.Unbounded_String;
   I : Integer;
begin
   Ada.Text_IO.Put("Enter a string: ");
   S := Ada.Strings.Unbounded.To_Unbounded_String(Ada.Text_IO.Get_Line);
   Ada.Text_IO.Put_Line(Ada.Strings.Unbounded.To_String(S));
   Ada.Text_IO.Unbounded_IO.Put_Line(S);
   Ada.Text_IO.Put("Enter an integer: ");
   Ada.Integer_Text_IO.Get(I);
   Ada.Text_IO.Put_Line(Integer'Image(I));
end User_Input2;

File: numeric_4.adb (view, plain text, download page, browse all)

with Ada.Strings.Unbounded;

  package Str renames Ada.Strings.Unbounded;
  function Get_Line return Str.Unbounded_String;

  use type Str.Unbounded_String;

  Operation : Str.Unbounded_String;

  function Get_Line return Str.Unbounded_String is
     BufferSize : constant := 2000;
     Retval     : Str.Unbounded_String := Str.Null_Unbounded_String;
     Item       : String (1 .. BufferSize);
     Last       : Natural;
  begin
     Get_Whole_Line :
        loop
           T_IO.Get_Line (Item => Item, Last => Last);

           Str.Append (Source => Retval, New_Item => Item (1 .. Last));

           exit Get_Whole_Line when Last < Item'Last;
        end loop Get_Whole_Line;

     return Retval;
  end Get_Line;

Specification

--                     Standard Ada library specification
--   Copyright (c) 2003-2018 Maxim Reznik <reznikmm@gmail.com>
--   Copyright (c) 2004-2016 AXE Consultants
--   Copyright (c) 2004, 2005, 2006 Ada-Europe
--   Copyright (c) 2000 The MITRE Corporation, Inc.
--   Copyright (c) 1992, 1993, 1994, 1995 Intermetrics, Inc.
--   SPDX-License-Identifier: BSD-3-Clause and LicenseRef-AdaReferenceManual
-- -------------------------------------------------------------------------

with Ada.Strings.Maps;
package Ada.Strings.Unbounded is
   pragma Preelaborate (Unbounded);

   type Unbounded_String is private;
   pragma Preelaborable_Initialization (Unbounded_String);

   Null_Unbounded_String : constant Unbounded_String;

   function Length (Source : in Unbounded_String) return Natural;

   type String_Access is access all String;
   procedure Free (X : in out String_Access);

   --  Conversion, Concatenation, and Selection functions

   function To_Unbounded_String (Source : in String)
                                return Unbounded_String;

   function To_Unbounded_String (Length : in Natural)
                                return Unbounded_String;

   function To_String (Source : in Unbounded_String) return String;

   procedure Set_Unbounded_String
     (Target :    out Unbounded_String;
      Source : in     String);

   procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Unbounded_String);

   procedure Append (Source   : in out Unbounded_String;
                     New_Item : in String);

   procedure Append (Source   : in out Unbounded_String;
                     New_Item : in Character);

   function "&" (Left, Right : in Unbounded_String)
                return Unbounded_String;

   function "&" (Left : in Unbounded_String; Right : in String)
                return Unbounded_String;

   function "&" (Left : in String; Right : in Unbounded_String)
                return Unbounded_String;

   function "&" (Left : in Unbounded_String; Right : in Character)
                return Unbounded_String;

   function "&" (Left : in Character; Right : in Unbounded_String)
                return Unbounded_String;

   function Element (Source : in Unbounded_String;
                     Index  : in Positive)
                    return Character;

   procedure Replace_Element (Source : in out Unbounded_String;
                              Index  : in Positive;
                              By     : in Character);

   function Slice (Source : in Unbounded_String;
                   Low    : in Positive;
                   High   : in Natural)
                  return String;

   function Unbounded_Slice
     (Source : in Unbounded_String;
      Low    : in Positive;
      High   : in Natural)
     return Unbounded_String;

   procedure Unbounded_Slice
     (Source : in     Unbounded_String;
      Target :    out Unbounded_String;
      Low    : in     Positive;
      High   : in     Natural);

   function "="  (Left, Right : in Unbounded_String) return Boolean;

   function "="  (Left : in Unbounded_String; Right : in String)
                 return Boolean;

   function "="  (Left : in String; Right : in Unbounded_String)
                 return Boolean;

   function "<"  (Left, Right : in Unbounded_String) return Boolean;

   function "<"  (Left : in Unbounded_String; Right : in String)
                 return Boolean;

   function "<"  (Left : in String; Right : in Unbounded_String)
                 return Boolean;

   function "<=" (Left, Right : in Unbounded_String) return Boolean;

   function "<="  (Left : in Unbounded_String; Right : in String)
                  return Boolean;

   function "<="  (Left : in String; Right : in Unbounded_String)
                  return Boolean;

   function ">"  (Left, Right : in Unbounded_String) return Boolean;

   function ">"  (Left : in Unbounded_String; Right : in String)
                 return Boolean;

   function ">"  (Left : in String; Right : in Unbounded_String)
                 return Boolean;

   function ">=" (Left, Right : in Unbounded_String) return Boolean;

   function ">="  (Left : in Unbounded_String; Right : in String)
                  return Boolean;

   function ">="  (Left : in String; Right : in Unbounded_String)
                  return Boolean;

   --  Search subprograms

   function Index (Source  : in Unbounded_String;
                   Pattern : in String;
                   From    : in Positive;
                   Going   : in Direction := Forward;
                   Mapping : in Maps.Character_Mapping := Maps.Identity)
                  return Natural;

   function Index (Source  : in Unbounded_String;
                   Pattern : in String;
                   From    : in Positive;
                   Going   : in Direction := Forward;
                   Mapping : in Maps.Character_Mapping_Function)
                  return Natural;

   function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping
                     := Maps.Identity)
                  return Natural;

   function Index (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Going    : in Direction := Forward;
                   Mapping  : in Maps.Character_Mapping_Function)
                  return Natural;

   function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   From   : in Positive;
                   Test   : in Membership := Inside;
                   Going  : in Direction := Forward)
                  return Natural;

   function Index (Source : in Unbounded_String;
                   Set    : in Maps.Character_Set;
                   Test   : in Membership := Inside;
                   Going  : in Direction  := Forward) return Natural;

   function Index_Non_Blank (Source : in Unbounded_String;
                             From   : in Positive;
                             Going  : in Direction := Forward)
                            return Natural;

   function Index_Non_Blank (Source : in Unbounded_String;
                             Going  : in Direction := Forward)
                            return Natural;

   function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping
                     := Maps.Identity)
                  return Natural;

   function Count (Source   : in Unbounded_String;
                   Pattern  : in String;
                   Mapping  : in Maps.Character_Mapping_Function)
                  return Natural;

   function Count (Source   : in Unbounded_String;
                   Set      : in Maps.Character_Set)
                  return Natural;

   procedure Find_Token (Source : in Unbounded_String;
                         Set    : in Maps.Character_Set;
                         Test   : in Membership;
                         First  : out Positive;
                         Last   : out Natural);

   --  String translation subprograms

   function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping)
                      return Unbounded_String;

   procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping);

   function Translate (Source  : in Unbounded_String;
                       Mapping : in Maps.Character_Mapping_Function)
                      return Unbounded_String;

   procedure Translate (Source  : in out Unbounded_String;
                        Mapping : in Maps.Character_Mapping_Function);

   --  String transformation subprograms

   function Replace_Slice (Source   : in Unbounded_String;
                           Low      : in Positive;
                           High     : in Natural;
                           By       : in String)
                          return Unbounded_String;

   procedure Replace_Slice (Source   : in out Unbounded_String;
                            Low      : in Positive;
                            High     : in Natural;
                            By       : in String);

   function Insert (Source   : in Unbounded_String;
                    Before   : in Positive;
                    New_Item : in String)
                   return Unbounded_String;

   procedure Insert (Source   : in out Unbounded_String;
                     Before   : in Positive;
                     New_Item : in String);

   function Overwrite (Source    : in Unbounded_String;
                       Position  : in Positive;
                       New_Item  : in String)
                      return Unbounded_String;

   procedure Overwrite (Source    : in out Unbounded_String;
                        Position  : in Positive;
                        New_Item  : in String);

   function Delete (Source  : in Unbounded_String;
                    From    : in Positive;
                    Through : in Natural)
                   return Unbounded_String;

   procedure Delete (Source  : in out Unbounded_String;
                     From    : in Positive;
                     Through : in Natural);

   function Trim (Source : in Unbounded_String;
                  Side   : in Trim_End)
                 return Unbounded_String;

   procedure Trim (Source : in out Unbounded_String;
                   Side   : in Trim_End);

   function Trim (Source : in Unbounded_String;
                  Left   : in Maps.Character_Set;
                  Right  : in Maps.Character_Set)
                 return Unbounded_String;

   procedure Trim (Source : in out Unbounded_String;
                   Left   : in Maps.Character_Set;
                   Right  : in Maps.Character_Set);

   function Head (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
                 return Unbounded_String;

   procedure Head (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

   function Tail (Source : in Unbounded_String;
                  Count  : in Natural;
                  Pad    : in Character := Space)
                 return Unbounded_String;

   procedure Tail (Source : in out Unbounded_String;
                   Count  : in Natural;
                   Pad    : in Character := Space);

   function "*" (Left  : in Natural;
                 Right : in Character)
                return Unbounded_String;

   function "*" (Left  : in Natural;
                 Right : in String)
                return Unbounded_String;

   function "*" (Left  : in Natural;
                 Right : in Unbounded_String)
                return Unbounded_String;

private

   pragma Import (Ada, Unbounded_String);
   pragma Import (Ada, Null_Unbounded_String);

end Ada.Strings.Unbounded;

See also

Wikibook

• Ada Programming
• Ada Programming/Libraries
• Ada Programming/Strings#Unbounded-length string handling

Ada Reference Manual

Ada 95

• A.4.5: Unbounded-Length String Handling ^[Annotated]

Ada 2005

• A.4.5: Unbounded-Length String Handling ^[Annotated]

Ada 2012

• A.4.5: Unbounded-Length String Handling ^[Annotated]

Open-Source Implementations

FSF GNAT

• Specification: a-strunb.ads
• Body: a-strunb.adb

drake

• Specification: strings/a-strunb.ads