Справочник по Ada (Ada 2022)
9.6.1 Форматирование, временные зоны и другие операции для времени
Статические семантика
Ниже приведены определённые языком библиотечные пакеты:
package Ada.Calendar.Time_Zones
with Nonblocking, Global => in out synchronized is
with Nonblocking, Global => in out synchronized is
-- Обработка временных зон:
type Time_Offset is range -28*60 .. 28*60;
Unknown_Zone_Error : exception;
function Local_Time_Offset (Date : Time := Clock) return Time_Offset;
function UTC_Time_Offset (Date : Time := Clock) return Time_Offset
renames Local_Time_Offset;
renames Local_Time_Offset;
end Ada.Calendar.Time_Zones;
package Ada.Calendar.Arithmetic
with Nonblocking, Global => in out synchronized 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
with Nonblocking, Global => in out synchronized 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 Local_Image (Date : Time;
Include_Time_Fraction : Boolean := False)
return String is
(Image (Date, Include_Time_Fraction,
Time_Zones.Local_Time_Offset (Date)));
Include_Time_Fraction : Boolean := False)
return String is
(Image (Date, Include_Time_Fraction,
Time_Zones.Local_Time_Offset (Date)));
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 представляет для данного места и момента времени количество минут, на которое местное время в этот момент опережает (+) или отстаёт (-) скоординированного универсального времени (сокращённо UTC). Time_Offset для UTC равен нулю.
function Local_Time_Offset (Date : Time := Clock) return Time_Offset;
Возвращает, как число минут, Time_Offset реализованной в Ada временной зоны в момент Date. Если временная зона реализации Ada неизвестна, то возникает 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. Если 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 в False. Если Date представляет время в високосной секунде, устанавливает составляющие части на значения, соответствующие времени на одну секунду раньше, чем задано в Date, относительно заданного смещения часового пояса, и устанавливает Leap_Second в 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_Second в 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-значные значения, определенных в 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 должен возвращать False для Leap_Second, а Time_Of должен генерировать Time_Error, если Leap_Second истинно.
ПРИМЕЧАНИЕ 1 Реализация часового пояса пакета Calendar по умолчанию может быть локальным часовым поясом. Local_Time_Offset всегда возвращает разницу относительно реализации часового пояса пакета Calendar. Если Local_Time_Offset не генерирует Unknown_Zone_Error, время UTC можно безопасно вычислить (с точностью до базового источника времени).
ПРИМЕЧАНИЕ 2 Вызов Split для результатов вычитания Duration(Local_Time_Offset*60) из Clock предоставляет компоненты (часы, минуты и т. д.) времени UTC. Например, в Соединённых Штатах Local_Time_Offset обычно будет отрицательным.
