Contents Index Search Previous Next
F.3.3 The Package Text_IO.Editing
1
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
2
The library package
Text_IO.Editing has the following declaration:
3
package Ada.Text_IO.Editing is
4
5
function Valid (Pic_String : in String;
Blank_When_Zero : in Boolean := False) return Boolean;
6
function To_Picture (Pic_String : in String;
Blank_When_Zero : in Boolean := False)
return Picture;
7
function Pic_String (Pic : in Picture) return String;
function Blank_When_Zero (Pic : in Picture) return Boolean;
8
Max_Picture_Length : constant := implementation_defined;
9
Picture_Error : exception;
10
Default_Currency : constant String := "$";
Default_Fill : constant Character := '*';
Default_Separator : constant Character := ',';
Default_Radix_Mark : constant Character := '.';
11
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;
12
function Valid (Item : in Num;
Pic : in Picture;
Currency : in String := Default_Currency)
return Boolean;
13
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;
14
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);
15
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);
16
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;
17
The exception Constraint_Error
is raised if the Image function or any of the Put procedures is invoked
with a null string for Currency.
18
function Valid (Pic_String : in String;
Blank_When_Zero : in Boolean := False) return Boolean;
19
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 '*'.
20
function To_Picture (Pic_String : in String;
Blank_When_Zero : in Boolean := False)
return Picture;
21
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).
22
function Pic_String (Pic : in Picture) return String;
function Blank_When_Zero (Pic : in Picture) return Boolean;
23
If Pic is To_Picture(String_Item,
Boolean_Item) for some String_Item and Boolean_Item, then:
24
- 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
25
- Blank_When_Zero(Pic) returns
Boolean_Item.
26
If Pic_1 and
Pic_2 are objects of type Picture, then "="(Pic_1, Pic_2) is
True when
27
- Pic_String(Pic_1) = Pic_String(Pic_2),
and
28
- Blank_When_Zero(Pic_1)
= Blank_When_Zero(Pic_2).
29
function Length (Pic : in Picture;
Currency : in String := Default_Currency)
return Natural;
30
Length returns
Pic_String(Pic)'Length + Currency_Length_Adjustment - Radix_Adjustment
where
31
- Currency_Length_Adjustment
=
32
- Currency'Length
- 1 if there is some occurrence of '$' in Pic_String(Pic), and
33
34
35
- 1 if there is an
occurrence of 'V' or 'v' in Pic_Str(Pic), and
36
37
function Valid (Item : in Num;
Pic : in Picture;
Currency : in String := Default_Currency)
return Boolean;
38
Valid returns
True if Image(Item, Pic, Currency) does not raise Layout_Error, and returns
False otherwise.
39
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;
40
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.
41
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);
42
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'').
43
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);
44
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
45
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.
46
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:
47
- The COBOL provisions
for picture string localization and for 'P' format are absent from Ada.
48
- The
following Ada facilities are not in COBOL:
49
- currency
symbol placement after the number,
50
- 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
51
- localization
of the radix mark, digits separator, and fill character, and
52
- parenthesization
of negative values.
52.1
The value of 30 for Max_Picture_Length
is the same limit as in COBOL.
Contents Index Search Previous Next Legal