Timepoints -- Durations -- Intervals (Periods) -- Special Value Handling

Timepoints

В этом разделе описаны некоторые основные арифметические правила, которые могут быть выполнены с точками времени. В целом, точки времени поддерживают базовую арифметику в сочетании со следующими сроками:

      Timepoint + Duration  --> Timepoint
      Timepoint - Duration  --> Timepoint
      Timepoint - Timepoint --> Duration
    

В отличие от обычных числовых типов, следующие операции не определены:

      Duration + Timepoint  --> Undefined
      Duration - Timepoint  --> Undefined
      Timepoint + Timepoint --> Undefined
    

Durations

Продолжительность представляет собой промежуток времени и может иметь положительные и отрицательные значения. Часто полезно уметь выполнять вычисления с другими длительностями и простыми интегральными значениями. Ниже описаны эти расчеты:

      Duration + Duration  --> Duration
      Duration - Duration  --> Duration
      
      Duration * Integer   --> Duration
      Integer  * Duration  --> Duration
      Duration / Integer   --> Duration  (Integer Division rules)
    

Intervals (Periods)

Интервальная логика чрезвычайно полезна для упрощения многих «расчетов» по датам и времени. Ниже описаны операции, предоставляемые периодами, которые основаны на полуоткрытом диапазоне. Следующие операции вычисляют новые периоды времени на основе двух входных периодов времени:

Timeperiod intersection Timeperiod --> Timeperiod 
  (null interval if no intersection)
Timeperiod merge Timeperiod        --> Timeperiod 
  (null interval if no intersection)
Timeperiod shift Duration          --> Timeperiod 
  (shift start and end by duration amount)
    

Кроме того, периоды поддерживают различные запросы, которые вычисляют булевы результаты. Первый набор — это калукуляции с другими периодами времени:

  Timeperiod == Timeperiod           --> bool
  Timeperiod < Timeperiod            --> bool (true if lhs.last <= rhs.begin)
  Timeperiod intersects Timeperiod   --> bool
  Timeperiod contains Timeperiod     --> bool
  Timeperiod is_adjacent Timeperiod  --> bool 
    

Следующие вычисления выполняются против точки времени.

  Timeperiod contains Timepoint      --> bool
  Timeperiod is_before Timepoint     --> bool
  Timeperiod is_after Timepoint      --> bool 
    

Special Value Handling

Для многих временных задач для типов Продолжительность и Точка Времени полезно поддерживать специальные значения, такие как время без даты (NADT) и бесконечность. В общем случае специальные значения, такие как время без даты (NADT) и бесконечность, должны следовать правилам, таким как значения с плавающей запятой. Обратите внимание, что должна быть возможность настроить системы на основе NADT, чтобы бросить исключение вместо результата в NADT.

  Timepoint(NADT) + Duration --> Timepoint(NADT)
  Timepoint(∞) + Duration    --> Timepoint(∞)
  Timepoint + Duration(∞)    --> Timepoint(∞)
  Timepoint - Duration(∞)    --> Timepoint(-∞)
    

При выполнении операций как на положительных, так и на отрицательных бесконечностях библиотека будет давать результаты, соответствующие следующим.

  Timepoint(+∞) + Duration(-∞) --> NADT
  Duration(+∞) + Duration(-∞)  --> NADT
  Duration(±∞) * Zero          --> NADT
  
  Duration(∞) * Integer(Not Zero) --> Duration(∞)
  Duration(+∞) * -Integer         --> Duration(-∞)
  Duration(∞) / Integer           --> Duration(∞)
    

Unavoidable Trade-offs

Библиотека делает все возможное, чтобы предоставить все, что может захотеть пользователь, но есть определенные неотъемлемые ограничения, которые ограничивают то, что может сделать любая временная библиотека. В частности, пользователь должен выбрать, какие из следующих трех возможностей необходимы в конкретном приложении:

Некоторые библиотеки могут неявно пообещать доставить все три, но если вы действительно подвергнете их испытанию, только две могут быть верными одновременно. Это ограничение не является недостатком при проектировании или внедрении какой-либо конкретной библиотеки; скорее оно является следствием того, как различные системы времени определяются международными стандартами. Рассмотрим каждый из трех случаев:

