jdatetime.gtw

~~LANG:FR@frman:classes-utiles/jdatetime~~

jDateTime is a class encapsulating a date. It defines an API to convert date to
different formats and do some time calculation.

There is different ways to create a jDateTime object:
   * either pass  a date value to jDateTime constructor : year, month, day,
     hour, minute, second arguments are all integer values and optional.
   * either use @@M@setFromString@@ method on a jDateTime object. Its argument
     must be a date-formatted string

Note: for your time calculations, **prefer the use of the object DateTime**.
jDatetime have some limitations (it doesn't work with date lower than 01/01/1970).

===== Retrieving the current date =====

The @@M@now()@@ method allow to set a @@C@jDatetime@@ object to the current date.

<code php>
  $dt = new jDateTime();
 
  $dt->now();
 
  $date = $dt->toString(jDateTime::LANG_DFORMAT);
</code>

@@V@$date@@ content the current date formatted for the current language in the application.


===== Convert a string to date-time =====

@@M@setFromString@@, as said before, takes a string as first argument and an
optional format type as last argument. The latter is a numeric value. jDateTime
defines in its namespace, constants enumerating those formats.

Lists of date and time formats accepted by jDateTime:

^ constantes de classe   ^ format ^
| jDateTime::LANG_DFORMAT | date format of current application lang (with //en//, this is mm/jj/aaaa) |
| jDateTime::LANG_DTFORMAT |date and time format of current application lang |
| jDateTime::LANG_TFORMAT | time format of current application lang |
| jDateTime::LANG_SHORT_DTFORMAT | date and time without seconds formated using the current application lang  |
| jDateTime::LANG_SHORT_TFORMAT | time without seconds formated using the current application lang  |
| jDateTime::DB_DFORMAT | date format of classic database style: "AAAA-MM-JJ" |
| jDateTime::DB_DTFORMAT | date and time format of classic database style: "AAAA-MM-JJ HH:mm:SS" |
| jDateTime::DB_TFORMAT | time format of classic database style: "HH:mm:SS" |
| jDateTime::ISO8601_FORMAT | ISO8601 format |
| jDateTime::RFC822_FORMAT |  RFC822 format "D, d M y H:i:s O" |
| jDateTime::TIMESTAMP_FORMAT | integer, number of seconds since 1/1/1970 |
| jDateTime::FULL_LANG_DATE | full format date (i.e. day of week and month in letter) respecting language conventions (ex: thursday, may 27th 2017) |


Note: LANG_* formats are converted by jDateTime based on locales **format**
file located in jelix module and current lang selected by your application.

Example:

<code php>
  $dt = new jDateTime();

  $dt->setFromString("2017-04-10",jDateTime::DB_DFORMAT);

  echo "your date is ", $dt->year, ",", $dt->month, ",", $dt->day, ",", $dt->hour, ",", $dt->minute, ",", $dt->second;

</code>

You'll have noticed all member properties representing elements of a date.

@@P@defaultFormat@@ property allows to not specify a format for each jDateTime method call. 

<code php>
  $dt = new jDateTime();
  $dt->defaultFormat = jDateTime::DB_DFORMAT;

  $dt->setFromString("2017-04-10");
</code>

===== Convert date-time to string =====

@@M@toString@@ method convert date to string. It accepts an optional argument
specifying a format (see above for formats).

<code php>
  $dt->toString(jDateTime::LANG_DFORMAT);
</code>

===== date-time calculation =====

@@M@sub()@@ and @@M@add()@@ methods does substract or add duration to a date.
You specify duration with the object @@jDuration@@.

<code php>
  $dt = new jDateTime();
  $dt->setFromString("2017-04-10",jDateTime::DB_DFORMAT);

  // substract 2 days
  $dur1 = new jDuration(array('day'=>2));
  $dt->sub($dur1);
  echo $dt->toString(jDateTime::DB_DFORMAT); // displays 2017-04-08

  // add 27h15 hours
  $dur2 = new jDuration(array('hour'=>27, 'minute'=>15));
  $dt->add($dur2);
  echo $dt->toString(jDateTime::DB_DTFORMAT); // displays 2017-04-09 03:15:00

</code>

@@M@durationTo()@@ method gives the duration between two dates. it returns a jDuration object:

<code php>
  $dt = new jDateTime();
  $dt->setFromString("2017-04-10",jDateTime::DB_DFORMAT);

  $dt2 = new jDateTime();
  $dt2->setFromString("2017-04-12",jDateTime::DB_DFORMAT);

  // duration between $dt and $dt2
  $dt3 = $dt->durationTo($dt2);
  echo $duration->months, ' ', $duration->days, ' ', $duration->seconds;
</code>

Note: be aware to use dates higher than 01/01/1970.

It is possible to do some subtraction of dates by using the method @@M@substract()@@
which takes and returns a jDateTime object.

===== date-time comparison =====

@@M@compareTo()@@ method compares two dates

<code php>
  $dt = new jDateTime();
  $dt->setFromString("2017-04-10",jDateTime::DB_DFORMAT);

  $dt2 = new jDateTime();
  $dt2->setFromString("2017-04-12",jDateTime::DB_DFORMAT);

  $result = $dt->compareTo($dt2);
</code>

compareTo returns:

   * -1 if $dt < $dt2
   * 0 if dates are equal
   * 1 if $dt > $dt2