F.3.3 The Package Text_IO.Editing

From OC Systems Wiki!
< Guide:95lrm
Revision as of 08:45, 2 May 2019 by imported>WikiVisor
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The package Text_IO.Editing provides a private type Picture with associated operations, and a generic package Decimal_Output. An object of type Picture is composed from a well-formed picture String (see F.3.1) and a Boolean item indicating whether a zero numeric value will result in an edited output string of all space characters. The package Decimal_Output contains edited output subprograms implementing the effects defined in F.3.2.

Static Semantics

The library package Text_IO.Editing has the following declaration:

package Ada.Text_IO.Editing is

    type Picture is private;

    function Valid (Pic_String      in String; 
                    Blank_When_Zero in Boolean := False)
        return Boolean;

    function To_Picture (Pic_String      in String; 
                         Blank_When_Zero in Boolean := False)
        return Picture;

    function Pic_String      (Pic in Picture) return String; 
    function Blank_When_Zero (Pic in Picture) return Boolean;

    Max_Picture_Length  : constant := implementation_defined;

    Picture_Error       : exception;

    Default_Currency    : constant String    := "$"; 
    Default_Fill        : constant Character := '*'; 
    Default_Separator   : constant Character := ','; 
    Default_Radix_Mark  : constant Character := '.';

    generic
        type Num is delta <> digits <>; 
        Default_Currency   : in String    := Text_IO.Editing.Default_Currency; 
        Default_Fill       : in Character := Text_IO.Editing.Default_Fill; 
        Default_Separator  : in Character := 
                             Text_IO.Editing.Default_Separator; 
        Default_Radix_Mark : in Character := 
                             Text_IO.Editing.Default_Radix_Mark;
    package Decimal_Output is
        function Length (Pic      in Picture; 
                         Currency in String := Default_Currency)
            return Natural;

       function Valid (Item     in Num;
                       Pic      in Picture; 
                       Currency in String := Default_Currency)
           return Boolean;

       function Image (Item       in Num;
                       Pic        in Picture; 
                       Currency   in String    := Default_Currency; 
                       Fill       in Character := Default_Fill; 
                       Separator  in Character := Default_Separator; 
                       Radix_Mark in Character := Default_Radix_Mark)
           return String;

       procedure Put (File       in File_Type;
                      Item       in Num;
                      Pic        in Picture; 
                      Currency   in String    := Default_Currency; 
                      Fill       in Character := Default_Fill; 
                      Separator  in Character := Default_Separator; 
                      Radix_Mark in Character := Default_Radix_Mark);

       procedure Put (Item       in Num;
                      Pic        in Picture; 
                      Currency   in String    := Default_Currency; 
                      Fill       in Character := Default_Fill; 
                      Separator  in Character := Default_Separator; 
                      Radix_Mark in Character := Default_Radix_Mark);

       procedure Put (To         out String;
                      Item       in Num;
                      Pic        in Picture; 
                      Currency   in String    := Default_Currency; 
                      Fill       in Character := Default_Fill; 
                      Separator  in Character := Default_Separator; 
                      Radix_Mark in Character := Default_Radix_Mark); 
    end Decimal_Output;
private
    ... -- not specified by the language
end Ada.Text_IO.Editing;

The exception Constraint_Error is raised if the Image function or any of the Put procedures is invoked with a null string for Currency.

function Valid (Pic_String      in String; 
                Blank_When_Zero in Boolean := False) return Boolean;

Valid returns True if Pic_String is a well-formed picture String (see F.3.1) the length of whose expansion does not exceed Max_Picture_Length, and if either Blank_When_Zero is False or Pic_String contains no '*'.

function To_Picture (Pic_String      in String; 
                     Blank_When_Zero in Boolean := False) return Picture;

To_Picture returns a result Picture such that the application of the function Pic_String to this result yields an expanded picture String equivalent to Pic_String, and such that Blank_When_Zero applied to the result Picture is the same value as the parameter Blank_When_Zero. Picture_Error is raised if not Valid(Pic_String, Blank_When_Zero).

function Pic_String      (Pic in Picture) return String;
function Blank_When_Zero (Pic in Picture) return Boolean;