Если вы хотите точного согласования с настенным временем, вы должны использовать UTC или местное время. Если вы вычислите продолжительность, вычитая одно время UTC из другого, и вы хотите получить точный ответ на второй, два раза не должны быть слишком далеко в будущем, потому что високосные секунды влияют на подсчет, но определяются только за 6 месяцев. При местном времени расчет будущей продолжительности может быть отложен на целый час, поскольку законодательные органы могут изменять правила DST по своему усмотрению.

Если вы хотите справиться с настенными часами в будущем, вы не сможете (в общем случае) рассчитать точную продолжительность по тем же причинам, которые описаны выше.

Если вам нужны точные вычисления с будущим временем, вам придется использовать TAI или эквивалент, но отображение от TAI до UTC или местного времени зависит от секунд прыжка, поэтому у вас не будет точного согласия с временем настенных часов.

Stability, Predictability, and Approximations

Вот некоторые основные теории, которые помогают объяснить, что происходит. Помните, что временный тип, как и любой абстрактный тип данных (ADT), представляет собой набор значений вместе с операциями на этих значениях.

Stability

Представление типа являетсястабильным, если битовый рисунок, связанный с заданным значением, не изменяется с течением времени. Тип с нестабильным представлением вряд ли будет кому-то полезен, поэтому мы будем настаивать на том, что любая временная библиотека использует только стабильные представления.

Операция по типу является стабильной, если результат применения операции к конкретному операнду(ам) не изменяется с течением времени.

Predictability

Наборы чаще всего подразделяются на две категории: четко определенные и плохо определенные. Поскольку тип является набором, мы можем расширить эти определения, чтобы охватить типы. Для любого типа T должен быть предикат- член(x), который определяет, является ли значение x членом типа T. Этот предикат должен вернутьсяистинным, ложным,илине знающим.

Если для всех x, is_member(x) возвращает либо истинное, либо ложное, мы говорим, что множество Tчетко определено.

Если для какого-либо x, is_member(x) returns dont_know, мы говорим, что множество Tплохо определено.

Это правила, которые обычно используются в математике. Однако из-за особых характеристик временных типов полезно уточнить эту точку зрения и создать третью категорию следующим образом:

Для любого временного типа T должен существовать предикат— член(x, t), который определяет, является ли значение x членом T. Параметр t представляет время, когда оценивается предикат. Для каждого x_iдолжно быть время t_iи значение v, такое, что:

Таким образом, t_i— это время, когда мы «узнаем», является ли x_iчленом T. Теперь мы можем определить три категории временных типов:

Если для всех x_i, t_i= отрицательная бесконечность, мы говорим, что тип Tпредсказуем.

Если для некоторых x_i, t_i= положительная бесконечность, мы говорим, что тип Tплохо сформирован.

В противном случае мы говорим, что тип Tнепредсказуем(это означает, что для некоторых x_i, t_iявляется конечным).

Плохо сформированные наборы не имеют большого практического применения, поэтому мы не будем обсуждать их дальше. В простом английском языке выше просто говорится, что все значения предсказуемого типа известны заранее, но некоторые значения непредсказуемого типа не известны до определенного времени.

Stability of Operations

Предсказуемые типы имеют несколько важных свойств:

Практический эффект этого заключается в том, что вычисления продолжительности могут быть реализованы с простым целым вычитанием. Примерами предсказуемых типов являются временные точки TAI и григорианские даты.

Непредсказуемые типы обладают прямо противоположными свойствами:

Примерами непредсказуемых типов являются точки времени UTC и локальные точки времени.

Мы можем немного уточнить это, сказав, что диапазон в непредсказуемом типе может быть предсказуемым, и операции, выполняемые полностью на значениях в этом диапазоне, будут стабильными. Например, диапазон точек времени UTC от 1970-01-01 до настоящего времени предсказуем, поэтому расчеты длительностей в этом диапазоне будут стабильными.

Approximations

