====== lmbDate ======

**Класс lmbDate** - инкапсулирует дату (под датой здесь понимается полная дата, то есть число и время) и предоставляет методы для ее работы с ней, в частности модификации и форматирования. 

Ниже идут примеры использования различных методов класса lmbDate сгрупированных по назначению.


===== Инициализация объектов класса lmbDate =====

**Конструктор lmbDate** может принимать различное число параметров:

**Без параметров, тогда будет использован timestamp из time()**
<code php>
  lmb_require('limb/datetime/src/lmbDate.class.php');
  $date = new lmbDate(); // Эквивалентно new lmbDate(time());
</code>

**Целочисленное число, которое будет воспринято как timestamp:**

<code php>
 $date = new lmbDate(time());
 $date = new lmbDate(1178867400);
</code>
 
**2 целочисленных числа, тогда первое будет воспринято как timestamp, а второе - как часовой пояс:**

<code php>
 $date = new lmbDate(time(), 2);
</code>
**Объект класса lmbDate, тогда по сути мы создадим клон переданного объекта:**

<code php>
 $date1 = new lmbDate(time());
 $date2 = new lmbDate($date1);
</code>

**6 целочисленных чисел, которые означают соответственно год, месяц, день, час, минуту и секунду. Любое количество параметров, кроме года и месяца можно опустить (будут использованы нулевые значения или 1 для дня):**

<code php>
 $date1 = new lmbDate(2006, 12, 1, 12, 20, 20);
 $date2 = new lmbDate(2006, 12, 1, 12, 20); // эквивалентно new lmbDate(2006, 12, 1, 12, 20, 0)
 $date3 = new lmbDate(2006, 12, 1, 12); // эквивалентно new lmbDate(2006, 12, 1, 12, 0, 0)
 $date4 = new lmbDate(2006, 12); // эквивалентно new lmbDate(2006, 12, 1)
</code>

**7 целочисленных чисел, которые означают соответственно год, месяц, день, час, минуту, секунду и часовой пояс.:**
<code php>
 $date = new lmbDate(2006, 12, 1, 12, 20, 20, "Etc/GMT-3");
</code>

**Строку с датой в ISO-формате:**
<code php>
 $date1 = new lmbDate("2006-12-01 12:20:20");
 $date2 = new lmbDate("2006-12-01 12:20"); // эквивалентно new lmbDate("2006-12-01 12:20:0");
 $date3 = new lmbDate("2006-12-01"); // эквивалентно new lmbDate("2006-12-01 00:00:00");
 $date4 = new lmbDate("2006-12-01 12:20:20", "Etc/GMT-3");
</code>

Помимо вызова конструктора lmbDate есть несколько других способов создать объект класса lmbDate:
  * **create(...)** - в целом повторяет сигнатуру конструктора, но этот метод удобно использовать в chain-операциях (см. пример ниже), так как PHP не позволяет вызывать методы объекта сразу после вызова конструктора.
  * **createByDays($days)** - создает дату на основании количества дней, прошедних с 1 января 1970 года.

Например:

<code php>
  $date = lmbDate :: create("2006-12-01 12:20:20")->addMinute(10)->addSecond(30); // вместо lmbDate("2006-12-01 12:20:20")->addMinute(10)->addSecond(30); , что в PHP запрещено.
  $days = $date->getDateDays();
  $date2 = lmbDate :: createByDays($days + 3); // получили дату на 3 дня больше, то есть "2006-12-03 12:30:50"
</code>

===== Получение информации о текущей дате =====

lmbDate содержит большой набор методов для получения информации о дате:
  * **getStamp()** - возвращает timestamp даты
  * **getYear()** - возвращает значение года
  * **getMonth()** - возвращает значение месяца (1 - 12)
  * **getDay()** - возвращает значение дня (1 - 31)
  * **getHour()** - возвращает значение часа (0 - 23)
  * **getMinute()** - возвращает значение минуты (0 - 59)
  * **getSecond()** - возвращает значение секунды (0 - 59)
  * **getTimeZone()** - возвращает номер часового пояса
  * **getTimeZoneObject()** - возвращает объект класса [[lmbTimeZone]] для часового пояса
  * **getPhpDayOfWeek()** - возвращает номер дня недели, найденное при помощи php-функции date('w') (0 - Воскресенье).
  * **getIntlDayOfWeek()** - возвращает номер дня недели с коррекцией (0 - Понедельник, 6 - Воскресенье).
  * **isLeapYear()** - возвращает true, если год високосный.
  * **getDayOfYear()** - возвращает порядковый номер дня в указанном году, начиная с 1. Например, 3 февраля - это 34.
  * **getWeekOfYear()** возвращает порядковый номер недели в указанном году, начиная с 1. Например, 31 декабря - это 52

