summaryrefslogtreecommitdiff
path: root/doc/api/libdate/manipulation.txt
blob: 22f9b9e8b33c49b4a549f7a904cfbf736c9e0238 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

{
	title: Creation and Manipulation
	description: Libdate API documentation.
}

Creation and Manipulation
-------------------------
    pkg date =
            /* useful constructors */
            const utcnow	: (-> instant)
            const now	: (tz : byte[:] -> instant)
            const tozone	: (d : instant, zone : byte[:]	-> instant)
            const mkdate	: (y : int, m : int, day : int, zone : byte[:]	-> instant)
            const mkdatetime	: (year : int, mon : int, day : int, \
                    h : int, m : int, s : int, zone : byte[:]	-> instant)
            const mkinstant	: (tm : std.time, zone : byte[:]	-> instant)

            const localoff	: (tm : std.time -> duration)
            const tzoff	: (tzname : byte[:], tm : std.time	-> duration)
            const tzname	: (tzoff : int -> byte[:])
            const isleap	: (d : instant	-> bool)

            /* date differences */
            const add	: (d : instant, dt : duration	-> instant)
            const sub	: (d : instant, dt : duration	-> instant)
            const addperiod	: (d : instant, dt : period	-> instant)
            const subperiod	: (d : instant, dt : period	-> instant)

            const duration	: (a : instant, b : instant	-> duration)

            pkglocal const recalc	: (inst : instant# -> std.time)
    ;;

Creation
-----------

    const utcnow	: (-> instant)

Creates an instant representing the current time. The timezone is UTC. As a
general philosophical point, dates written out persisetntly should generally
be in UTC, so this function should generally be used to get dates.

Returns: An instant representing the current time in the UTC timezone.

    const now	: (tz : byte[:] -> instant)

Creates an instant representing the current time. The timezone is the local
time. This is useful for displaying dates and times to the user.

Returns: An instant representing the current time in the local timezone.

    const tozone	: (d : instant, zone : byte[:]	-> instant)

Takes an instant and converts it to a new timezone. This takes the instants by
value, and therefore, does not mutate any of its arguments.

Returns: An instant representing provided time in the requested timezone.

    const mkdate	: (y : int, m : int, day : int, zone : byte[:]	-> instant)

Creates a date with the given year, month, and day in the given timezone. The
time is set to 0:00:00

Returns: A date representing the given ymd

    const mkdatetime	: (year : int, mon : int, day : int, \
            h : int, m : int, s : int, zone : byte[:]	-> instant)

Creates a date and time pair with the given year, month, day, at the time
h, m, s, in the provided timezone. The microseconds are zeroed.

Returns: A date representing the given ymd:hms

    const mkinstant	: (tm : std.time, zone : byte[:]	-> instant)

Creates an instant from a time type. This time can be derived from the
standard library, or computed from any other source. The time is in
microseconds since the Unix epoch (Jan 1 1970, 0:00, UTC).

Returns: An instant representing a std.time in the requested timezone

Timezones
---------

    const localoff	: (tm : std.time -> duration)

Gets the local timezone offset for a time. Note that timezones can change due
daylight savings, politics, and other similar factors, so a timezone offset
needs to be associated with a specific instant.

Returns: a duration representing the local timezone offset.

    const tzoff	: (tzname : byte[:], tm : std.time	-> duration)

Gets the timezone offset for a time and timezone pair. Note that timezones can
change due daylight savings, politics, and other similar factors, so a
timezone offset needs to be associated with a specific instant.

Returns: a duration representing the requested timezone offset.

    const isleap	: (d : instant	-> bool)

Returns: whether a specific instant is within a leap year or not.

Manipulation
------------
    
    const add	: (d : instant, dt : duration	-> instant)
    const sub	: (d : instant, dt : duration	-> instant)

Adds or subtracts a duration from a date. A duration is an absolute length of
time, and is not adjusted for calendar shifts around DST and similar events.

Returns: an instant representing the adjusted time.

    const addperiod	: (d : instant, dt : period	-> instant)
    const subperiod	: (d : instant, dt : period	-> instant)

Adds or subtracts a period from a date. A period is a humanized length of
time, and is adjusted for calendar shifts around DST and similar events.

Returns: an instant representing the adjusted time.

    const duration	: (a : instant, b : instant	-> duration)

Returns: the duration representing the difference between the two provided
instants.