Эти ограничения проблематичны, потому что важные временные типы, такие как UTC и Local Time, на самом деле непредсказуемы, и поэтому операции над ними иногда нестабильны. Тем не менее, в практическом плане мы часто хотим выполнять такие операции, как вычисление продолжительности между двумя точками времени в будущем, которые указаны в локальном времени.

Лучшее, что может сделать библиотека, — это обеспечить приближение, которое обычно возможно и для большинства целей будет достаточно хорошим. Конечно, в документации должно быть указано, когда ответ будет приблизительным (и, следовательно, нестабильным) и насколько большой может быть ошибка. Во многих отношениях вычисление с непредсказуемыми наборами аналогично использованию чисел с плавающей точкой, для которых результаты, как ожидается, будут только приблизительно правильными. Затем вычисление с помощью предсказуемых наборов будет аналогично пользователю целых чисел, где результаты, как ожидается, будут точными.

Для ситуаций, когда требуются точные ответы или нестабильность не может быть допущена, пользователь должен иметь возможность указать это, а затем библиотека должна выбросить исключение, если пользователь запрашивает вычисления, для которых точный, стабильный ответ невозможен.

Ниже приведен ряд терминов, относящихся к домену даты-времени.

Таксономия временных типов:

И некоторые другие термины:

Стандартная терминология даты:

Еще несколько экспериментальных:

Это дизайнерские термины:

Дизайн библиотеки в настоящее время разрабатывается с использованием Wiki и электронной почты. Более подробную информацию можно найти по адресу:Boost Wiki GDTL Start Page.

Date Calendar References

Time

Other C/C++ Libraries

JAVA Date & Time Library Quick Reference

Scripting Language Libraries

Related Commercial and Fanciful Pages

Resolution, Precision, and Accuracy

Overview -- Compilation Options -- Compiler/Portability Notes -- Directory Structure -- Required Boost Libraries

Overview

Библиотека имеет несколько функций, которые требуют создания библиотечного файла (в основном To_string, From_string). Большинство пользователей библиотеки могут эффективно использовать библиотеку БЕЗ создания библиотеки, но просто включив необходимые заголовки. Если библиотека необходима, Jamfile в каталоге сборки будет создавать «статическую» библиотеку (libboost_date_time) и «динамическую/общую» библиотеку (boost_date_time), которая содержит эти функции. Обратите внимание, что для использования библиотеки без библиотеки (особенно на окнах) может потребоваться использование флага BOOST_DATE_TIME_NO_LIB для вариантов компиляции.

Compilation Options

По умолчанию система posix_time использует одно 64-битное целое число для обеспечения разрешения микросекундного уровня. В качестве альтернативы, комбинация 64-битного целого и 32-битного целого (96-битное разрешение) может использоваться для обеспечения разрешений наносекундного уровня. Реализация по умолчанию может обеспечить лучшую производительность и более компактное использование памяти для многих приложений, которые не требуют наносекундного разрешения.

Для использования альтернативного разрешения (96 бит наносекунд) переменная<BOOST_DATE_TIME_POSIX_TIME_STD_CONFIG>должна быть определена в библиотеке пользователей проектных файлов (т.е. Makefile, Jamfile и т.д.). Этот макрос не используется григорианской системой и поэтому не имеет никакого эффекта при строительстве библиотеки.

На версии 1.33 библиотека date_time представила новую потоковую систему ввода-вывода. Некоторые компиляторы не могут использовать эту новую систему. Для этих составителей более раннее («наследие») Система IO все еще доступна. Неподдерживаемые компиляторы автоматически выбирают унаследованную систему, но пользователь может принудительно использовать унаследованную систему, определив<USE_DATE_TIME_PRE_1_33_FACET_IO>.

Для удобства<date_time>предоставил некоторыедополнительные типы продолжительности. Использование этих типов может привести к неожиданным результатам из-за поведения в течение месяца (см.Обратимость ловушки операцийдля полных деталей и примеров). Эти типы включены по умолчанию. Чтобы отключить эти типы, просто отключите<BOOST_DATE_TIME_OPTIONAL_GREGORIAN_TYPES>в файле проекта.

