Compatible Doclog docs for library(between).
+/** Predicates that generate integers
+
+These predicates can be used to reason about integers in a reduced domain that
+follow some property. `library(clpz)` provides another way of reasoning about
+integers that may also be interesting.
+*/
+
:- module(between, [between/3, gen_int/1, gen_nat/1, numlist/2, numlist/3, repeat/1]).
%% TODO: numlist/5.
:- use_module(library(lists), [length/2]).
:- use_module(library(error)).
+%% between(+Lower, +Upper, -X).
+%
+% Given Lower and Upper are both integer numbers, true iff X is an integer so that _Lower =< X =< Upper_.
+% Can be used both to check if X is between Lower and Upper or to generate an integer between
+% Lower and Upper.
+%
+% Examples:
+%
+% ```
+% ?- between(10, 20, 15).
+% true.
+% ?- between(10, 20, 25).
+% false.
+% ?- between(3, 5, X).
+% X = 3
+% ; X = 4
+% ; X = 5.
+% ```
between(Lower, Upper, X) :-
must_be(integer, Lower),
must_be(integer, Upper),
@@ -30,6 +55,9 @@ enumerate_nats(I0, N) :-
I1 is I0 + 1,
enumerate_nats(I1, N).
+%% gen_nat(?N)
+%
+% True iff N is a natural number.
gen_nat(N) :-
can_be(integer, N),
( var(N) -> enumerate_nats(0, N)
@@ -44,6 +72,9 @@ enumerate_ints(I0, N) :-
I1 is I0 + 1,
enumerate_ints(I1, N).
+%% gen_int(?N)
+%
+% True iff N is an integer.
gen_int(N) :-
can_be(integer, N),
( var(N) -> enumerate_ints(0, N)
@@ -55,9 +86,24 @@ repeat_integer(N) :-
repeat_integer(N0) :-
N0 > 0, N1 is N0 - 1, repeat_integer(N1).
+%% repeat(+N)
+%
+% Succeeds N times. This predicate is only included for compatibility and *should not be used*
+% because it lacks a declarative interpretation.
repeat(N) :-
must_be(integer, N), repeat_integer(N).
+%% numlist(?Upper, ?List)
+%
+% True iff List is the list of integers _[1, ..., Upper]_. Example:
+%
+% ```
+% ?- numlist(X, Y).
+% X = 1, Y = [1],
+% ; X = 2, Y = [1,2]
+% ; X = 3, Y = [1,2,3]
+% ; ... .
+% ```
numlist(Upper, List) :-
( integer(Upper) -> findall(X, between(1, Upper, X), List)
; List = [_|_], length(List, Upper), findall(X, between(1, Upper, X), List)
@@ -106,5 +152,14 @@ gen_ints(L, U) :-
),
L =< U.
+%% numlist(?Lower, ?Upper, ?List).
+%
+% True iff List is a list of the form _[Lower, ..., Upper]_.
+% Example:
+%
+% ```
+% ?- numlist(5, 10, X).
+% X = [5,6,7,8,9,10].
+% ```
numlist(Lower, Upper, List) :-
gen_ints(Lower, Upper), findall(X, between(Lower, Upper, X), List).
