Тип «Длительность»

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

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

Минимальное и максимальное значения, соответственно: -999999999999999мс и 999999999999999мс.

Значение типа Длительность можно получить следующим способом:

С помощью конструктора типа, в котором составляющие интервала вводятся отдельными параметрами конструктора. Обязательность указания параметров конструктора зависит от используемого конструктора.
С помощью литерала, описывающего длительность. Литерал имеет вид [+|-][<А>д][<Б>ч][<В>м][<Г>с][<Д>мс]. В этом литерале любой элемент может быть опущен, если соответствующее значение равно нулю. Компоненты означают следующее:
- <А> — значение дней.
- <Б> — значение часов.
- <В> — значение минут.
- <Г> — значение секунд.
- <Д> — значение миллисекунд.

В результате вычитания значений работы с датой и временем.

Для значений типа Длительность поддерживаются стандартные арифметические операции. Значение типа Длительность может участвовать в качестве одного из операндов в операциях сложения и вычитания для значений типа Дата, Время, Момент, ДатаВремя. Значение типа Длительность получается в результате вычитания значений типа Дата, Время, Момент, ДатаВремя.

метод Скрипт()
    пер ДатаНачала = новый Дата(2020, 3, 1)
    пер ДатаОкончания = Дата{2020-03-10}
    пер ВремяНачала = новый Время(9, 15, 0)
    пер ВремяОкончания = Время{18:0:0}
    пер МоментВремени1 = новый Момент("2020-01-01 0:0:0 Z")
    пер МоментВремени2 = новый Момент("2020-12-31 12:59:59 Z")
    пер ПолтораЧаса = новый Длительность(1, 30, 0)
    пер ДваДня = 2д
    пер РезультатОперации: неизвестно
    РезультатОперации = ДатаНачала + ДваДня
    РезультатОперации = ДатаНачала + 5д
    РезультатОперации = ДатаОкончания - ДатаНачала
    РезультатОперации = МоментВремени2 - 5д14ч30м
;

Форматирование длительности

Тип Длительность является потомком типа Форматируемое, а значит, для значений этого типа поддерживается возможность указывать форматную строку для получения нужного представления значения данного типа. Для форматирования длительности используется встроенный метод Представление(Формат: Строка), который принимает как аргумент указанный формат и возвращает строку с длительностью в этом формате.

Пример

Форматирование типа Длительность осуществляется за счет шаблонов, созданных пользователем. В примере ниже для переменной ДлительностьСеминара типа Длительность вызывается метод Представление(Формат: Строка), который позволяет представить ее значение в виде строки соответствующего формата. Для указания места, куда необходимо вставить значения единиц измерения длительности, используются специальные символы. Результат форматирования помещается в переменную ДлительностьСеминараФормат:

метод ФорматированиеДлительности(): неизвестно        
        пер ДлительностьСеминара = 1д5ч30м55с333мс
        пер ДлительностьСеминараФормат = ДлительностьСеминара.Представление("дд:ЧЧ:мм")
        возврат ДлительностьСеминараФормат
;

После вызова метода будет возвращено:

01:05:30

Если в метод Представление() не передать ни одного аргумента, то будет использоваться значение по умолчанию: "ЗЧЧ:мм:сс".

Если в строке Формат отсутствуют специальные символы, обозначающие какую-либо временную единицу, то данная единица переводится в ближайшую меньшую временную единицу, символ которой присутствует в форматной строке:

1ч12м.Представление("м") → 72

Если символ ближайшей меньшей единицы отсутствует в форматной строке, то данная временная единица отбрасывается:

25м13с.Представление("м") → 25

Если символ ближайшей меньшей временной единицы отсутствует в форматной строке, однако ее значение может быть переведено в ближайшую бо́льшую временную единицу, символ которой присутствует в форматной строке (например, 60 секунд = 1 минута), тогда меньшая временная единица переводится в ближайшую бо́льшую временную единицу. Целая часть суммируется со значением большей временной единицы, если таковая уже присутствует в строке, а остаток отбрасывается:

25м65с.Представление("м") → 26

В случае указания некорректной форматной строки будет выброшено исключение IllegalFormatBslException.

