new

 my $ft = Astro::App::Satpass2::FormatTime->new();

This method instantiates a time formatter object.

gmt

 $ft->gmt ( 1 );
 print 'The gmt attribute is ', $ft->gmt() ? "true\n" : "false\n";

This method is both accessor and mutator for the "gmt" attribute. This boolean attribute provides a default for the "gmt" argument of format_datetime().

If called with an argument, the argument becomes the new value of the "gmt" attribute. The object is returned to allow call chaining.

If called without an argument, the current value of the "gmt" attribute is returned.

format_datetime

 print 'Time now: ', $ft->format_datetime( '%H:%M:%S', time, 0 ), "\n";

This attribute uses the format passed in the first argument to format the Perl time passed in the second argument. The third argument, if defined, overrides the gmt attribute, forcing the time to be GMT if true, or local if false.

The string representing the formatted time is returned.

This method must be overridden by the subclass. The override may use the value of the tz attribute to format the local time in the given zone, provided the value of tz is defined and not ''. The override may accept times in formats other than Perl epoch, but it need not document or support these.

format_datetime_width

 my $wid = $ft->format_datetime_width( '%H:%M:%S', $gmt );

This method computes the maximum width required to display a time in the given format. This is done by assuming only the month, day, and meridian might affect the width, and then trying each and returning the width of the widest.

The optional $gmt argument, if defined, overrides the gmt attribute.

__format_datetime_width_adjust_object

 my $ref = $self->__format_datetime_width_adjust_object( undef, year => 2100 );

This method must be overridden by the subclass. It exists to support format_datetime_width(), and should not be called directly. It is not itself supported, in the sense that the author reserves the right to change or revoke it without notice. Though since this whole mess is unsupported in that sense, this statement is redundant.

This method takes as its arguments a time in any format supported by the format_datetime() method, the name of a component ("year", "month", "day", "hour", "minute", or "second"), and a value for that component. The time is returned with the given component set to the given value. If the time is "undef", a new time representing "01-Jan-2100 00:00:00" is constructed, adjusted, and returned.

round_time

 $ft->round_time( 60 );
 print 'Time rounded to ', $ft->round_time(), ' seconds';

This method is both accessor and mutator for the time rounding specification maintained on behalf of the subclass. If the subclass overrides this, it must call SUPER::round_time with the same arguments.

If called with an argument, the argument becomes the new rounding specification, in seconds. The argument must be an integer number of seconds, the special-cased strings 'second', 'minute' or 'hour' (which specify 1, 60 and 3600 respectively), or "undef" to turn off rounding. Be aware that if rounding is turned off the time formatter may truncate the time.

If called without an argument, the current value of the "round_time" attribute is returned. This will always be an integer.

The default value is 1.

__round_time_value

 $time = $ft->__round_time_value( $time );

This method exists to support the rounding of time values by subclasses, and should not be called directly. It is not itself supported, in the sense that the author reserves the right to change or revoke it without notice.

This method takes as its argument an epoch time, and returns it rounded to the precision specified by "$ft->round_time()".

tz

 $ft->tz( 'mst7mdt' );
 print 'Current zone: ', $ft->tz(), "\n";

This method is both accessor and mutator for the time zone, maintained on behalf of the subclass. If the subclass overrides this, it must call SUPER::tz with the same arguments.

If called with an argument, the argument becomes the new zone, with either '' or "undef" representing the default zone. The object is returned to allow call chaining.

If called without an argument, the current value of the "tz" attribute is returned.