!standard 5.5.2(2/3) 19-02-22 AI12-0312-1/01 !class presentation 19-02-07 !status work item 19-02-07 !status received 19-02-07 !priority Low !difficulty Easy !subject Examples for Ada 2020 !summary Additional examples are added, and existing ones improved. !question Some new parts of the Standard have few or no examples, while others have too many examples (see 4.3.5). We need a more consistent use of examples, right? (Yes.) !response (See Summary.) !wording delete paragraphs 4.3.5 (86/5 - 86/5) [Already show example of empty container aggregate] delete paragraph 4.3.5 (97/5) [Alternate form example shown above] delete paragraphs 4.3.5 (99/5 - 100/5) [Already show example of empty container aggregate] delete paragraphs 4.3.5 (105/5 - 106/5) [Example is not that different from others] Modify 5.5 (22/5) "Example{s} of [a] parallel loop{s}: " Add after 5.5 (23/5) declare subtype Chunk_Number is Natural range 1 .. 8; Partial_Sum, Partial_Max : array (Chunk_Number) of Natural := (others => 0); Partial_Min : array (Chunk_Number) of Natural := (others => Natural'Last); begin parallel (Chunk in Chunk_Number) for I in Grid'Range(1) loop declare True_Count : constant Natural := (for J in Grid'Range(2) => (if Grid (I, J) then 1 else 0))'Reduce("+",0); begin Partial_Sum (Chunk) := @ + True_Count; Partial_Min (Chunk) := Natural'Min(@, True_Count); Partial_Max (Chunk) := Natural'Max(@, True_Count); end; end loop; Put_Line("Total=" & Partial_Sum'Reduce("+", 0) & ", Min=" & Partial_Min'Reduce(Natural'Min, Natural'Last) & ", Max=" & Partial_Max'Reduce(Natural'Max, 0)); end; Append after 11.3 (7) For examples of raise expressions, see the Streams Subsytem definitions in 13.13.1 Append after B.3 (78/3) procedure Printf (Format : in C.char_array) with Import => True, Convention => C_Variadic_1, External_Name => "printf"; Append after B.3 (83) Printf("The String=%s, Length=%d", Chars1, Chars1'Length); Append after 4.5.7 (21/3) Examples Put_Line ("George is " & (if George.Sex = M then "Male" else "Female")); -- See 3.10.1 function Value (Digit : Roman_Digit) return Natural is -- See 3.5.2 (case Digit is when 'I' => 1, when 'V' => 5, when 'X' => 10, when 'L' => 50, when 'C' => 100, when 'D' => 500, when 'M' => 1000); Value : constant Natural := (case type Roman_Digit is ('I', 'V', 'X', 'L', 'C', 'D', 'M'); Append after 6.1.1 (41/3) 6 For an example of the use of these aspects and attributes, see the Streams Subsystem definitions in 13.13.1. Append after 6.1.2 (42/5) NOTES For an example of the use of these aspects, see the Vector container definition in A.18.2. Append after 7.3.2 (24/3) Examples package Work_Orders is type Work_Order is private with Type_Invariant => Day_Scheduled (Work_Order) in Weekday or else Priority (Work_Order) = Urgent; -- See 3.5.1 function Day_Scheduled (Order : in Work_Order) return Day; -- See 3.5.1 function Priority (Order : in Work_Order) return Level; -- See 3.5.1 ... private type Work_Order is record Scheduled : Day; Urgency : Level; ... end record; function Day_Scheduled (Order : in Work_Order) return Day is (Order.Scheduled); function Priority (Order : in Work_Order) return Level is (Order.Urgency); ... end Work_Orders; Append after 7.3.3 (9/5) NOTES For an example of the use of this aspect, see the Vector container definition in A.18.2. Append after 4.3.3 (47/5) Empty_Matrix : constant Matrix := []; -- A matrix without elements Append after 4.2.1 (10/5) Examples -- The Date Example in 3.8 could be augmented to support integer literal representation type Month_Name is (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec); type Date is record Day : Integer range 1 .. 31; Month : Month_Name; Year : Integer range 0 .. 4000; end record with Integer_Literal => To_Date; function To_Date (Value : String) return Date; function To_Date (Value : String) return Date is (declare Integer_String : constant String := Integer'Image (Integer'Value (Value)); begin (Day => Integer'Value(Integer_String (Integer_String'Last-5 .. Integer_String'Last-4)), Year => Integer'Value (Integer_String (Integer_String'Last - 3 .. Integer_String'Last)), Month => Month_Name'Val (Integer'Value(Integer_String (Integer_String'First .. Integer_String'Last - 6))-1))); ... Today : Date := 2_22_2019; -- Integer representation of date (MMDDYYYY format) !discussion A survey of the RM found that there were no examples in the defining sections for: - Conditional Expressions (4.5.7) - Pre and Post conditions (6.1.1) - Global Aspect (6.1.2) - Type Invariants (7.3.2) - Default Initial Conditions (7.3.3) - raise expressions and Predicate_Failure (11.3) - Image Attributes (4.10) - Variadic C functions (B.3) [Author Note: - Stable Properties has a note 7.3.4 (24/5) that says, "For an example of the use of these aspects, see the Vector container definition in A.18.2." but currently no use of Stable_Properties exists there. Presumably this will be added as part of AI12-0112-1.] - User Defined Literals (4.2.1) - Explicit Chunk definition for parallel loops (5.5) - implicit subtype mark in object renames (8.5.1) - null array aggregates (4.3.3) For the Global aspect, a note was added to refer to the Vector Container package for examples of use. At the time of writing, the Global aspects had not yet been added to the containers. Presumably, this will happen, and will provide some good examples. The 'Image attribute has existed since Ada 83, but improved in Ada 202x, however it doesn't seem that an example is necessary. Similarly, there is an existing example for object renames, with an explicit subtype mark. It seems to not be worthwhile to add another example where the subtype mark is implicit. !ASIS None needed. !ACATS test No ACATS tests needed. !appendix From: Brad Moore Sent: Friday, February 22, 2019 5:45 PM I managed to get an initial draft of this AI, possibly just under or over the deadline. So far, Jeff and Ed have not seen this or have had a chance to comment on it, yet they are listed as being involved in the homework assignment. Had I finished this earlier, I would have sent it an initial draft out to them, but since it is this close to the deadline, I figured it would be better to just send this out to the group, in case we want to discuss it at the meeting. In the meantime, it would be great if Jeff and/or Ed could review with an eye to; 1) Did I miss some features that need examples? 2) Are the examples I have satisfactory, or could be improved upon? 3) Did I reduce the container aggregate examples sufficiently, or perhaps cut off too much? 4) Do you have additional examples that you'd like to see added? Some of the features are actually Ada 2005 features, such as type invariants. However, since the goal of this work is to make the RM more consistent in the examples department, this seemed like a good idea to provide a few extra examples. **************************************************************** From: Brad Moore Sent: Friday, February 22, 2019 6:04 PM A minor correction to the User Defined Literal example: function To_Date (Value : String) return Date is (declare Integer_String : constant String := Integer'Image (Integer'Value (Value)); begin (Day => Integer'Value(Integer_String (Integer_String'Last-5 .. Integer_String'Last-4)), Year => Integer'Value (Integer_String (Integer_String'Last - 3 .. Integer_String'Last)), Month => Month_Name'Val (Integer'Value(Integer_String (Integer_String'First .. Integer_String'Last - 6))-1))); In determining the Month component, I needed to subtract 1 before applying 'Val on the Month_Name enumeration. Also, I believe I was missing a semicolon on the declaration of Integer_String in the declare expression. The above has these corrections. **************************************************************** From: Randy Brukardt Sent: Friday, February 22, 2019 9:32 PM > I managed to get an initial draft of this AI, possibly just under or > over the deadline. This message was time-stamped at 5:45 CST, so you were 45 minutes late. As always, I ask that people that might be late send me a heads-up. It didn't matter today, as processing the draft of the hour for AI12-0191-1 took forever. > Some of the features are actually Ada 2005 features, such as type invariants. Type invariants are an Ada 2012 feature. Not that that matters to your point... > A minor correction to the User Defined Literal example: Correction applied. > function To_Date (Value : String) return Date is > (declare > Integer_String : constant String := Integer'Image (Integer'Value (Value)); > begin > (Day => Integer'Value(Integer_String (Integer_String'Last-5 .. Integer_String'Last-4)), > Year => Integer'Value (Integer_String (Integer_String'Last - 3 .. Integer_String'Last)), > Month => Month_Name'Val (Integer'Value(Integer_String > (Integer_String'First .. Integer_String'Last - 6))-1))); Some of these lines are too long to put in the RM as-is. It would help to break them to be shorter, so I don't have to guess where to do it. >!wording > >delete paragraphs 4.3.5 (86/5 - 86/5) [Already show example of empty container aggregate] You have a range with one paragraph in it; I suspect that you meant something else. >Append after 4.5.7 (21/3) ... >Value : constant Natural := (case >type Roman_Digit is ('I', 'V', 'X', 'L', 'C', 'D', 'M'); There is something wrong with this! I haven't previously encountered the "case type expression"! :-) **************************************************************** From: Brad Moore Sent: Friday, February 22, 2019 10:23 PM >> I managed to get an initial draft of this AI, possibly just under or >> over the deadline. > > This message was time-stamped at 5:45 CST, so you were 45 minutes > late. As always, I ask that people that might be late send me a > heads-up. It didn't matter today, as processing the draft of the hour > for AI12-0191-1 took forever. Whew! Glad to hear it made it under the door even if only by luck.... ... >> function To_Date (Value : String) return Date is >> (declare >> Integer_String : constant String := Integer'Image > (Integer'Value (Value)); >> begin >> (Day => Integer'Value(Integer_String (Integer_String'Last-5 .. > Integer_String'Last-4)), >> Year => Integer'Value (Integer_String (Integer_String'Last >> - 3 > .. Integer_String'Last)), >> Month => Month_Name'Val (Integer'Value(Integer_String > (Integer_String'First .. Integer_String'Last - 6))-1))); > > Some of these lines are too long to put in the RM as-is. It would help > to break them to be shorter, so I don't have to guess where to do it. I found it helped to shorten some of the variable names. Here is what I have currently. function To_Date (Value : String) return Date is declare S : constant String := Integer'Image (Integer'Value (Value)); begin (Day => Integer'Value (S (S'Last-5 .. S'Last-4)), Year => Integer'Value (S (S'Last-3 .. S'Last)), Month => Month_Name'Val (Integer'Value (S (S'First .. S'Last-6))-1)); One question. I wasn't sure if I need an extra set of parens around the expression function, or can the parens used for the aggregate object suffice? If not, you'll need to add those. Also not sure if style here warrants putting the declare and begin on the same line, but I quite like the new look of this example. >>!wording >> >>delete paragraphs 4.3.5 (86/5 - 86/5) [Already show example of empty > container aggregate] > > You have a range with one paragraph in it; I suspect that you meant > something else. I meant (86/5 - 87/5) >>Append after 4.5.7 (21/3) > ... >>Value : constant Natural := (case >>type Roman_Digit is ('I', 'V', 'X', 'L', 'C', 'D', 'M'); > > There is something wrong with this! I haven't previously encountered the > "case type expression"! :-) These two lines are garbage and should be deleted.... "Value : constant Natural := (case type Roman_Digit is ('I', 'V', 'X', 'L', 'C', 'D', 'M');" **************************************************************** From: Randy Brukardt Sent: Friday, February 22, 2019 10:59 PM ... > Whew! Glad to hear it made it under the door even if only by luck.... ...but not with this message. :-) ... > > Some of these lines are too long to put in the RM as-is. It would > > help to break them to be shorter, so I don't have to guess where to do it. > > > > I found it helped to shorten some of the variable names. Here is what > I have currently. > > function To_Date (Value : String) return Date is > declare S : constant String := Integer'Image (Integer'Value > (Value)); begin > (Day => Integer'Value (S (S'Last-5 .. S'Last-4)), > Year => Integer'Value (S (S'Last-3 .. S'Last)), > Month => Month_Name'Val (Integer'Value (S (S'First .. S'Last-6))-1)); > > One question. I wasn't sure if I need an extra set of parens around > the expression function, or can the parens used for the aggregate > object suffice? If not, you'll need to add those. This example doesn't have any parens at all (needed around the declare expression), so that's a problem. And putting the declare/declaration/begin on the same line isn't the recommended style, and it's probably too long anyway (only room for roughly 70 characters on a line in an example, including the indenting white space), so let's not do that. > Also not sure if style here warrants putting the declare and begin on > the same line, but I quite like the new look of this example. See above. **************************************************************** From: Jeff Cousins Sent: Monday, February 22, 2019 2:27 PM Presumably "delete paragraphs (86/5 – 86/5)" should be "Delete paragraphs (86/5 – 87/5)". "Add after 5.5 (23/5)" It would help to begin with a comment of explanation, e.g. that it is an example of explicit chunk definition. "Append after 11.3 (7)" I can only see one example in 13.13.1; if so, this should be in singular. "Append after B.3 (78/3)" It would help to begin with a comment of explanation, e.g. that it is an example of a variadic C function. "Append after 4.5.7 (21/3)" Is the last line simply spurious, partly cut and pasted from 3.5.2? Also, could all these be put in RM order? ****************************************************************