| 1 | package RWDE::Time; | ||
| 2 | |||
| 3 | use strict; | ||
| 4 | use warnings; | ||
| 5 | |||
| 6 | use RWDE::DB::Record; | ||
| 7 | use RWDE::DB::DefaultDB; | ||
| 8 | |||
| 9 | use base qw(RWDE::DB::DefaultDB RWDE::DB::Record); | ||
| 10 | |||
| 11 | use vars qw($VERSION); | ||
| 12 | $VERSION = sprintf "%d", q$Revision: 516 $ =~ /(\d+)/; | ||
| 13 | |||
| 14 | =pod | ||
| 15 | |||
| 16 | =head1 RWDE::Time | ||
| 17 | |||
| 18 | Class for performing time related queries. RWDE doesn't use any external perl libraries, instead | ||
| 19 | it queries the database set up in the project configuration file. | ||
| 20 | |||
| 21 | =cut | ||
| 22 | |||
| 23 | |||
| 24 | =head2 fetch_time({ timestamp, interval }) | ||
| 25 | |||
| 26 | Fetch a calculated date. Provided a timestamp and the desired interval the database will be queried | ||
| 27 | and the resulting calculation returned back. An added bonus is that the standard sql for dates can be | ||
| 28 | used here when passing your parameters. | ||
| 29 | |||
| 30 | For example, to return the timestamp representing 5 days for right now: | ||
| 31 | |||
| 32 | RWDE::Time->fetch_time({ timestamp => 'now()', interval => "5 days"}); | ||
| 33 | |||
| 34 | =cut | ||
| 35 | |||
| 36 | sub fetch_time { | ||
| 37 | my ($self, $params) = @_; | ||
| 38 | |||
| 39 | my @required = qw( timestamp interval ); | ||
| 40 | RWDE::RObject->check_params({ required => \@required, supplied => $params }); | ||
| 41 | |||
| 42 | #insert regex for timestamp validation and interval validation... | ||
| 43 | |||
| 44 | my $select = 'CAST(? as timestamp) + CAST(? as interval)'; | ||
| 45 | my @query_params = ($$params{timestamp}, $$params{interval}); | ||
| 46 | |||
| 47 | return $self->fetch_single({ select => $select, query_params => \@query_params }); | ||
| 48 | } | ||
| 49 | |||
| 50 | =head2 fetch_difference({ start_stamp, stop_stamp }) | ||
| 51 | |||
| 52 | Fetch the number of days elapsed between two dates. Provided a start and stop date return the number of full days | ||
| 53 | that have passed between the two. An added bonus is that the standard sql for dates can be used here when passing | ||
| 54 | your parameters. | ||
| 55 | |||
| 56 | Note the parameters can be formatted as timestamps but the method will cast them to dates anyway. If you are | ||
| 57 | looking for the total elapsed time between two timestamps use fetch_exact_difference. | ||
| 58 | |||
| 59 | For example, to return how many days have passed since New Years 2008: | ||
| 60 | |||
| 61 | RWDE::Time->fetch_diff({ start_stamp => '01/01/2008 00:00:00', stop_stamp => 'now()' }); | ||
| 62 | |||
| 63 | =cut | ||
| 64 | |||
| 65 | sub fetch_diff { | ||
| 66 | my ($self, $params) = @_; | ||
| 67 | |||
| 68 | if (not defined $$params{start_stamp} or not defined $$params{stop_stamp}) { | ||
| 69 | return; | ||
| 70 | } | ||
| 71 | |||
| 72 | my $select = 'CAST(? as date) - CAST(? as date)'; | ||
| 73 | |||
| 74 | my @query_params = ($$params{stop_stamp}, $$params{start_stamp}); | ||
| 75 | |||
| 76 | return $self->fetch_single({ select => $select, query_params => \@query_params }); | ||
| 77 | } | ||
| 78 | |||
| 79 | =head2 is_before({ start_stamp, stop_stamp }) | ||
| 80 | |||
| 81 | Returns true if start_stamp is before stop_stamp, false otherwise | ||
| 82 | |||
| 83 | =cut | ||
| 84 | |||
| 85 | sub is_before{ | ||
| 86 | my ($self, $params) = @_; | ||
| 87 | |||
| 88 | RWDE::RObject->check_params({ required => ['start_stamp','stop_stamp'], supplied => $params }); | ||
| 89 | |||
| 90 | #insert regex for timestamp validation and interval validation... | ||
| 91 | |||
| 92 | my $select = "to_char(CAST(? as timestamp) - CAST(? as timestamp),'SS')"; | ||
| 93 | |||
| 94 | my @query_params = ($$params{stop_stamp}, $$params{start_stamp}); | ||
| 95 | |||
| 96 | my $diff = $self->fetch_single({ select => $select, query_params => \@query_params }); | ||
| 97 | |||
| 98 | if ($diff > 0) { | ||
| 99 | return 1; | ||
| 100 | } | ||
| 101 | else{ | ||
| 102 | return 0; | ||
| 103 | } | ||
| 104 | } | ||
| 105 | |||
| 106 | =head2 now() | ||
| 107 | |||
| 108 | Fetch the timestamp that currently represents exactly "now". | ||
| 109 | |||
| 110 | This is useful for timestamping events within the system, etc. | ||
| 111 | |||
| 112 | RWDE::Time->now() would returns a timestamp that conforms to your database default timestamp representation | ||
| 113 | |||
| 114 | =cut | ||
| 115 | |||
| 116 | sub now { | ||
| 117 | my ($self, $params) = @_; | ||
| 118 | |||
| 119 | return $self->fetch_time({ timestamp => 'NOW()', interval => 0 }); | ||
| 120 | } | ||
| 121 | |||
| 122 | =head2 days_passed | ||
| 123 | |||
| 124 | This is a macro to fetch_diff whereby the ending timestamp is always represented by the current date. | ||
| 125 | |||
| 126 | This simply returns back the number of days that have passed between the start stamp and the time when | ||
| 127 | the method is executed. | ||
| 128 | |||
| 129 | =cut | ||
| 130 | |||
| 131 | sub days_passed { | ||
| 132 | my ($self, $params) = @_; | ||
| 133 | |||
| 134 | my $interval = RWDE::Time->fetch_diff({ start_stamp => $$params{timestamp}, stop_stamp => 'now()' }); | ||
| 135 | |||
| 136 | # extract the number from the db response with the optional minus | ||
| 137 | #$interval =~ m/([-]?\d+)\s+(day)/; | ||
| 138 | |||
| 139 | #my $days = $1; | ||
| 140 | #unless (defined($days)) { | ||
| 141 | # $days = 0; | ||
| 142 | #} | ||
| 143 | |||
| 144 | return $interval; | ||
| 145 | } | ||
| 146 | |||
| 147 | =head2 format_date | ||
| 148 | |||
| 149 | Generate a time hash that represents the timestamp parameter. | ||
| 150 | |||
| 151 | The method parses through the timestamp and separates each of the timestamp components into a separate key. | ||
| 152 | date, time, year, month, and day are all represented within the time hash | ||
| 153 | |||
| 154 | =cut | ||
| 155 | |||
| 156 | sub format_date { | ||
| 157 | my ($self, $params) = @_; | ||
| 158 | |||
| 159 | my @required = qw( timestamp ); | ||
| 160 | RWDE::RObject->check_params({ required => \@required, supplied => $params }); | ||
| 161 | |||
| 162 | my @parts = split / /, $$params{timestamp}; | ||
| 163 | |||
| 164 | my $time = {}; | ||
| 165 | $$time{date} = $parts[0]; | ||
| 166 | $$time{time} = $parts[1]; | ||
| 167 | |||
| 168 | @parts = split(/-/, $$time{date}); | ||
| 169 | |||
| 170 | $$time{year} = $parts[0]; | ||
| 171 | $$time{month} = $parts[1]; | ||
| 172 | $$time{day} = $parts[2]; | ||
| 173 | |||
| 174 | return $time; | ||
| 175 | } | ||
| 176 | |||
| 177 | =head2 format_qdate | ||
| 178 | |||
| 179 | Generate a qdate from the passed in timestamp parameter. | ||
| 180 | |||
| 181 | =cut | ||
| 182 | |||
| 183 | sub format_qdate { | ||
| 184 | my ($self, $params) = @_; | ||
| 185 | |||
| 186 | my @required = qw( timestamp ); | ||
| 187 | RWDE::RObject->check_params({ required => \@required, supplied => $params }); | ||
| 188 | |||
| 189 | my $time = $self->format_date({ timestamp => $$params{timestamp} }); | ||
| 190 | |||
| 191 | return ("$$time{month}/$$time{day}/$$time{year}"); | ||
| 192 | } | ||
| 193 | |||
| 194 | =head2 format_rfc | ||
| 195 | |||
| 196 | Generate an RFC 822 formatted date from the passed in timestamp parameter. | ||
| 197 | |||
| 198 | RSS requires this specific RFC date formatting | ||
| 199 | |||
| 200 | =cut | ||
| 201 | |||
| 202 | sub format_rfc { | ||
| 203 | my ($self, $params) = @_; | ||
| 204 | |||
| 205 | my @required = qw( timestamp ); | ||
| 206 | RWDE::RObject->check_params({ required => \@required, supplied => $params }); | ||
| 207 | |||
| 208 | my $select = 'to_char(?::TIMESTAMP WITH TIME ZONE, ?)'; | ||
| 209 | my @query_params = ($$params{timestamp}, 'Dy, DD Mon YYYY HH12:MI:SS TZ'); | ||
| 210 | |||
| 211 | return $self->fetch_single({ select => $select, query_params => \@query_params }); | ||
| 212 | } | ||
| 213 | |||
| 214 | =head2 format_human | ||
| 215 | |||
| 216 | Generate an arbitrary human readable date from the passed in timestamp parameter. | ||
| 217 | |||
| 218 | The returned date formating is: YYYY-MM-DD HH12:MI:SS TZ | ||
| 219 | |||
| 220 | =cut | ||
| 221 | |||
| 222 | sub format_human { | ||
| 223 | my ($self, $params) = @_; | ||
| 224 | |||
| 225 | my @required = qw( timestamp ); | ||
| 226 | RWDE::RObject->check_params({ required => \@required, supplied => $params }); | ||
| 227 | |||
| 228 | my $select = 'to_char(?::TIMESTAMP WITH TIME ZONE, ?)'; | ||
| 229 | my @query_params = ($$params{timestamp}, 'YYYY-MM-DD HH12:MI:SS TZ'); | ||
| 230 | |||
| 231 | return $self->fetch_single({ select => $select, query_params => \@query_params }); | ||
| 232 | } | ||
| 233 | |||
| 234 | =head2 extract_dow | ||
| 235 | |||
| 236 | Determine the day of week of a given timestamp parameter | ||
| 237 | |||
| 238 | =cut | ||
| 239 | |||
| 240 | sub extract_dow { | ||
| 241 | my ($self, $params) = @_; | ||
| 242 | my @required = qw( timestamp ); | ||
| 243 | RWDE::RObject->check_params({ required => \@required, supplied => $params }); | ||
| 244 | |||
| 245 | my $select = 'EXTRACT(DOW FROM ?::timestamp)'; | ||
| 246 | my @query_params = ($$params{timestamp}); | ||
| 247 | |||
| 248 | return $self->fetch_single({ select => $select, query_params => \@query_params }); | ||
| 249 | } | ||
| 250 | |||
| 251 | =head2 db_format_timestamp | ||
| 252 | |||
| 253 | Take a database timestamp and make it look nice for humans to read. | ||
| 254 | |||
| 255 | This is for Postgres database which tack on a numeric timezone. | ||
| 256 | |||
| 257 | =cut | ||
| 258 | |||
| 259 | sub db_format_timestamp { | ||
| 260 | my ($self, $db_timestamp) = @_; | ||
| 261 | |||
| 262 | return substr $db_timestamp, 0, 19; | ||
| 263 | } | ||
| 264 | |||
| 265 | 1; |