Для того чтобы преобразовать длительность в формат ISO, можно использовать метод ВФорматеIso(). Данный метод осуществляет форматирование длительности по формату ISO-8601: PnDTnHnMn.nS, где D — дни, H — часы, M — минуты, S — секунды. Пример:

2д3ч4м.ВФорматеIso() → P2DT3H4M
-6ч3м.ВФорматеIso() → -P6H3M

Экранирование

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

метод ФорматированиеДлительности(): неизвестно
    пер ДлительностьСеминара = 1д5ч30м55с333мс
    пер ДатаСозданияФормат = ДлительностьСеминара.Представление("'Длительность:' д 'день' Ч 'часов'")
    возврат ДатаСозданияФормат
;

После вызова метода будет возвращено:

Длительность: 1 день 5 часов

В примере выше экранирование используется для строк «Длительность:», «день», «часов».

При использовании символа « ' » (одинарная кавычка) в разделе текста его необходимо экранировать еще одной кавычкой: « '' » (две подряд идущие одинарные кавычки).

Интерполяция

Для интерполяции используется метод Шаблон типа Строки, который принимает как аргументы строку и переменные объекта, которые нужно вставить в эту строку. Индекс объектов отсчитывается с нуля, т. е. с %0.

Синтаксис:

Строки.Шаблон("Текст шаблона %Индекс1", объект с переменными).

Если объектов несколько, то передается список объектов:

Строки.Шаблон("Текст шаблона %Индекс1 ... %Индекс2 ... %ИндексN", [Объект1, Объект2, ..., ОбъектN]).

Например:

метод ФорматированиеДлительности(): неизвестно
    пер МинимальнаяДлительность = 5ч30м55с333мс
    пер МаксимальнаяДлительность = 7ч40м55с333мс
    пер МинимальнаяДлительностьФормат = МинимальнаяДлительность.Представление("Ч 'ч' мм 'мин'")
    пер МаксимальнаяДлительностьяФормат = МаксимальнаяДлительность.Представление("Ч 'ч' мм 'мин'")
    пер Диапазон = Строки.Шаблон("Длительность составит: от %0 до %1",
                                [МинимальнаяДлительностьФормат, МаксимальнаяДлительностьяФормат])
    возврат Диапазон
;

После вызова метода будет возвращено:

Длительность составит: от 5 ч 30 мин до 7 ч 40 мин

Список доступных специальных символов для использования в форматной строке

д

Количество дней.

Количество идущих подряд букв «д» задает количество цифр, которое будет использовано при выводе значения. При этом количество цифр в выводе = МАКС(количество символов «д», минимально необходимое количество цифр для вывода значения).

11д2ч3м4с.Представление("д") → 11
1д2ч3м4с.Представление("дд") → 01

Ч

Количество часов.

Количество подряд идущих букв «Ч» задает количество цифр, которое будет использовано при выводе значения. При этом количество цифр в выводе = МАКС(количество символов «Ч», минимально необходимое количество цифр для вывода значения).

22ч3м4с.Представление("Ч") → 22
2ч3м4с.Представление("ЧЧ") → 02

м

Количество минут.

Количество подряд идущих букв «м» задает количество цифр, которое будет использовано при выводе значения. При этом количество цифр в выводе = МАКС(количество символов «м», минимально необходимое количество цифр для вывода значения).

33м4с.Представление("м") → 33
3м4с.Представление("мм") → 03

с

Количество секунд.

Количество подряд идущих букв «с» задает количество цифр, которое будет использовано при выводе значения. При этом количество цифр в выводе = МАКС(количество символов «с», минимально необходимое количество цифр для вывода значения).

44с300мс.Представление("с") → 44
4с300мс.Представление("сс") → 04

С

Количество миллисекунд.

Количество идущих подряд букв «С» задает количество цифр, которое будет использовано при выводе значения. При этом количество цифр в выводе = МАКС(количество символов «С», минимально необходимое количество цифр для вывода значения).

300мс.Представление("С") → 300
300мс.Представление("СССС") → 0300

З

Знак длительности. Если длительность положительная, отформатированное значение выводится без знака минуса, если длительность отрицательная, отформатированное значение выводится с минусом:

20ч30м40с.Представление("ЗЧ:м:с") → 20:30:40
(-20ч30м40с).Представление("ЗЧ:м:с") → -20:30:40
(-20ч30м40с).Представление("Ч:м:с") → 20:30:40