document date information

diff --git a/lib/DBIx/Class/SQLMaker.pm b/lib/DBIx/Class/SQLMaker.pm
index 4f794d2..4b444f3 100644 (file)
--- a/lib/DBIx/Class/SQLMaker.pm
+++ b/lib/DBIx/Class/SQLMaker.pm
@@ -31,6 +31,61 @@ Currently the enhancements to L<SQL::Abstract> are:
 
 =item * The L</-value> operator
 
+=item * Date Functions:
+
+Note that for the following functions use different functions for different
+RDBMS'.  See the SQLMaker docs for your database to see what functions are
+used.
+
+=over
+
+=item * -dt => $date_time_obj
+
+This function will convert the passed datetime to whatever format the current
+database prefers
+
+=item * -dt_diff => [$unit, \'foo.date_from', \'foo.date_to']
+
+This function will diff two dates and return the units requested. Note that
+it correctly recurses if you pass it something like a function or a date value.
+Also note that not all RDBMS' are equal; some units supported on some databases
+and some are supported on others.  See the documentation for the SQLMaker class
+for your database.
+
+=item * -dt_get => [$part, \'foo.date_col']
+
+This function will extract the passed part from the passed column.  Note that
+it correctly recurses if you pass it something like a function or a date value.
+Also note that not all RDBMS' are equal; some parts supported on some databases
+and some are supported on others.  See the documentation for the SQLMaker class
+for your database.
+
+=item * -dt_year => \'foo.date_col'
+
+A shortcut for -dt_get => [year => ...]
+
+=item * -dt_month => \'foo.date_col'
+
+A shortcut for -dt_get => [month => ...]
+
+=item * -dt_day => \'foo.date_col'
+
+A shortcut for -dt_get => [day_of_month => ...]
+
+=item * -dt_hour => \'foo.date_col'
+
+A shortcut for -dt_get => [hour => ...]
+
+=item * -dt_minute => \'foo.date_col'
+
+A shortcut for -dt_get => [minute => ...]
+
+=item * -dt_second => \'foo.date_col'
+
+A shortcut for -dt_get => [second => ...]
+
+=back
+
 =back
 
 Another operator is C<-func> that allows you to call SQL functions with

diff --git a/lib/DBIx/Class/SQLMaker/MSSQL.pm b/lib/DBIx/Class/SQLMaker/MSSQL.pm
index 99a45f5..9800945 100644 (file)
--- a/lib/DBIx/Class/SQLMaker/MSSQL.pm
+++ b/lib/DBIx/Class/SQLMaker/MSSQL.pm
@@ -42,5 +42,34 @@ sub _rno_default_order {
   }
 }
 
+=head1 DATE FUNCTION IMPLEMENTATION
+
+The function used to extract date information is C<DATEPART>, which supports
+
+ year
+ quarter
+ month
+ day_of_year
+ day_of_month
+ week
+ day_of_week
+ hour
+ minute
+ second
+ millisecond
+
+The function used to diff dates is C<DATEDIFF>, which supports
+
+ year
+ quarter
+ month
+ day
+ week
+ hour
+ minute
+ second
+ millisecond
+
+=cut
 
 1;

diff --git a/lib/DBIx/Class/SQLMaker/MySQL.pm b/lib/DBIx/Class/SQLMaker/MySQL.pm
index 465e6b0..7c8a8ee 100644 (file)
--- a/lib/DBIx/Class/SQLMaker/MySQL.pm
+++ b/lib/DBIx/Class/SQLMaker/MySQL.pm
@@ -55,7 +55,6 @@ sub _lock_select {
     month              => 'MONTH',
     quarter            => 'QUARTER',
     year               => 'YEAR',
-    # should we support these or what?
     second_microsecond => 'SECOND_MICROSECOND',
     minute_microsecond => 'MINUTE_MICROSECOND',
     minute_second      => 'MINUTE_SECOND',
@@ -84,4 +83,56 @@ sub _lock_select {
   }
 }
 