If Pic is To_Picture(String_Item, Boolean_Item) for some String_Item and Boolean_Item, then:

  • Pic_String(Pic) returns an expanded picture String equivalent to String_Item and with any lower-case letter replaced with its corresponding upper-case form, and

  • Blank_When_Zero(Pic) returns Boolean_Item.

If Pic_1 and Pic_2 are objects of type Picture, then "="(Pic_1, Pic_2) is True when

  • Pic_String(Pic_1) = Pic_String(Pic_2), and

  • Blank_When_Zero(Pic_1) = Blank_When_Zero(Pic_2).

function Length (Pic      in Picture; 
                 Currency in String := Default_Currency) return Natural;

Length returns Pic_String(Pic)'Length + Currency_Length_Adjustment - Radix_Adjustment where

  • Currency_Length_Adjustment}}

  • Currency'Length - 1 if there is some occurrence of '$' in Pic_String(Pic), and

  • 0 otherwise.

  • Radix_Adjustment}}

  • 1 if there is an occurrence of 'V' or 'v' in Pic_Str(Pic), and

  • 0 otherwise.

function Valid (Item     in Num;
                Pic      in Picture; 
                Currency in String := Default_Currency)
    return Boolean;

Valid returns True if Image(Item, Pic, Currency) does not raise Layout_Error, and returns False otherwise.

function Image (Item       in Num;
                Pic        in Picture; 
                Currency   in String    := Default_Currency; 
                Fill       in Character := Default_Fill; 
                Separator  in Character := Default_Separator; 
                Radix_Mark in Character := Default_Radix_Mark)
    return String;

Image returns the edited output String as defined in F.3.2 for Item, Pic_String(Pic), Blank_When_Zero(Pic), Currency, Fill, Separator, and Radix_Mark. If these rules identify a layout error, then Image raises the exception Layout_Error.

procedure Put (File       in File_Type;
               Item       in Num;
               Pic        in Picture; 
               Currency   in String    := Default_Currency; 
               Fill       in Character := Default_Fill; 
               Separator  in Character := Default_Separator; 
               Radix_Mark in Character := Default_Radix_Mark);

procedure Put (Item       in Num;
               Pic        in Picture; 
               Currency   in String    := Default_Currency; 
               Fill       in Character := Default_Fill; 
               Separator  in Character := Default_Separator; 
               Radix_Mark in Character := Default_Radix_Mark);

Each of these Put procedures outputs Image(Item, Pic, Currency, Fill, Separator, Radix_Mark) consistent with the conventions for Put for other real types in case of bounded line length (see A.10.6, Get and Put Procedures).

procedure Put (To         out String;
               Item       in Num;
               Pic        in Picture; 
               Currency   in String    := Default_Currency; 
               Fill       in Character := Default_Fill; 
               Separator  in Character := Default_Separator; 
               Radix_Mark in Character := Default_Radix_Mark);

Put copies Image(Item, Pic, Currency, Fill, Separator, Radix_Mark) to the given string, right justified. Otherwise unassigned Character values in To are assigned the space character. If To'Length is less than the length of the string resulting from Image, then Layout_Error is raised.

Implementation Requirements

Max_Picture_Length shall be at least 30. The implementation shall support currency strings of length up to at least 10, both for Default_Currency in an instantiation of Decimal_Output, and for Currency in an invocation of Image or any of the Put procedures.

Notes

4  The rules for edited output are based on COBOL (ANSI X3.23:1985, endorsed by ISO as ISO 1989-1985), with the following differences:

  • The COBOL provisions for picture string localization and for 'P' format are absent from Ada.
  • The following Ada facilities are not in COBOL:

  • currency symbol placement after the number,

  • localization of edited output string for multi-character currency string values, including support for both length-preserving and length-expanding currency symbols in picture strings

  • localization of the radix mark, digits separator, and fill character, and

  • parenthesization of negative values.

The value of 30 for Max_Picture_Length is the same limit as in COBOL.

Copyright © 1992,1993,1994,1995 Intermetrics, Inc.
Copyright © 2000 The MITRE Corporation, Inc. Ada Reference Manual