Справочник Ada 2005
9.6.1 Форматирование, часовые пояса и другие операции для времени
Статические семантика
Ниже приведены определенные языком библиотечные пакеты:
package Ada.Calendar.Time_Zones is
-- Управление часовыми поясами:
type Time_Offset is range -28*60 .. 28*60;
Unknown_Zone_Error : exception;
function UTC_Time_Offset (Date : Time := Clock) return Time_Offset;
end Ada.Calendar.Time_Zones;
package Ada.Calendar.Arithmetic is
-- Арифметические операции над днями:
type Day_Count is range
-366*(1+Year_Number'Last - Year_Number'First)
..
366*(1+Year_Number'Last - Year_Number'First);
-366*(1+Year_Number'Last - Year_Number'First)
..
366*(1+Year_Number'Last - Year_Number'First);
subtype Leap_Seconds_Count is Integer range -2047 .. 2047;
procedure Difference (Left, Right : in Time;
Days : out Day_Count;
Seconds : out Duration;
Leap_Seconds : out Leap_Seconds_Count);
Days : out Day_Count;
Seconds : out Duration;
Leap_Seconds : out Leap_Seconds_Count);
function "+" (Left : Time; Right : Day_Count) return Time;
function "+" (Left : Day_Count; Right : Time) return Time;
function "-" (Left : Time; Right : Day_Count) return Time;
function "-" (Left, Right : Time) return Day_Count;
function "+" (Left : Day_Count; Right : Time) return Time;
function "-" (Left : Time; Right : Day_Count) return Time;
function "-" (Left, Right : Time) return Day_Count;
end Ada.Calendar.Arithmetic;
with Ada.Calendar.Time_Zones;
package Ada.Calendar.Formatting is
-- День недели:
type Day_Name is (Monday, Tuesday, Wednesday, Thursday,
Friday, Saturday, Sunday);
Friday, Saturday, Sunday);
function Day_of_Week (Date : Time) return Day_Name;
-- Часы:Минуты:Секунды:
subtype Hour_Number is Natural range 0 .. 23;
subtype Minute_Number is Natural range 0 .. 59;
subtype Second_Number is Natural range 0 .. 59;
subtype Second_Duration is Day_Duration range 0.0 .. 1.0;
subtype Minute_Number is Natural range 0 .. 59;
subtype Second_Number is Natural range 0 .. 59;
subtype Second_Duration is Day_Duration range 0.0 .. 1.0;
function Year (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Year_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Year_Number;
function Month (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Month_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Month_Number;
function Day (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Day_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Day_Number;
function Hour (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Hour_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Hour_Number;
function Minute (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Minute_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Minute_Number;
function Second (Date : Time)
return Second_Number;
return Second_Number;
function Sub_Second (Date : Time)
return Second_Duration;
return Second_Duration;
function Seconds_Of (Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number := 0;
Sub_Second : Second_Duration := 0.0)
return Day_Duration;
Minute : Minute_Number;
Second : Second_Number := 0;
Sub_Second : Second_Duration := 0.0)
return Day_Duration;
procedure Split (Seconds : in Day_Duration;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration);
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration);
function Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number;
Sub_Second : Second_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
Month : Month_Number;
Day : Day_Number;
Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number;
Sub_Second : Second_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
function Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Seconds : Day_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
Month : Month_Number;
Day : Day_Number;
Seconds : Day_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
return Time;
procedure Split (Date : in Time;
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration;
Time_Zone : in Time_Zones.Time_Offset := 0);
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration;
Time_Zone : in Time_Zones.Time_Offset := 0);
procedure Split (Date : in Time;
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration;
Leap_Second: out Boolean;
Time_Zone : in Time_Zones.Time_Offset := 0);
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Hour : out Hour_Number;
Minute : out Minute_Number;
Second : out Second_Number;
Sub_Second : out Second_Duration;
Leap_Second: out Boolean;
Time_Zone : in Time_Zones.Time_Offset := 0);
procedure Split (Date : in Time;
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Seconds : out Day_Duration;
Leap_Second: out Boolean;
Time_Zone : in Time_Zones.Time_Offset := 0);
Year : out Year_Number;
Month : out Month_Number;
Day : out Day_Number;
Seconds : out Day_Duration;
Leap_Second: out Boolean;
Time_Zone : in Time_Zones.Time_Offset := 0);
-- Простое изображение и значение:
function Image (Date : Time;
Include_Time_Fraction : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0) return String;
function Image (Date : Time;
Include_Time_Fraction : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0) return String;
function Value (Date : String;
Time_Zone : Time_Zones.Time_Offset := 0) return Time;
Time_Zone : Time_Zones.Time_Offset := 0) return Time;
function Image (Elapsed_Time : Duration;
Include_Time_Fraction : Boolean := False) return String;
Include_Time_Fraction : Boolean := False) return String;
function Value (Elapsed_Time : String) return Duration;
end Ada.Calendar.Formatting;
Тип Time_Offset представляет разницу в минутах между реализацией часового пояса, используемого в Calendar, и другим часовым поясом.
function UTC_Time_Offset (Date : Time := Clock) return Time_Offset;
Возвращает разницу в минутах между реализацией часового пояса Calendar и временем UTC в момент времени Date. Если часовой пояс реализации Calendar неизвестен, возникает ошибка Unknown_Zone_Error.
procedure Difference (Left, Right : in Time;
Days : out Day_Count;
Seconds : out Duration;
Leap_Seconds : out Leap_Seconds_Count);
Days : out Day_Count;
Seconds : out Duration;
Leap_Seconds : out Leap_Seconds_Count);
Возвращает разницу между Left и Right. Days — количество дней разницы, Seconds — остаток в секундах разницы, исключая високосные секунды, а Leap_Seconds — количество високосных секунд. Если Left < Right, то Seconds <= 0.0, Days <= 0, и Leap_Seconds <= 0. В противном случае все значения неотрицательны. Абсолютное значение Seconds всегда меньше 86_400.0. Для возвращаемых значений, если Days = 0, то Seconds + Duration(Leap_Seconds) = Calendar."–" (Left, Right).
function "+" (Left : Time; Right : Day_Count) return Time;
function "+" (Left : Day_Count; Right : Time) return Time;
function "+" (Left : Day_Count; Right : Time) return Time;
Прибавляет к значению времени заданное количество дней. Time_Error возникает, если результат не может быть представлен как значение типа Time.
function "-" (Left : Time; Right : Day_Count) return Time;
Вычитает заданное количество дней из значения времени. Time_Error возникает, если результат не может быть представлен как значение типа Time.
function "-" (Left, Right : Time) return Day_Count;
Вычитает два значения времени и возвращает количество дней между ними. Это то же значение, которое Difference вернет в Days.
function Day_of_Week (Date : Time) return Day_Name;
Возвращает день недели для Time. Основано на значениях Year, Month и Day времени.
function Year (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Year_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Year_Number;
Возвращает год для Date, соответствующий указанному смещению часового пояса.
function Month (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Month_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Month_Number;
Возвращает месяц для Date, соответствующий указанному смещению часового пояса.
function Day (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Day_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Day_Number;
Возвращает номер дня для Date, соответствующий указанному смещению часового пояса.
function Hour (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Hour_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Hour_Number;
Возвращает час для Date, соответствующий указанному смещению часового пояса.
function Minute (Date : Time;
Time_Zone : Time_Zones.Time_Offset := 0)
return Minute_Number;
Time_Zone : Time_Zones.Time_Offset := 0)
return Minute_Number;
Возвращает количество минут в часе для Date, соответствующее указанному смещению часового пояса.
function Second (Date : Time)
return Second_Number;
return Second_Number;
Возвращает количество секунд в часе и минуте для Date.
function Sub_Second (Date : Time)
return Second_Duration;
return Second_Duration;
Возвращает дробную часть секунды для Date (точная, как Day_Duration). Возвращаемое значение всегда меньше 1.0.
function Seconds_Of (Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number := 0;
Sub_Second : Second_Duration := 0.0)
return Day_Duration;
Minute : Minute_Number;
Second : Second_Number := 0;
Sub_Second : Second_Duration := 0.0)
return Day_Duration;
Возвращает значение Day_Duration для сочетания заданных Hour, Minute, Second и Sub_Second. Это значение может быть использовано в Calendar.Time_Of, а также в качестве аргумента для Calendar."+" и Calendar."–". Если Seconds_Of вызывается со значением Sub_Second 1.0, возвращаемое значение равно значению Seconds_Of для следующей секунды со значением Sub_Second 0.0.
процедура Split (Seconds : входной Day_Duration;
Hour : выходной Hour_Number;
Minute : выходной Minute_Number;
Second : выходной Second_Number;
Sub_Second : выходной Second_Duration);
Hour : выходной Hour_Number;
Minute : выходной Minute_Number;
Second : выходной Second_Number;
Sub_Second : выходной Second_Duration);
Разделяет Seconds на Hour, Minute, Second и Sub_Second таким образом, что все полученные значения принадлежат соответствующим подтипам. Значение, возвращаемое в параметре Sub_Second, всегда меньше 1.0.
функция Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number;
Sub_Second : Second_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
возвращает Time;
Month : Month_Number;
Day : Day_Number;
Hour : Hour_Number;
Minute : Minute_Number;
Second : Second_Number;
Sub_Second : Second_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
возвращает Time;
Если Leap_Second ложно, возвращает Time, построенный из значений даты и времени, относительно заданного смещения часового пояса. Если Leap_Second истинно, возвращает Time, представляющий время в пределах високосной секунды, которое на одну секунду позже, чем время, указанное другими параметрами. Time_Error возникает, если параметры не образуют корректной даты или времени. Если Time_Of вызывается со значением Sub_Second равным 1.0, возвращаемое значение равно значению Time_Of для следующей секунды со значением Sub_Second равным 0.0.
функция Time_Of (Year : Year_Number;
Month : Month_Number;
Day : Day_Number;
Seconds : Day_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
возвращает Time;
Month : Month_Number;
Day : Day_Number;
Seconds : Day_Duration := 0.0;
Leap_Second: Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0)
возвращает Time;
Если Leap_Second ложно, возвращает Time, построенный из значений даты и времени, относительно заданного смещения часового пояса. Если Leap_Second истинно, возвращает Time, представляющий время в пределах високосной секунды, которое на одну секунду позже, чем время, указанное другими параметрами. Time_Error возникает, если параметры не образуют корректной даты или времени. Если Time_Of вызывается со значением Seconds равным 86_400.0, возвращаемое значение равно значению Time_Of для следующего дня со значением Seconds равным 0.0.
процедура Split (Date : входной Time;
Year : выходной Year_Number;
Month : выходной Month_Number;
Day : выходной Day_Number;
Hour : выходной Hour_Number;
Minute : выходной Minute_Number;
Second : выходной Second_Number;
Sub_Second : выходной Second_Duration;
Leap_Second: выходной Boolean;
Time_Zone : входной Time_Zones.Time_Offset := 0);
Year : выходной Year_Number;
Month : выходной Month_Number;
Day : выходной Day_Number;
Hour : выходной Hour_Number;
Minute : выходной Minute_Number;
Second : выходной Second_Number;
Sub_Second : выходной Second_Duration;
Leap_Second: выходной Boolean;
Time_Zone : входной Time_Zones.Time_Offset := 0);
Если Date не представляет время в пределах високосной секунды, разделяет Date на составные части (Year, Month, Day, Hour, Minute, Second, Sub_Second), относительно заданного смещения часового пояса, и устанавливает Leap_Second в False. Если Date представляет время в пределах високосной секунды, устанавливает составные части на значения, соответствующие времени на одну секунду ранее, чем задано в Date, относительно заданного смещения часового пояса, и устанавливает Leap_Seconds в True. Значение, возвращаемое в параметре Sub_Second, всегда меньше 1.0.
процедура Split (Date : входной Time;
Year : выходной Year_Number;
Month : выходной Month_Number;
Day : выходной Day_Number;
Hour : выходной Hour_Number;
Minute : выходной Minute_Number;
Second : выходной Second_Number;
Sub_Second : выходной Second_Duration;
Time_Zone : входной Time_Zones.Time_Offset := 0);
Year : выходной Year_Number;
Month : выходной Month_Number;
Day : выходной Day_Number;
Hour : выходной Hour_Number;
Minute : выходной Minute_Number;
Second : выходной Second_Number;
Sub_Second : выходной Second_Duration;
Time_Zone : входной Time_Zones.Time_Offset := 0);
Разделяет Date на составные части (Year, Month, Day, Hour, Minute, Second, Sub_Second), относительно заданного смещения часового пояса. Значение, возвращаемое в параметре Sub_Second, всегда меньше 1.0.
процедура Split (Date : входной Time;
Year : выходной Year_Number;
Month : выходной Month_Number;
Day : выходной Day_Number;
Seconds : выходной Day_Duration;
Leap_Second: выходной Boolean;
Time_Zone : входной Time_Zones.Time_Offset := 0);
Year : выходной Year_Number;
Month : выходной Month_Number;
Day : выходной Day_Number;
Seconds : выходной Day_Duration;
Leap_Second: выходной Boolean;
Time_Zone : входной Time_Zones.Time_Offset := 0);
Если Date не представляет время в пределах високосной секунды, разделяет Date на составные части (Year, Month, Day, Seconds), относительно заданного смещения часового пояса, и устанавливает Leap_Second в False. Если Date представляет время в пределах високосной секунды, устанавливает составные части на значения, соответствующие времени на одну секунду ранее, чем задано в Date, относительно заданного смещения часового пояса, и устанавливает Leap_Seconds в True. Значение, возвращаемое в параметре Seconds, всегда меньше 86_400.0.
функция Image (Date : Time;
Include_Time_Fraction : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0) возвращает String;
Include_Time_Fraction : Boolean := False;
Time_Zone : Time_Zones.Time_Offset := 0) возвращает String;
Возвращает строковое представление Date относительно заданного Time_Zone. Формат: "Год-Месяц-День Час:Минута:Секунда", где год — 4-значное значение, а все остальные — 2-значные, с ведущим нулём, если необходимо. Разделители между значениями — дефис, дефис, двоеточие и пробел между днём и часом. Если Include_Time_Fraction истинно, целая часть Sub_Seconds*100 добавляется к строке в виде точки, за которой следует 2-значное значение.
функция Value (Date : String;
Time_Zone : Time_Zones.Time_Offset := 0) возвращает Time;
Time_Zone : Time_Zones.Time_Offset := 0) возвращает Time;
Возвращает значение Time для изображения, заданного как Date, относительно заданного часового пояса. Constraint_Error возникает, если строка не имеет формата, описанного для Image, или функция не может интерпретировать заданную строку как значение Time.
функция Image (Elapsed_Time : Duration;
Include_Time_Fraction : Boolean := False) возвращает String;
Include_Time_Fraction : Boolean := False) возвращает String;
Возвращает строковое представление Elapsed_Time. Формат: "Час:Минута:Секунда", где все значения — 2-значные, с ведущим нулём, если необходимо. Разделители между значениями — двоеточия. Если Include_Time_Fraction истинно, целая часть Sub_Seconds*100 добавляется к строке в виде точки, за которой следует 2-значное значение. Если Elapsed_Time < 0.0, результат — Image (abs Elapsed_Time, Include_Time_Fraction) с префиксом минус. Если abs Elapsed_Time представляет 100 часов или более, результат определён на уровне реализации.
функция Value (Elapsed_Time : String) возвращает Duration;
Возвращает значение Duration для изображения, заданного как Elapsed_Time. Constraint_Error возникает, если строка не имеет формата, описанного для Image, или функция не может интерпретировать заданную строку как значение Duration.
Рекомендации по реализации
Реализация должна поддерживать високосные секунды, если целевая система их поддерживает. Если високосные секунды не поддерживаются, Difference должна возвращать ноль для Leap_Seconds, Split должна возвращать False для Leap_Second, а Time_Of должна вызывать Time_Error, если Leap_Second истинно.
ПРИМЕЧАНИЯ
37 Реализуемый часовой пояс пакета Calendar может, но не обязательно, быть местным часовым поясом. UTC_Time_Offset всегда возвращает разницу относительно реализуемого часового пояса пакета Calendar. Если UTC_Time_Offset не вызывает Unknown_Zone_Error, UTC-время можно безопасно рассчитать (в пределах точности базового источника времени).
38 Вызов Split для результатов вычитания Duration(UTC_Time_Offset*60) из Clock обеспечивает компоненты (часы, минуты и т. д.) UTC-времени. Например, в США UTC_Time_Offset обычно будет отрицательным.