+=head1 DATE FUNCTION IMPLEMENTATION
+
+=head1 DATE FUNCTION IMPLEMENTATION
+
+The function used to extract date information is C<DATEPART>, which supports
+
+ microsecond
+ second
+ minute
+ hour
+ day_of_month
+ week
+ month
+ quarter
+ year
+ second_microsecond
+ minute_microsecond
+ minute_second
+ hour_microsecond
+ hour_second
+ hour_minute
+ day_microsecond
+ day_second
+ day_minute
+ day_hour
+ year_month
+
+The function used to diff dates is C<TIMESTAMPDIFF>, which supports
+
+ microsecond
+ second
+ minute
+ hour
+ day
+ week
+ month
+ quarter
+ year
+ second_microsecond
+ minute_microsecond
+ minute_second
+ hour_microsecond
+ hour_second
+ hour_minute
+ day_microsecond
+ day_second
+ day_minute
+ day_hour
+ year_month
+
+=cut
+
 1;

diff --git a/lib/DBIx/Class/SQLMaker/Oracle.pm b/lib/DBIx/Class/SQLMaker/Oracle.pm
index 10465a0..aa6a3ba 100644 (file)
--- a/lib/DBIx/Class/SQLMaker/Oracle.pm
+++ b/lib/DBIx/Class/SQLMaker/Oracle.pm
@@ -287,4 +287,36 @@ sub _insert_returning {
     "TIMESTAMPDIFF($part_map{$_[1]}, $_[2], $_[3])"
   }
 }
+
+=head1 DATE FUNCTION IMPLEMENTATION
+
+A separate function is used for each extraction type in Oracle.  The types
+supported are:
+
+ month
+ day_of_month
+ day_of_year
+ day_of_quarter
+ quarter
+ month_of_quarter
+ year
+ hour
+ minute
+ second
+ week_of_quarter
+ week_of_year
+
+The function used to diff dates is C<TIMESTAMPDIFF>, which supports
+
+ second
+ minute
+ hour
+ week
+ quarter
+ month
+ day_of_year
+ year
+
+=cut
+
 1;

diff --git a/lib/DBIx/Class/SQLMaker/Pg.pm b/lib/DBIx/Class/SQLMaker/Pg.pm
index baeb5bf..0f0e588 100644 (file)
--- a/lib/DBIx/Class/SQLMaker/Pg.pm
+++ b/lib/DBIx/Class/SQLMaker/Pg.pm
@@ -43,4 +43,55 @@ use Carp::Clan qw/^DBIx::Class|^SQL::Abstract/;
   }
 }
 
+=head1 DATE FUNCTION IMPLEMENTATION
+
+The function used to extract date information is C<EXTRACT>, which supports
+
+ century
+ decade
+ day_of_month
+ day_of_week
+ day_of_year
+ seconds_since_epoch
+ hour
+ iso_day_of_week
+ iso_year
+ microsecond
+ millenium
+ millisecond
+ minute
+ month
+ quarter
+ second
+ timezone
+ timezone_hour
+ timezone_minute
+ week
+ year
+
+The function used to diff dates is subtraction and C<EXTRACT>, which supports
+
+ century
+ decade
+ day
+ seconds_since_epoch
+ hour
+ iso_day_of_week
+ iso_year
+ microsecond
+ millenium
+ millisecond
+ minute
+ month
+ quarter
+ second
+ timezone
+ timezone_hour
+ timezone_minute
+ week
+ year
+
+=cut
+
+
 1;

diff --git a/lib/DBIx/Class/SQLMaker/SQLite.pm b/lib/DBIx/Class/SQLMaker/SQLite.pm
index 5c2aac3..bd0212c 100644 (file)
--- a/lib/DBIx/Class/SQLMaker/SQLite.pm
+++ b/lib/DBIx/Class/SQLMaker/SQLite.pm
@@ -21,7 +21,6 @@ sub _lock_select () { '' };
      day_of_week         => 'w',
      week                => 'W',
      year                => 'Y',
-     # should we support these or what?
      julian_day          => 'J',
      seconds_since_epoch => 's',
      fractional_seconds  => 'f',
@@ -45,4 +44,29 @@ sub _datetime_diff_sql {
    }
 }
 
+=head1 DATE FUNCTION IMPLEMENTATION
+
+The function used to extract date information is C<STRFTIME>, which supports
+
+ month
+ day_of_month
+ year
+ hour
+ day_of_year
+ minute
+ seconds
+ day_of_week
+ week
+ year
+ julian_day
+ seconds_since_epoch
+ fractional_seconds
+
+The function used to diff dates differs and only supports
+
+ day
+ second
+
+=cut
+
 1;