C++ Boost

Boost Date-Time Library Documentation


Version 1.00


Contents


Overview

Introduction -- Motivation -- Usage Examples -- Domain Concepts -- Tests -- Design and Extensions -- Acknowledgements -- More Info

Build-Compiler Information

Date Programming

Gregorian Date System

Time Programming

Posix Time System

Introduction

A set of date-time libraries based on generic programming concepts.
ジェネリックプログラミングの概念に基づいた日付・時間ライブラリ

Motivation

The motivation for this library comes from working with and helping build several date-time libraries on several projects. Date-time libraries provide fundamental infrastructure for most development projects. However, most of them have limitations in their ability to calculate, format, convert, or perform some other functionality. For example, most libraries do not correctly handle leap seconds, provide concepts such as infinity, or provide the ability to use high resolution or network time sources. These libraries also tend to be rigid in their representation of dates and times. Thus customized policies for a project or subproject are not possible.
このライブラリの開発動機は、多くのプロジェクトの多くの日付時間ライブラリで動作すること、また、それらの構築を手助けすることである。 日付時間ライブラリは多くの開発プロジェクトに対して、基礎的な構造を提供する。 しかしそれらの多くは、計算、書式化、変換、その他のいくつかの機能に限界がある。 例えば多くのライブラリは、うるう秒を正しく扱うこと、無限のような概念を提供すること、高分解能の時間資源やネットワーク上の時間資源を利用することが出来ない。 そのうえ、これらのライブラリは、どれも日付や時間の表現形式が厳密である傾向にあるため、プロジェクトやサブプロジェクトのためにカスタマイズすることが出来ない。

Programming with dates and times should be almost as simple and natural as programming with strings and integers. Applications with lots of temporal logic can be radically simplified by having a robust set of operators and calculation capabilities. Classes should provide the ability to compare dates and times, add lengths or time durations, retrieve dates and times from clocks, and work naturally with date and time intervals.
日付や時間に関するプログラミングは、文字列や整数に関するプログラミングと同じくらいシンプルで自然であるべきである。 多くの時間論理を備えたアプリケーションは、演算子と計算能力の頑健な集合により、根本的に単純化することができる。 クラスは日付時間の比較、時間の長さ(length)や期間(duration)の加算、時計からの日付時間の取得、日付時間間隔(interval)に関する自然な動作を提供すべきである。

Usage Examples

The following shows examples of the sorts of code that can be written using the gregorian date system. See Date Programming for more details.
次に,グレゴリオ暦システムの使用例を示す。 詳細はDate Programmingで解説する。

     using namespace boost::gregorian; 
     date weekstart(2002,Feb,1);
     date weekend  (2002,Feb,7);
     date_duration fiveDays(5); 
     date d3 = d1 + fiveDays;
     date today = day_clock::local_day();
     if (d3 >= today) {} //date comparison operators
     
     date_period thisWeek(d1,d2);
     if (thisWeek.contains(today)) {}//do something
    
     //iterate and print the week
     day_iterator itr(weekstart);
     for (; itr <= weekend; ++itr) {
       std::cout << to_iso_extended_string(*itr) << std::endl;
     }     

And some time examples using the posix_time system. See Time Programming for more details.
そして posix_time システムの使用例である。 詳細はTime Programmingで解説する。

     using namespace boost::posix_time; 
     date d(2002,Feb,1); //an arbitrary date
     ptime t1(d, hours(5)+nanosec(100));//date + time of day offset
     ptime t2 = t1 - minutes(4)+seconds(2);
     ptime now = second_clock::local_time(); //use the clock
     //Get the date part out of the time
     date today = now.date();
     date tommorrow = today + date_duration(1);
     ptime tommorrow_start(tommorrow); //midnight 

     //starting at current time iterator adds by one hour
     time_iterator titr(now,hours(1)); 
     for (; titr < tommorrow_start; ++titr) {
       std::cout << to_simple_string(*titr) << std::endl;
     }

Domain Concepts

The date time domain is rich in terminology and problems. The following is a brief introduction to the concepts you will find reflected in the library.
日付・時間の分野には専門用語と問題が多い。以下はライブラリ中に見られる概念の簡単な紹介である。

The library supports 3 basic temporal types:
ライブラリは3つの基本的な時間型をサポートする。

Time Point
Specifier for a location in the time continuum.
時間位置。時刻。連続する時間内での位置を示す
Time Duration
A length of time unattached to any point on the time continuum.
時間長。時間連続体においてどの位置にも結びついていない時間の長さ
Time Interval
A duration of time attached to a specific point in the time continuum. Also known as a time period.
時間間隔。時間連続体の特定の位置に結びついた時間長。期間とも

