NAME

       Weather::Com::DateTime - date and time class

SYNOPSIS

         #!/usr/bin/perl -w
         use Weather::Com::DateTime;

         my $gmt_offset = 1; # e.g. for Germany in winter
         my $datetime = Weather::Com::DateTime->new($gmt_offset);
         $datetime->set_lsup('02/25/05 11:21 PM Local Time');

         print "This is the date '02/25/05 11:21 PM' in Germany:\n";
         print "Epoc:                    ", $datetime->epoc(), "\n";
         print "GMT (UTC):               ". gmtime($datetime->epoc()). "\n";
         print "My local time:           ". localtime($datetime->epoc()). "\n";
         print "And finally German time: ", $datetime->time(), " o'clock at ",
               $datetime->date(), "\n\n";

DESCRIPTION

       Weather::Com::DateTime objects are used to encapsulate a date or time provided by the OO interface (e.g.
       localtime, sunrise, sunset, etc.).

       This is done because there are many ways to use a date or time and to present it in your programs using
       Weather::Com. This class provides some predefined formats for date and time but also enables you to
       easily define your own ones.

       These objects always represent the local time of a Weather::Com::Location object. That is, if you have a
       location object for New York City and your server running the weather script is located in Los Angeles,
       for example, this line

         print "Sunrise at: ", $location->sunrise()->time(), "\n";

       will print the time of sunrise (in 24h format) in EST and not corresponding to the timezone of Los
       Angeles! If you'd like to now what this is in GMT you could call

         print "Sunrise at: ". gmtime($location->sunrise()->epoc()). "\n";

       or if you want to know when the sun rises at the location in your servers local time than just call

         print "Sunrise at: ". localtime($location->sunrise()->epoc()). "\n";

       There are two ways to get your own date or time format:

       1.  You use the "formatted()" method and provide a format string to it.

       2.  If  you'd  like  to  define  your  own  "date()"  or "time()" method, simply change the corresponding
           methods.

           What you can change in which way  without  destroying  the  whole  class,  is  described  in  section
           INTERFACE.

CONSTRUCTOR

       You usually would not construct an object of this class yourself.  This is implicitely done when you call
       one of the OO interfaces date or time methods.

       The constructor can take a GMT offset in positive or negative hours.

       If one calls the constructor without any GMT offset, we assume you want a GMT object.

METHODS

       epoc(epoc seconds)

       With this method you can set the date and time using epocs (GMT) directly.

       It returns the currently set epoc seconds (GMT).

       formatted(format)

       This  method  returns a date or time formatted in the way you ask for and corresponding to the local time
       of the parent object.

       The "format" you provide to this method has to be a valid Time::Format format. For details  please  refer
       to Time::Format.

       set_date(date)

       With this method one can set the date of the object using an input format like "Feb 13" which is the 13th
       of february of the current year.

       Using this method, the time is set to 00:00. The year is the current one.

       set_time(time)

       With this method one can set the time of the object using an input format like "8:30 AM".

       The date is set to the current date of the host the script is running on.

       set_lsup(lsup)

       With  this  method  one can set the date of the object using the weather.com's special last update format
       that is like "2/12/05 4:50 PM Local Time".

       date()

       Returns the date in the format "1. February 2005".

       time()

       Returns the time in the format "22:15".

       time_ampm()

       Returns the time in the format "10:15 PM".

       weekday()

       Returns the day of week with like "Wednesday".

       day()

       Returns the day in month.

       month()

       Returns the name of the month.

       mon()

       Returns the number of the month

       year()

       Returns the year (4 digits).

AUTHOR

       Thomas Schnuecker, <thomas@schnuecker.de>

COPYRIGHT AND LICENSE

       Copyright (C) 2004-2007 by Thomas Schnuecker

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

       The  data  provided  by  weather.com  and made accessible by this OO interface can be used for free under
       special  terms.   Please  have  a  look   at   the   application   programming   guide   of   weather.com
       (<http://www.weather.com/services/xmloap.html>)!

perl v5.10.0                                       2007-07-09                        Weather::Com::DateTime(3pm)