[m-rev.] for review: Deprecate array least_index/greatest_index functions and add replacements.

[Peter Wang]

As suggested by Julien a few months back.

library/array.m:
    Add det_least_index, semidet_least_index, det_greatest_index,
    semidet_greatest_index functions.

    Deprecate least_index, greatest_index with the intention of making
    them semidet eventually.

NEWS:
    Announce changes.
---
 NEWS            | 14 +++++++++++-
 library/array.m | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index 759c4130a..409d05c7a 100644
--- a/NEWS
+++ b/NEWS
@@ -443,7 +443,19 @@ Changes to the Mercury standard library:
    - snoc/3
    - find_first_match/3
 
-* The following function has been added to the array2d module
+* The following function has been added to the array module:
+
+   - det_least_index/1
+   - semidet_least_index/1
+   - det_greatest_index/1
+   - semidet_greatest_index/1
+
+   The following functions in the array module have been deprecated:
+
+   - least_index/1
+   - greatest_index/1
+
+* The following function has been added to the array2d module:
 
    - is_empty/1
 
diff --git a/library/array.m b/library/array.m
index 5291fdf72..1e38f4a90 100644
--- a/library/array.m
+++ b/library/array.m
@@ -2,6 +2,7 @@
 % vim: ft=mercury ts=4 sw=4 et
 %---------------------------------------------------------------------------%
 % Copyright (C) 1993-1995, 1997-2012 The University of Melbourne.
+% Copyright (C) 2013-2018 The Mercury team.
 % This file may only be copied under the terms of the GNU Library General
 % Public License - see the file COPYING.LIB in the Mercury distribution.
 %---------------------------------------------------------------------------%
@@ -147,10 +148,29 @@
 %:- mode min(array_ui) = out is det.
 :- mode min(in) = out is det.
 
+    % least_index returns the lower bound of the array.
+    % In future, it will be changed to behave like semidet_least_index,
+    % failing on an empty array instead of returning an out-of-bounds index.
+    %
+:- pragma obsolete(least_index/1).
 :- func least_index(array(T)) = int.
 %:- mode least_index(array_ui) = out is det.
 :- mode least_index(in) = out is det.
 
+    % det_least_index returns the lower bound of the array.
+    % Throws an exception if the array is empty.
+    %
+:- func det_least_index(array(T)) = int.
+%:- mode det_least_index(array_ui) = out is det.
+:- mode det_least_index(in) = out is det.
+
+    % semidet_least_index returns the lower bound of the array,
+    % or fails if the array is empty.
+    %
+:- func semidet_least_index(array(T)) = int.
+%:- mode semidet_least_index(array_ui) = out is semidet.
+:- mode semidet_least_index(in) = out is semidet.
+
     % max returns the upper bound of the array.
     % Returns lower bound - 1 for an empty array
     % (always -1 in this implementation).
@@ -163,10 +183,29 @@
 %:- mode max(array_ui) = out is det.
 :- mode max(in) = out is det.
 
+    % greatest_index returns the upper bound of the array.
+    % In future, it will be changed to behave like semidet_greatest_index,
+    % failing on an empty array instead of returning an out-of-bounds index.
+    %
+:- pragma obsolete(greatest_index/1).
 :- func greatest_index(array(T)) = int.
 %:- mode greatest_index(array_ui) = out is det.
 :- mode greatest_index(in) = out is det.
 
+    % det_greatest_index returns the upper bound of the array.
+    % Throws an exception if the array is empty.
+    %
+:- func det_greatest_index(array(T)) = int.
+%:- mode det_greatest_index(array_ui) = out is det.
+:- mode det_greatest_index(in) = out is det.
+
+    % semidet_greatest_index returns the upper bound of the array,
+    % or fails if the array is empty.
+    %
+:- func semidet_greatest_index(array(T)) = int.
+%:- mode semidet_greatest_index(array_ui) = out is semidet.
+:- mode semidet_greatest_index(in) = out is semidet.
+
     % size returns the length of the array,
     % i.e. upper bound - lower bound + 1.
     %
@@ -3138,8 +3177,38 @@ out_of_bounds_error(Array, Index, PredName) :-
 
 least_index(A) = array.min(A).
 
+det_least_index(A) = Index :-
+    ( if array.is_empty(A) then
+        error("array.det_least_index: empty array")
+    else
+        Index = array.min(A)
+    ).
+
+semidet_least_index(A) = Index :-
+    ( if array.is_empty(A) then
+        fail
+    else
+        Index = array.min(A)
+    ).
+
+%---------------------------------------------------------------------------%
+
 greatest_index(A) = array.max(A).
 
+det_greatest_index(A) = Index :-
+    ( if array.is_empty(A) then
+        error("array.det_greatest_index: empty array")
+    else
+        Index = array.max(A)
+    ).
+
+semidet_greatest_index(A) = Index :-
+    ( if array.is_empty(A) then
+        fail
+    else
+        Index = array.max(A)
+    ).
+
 %---------------------------------------------------------------------------%
 
 array_to_doc(A) =
-- 
2.16.3