Еще одно удобство — конструкторы по умолчанию для<date>и<ptime>. Эти конструкторы включены по умолчанию. Чтобы отключить их, просто определите<DATE_TIME_NO_DEFAULT_CONSTRUCTOR>в файле проекта.

Compiler/Portability Notes

Библиотека Boost Date-Time была построена и протестирована со многими компиляторами и платформами. Однако некоторые компиляторы и стандартные библиотеки имеют проблемы. Хотя некоторые из этих проблем могут быть решены, другие трудно решить. Известно, что следующие компиляторы полностью поддерживают все аспекты библиотеки:

К сожалению, у компилятора VC8 есть некоторые проблемы с кодом даты. Наиболее серьезной проблемой является утечка памяти, которая была введена в стандартный библиотечный код VC8 basic_stream. Код был изменен, чтобы избежать этого, но если вы используете устаревшую опцию ввода-вывода (не по умолчанию с VC8), проблема все еще может возникнуть. См.архив рассылкидля более подробной информации.

В дополнение к вышеприведенной проблеме, некоторые версии библиотеки VC8 ограничили диапазон допустимых значений в структуре<std::tm>положительными значениями. Это было новое ограничение, добавленное в VC8. Результатом является то, что даты до 1900 года будут вызывать исключения. К сожалению, в этом вопросе нет простого обходного пути. Обратите внимание, что новая 64-битная версия компилятора VC8, похоже, не имеет этого ограничения.

Эти компиляторы поддерживают все аспекты библиотеки, кроме вывода<wstring/wstream>.

В частности, отсутствие поддержки стандартных локализаций ограничивает способность библиотеки поддерживать входной выход на основе iostream. Для этих компиляторов предусмотрен набор более ограниченных строк на основе ввода-вывода. Некоторые компиляторы/стандартные библиотеки с этим ограничением включают:

Официальная поддержка некоторых старых компиляторов была прекращена. Это включает в себя:

Visual Studio & STLPort

Существует известная проблема с Visual Studio (7.0 & 7.1) и STLPort. Ошибки сборки обычно ссылаются на проблему типа или «неприемлемое преобразование» и пытаются создать шаблон с помощью<wchar_t>. По умолчанию сборка STLPort не поддерживает<wchar_t>. Есть два возможных обходных пути для этого вопроса. Самое простое заключается в том, что пользователь может создавать дату_время без широкого потока/струн и т.д. Другой вариант — восстановление STLPort с поддержкой wchar_t.

Чтобы построить date_time без широкого потока/струн и т.д., выполните следующую команду из<$BOOST_ROOT>:

bjam -a "-sTOOLS=vc-7_1-stlport" "-sSTLPORT_PATH=..." \
     "-sBUILD=<define>BOOST_NO_STD_WSTRING"           \
     --stagedir=... --with-date_time stage

(Замените эллипс правильными дорожками для системы сборки и при необходимости настройте<TOOLS>на соответствующий набор инструментов)

Восстановление STLPort с поддержкой<wchar_t>включает размещение</Zc:wchar_t>в файле STLPort. Дата_время должно быть построено со следующей командой от<$BOOST_ROOT>:

bjam -a "-sTOOLS=vc-7_1-stlport" "-sSTLPORT_PATH=..." \
     "-sBUILD=&native-wchar_t>on"                     \
     --stagedir=... --with-date_time stage

(Замените эллипс правильными дорожками для системы сборки и при необходимости настройте<TOOLS>на соответствующий набор инструментов)

Directory Structure

Дерево каталога имеет следующую структуру:

/boost/date_time                    -- common headers and template code
/boost/date_time/gregorian          -- Gregorian date system header files
/boost/date_time/posix_time         -- Posix time system headers
/boost/date_time/local_time         -- Local time system headers
/libs/date_time/build               -- build files and output directory
/libs/date_time/test                -- test battery for generic code
/libs/date_time/test/gregorian      -- test battery for the Gregorian system
/libs/date_time/test/posix_time     -- test battery for the posix_time system
/libs/date_time/test/local_time     -- test battery for the local_time system
/libs/date_time/examples/gregorian  -- example programs for dates
/libs/date_time/examples/posix_time -- time example programs
/libs/date_time/examples/local_time -- nifty example programs
/libs/date_time/src/gregorian       -- cpp files for libboost_date_time
/libs/date_time/src/posix_time      -- empty (one file, but no source code...)

