From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=-0.3 required=5.0 tests=BAYES_00,
	REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,21d5b919bf1b9ba5
X-Google-Attributes: gid103376,public
X-Google-ArrivalTime: 2000-09-08 21:47:12 PST
Path: 
 supernews.google.com!sn-xit-02!sn-east!supernews.com!news-feed.riddles.org.uk!newsfeed.direct.ca!look.ca!newshub2.rdc1.sfba.home.com!news.home.com!news1.sttls1.wa.home.com.POSTED!not-for-mail
Reply-To: "DuckE" <nospam_steved94@home.com>
From: "DuckE" <nospam_steved94@home.com>
Newsgroups: comp.lang.ada
References: <8p7247$8q61@news.cis.okstate.edu> <8pc4h4$88e$1@nnrp1.deja.com>
Subject: Re: Looking for book on Ada Standard Library
X-Priority: 3
X-MSMail-Priority: Normal
X-Newsreader: Microsoft Outlook Express 5.00.2919.6700
X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2919.6700
Message-ID: <jhju5.61990$Ur3.756531@news1.sttls1.wa.home.com>
Date: Sat, 09 Sep 2000 04:47:11 GMT
NNTP-Posting-Host: 24.6.221.63
X-Complaints-To: abuse@home.net
X-Trace: news1.sttls1.wa.home.com 968474831 24.6.221.63 (Fri,
 08 Sep 2000 21:47:11 PDT)
NNTP-Posting-Date: Fri, 08 Sep 2000 21:47:11 PDT
Organization: @Home Network
Xref: supernews.google.com comp.lang.ada:556
Date: 2000-09-09T04:47:11+00:00
List-Id: <comp.lang.ada>

I started trying to put together a somewhat verbose description of each
library module.  I haven't gone very far (Im only through part of the
Ada.Calendar package).  You can see my descriptions below.

I started this because in my opinion this is one of the areas in which Ada
is lacking.  Even though Ada code is quite readable it is still code.

I recall seeing some library documentation where each function and data type
was clearly explained and given an example of use.  I have not seen this
kind of documentation recently for any language.

Personally I use Appendix A of the LRM to learn about the standard library
and often wind up writing a small test program to figure out how things
"really" work.

Maybe I'll continue on this project some time.

Sample:
==========================================================
Ada.Calendar

Package Overview
  The Calendar package defines the abstract type "Time" containing an
  implementation specific representation of an absolute time.  This
  package is normally used for functions relating to time of day
  where timing is not critical.  For critical see the package
  Ada.Real_Time.

  Functions are provided for addition and subtraction of "Duration"
  values and for determining a duration as a difference of time values.

  Procedures are provided for breaking the time value into year, month,
  day and second, and for converting a combination of year, month, day
  and seconds of duration to a time value.

  Types for year, month and day are defined as subtypes of integer.

  The type Day_Duration is defined as a subtype of Duration that contains
  one day.

Package Specification (From LRM)

package Ada.Calendar is

   type Time is private;

   subtype Year_Number  is Integer range 1901 .. 2099;
   subtype Month_Number is Integer range 1 .. 12;
   subtype Day_Number   is Integer range 1 .. 31;

   subtype Day_Duration is Duration range 0.0 .. 86_400.0;

   function Clock return Time;

   function Year    (Date : Time) return Year_Number;
   function Month   (Date : Time) return Month_Number;
   function Day     (Date : Time) return Day_Number;
   function Seconds (Date : Time) return Day_Duration;

   procedure Split
     (Date    : Time;
      Year    : out Year_Number;
      Month   : out Month_Number;
      Day     : out Day_Number;
      Seconds : out Day_Duration);

   function Time_Of
     (Year    : Year_Number;
      Month   : Month_Number;
      Day     : Day_Number;
      Seconds : Day_Duration := 0.0)
      return    Time;

   function "+" (Left : Time;     Right : Duration) return Time;
   function "+" (Left : Duration; Right : Time)     return Time;
   function "-" (Left : Time;     Right : Duration) return Time;
   function "-" (Left : Time;     Right : Time)     return Duration;

   function "<"  (Left, Right : Time) return Boolean;
   function "<=" (Left, Right : Time) return Boolean;
   function ">"  (Left, Right : Time) return Boolean;
   function ">=" (Left, Right : Time) return Boolean;

   Time_Error : exception;

