develooper Front page | perl.perl5.porters | Postings from August 1999

Re: perlfunc annonations or OOB enhancements?

From:
Tom Christiansen
Date:
August 27, 1999 20:27
Subject:
Re: perlfunc annonations or OOB enhancements?
Message ID:
199908280326.VAA15447@jhereg.perl.com
>Johan documents 0..11 and 0..6 in prose, not in the line which says
>localtime [ EXPR ].  Moving to more descriptiveness is *better*, 
>not optimal.  Describing every nuance is not possible, given that
>the objetive is to keep POD somewhat plain.  Prose documentation 
>will exist and will still need to exist.  

I think it's time to bite the bullet and make real man3 pieces.
I believe this will solve this problem insofar as perlfunc
is concerned.  I can't give you a general answer for how
to construct a general /usr/lib/lint/llib-lc for all possible
perl built-ins, functions, and methods from both the standard
release and from outside that set.

But this at least we should do.  The SYNOPSIS and SEE ALSO are the
parts that really aren't treated well in perlfunc.  The first one should
address your needs.  I don't think adding "types" is a good idea.

--tom


=head1 NAME

localtime - convert UNIX time into record or string using local time

=head1 SYNOPSIS

    # LIST CONTEXT
    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
					localtime($epoch_seconds);
    # SCALAR CONTEXT
    $timedate_string = localtime($epoch_seconds);

=head1 DESCRIPTION

=for index
localtime function 
time;local=for local timezone 
converting;time 

This function converts the value returned by L<time> to a nine-element
list with the time corrected for the local time zone. It's typically
used as follows:

    #  0    1    2     3     4    5     6     7     8
    ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
            localtime(time);

All list elements are numeric, and come straight out of a C<struct tm>.
In particular this means that C<$mon> has the range C<0..11> and C<$wday>
has the range C<0..6> with sunday as day C<0>.  Also, C<$year> is the
number of years since 1900, that is, C<$year> is C<123> in year 2023,
I<not> simply the last two digits of the year.  If you assume it is,
then you create non-Y2K-compliant programs--and you wouldn't want to do
that, would you?

(You can remember which ones are 0-based because those are the ones
you're always using as subscripts into 0-based arrays containing
month and day names.) If I<EXPR> is omitted, it does C<localtime(time())>.
For example, to get the name of the current day of the week:

    $thisday = (Sun,Mon,Tue,Wed,Thu,Fri,Sat)[(localtime)[6]];

=for index
timelocal subroutine 

The Perl library module Time::Local contains a subroutine,
C<timelocal()>, that can convert in the opposite direction.

=for index
date function==>localtime function 

In scalar context, L<localtime> returns a I<ctime>(3)-like string based
on the localtime value.  For example, the I<date>(1) command can be
emulated with:

    perl -e 'print scalar localtime'


=head1 SEE ALSO

The C<POSIX::strftime()> function for a more fine-grained approach
to formatting times.  The Time::localtime module supports a
by-name interface to this function.



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About