rishi/scryer-prolog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #1698 from triska/time_doc

Browse Source 
DOC: convert library(time) documentation to DocLog format
This commit is contained in:
Mark Thom
2023-01-24 22:43:53 +01:00
committed by GitHub
parent 1f872c3f0c d742d4cde9
commit c30c9dc98f
1 changed files with 59 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
src/lib/time.pl
View File

@@ -1,47 +1,11 @@
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Written 2020, 2021 by Markus Triska (triska@metalevel.at)
Written 2020-2023 by Markus Triska (triska@metalevel.at)
Part of Scryer Prolog.
This library provides predicates for reasoning about time.
current_time(T) yields the current system time in an opaque form,
called a time stamp. Use format_time//2 to describe strings that
contain attributes of the time stamp.
The nonterminal format_time//2 describes a list of characters that
are formatted according to a format string. Usage:
phrase(format_time(FormatString, TimeStamp), Cs)
TimeStamp represents a moment in time in an opaque form, as for
example obtained by current_time/1.
FormatString is a list of characters that are interpreted literally,
except for the following specifiers (and possibly more in the future):
%Y year of the time stamp. Example: 2020.
%m month number (01-12), zero-padded to 2 digits
%d day number (01-31), zero-padded to 2 digits
%H hour number (00-24), zero-padded to 2 digits
%M minute number (00-59), zero-padded to 2 digits
%S second number (00-60), zero-padded to 2 digits
%b abbreviated month name, always 3 letters
%a abbreviated weekday name, always 3 letters
%A full weekday name
%j day of the year (001-366), zero-padded to 3 digits
%% the literal %
Example:
?- current_time(T), phrase(format_time("%d.%m.%Y (%H:%M:%S)", T), Cs).
T = [...], Cs = "11.06.2020 (00:24:32)".
sleep(S) sleeps for S seconds (a floating point number).
time(Goal) reports the execution time of Goal.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
/** This library provides predicates for reasoning about time.
*/
:- module(time, [max_sleep_time/1, sleep/1, time/1, current_time/1, format_time//2]).
:- use_module(library(format)).
@@ -51,10 +15,51 @@
:- use_module(library(lists)).
:- use_module(library(charsio), [read_from_chars/2]).
%% current_time(-T)
%
% Yields the current system time _T_ in an opaque form, called a
% _time stamp_. Use `format_time//2` to describe strings that contain
% attributes of the time stamp.
current_time(T) :-
'$current_time'(T0),
read_from_chars(T0, T).
%% format_time(FormatString, TimeStamp)//
%
% The nonterminal format_time//2 describes a list of characters that
% are formatted according to a format string. Usage:
%
% ```
% phrase(format_time(FormatString, TimeStamp), Cs)
% ```
%
% TimeStamp represents a moment in time in an opaque form, as for
% example obtained by `current_time/1`.
%
% FormatString is a list of characters that are interpreted literally,
% except for the following specifiers (and possibly more in the future):
%
% | %Y | year of the time stamp. Example: 2020. |
% | %m | month number (01-12), zero-padded to 2 digits |
% | %d | day number (01-31), zero-padded to 2 digits |
% | %H | hour number (00-24), zero-padded to 2 digits |
% | %M | minute number (00-59), zero-padded to 2 digits |
% | %S | second number (00-60), zero-padded to 2 digits |
% | %b | abbreviated month name, always 3 letters |
% | %a | abbreviated weekday name, always 3 letters |
% | %A | full weekday name |
% | %j | day of the year (001-366), zero-padded to 3 digits |
% | %% | the literal % |
%
% Example:
%
% ```
% ?- current_time(T), phrase(format_time("%d.%m.%Y (%H:%M:%S)", T), Cs).
% T = [...], Cs = "11.06.2020 (00:24:32)".
% ```
format_time([], _) --> [].
format_time(['%','%'|Fs], T) --> !, "%", format_time(Fs, T).
format_time(['%',Spec|Fs], T) --> !,
@@ -65,8 +70,17 @@ format_time(['%',Spec|Fs], T) --> !,
format_time(Fs, T).
format_time([F|Fs], T) --> [F], format_time(Fs, T).
%% max_sleep_time(T)
%
% The maximum admissible time span for `sleep/1`.
max_sleep_time(0xfffffffffffffbff).
%% sleep(S)
%
% Sleeps for S seconds (a floating point number or integer).
sleep(T) :-
builtins:must_be_number(T, sleep),
( T < 0 ->
@@ -91,6 +105,11 @@ time_next_id(N) :-
),
asserta(time_id(N)).
%% time(Goal)
%
% Reports the execution time of Goal.
time(Goal) :-
'$cpu_now'(T0),
time_next_id(ID),