[m-rev.] for post-commit review: centralize decisions about mutables' aux preds

[Julien Fischer]

Hi Zoltan,

On Thu, 5 Sep 2019, Zoltan Somogyi wrote:

> On Sun, 01 Sep 2019 18:21:45 +1000 (AEST), "Zoltan Somogyi" <zoltan.somogyi at runbox.com> wrote:
>> I know the new predicates in set.m need both copying to the other
>> set modules and an entry in NEWS, but I want to do that in a day or two,
>> after I propose and get your feedback on a standard order of predicates
>> in the various set modules.
>
> The proposed order of predicates in set.m is attached. I tried to
>
> - put the predicates into logical groups,
> - put the groups into a logical order, and
> - put the predicates into a logical order within each group.
>
> Tell me what you think.

I think the proposed ordering and grouping is fine.  There a few issues
and one proposal that I've noted below.

> :- module set.
> :- interface.
>
> :- import_module bool.
> :- import_module list.
>
> %---------------------------------------------------------------------------%
>
> :- type set(T).
>
> %---------------------------------------------------------------------------%
> %
> % The initial creation of sets.
> %

You can dispense with the word "The" there.

>     % `init(Set)' is true iff `Set' is an empty set.
>     %
> :- func init = set(T).
> :- pred init(set(T)::uo) is det.
>
>     % `singleton_set(Elem, Set)' is true iff `Set' is the set
>     % containing just the single element `Elem'.
>     %
> :- pred singleton_set(T, set(T)).
> :- mode singleton_set(in, out) is det.
> :- mode singleton_set(out, in) is semidet.
>
> :- func make_singleton_set(T) = set(T).
>
> %---------------------------------------------------------------------------%
> %
> % Emptyness and singleton-ness tests.
> %

Emptiness.

>     % `empty(Set)' is true iff `Set' is an empty set.
>     % `is_empty' is a synonym for `empty'.
>     %
> :- pred empty(set(T)::in) is semidet.
> :- pred is_empty(set(T)::in) is semidet.
>
>     % `non_empty(Set)' is true iff `Set' is not an empty set.
>     % `is_non_empty' is a synonym for `non_empty'.
>     %
> :- pred non_empty(set(T)::in) is semidet.
> :- pred is_non_empty(set(T)::in) is semidet.
>
> :- pred is_singleton(set(T)::in, T::out) is semidet.
>

I think we should consider deprecating empty/1 and non_empty/1 in favour
of the is_ versions.

> %---------------------------------------------------------------------------%
> %
> % Membership tests.
> %
>
>     % `member(X, Set)' is true iff `X' is a member of `Set'.
>     %
> :- pred member(T, set(T)).
> :- mode member(in, in) is semidet.
> :- mode member(out, in) is nondet.
>
>     % `set_is_member(X, Set, Result)' returns `Result = yes'

There's a (existing) typo there: s/set_is_member/is_member/

>     % iff `X' is a member of `Set'.
>     %
> :- pred is_member(T::in, set(T)::in, bool::out) is det.
>
>     % `contains(Set, X)' is true iff `X' is a member of `Set'.
>     %
> :- pred contains(set(T)::in, T::in) is semidet.

Julien.