Справочное руководство по Ada 2012
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, возникает исключение Time_Error.
function "-" (Left : Time; Right : Day_Count) return Time;
Вычитает из значения времени указанное количество дней. Если результат не может быть представлен как значение типа Time, возникает исключение Time_Error.
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 для заданных часов, минут, секунд и дробной части секунды. Это значение может быть использовано в Calendar.Time_Of, а также в качестве аргумента для Calendar."+" и Calendar."–". Если Seconds_Of вызывается со значением Sub_Second равным 1.0, то возвращаемое значение равно значению Seconds_Of для следующей секунды со значением Sub_Second равным 0.0.
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);
Разделяет секунды на часы, минуты, секунды и доли секунды таким образом, что все результирующие значения принадлежат соответствующим подтипам. Значение, возвращаемое в параметре Sub_Second, всегда меньше 1.0. Если Seconds = 86400.0, Split генерирует ошибку Time_Error.
функция 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 в ложь. Если Date представляет время внутри високосной секунды, устанавливает составляющие части в значения, соответствующие времени на одну секунду раньше, чем заданное Date, относительно указанного смещения часового пояса, и устанавливает Leap_Seconds в истину. Значение, возвращаемое в параметре 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 в ложь. Если Date представляет время внутри високосной секунды, устанавливает составляющие части в значения, соответствующие времени на одну секунду раньше, чем заданное Date, относительно указанного смещения часового пояса, и устанавливает Leap_Seconds в истину. Значение, возвращаемое в параметре 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-значные значения, определённых в Calendar и Calendar.Formatting, включая ведущий ноль, если необходимо. Разделители между значениями — дефис, ещё один дефис, двоеточие и пробел между Днём и Часом. Если 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 должна возвращать ложь для Leap_Second, а Time_Of должна генерировать Time_Error, если Leap_Second истинно.
ПРИМЕЧАНИЯ
38 Реализация часового пояса пакета Calendar, но не обязательно, может быть локальным часовым поясом. UTC_Time_Offset всегда возвращает разницу относительно реализованного часового пояса пакета Calendar. Если UTC_Time_Offset не генерирует Unknown_Zone_Error, UTC время может быть рассчитано безопасно (в пределах точности базовой временной базы).
39 Вызов Split для результатов вычитания Duration(UTC_Time_Offset*60) из Clock предоставляет компоненты (часы, минуты и т. д.) UTC времени. В США, например, UTC_Time_Offset обычно будет отрицательным.
