This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
4e1359b36d90d618239800462dc85fc4fcabe8d3
[perl5.git] / lib / Time / gmtime.pm
1 package Time::gmtime;
2 use strict;
3 use 5.006_001;
4
5 use Time::tm;
6
7 our(@ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS, $VERSION);
8 BEGIN { 
9     use Exporter   ();
10     @ISA         = qw(Exporter Time::tm);
11     @EXPORT      = qw(gmtime gmctime);
12     @EXPORT_OK   = qw(  
13                         $tm_sec $tm_min $tm_hour $tm_mday 
14                         $tm_mon $tm_year $tm_wday $tm_yday 
15                         $tm_isdst
16                     );
17     %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
18     $VERSION     = 1.02;
19 }
20 use vars      @EXPORT_OK;
21
22 sub populate (@) {
23     return unless @_;
24     my $tmob = Time::tm->new();
25     @$tmob = (
26                 $tm_sec, $tm_min, $tm_hour, $tm_mday, 
27                 $tm_mon, $tm_year, $tm_wday, $tm_yday, 
28                 $tm_isdst )
29             = @_;
30     return $tmob;
31
32
33 sub gmtime (;$)    { populate CORE::gmtime(@_ ? shift : time)}
34 sub gmctime (;$)   { scalar   CORE::gmtime(@_ ? shift : time)} 
35
36 1;
37 __END__
38
39 =head1 NAME
40
41 Time::gmtime - by-name interface to Perl's built-in gmtime() function
42
43 =head1 SYNOPSIS
44
45  use Time::gmtime;
46  $gm = gmtime();
47  printf "The day in Greenwich is %s\n", 
48     (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm->wday() ];
49
50  use Time::gmtime w(:FIELDS;
51  printf "The day in Greenwich is %s\n", 
52     (qw(Sun Mon Tue Wed Thu Fri Sat Sun))[ gm_wday() ];
53
54  $now = gmctime();
55
56  use Time::gmtime;
57  use File::stat;
58  $date_string = gmctime(stat($file)->mtime);
59
60 =head1 DESCRIPTION
61
62 This module's default exports override the core gmtime() function,
63 replacing it with a version that returns "Time::tm" objects.
64 This object has methods that return the similarly named structure field
65 name from the C's tm structure from F<time.h>; namely sec, min, hour,
66 mday, mon, year, wday, yday, and isdst.
67
68 You may also import all the structure fields directly into your namespace
69 as regular variables using the :FIELDS import tag.  (Note that this
70 still overrides your core functions.)  Access these fields as variables
71 named with a preceding C<tm_> in front their method names.  Thus,
72 C<$tm_obj-E<gt>mday()> corresponds to $tm_mday if you import the fields.
73
74 The gmctime() function provides a way of getting at the 
75 scalar sense of the original CORE::gmtime() function.
76
77 To access this functionality without the core overrides,
78 pass the C<use> an empty import list, and then access
79 function functions with their full qualified names.
80 On the other hand, the built-ins are still available
81 via the C<CORE::> pseudo-package.
82
83 =head1 NOTE
84
85 While this class is currently implemented using the Class::Struct
86 module to build a struct-like class, you shouldn't rely upon this.
87
88 =head1 AUTHOR
89
90 Tom Christiansen