Each of these temporal types has a Resolution which is defined by the smallest representable duration. A Time system provides all these categories of temporal types as well as the rules for labeling and calculating with time points. Calendar Systems are simply time systems with a maximum resolution of one day. The Gregorian system is the most widely used calendar system today (the ISO system is basically a derivative of this). However, there are many other calendar systems as well. UTC (Coordinated Universal Time) is a widely used civil time system. UTC is adjusted for earth rotation at longitude 0 by the use of leap seconds (This is not predictable, only as necessary). Most local time systems are based on UTC but are also adjusted for earth rotation so that daylight hours are similar everywhere. In addition, some local times include daylight savings time (DST) adjustments to provide additional daylight during the summer.
これらの時間型にはそれぞれ表現可能な最小の時間間隔(duration)で定義される分解能がある。 時法系(Time system)は、時刻にラベルを付けて計算するための規則はもちろんのこと、これらすべての時間型も提供する。 暦法系(Calendar system)は最大の分解能(1日)を持っている簡素な時法系である。 グレゴリオ暦は今日最も広く使われている暦法系である(ISOシステムは基本的にこれの派生物である)。 しかし、他にも多くの暦法系がある。 UTC(Coordinated Universal Time;協定標準時)は広く使われている民間の時法系である。UTC がうるう秒(これは、必要に応じて適用されるもので、予測可能ではない)の使用によって経度0において地球自転に対して調整される。 たいていの地域時間システムが UTC に基づいているが、地球自転に対して同じように調整されるために、昼時間はどこでも同じである。 さらに、夏の昼時間を長くするためのサマータイム(DST)調整を含む地域時間もある。

A Clock Device is software component (tied to some hardware) that provides the current date or time with respect to a time system.
クロックデバイス は時法系に関して現在の日付あるいは時刻を供給する(あるハードウェアに結び付けられた)ソフトウェアコンポーネントである。

The library provides support for calculating with dates and times. However, time calculations are not quite the same as calculating with integers. If you are serious about the accuracy of your time calculations need to read about Stability, Predictability, and Approximations.
ライブラリは日付と時間の計算をサポートする。しかしながら、時間の計算は整数の計算と全く同じというわけにはいかない。 もし、時間計算の正確度(accuracy)が重要ならば、Stability, Predictability, and Approximations(安定性、予測性と近似)を読む必要がある。

Additional reference materials can be found in the following:
追加資料を以下に示す

Tests

The library provides a large number of tests in the
ライブラリは、以下のディレクトリで多数のテストを提供している。
   libs/date_time/test 
   libs/date_time/test/gregorian
   libs/date_time/test/posix_time
directories. Building and executing these tests assures that the installation is correct and that the library is functioning correctly. In addition, these tests facilitate the porting to new compilers. Finally, the tests provide examples of many functions not explicitly described in the usage examples.
これらのテストをビルドして実行することで、ライブラリが正しくインストールされ、確実に機能していることを確認できる。 加えて、これらのテストは新しいコンパイラへの移植を容易にする。 最後に、テストは使用例で明示的に記述されない多くの機能の例を提供する。

Design and Extensions

A large part of the genesis of this library has been the observation that few date-time libraries are built in a fashion that allows customization and extension. A typical example, the calendar logic is built directly into the date class. Or the clock retrieval functions are built directly into the time class. These design decisions usually make it impossible to extend or change the library behavior. At a more fundamental level, there are usually assumptions about the resolution of time representation or the gregorian calendar.
このライブラリの起源の大部分は(今まで)ほとんどの日付時間ライブラリがカスタマイズと拡張を許す方法で構築されないという観察であった。 典型的な例では、カレンダーロジックは直接日付クラスに構築される。 あるいは時計検索機能は直接時間クラスに作り上げられる。 これらのデザイン決定は通常、拡張したりライブラリの振る舞いを変更することを不可能にする。 もっと基本的なレベルにおいては、時間表現あるいはグレゴリオ暦の分解能について通常仮定がある。

Often times, the result is that a project must settle for a less than complete library because of a requirement for high resolution time representation or other assumptions that do not match the implementation of the library. This is extremely unfortunate because development of a library of this sort is far from a trivial task.
高分解能の時間表現やそれ以外の仮定からの要求を、時間ライブラリの実装が満たすことが出来ないために、結果的に不完全なライブラリを使わざるをえない、というのは、よくあることである。 この種のライブラリの開発は、まったく些細なことではないので、こういう結果は非常に残念なことである。

While the design is far from perfect the current design is far more flexible than any date-time library the author is aware of. It is expected that the various aspects of extensibility will be better documented in future versions. Information about the design goals of the library is summarized here.
(このライブラリの)設計は完璧というには程遠いが、それでも現在の設計は、著者の知るどんな時間ライブラリよりもはるかに柔軟である。 将来のバージョンでは、拡張性のさまざまな面について、さらに文書化されることが期待される。 ライブラリの設計目標についての情報はここに要約されている。

Acknowledgements

Many people have contributed to the development of this library. In particular Hugo Duncan and Joel de Guzman for help with porting to various compilers. For initial development of concepts and design Corwin Joy and Michael Kenniston deserve special thanks. Also extra thanks to Michael for writing up the theory and tradeoffs part of the documentation. Dave Zumbro for initial inspiration and sage thoughts. Many thanks to boost reviewers and users including: William Seymour, Kjell Elster, Beman Dawes, Gary Powell, Andrew Maclean, William Kempf, Peter Dimov, Chris Little, David Moore, Darin Adler, Gennadiy Rozental, Joachim Achtzehnter, Paul Bristow, Jan Langer, Mark Rodgers, Glen Knowles, Matthew Denman, and George Heintzelman.

More Info

The design of the library is currently being evolved using Wiki and email discussions. You can find more information at:
現在、ライブラリの設計はWikiと電子メールによる議論によって発展している。 詳しい情報はこちらへ:


Last modified: Thu Sep 5 07:22:00 MST 2002 by Jeff Garland © 2000-2002
Japanese Translation Copyright (C) 2003 Shoji Shinohara.