F.3.3 The Package Text_IO.Editing
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:
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;
{
AI12-0241-1}
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)
with Nonblocking => False;
{
AI12-0241-1}
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)
with Nonblocking => False;
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;
Implementation defined: The value of
Max_Picture_Length in the package 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);
{
AI05-0264-1}
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.
Discussion: This implies that a picture
string with character replications need not be supported (i.e., To_Picture
will raise Picture_Error) if its expanded form exceeds 30 characters.
Discussion:
{
AI12-0450-1}
The rules for edited output were based on the 1985 version of 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 the 1985 version of 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.
{
AI12-0450-1}
The value of 30 for Max_Picture_Length is the same limit as in COBOL.
Reason: There are several reasons we
have not adopted the COBOL-style permission to provide a single-character
replacement in the picture string for the `$' as currency symbol, or
to interchange the roles of `.' and `,' in picture strings
It would have introduced considerable complexity
into Ada, as well as confusion between run-time and compile-time character
interpretation, since picture Strings are dynamically computable in Ada,
in contrast with COBOL
Ada's rules for real literals provide a natural
interpretation of `_' as digits separator and `.' for radix mark; it
is not essential to allow these to be localized in picture strings, since
Ada does not allow them to be localized in real literals.
The COBOL restriction for the currency symbol
in a picture string to be replaced by a single character currency symbol
is a compromise solution. For general international usage a mechanism
is needed to localize the edited output to be a multi-character currency
string. Allowing a single-Character localization for the picture Character,
and a multiple-character localization for the currency string, would
be an unnecessary complication.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