===== Установка дня, соответствующего началу недели =====

lmbDate содержит статическую переменную **$week_starts_at**, которая содержит значение дня, который следует считать первым днем недели. По-умолчанию, эта переменная содержит 1, что соответствует Понедельнику. Если стоит значение 0 - это будет значит, что первый день недели - Воскресенье.

Для установки этой переменной есть метод lmbDate :: **setWeekStartsAt($n)**


===== Создание нового объекта lmbDate на основе существующего =====

lmbDate ведет себя как **value object**, то есть при его изменении всегда создается **новый** объект. lmbDate содержит большой набор методов, которые позволяют получить новый объект класса lmbDate на основе существующего.

Начнем с самых банальных:
  * **setYear($y)**
  * **setMonth($m)**
  * **setDay($d)**
  * **setHour($h)**
  * **setMinute($m)**
  * **setSecond($s)**

Каждый из этих методов возвращает объект класса lmbDate с новой датой.

Пример:
<code php>
  $date1 = new lmbDate(time());
  $date2 = $date1->setHour(0)->setMinute(0)->setSecond(0);
</code>

lmbDate поддерживает некоторое подобие **арифметических операций**:

  * **addYear($n=1)**
  * **addMonth($n=1)**
  * **addWeek($n=1)**
  * **addDay($n=1)**
  * **addHour($n=1)**
  * **addMinute($n=1)**
  * **addSecond($n=1)**

**$n** - может быть **отрицательным числом**, то есть таким образом можно отнимать года, месяца, дни и т.д.

Например:
<code php>
 // Для получения последнего числа текущего месяца.
 $date2 = $date->setDay(1)->addMonth(1)->addDay(-1);
</code>

Есть так же группа более специфичных методов, которые могут быть использованы, например, при построении календарей:

  * **getBeginOfDay()** - возвращает дату (объект класса lmbDate), у которой час, минута и секунда сброшены на 0.
  * **getEndOfDay()** - возвращает дату (объект класса lmbDate), у которой час = 23, минута =59 и секунда = 59.
  * **getBeginOfWeek()** - возвращает дату, которая соответствует первому дню недели от базовой даты. То, какому дню будет соответствовать первый день недели - Воскресенью или Понедельнику, зависит от статической переменной lmbDate :: week_starts_at.
  * **getEndOfWeek()** - возвращает дату, которая соответствует поснеднему дню недели от базовой даты. 
  * **getBeginOfMonth()** - возвращает дату, которая соответствует первому числу месяца базовой даты
  * **getEndOfMonth()** - возвращает дату, которая соответствует последему числу месяца базовой даты
  * **getBeginOfYear()** - возвращает дату, которая соответствует первому числу года базовой даты
  * **getEndOfYear()** - возвращает дату, которая соответствует последнему числу года базовой даты

  * **stripTime()** - аналог getBeginOfDay().
  * **stripDate()** - сбрасывает на 0 год, месяц и день.


===== Методы для сравнения дат =====

lmbDate также содержит набор методов для сравнения дат между собой:
  * **compare($d)** - возвращает 0, если даты равны, 1, если текущая дата после $d и -1, если текущая дата до $d.
  * **isBefore($d)** - возвращает true, если текущая дата до $d
  * **isAfter($d)** - возвращает true, если текущая дата после $d
  * **isEqual($d)** - возвращает true, если даты равны.
  * **isEqualDate($when)** - возвращает true, если числа дат равны

===== Методы для форматирования дат =====

lmbDate также содержит базовые методы для вывода даты (форматирования) в ISO-формате:

  * **getIsoDate($with_seconds = true)** - полная дата в ISO-формате с секундами или без.
  * **getIsoShortDate()** - только число без времени в ISO-формате
  * **getIsoTime($with_seconds = true)** - только время с секундами или без в ISO-формате
  * **getIsoShortTime()** - только время без секунда в ISO-формате

===== Дополнительные методы =====

  * **stampToIso($stamp)** - создает объект lmbDate на основе timestamp и форматирует его до ISO-даты.
  * **toString()** - алиас для getIsoDate()
  * **toUTC()** - возвращает объект даты приведенный к 0-му часовому поясу.