private
   ... -- not specified by the language
end Ada.Calendar;

------------------------------------------------------------------
Function: Clock
Package:  Ada.Calendar
Description:
  The "Clock" function returns a value of type Ada.Calendar.Time
reflecting the current time of day.

Prototype:

   function Clock return Time;

Program Example:

  WITH Ada.Calendar;
  WITH Ada.Text_Io;

  PROCEDURE Clock_Demo IS

    current_time : Ada.Calendar.Time;

  BEGIN
    current_time := Ada.Calendar.Clock;
    -- ...
    DECLARE
      year    : Ada.Calendar.Year_Number;
      month   : Ada.Calendar.Month_Number;
      day     : Ada.Calendar.Day_Number;
      seconds : Ada.Calendar.Day_Duration;
    BEGIN
      Ada.Calendar.Split
        ( Date    => current_time,
          Year    => year,
          Month   => month,
          Day     => day,
          Seconds => seconds );
      Ada.Text_Io.Put_Line( "Year:    " &
da.Calendar.Year_Number'IMAGE( year ) );
      Ada.Text_Io.Put_Line( "Month:   " &
da.Calendar.Month_Number'IMAGE( month ) );
      Ada.Text_Io.Put_Line( "Day:     " &
Ada.Calendar.Day_Number'IMAGE( day ) );
      Ada.Text_Io.Put_Line( "Seconds: " &
da.Calendar.Day_Duration'IMAGE( seconds ) );
    END;
  END Clock_Demo;

Output:
  Year:     2000
  Month:    8
  Day:      23
  Seconds:  76461.552700875
------------------------------------------------------------------
Function: Year
Package:  Ada.Calendar
Description:
  Given a value of type Ada.Calendar.Time returns the year in
  which the time value occurs.

Prototype:

  function Year(Date : Time) return Year_Number;

Program Example:
  WITH Ada.Calendar;
  WITH Ada.Text_Io;

  PROCEDURE Year_Demo IS

    current_time : Ada.Calendar.Time;

  BEGIN
    current_time := Ada.Calendar.Clock;
    -- ...
    DECLARE
      year_value    : Ada.Calendar.Year_Number;
    BEGIN
      year_value := Ada.Calendar.Year( current_time );
      Ada.Text_Io.Put_Line( "Year:    " &
da.Calendar.Year_Number'IMAGE( year_value ) );
    END;
  END Year_Demo;

Output:
  Year:     2000
------------------------------------------------------------------
Function: Month
Package:  Ada.Calendar
Description:
  Given a value of type Ada.Calendar.Time returns the month in
  which the time value occurs.

Prototype:

   function Month   (Date : Time) return Month_Number;

Program Example:
  WITH Ada.Calendar;
  WITH Ada.Text_Io;

  PROCEDURE Month_Demo IS

    current_time : Ada.Calendar.Time;

  BEGIN
    current_time := Ada.Calendar.Clock;
    -- ...
    DECLARE
      month_value   : Ada.Calendar.Month_Number;
    BEGIN
      month_value := Ada.Calendar.Month( current_time );
      Ada.Text_Io.Put_Line( "Month:" &
da.Calendar.Month_Number'IMAGE( month_value ) );
    END;
  END Month_Demo;

Output:
  Month: 8
------------------------------------------------------------------
Function: Day
Package: Ada.Calendar
Description:
  Given a value of type Ada.Calendar.Time returns the day of the
  month in which the time value occurs.

Prototype:

   function Day     (Date : Time) return Day_Number;

Program Example:
  WITH Ada.Calendar;
  WITH Ada.Text_Io;

  PROCEDURE Day_Demo IS

    current_time : Ada.Calendar.Time;

  BEGIN
    current_time := Ada.Calendar.Clock;
    -- ...
    DECLARE
      day_value : Ada.Calendar.Day_Number;
    BEGIN
      day_value := Ada.Calendar.Day( current_time );
      Ada.Text_Io.Put_Line( "Day:" &
da.Calendar.Day_Number'IMAGE( day_value ) );
    END;
  END Day_Demo;

Output:
  Day: 23
------------------------------------------------------------------