Lib:Architecture/Base Layer/Time Module

From GNUpdf

Library Module
Time Module
Layer	Base
API Documentation	Reference Manual
Source Files	src/base/pdf-time.h src/base/pdf-time.c

Contents 1 Overview 2 Data Abstractions 2.1 Time 2.2 Time Span 2.3 Calendar Structures 3 Supported Time Formats 4 Operations 4.1 Time Creation and Destruction 4.2 Time Values Management 4.3 Time Printing and Parsing 4.4 Getting the Current Time 4.5 Time Span Creation and Destruction 4.6 Time Span Values Management 4.7 Management of Time Span Calendar Structures

Overview

This module provides facilities to manipulate calendar dates, time spans and to perform basic time arithmetic.

Data Abstractions

Time

The pdf_time_t opaque data type represents a specific UTC date and time. It is a discrete point in the continuous timeline. The resolution is in seconds. Time values are attributed with an offset with GMT (positive or negative) to allow to represent local times. The implementation may impose a minimum and/or a maximum time value, defining an interval of valid time values.

Time Span

The pdf_time_span_t opaque data type represents a time span measured in seconds. The span may alternatively be positive or negative. The implementation may impose a minimum and/or a maximum time span size.

Calendar Structures

The time and time span abstractions are implemented in opaque types. The client does not know about the internal implementation of those data types: functions are provided to both get and manipulate the values of both time and time spans.

Two data structures are provided to hold the several attributes that conform time and time spans: pdf_time_cal_s and pdf_time_cal_span_s.

The pdf_time_cal_s structure holds information about a specific time represented in calendar items:

Year

A year number. Negative values may be supported in some systems.

Month

A month number. The valid range is 1..12.

Day

A day number. The valid range is 1..31.

Day of week

Day of the week. The valid range is 1..7 (Monday to Sunday).

Hour

An hour. The valid range is 0..23.

Minute

A minute. The valid range is 0..59.

Second

A second. The valid range is 0..59.

GMT Offset

A relative offset with GMT. May be negative.

The pdf_time_cal_span_s structure holds information about a time span represented in calendar items:

Years

Number of years of the time span.

Months

Number of months of the time span.

Days

Number of days of the time span.

Hours

Number of hours of the time span.

Minutes

Number of minutes of the time span.

Seconds

Number of seconds of the time span.

Note that many distinct calendar structures may correspond to a unique time span (12 months and 0 years is the same than 0 months and 1 year, for example). The functions filling pdf_time_cal_span_s will always use the normalized time span calendar structure for a given time span. The rule to build normalized time span calendar structures is to maximize the values of the fields with the following precedence relationship: years <- months <- days <- hours <- minutes <- seconds.

Supported Time Formats

The time module support the following time formats:

• PDF date strings (see Date).
• ISO 8601 date and time format [1].
• ASN1
• UTC ASN1

Conversion and parsing functions are provided for all the above date formats.

Operations

Time Creation and Destruction

The following operations are provided in order to create and destroy time data abstractions.

• Create a new time initialized to the Epoch (Jan 1 1970-01-01 00:00:00 UTC).
• Dup a new time variable from a given one, allocating any needed resource.
• Destroy a time data abstraction freeing all used resources.

Time Values Management

The following operations are provided in order to manage the values contained in time data abstractions. Calendar structures are used to hold the attributes of the time data abstractions.

• Copy the value of a time data abstraction to another data abstraction.
• Clear the value of a time data abstraction (set it to the Epoch).
• Add a time span data abstraction to the value of a given time data abstraction and store the result as the new value of the time data abstraction.
• Subtract a time span data abstraction to the value of a given time data abstraction and store the result as the new value of the time data abstraction.
• Add a time span represented in a calendar structure to the value of a given time data abstraction and store the result as the new value of the time data abstraction.
• Subtract a time span represented in a calendar structure to the value of a given time data abstraction and store the result as the new value of the time data abstraction.
• Fill a calendar structure with the local calendar time of a given time data abstraction.
• Fill a calendar structure with the UTC calendar time of a given time variable.
• Set the value of a time data abstraction to a given calendar time.
• Set the local time offset of a time data abstraction to the one used by the operating system.
• Calculate the time span that goes from a time data abstraction to another data abstraction and store its attributes into a calendar structure.
• Calculate the time span that goes from a time data abstraction to another data abstraction and store its attributes into a time span data abstraction.
• Compare two time data abstractions.

Time Printing and Parsing

The following operations are provided in order to perform string->time and time->string conversions.

• Create a string representation of a time data abstraction according to a given supported time format.
• Get a string containing a time specification in some format and fill a time data abstraction with the parsed values.

Getting the Current Time

The following operations are provided in order to get the current time indicated by the operating system.

• Set the value of a time data abstraction to the current local time used by the operating system.
• Set the value of a time data abstraction to the current UTC time used by the operating system.

Time Span Creation and Destruction

The following operations are provided in order to create and destroy time span data abstractions.

• Create a new time span data abstraction initialized with a zero value (0 seconds).
• Dup a new time span data abstraction from another time span data abstraction.
• Destroy a time span data abstraction freeing all used resources.

Time Span Values Management

The following operations are provided to manage the values contained into time span data abstractions. Calendar structures are used to hold the attributes of the time span data abstractions.

• Set the duration of a time span from two 32-bit integers representing the high part and the low part of a 64-bit value representing the number of seconds.
• Set the duration of a time span from a 32-bit integer representing the number of seconds.
• Make a positive time span into a negative one or make a negative time span into a positive one.
• Add two time span data abstractions and store the result in another time span abstraction.
• Copy the value of a time span data abstraction into another time span data abstraction.
• Difference two time span data abstractions and store the result (maybe negative) into another time span abstraction.
• Get the value of a time span abstraction in seconds.
• Compare the length of two given time span abstractions.

Management of Time Span Calendar Structures

The following operations are provided to ease the management of calendar structures containing the attributes of time span data abstractions.

• Add two calendar structures containing time spans and store the result in another calendar structure.
• Compare two calendar structures containing time spans previously resolved with a given base time.
• Compute the difference between two calendar structures containing time spans relative to a given base time and store it in a given calendar structure.