Required Boost Libraries

Различные части времени зависят от других библиотек. К ним относятся:

Эти библиотеки должны быть установлены.

Библиотека предоставляет большое количество тестов в

      libs/date_time/test
      libs/date_time/test/gregorian
      libs/date_time/test/posix_time
      libs/date_time/test/local_time
    

Каталоги. Создание и выполнение этих тестов гарантирует правильность установки и правильное функционирование библиотеки. Кроме того, эти тесты облегчают перенос на новые компиляторы. Наконец, тесты предоставляют примеры многих функций, явно не описанных в примерах использования.

Changes from Boost 1.41 to 1.44 (date_time 1.08 to 1.09)

Changes from Boost 1.40 to 1.41 (date_time 1.07 to 1.08)

Changes from Boost 1.38 to 1.40 (date_time 1.06 to 1.07)

Changes from Boost 1.34 to 1.38 (date_time 1.05 to 1.06)

Changes from Boost 1.33 to 1.34 (date_time 1.04 to 1.05)

Changes from Boost 1.32 to 1.33 (date_time 1.03 to 1.04)

template<class archive_type, class temporal_type>
void save_to(archive_type& ar,
             const temporal_type& tt)
{
  ar << tt;
}

Changes from Boost 1.31 to 1.32 (date_time 1.02 to 1.03)

days days_until_weekday(date, greg_weekday);
days days_before_weekday(date, greg_weekday);
date next_weekday(date, greg_weekday);
date previous_weekday(date, greg_weekday);

months m(12);
years y(1);
m == y; // true
days d(7);
weeks w(1);
d == w; // true
ptime t(...);
t += months(3);
date d(2004,Jan,30);
d += months(1); //2004-Feb-29
d -= months(1); //2004-Jan-29

ptime p_nadt(not_a_date_time);
ptime p_posinf(pos_infin);
ptime p; // p == NADT
date d;  // d == NADT

std::wstringstream wss;
date d(2003,Aug,21);
wss << d;

date d(not_a_date_time);
std::stringstream ss("2000-FEB-29");
ss >> d; //Feb 29th, 2000
std::wstringstream ws("2000-FEB-29");
ws >> d; //Feb 29th, 2000

Changes from Boost 1.30 to 1.31 (date_time 1.01 to 1.02)

seconds(1).total_milliseconds() == 1000
seconds(1).total_microseconds() == 1000000
hours(1).total_milliseconds() == 3600*1000 //3600 sec/hour
seconds(1).total_nanoseconds() == 1000000000

time_duration td(5,0,0); //5 hours
td = -td; //-5 hours

Changes from Boost 1.29 to 1.30 (date_time 1.00 to 1.01)

Обратите внимание: был изменен интерфейс класса part_date (см.date_algorithms). Изменился порядок параметров конструкции, что приведет к неисполнению некоторого кода. Это изменение было сделано для облегчения более общего кода корректировки местного времени. Таким образом, вместо указания part_date pd(Dec,25) код необходимо изменить на partial_date pd(25, Dec);

Многие люди внесли свой вклад в развитие этой библиотеки. В частности, Хьюго Дункан и Джоэл де Гусман за помощь в портировании на различные компиляторы. За первоначальную разработку концепций и дизайна Корвин Джой и Майкл Кеннистон заслуживают особой благодарности. Также большое спасибо Майклу за написание теории и компромиссов в документации. Дэйв Зумбро за вдохновение и мудрые мысли. Многие благодаря повышению рецензентов и пользователей, в том числе: Уильям Сеймур, Кьелл Элстер, Беман Дауэс, Гэри Пауэлл, Эндрю Маклин, Уильям Кемпф, Питер Димов, Крис Литтл, Дэвид Мур, Дарин Адлер, Геннадий Розенталь, Йоахим Ахтентер, Пол Бристоу, Ян Лангер, Марк Роджерс, Глен Ноулз, Мэттью Денман и Джордж Хайнцельман.