{"size": 4496, "ext": "scrbl", "max_stars_repo_path": "doc/sagittarius/timezone.scrbl", "max_stars_repo_name": "christoff-buerger/sagittarius-scheme", "max_stars_repo_stars_event_min_datetime": "2015-11-07T07:13:35.000Z", "max_stars_repo_stars_event_max_datetime": "2022-02-15T03:35:14.000Z", "max_issues_repo_path": "doc/sagittarius/timezone.scrbl", "max_issues_repo_name": "christoff-buerger/sagittarius-scheme", "max_issues_repo_issues_event_min_datetime": "2016-04-28T21:59:59.000Z", "max_issues_repo_issues_event_max_datetime": "2021-07-01T08:42:21.000Z", "max_forks_repo_path": "doc/sagittarius/timezone.scrbl", "max_forks_repo_name": "christoff-buerger/sagittarius-scheme", "max_forks_repo_forks_event_min_datetime": "2016-12-28T12:41:23.000Z", "max_forks_repo_forks_event_max_datetime": "2020-02-26T20:52:02.000Z"}
{"max_stars_count": 39, "max_issues_count": 3, "max_forks_count": 4, "avg_line_length": 38.7586206897, "max_line_length": 80, "alphanum_fraction": 0.7086298932}
@; -*- coding:utf-8; -*-

@subsection[:tag "lib.sagittarius.timezone"]{(sagittarius timezone) - Timezone}

@define[Library]{@name{(sagittarius timezone)}}
@desc{This library provides timezone related procedures. The timezone database
is from 
@hyperlink[:href "https://www.iana.org/time-zones"]{IANA - Time Zone Database}.
}

@define[Function]{@name{timezone?} @args{obj}}
@desc{Returns #t if given @var{obj} is a timezone object, otherwise #f.}

@define[Function]{@name{timezone} @args{name}}
@desc{Retrieves timezone object related to @var{name}. The @var{name}
must be a string and proper name of TZID such as @code{Europe/Amsterdam}.
If the given name is not found, then @code{GMT} is returned as the fallback.}

@define[Function]{@name{timezone-offset} @args{tz :optional when}}
@desc{Returns give offset of timezone @var{tz}.

If optional argument @var{when} is specified, it must be a time object,
then the offset is calculated the specified time. Otherwise @code{current-time},
is used.

This procedure considers daylight saving time (DST). Means, if the timezone
has DST, then the return value is depending on the @var{when}. For example, 
@code{Europe/Amsterdam} has DST so if the @var{when} is in DST, then the
returning offset is @code{7200}, otherwise @code{3600}.
}

@define[Function]{@name{timezone-dst?} 
 @args{tz :optional (when (current-time))}}
@desc{Returns #t if @var{when} is in DST, otherwise #f.}

@define[Function]{@name{timezone-short-name} 
 @args{tz :optional (when (current-time))}}
@desc{Returns the short name of given timezone @var{tz}.

This procedure considers DST. Means if @var{when} is in DST, then short name
is DST name, otherwise standard name. For example, timezone 
@code{Europe/Amsterdam} has 2 names, @code{CET} and @code{CEST}. If the
given @var{when} is in DST, then @code{CEST} is returned, otherwise @code{CET}
is returned.
}

@define[Function]{@name{timezone-raw-offset} @args{tz :optional when}}
@desc{Returns GMT offset of given timezone @var{tz}. 

If optional argument @var{when} is given and must be a time object, then
the returning offset is the historical offset. If it's not given, then
the procedure reutnrs current timezone offset.
}

Above procedures also considers when the timezone is started. Means, given
timezone has histories, such as when the daylight saving time is starting
or ending, when that timezone started, etc. It may return different value
according to the @var{when}. Following is the example of timezone history:
@codeblock{
(let ((tz (timezone "Europe/Dublin"))
      (now (date->time-utc (make-date 0 0 0 0 24 7 2015 0)))
      ;; 1:00	-	IST	1971 Oct 31  2:00u
      (no-rule-past (date->time-utc (make-date 0 0 0 0 24 7 1971 0)))
      ;; 0:00	GB-Eire	GMT/IST	1968 Oct 27
      (rule-past (date->time-utc (make-date 0 0 0 0 24 7 1968 0))))
  (timezone-short-name tz now)          ;; => "GMT/IST"
  (timezone-short-name tz no-rule-past) ;; => "IST"

  ;; no DST
  (timezone-offset tz no-rule-past)     ;; => 3600 

  (timezone-raw-offset tz)              ;; => 0
  (timezone-raw-offset tz no-rule-past) ;; => 3600
  (timezone-raw-offset tz rule-past)    ;; => 0

  (timezone-short-name tz rule-past)    ;; => "GMT/IST"
  )
}

@define[Function]{@name{timezone-name} @args{tz}}
@desc{Returns TZID of given timezone @var{tz}.}

@define[Function]{@name{timezone-name-list}}
@desc{Returns supported TZIDs.}

@define[Function]{@name{zone-offset->timezones} @args{offset :optional when}}
@desc{Returns list of timezones whose offsets matched @var{offset}.

This procedure considers the time. For example, if the given @var{offset} is
@code{3600} which is UTC+1 however if it's summer time, then the returning
list doesn't contain some of timezones (e.g. Amsterdam).

The optional argument @var{when} specifies the time to consider. If it's not
specified, then the returning value of @code{current-time} is used.

@codeblock{
(zone-offset->timezones 3600) ;; => '(#<timezone Etc/GMT-1> ...)
;; offset +15:00 doesn't exist
(zone-offset->timezones (* 15 3600)) ;; => '()
}

}

@define[Function]{@name{zone-offset->timezones*} @args{offset :optional when}}
@desc{Similar with @code{zone-offset->timezones*}, the difference is
this procedure creates an anonymous timezone if there's no registered timezone
matching with the given @var{offset}.

@codeblock{
(zone-offset->timezones* 3600) ;; => '(#<timezone Etc/GMT-1> ...)
;; offset +15:00 doesn't exist
(zone-offset->timezones* (* 15 3600)) ;; => '(#<timezone +15:00>)
}

}
