[m-rev.] for review: Clarify meaning of "abort" in library documentation.
Peter Wang
novalazy at gmail.com
Sun Oct 8 15:57:07 AEDT 2017
library/assoc_list.m:
library/bag.m:
library/bimap.m:
library/calendar.m:
library/char.m:
library/digraph.m:
library/list.m:
library/map.m:
library/multi_map.m:
library/psqueue.m:
library/rbtree.m:
library/string.m:
library/term.m:
library/tree234.m:
library/type_desc.m:
library/univ.m:
library/varset.m:
Replace most occurrences of "abort" with "throw an exception".
Slightly improve the documentation for map.search, map.lookup,
map.inverse_search.
library/deconstruct.m:
Replace "abort" with "runtime abort" where that is meant.
---
library/assoc_list.m | 3 ++-
library/bag.m | 9 +++++----
library/bimap.m | 2 +-
library/calendar.m | 6 +++---
library/char.m | 4 ++--
library/deconstruct.m | 10 +++++-----
library/digraph.m | 2 +-
library/list.m | 18 +++++++++---------
library/map.m | 33 ++++++++++++++++++---------------
library/multi_map.m | 18 +++++++++---------
library/psqueue.m | 2 +-
library/rbtree.m | 2 +-
library/string.m | 3 ++-
library/term.m | 2 +-
library/tree234.m | 4 ++--
library/type_desc.m | 6 +++---
library/univ.m | 2 +-
library/varset.m | 4 ++--
18 files changed, 68 insertions(+), 62 deletions(-)
diff --git a/library/assoc_list.m b/library/assoc_list.m
index a3c04fa96..6a65c2569 100644
--- a/library/assoc_list.m
+++ b/library/assoc_list.m
@@ -33,7 +33,8 @@
:- func reverse_members(assoc_list(K, V)) = assoc_list(V, K).
:- pred reverse_members(assoc_list(K, V)::in, assoc_list(V, K)::out) is det.
- % Zip together two lists; abort if they are of different lengths.
+ % Zip together two lists.
+ % Throw an exception if they are of different lengths.
%
:- func from_corresponding_lists(list(K), list(V)) = assoc_list(K, V).
:- pred from_corresponding_lists(list(K)::in, list(V)::in,
diff --git a/library/bag.m b/library/bag.m
index 1a22535dc..be17484ab 100644
--- a/library/bag.m
+++ b/library/bag.m
@@ -116,7 +116,7 @@
:- pred remove(T::in, bag(T)::in, bag(T)::out) is semidet.
% Remove one occurrence of a particular value from a bag.
- % Abort if the item does not exist in the bag.
+ % Throw an exception if the item does not exist in the bag.
%
:- func det_remove(bag(T), T) = bag(T).
:- pred det_remove(T::in, bag(T)::in, bag(T)::out) is det.
@@ -135,8 +135,8 @@
:- pred remove_list(list(T)::in, bag(T)::in, bag(T)::out) is semidet.
% Remove a list of values from a bag. Duplicates are removed from the bag
- % the appropriate number of times. Abort if any of the items in the list
- % do not exist in the bag.
+ % the appropriate number of times. Throw an exception if any of the items
+ % in the list do not exist in the bag.
%
:- func det_remove_list(bag(T), list(T)) = bag(T).
:- pred det_remove_list(list(T)::in, bag(T)::in, bag(T)::out) is det.
@@ -147,7 +147,8 @@
:- pred remove_set(set(T)::in, bag(T)::in, bag(T)::out) is semidet.
% Remove a set of values from a bag. Each value is removed once.
- % Abort if any of the items in the set do not exist in the bag.
+ % Throw an exception if any of the items in the set do not exist in the
+ % bag.
%
:- func det_remove_set(bag(T), set(T)) = bag(T).
:- pred det_remove_set(set(T)::in, bag(T)::in, bag(T)::out) is det.
diff --git a/library/bimap.m b/library/bimap.m
index 264e42ddd..4c21a04fd 100644
--- a/library/bimap.m
+++ b/library/bimap.m
@@ -122,7 +122,7 @@
% with corresponding value OldV, set MaybeOldV to yes(OldV). If it
% is not in the bimap, then insert it with value V. The value of V
% should be guaranteed to be different to all the values already
- % in !.Bimap. If it isn't, this predicate will abort.
+ % in !.Bimap. If it isn't, this predicate will throw an exception.
%
:- pred search_insert(K::in, V::in, maybe(V)::out,
bimap(K, V)::in, bimap(K, V)::out) is det.
diff --git a/library/calendar.m b/library/calendar.m
index 36a8a52a2..2abf9c50e 100644
--- a/library/calendar.m
+++ b/library/calendar.m
@@ -125,7 +125,7 @@
:- pred init_date(year::in, month::in, day_of_month::in, hour::in,
minute::in, second::in, microsecond::in, date::out) is semidet.
- % Same as above, but aborts if the date is invalid.
+ % Same as above, but throws an exception if the date is invalid.
%
:- func det_init_date(year, month, day_of_month, hour, minute, second,
microsecond) = date.
@@ -143,7 +143,7 @@
%
:- pred date_from_string(string::in, date::out) is semidet.
- % Same as above, but aborts if the string is not a valid date.
+ % Same as above, but throws an exception if the string is not a valid date.
%
:- func det_date_from_string(string) = date.
@@ -257,7 +257,7 @@
%
:- pred duration_from_string(string::in, duration::out) is semidet.
- % Same as above, but aborts if the duration string is invalid.
+ % Same as above, but throws an exception if the duration string is invalid.
%
:- func det_duration_from_string(string) = duration.
diff --git a/library/char.m b/library/char.m
index f1b9ff24f..73b0b8081 100644
--- a/library/char.m
+++ b/library/char.m
@@ -66,8 +66,8 @@
%
:- pred from_int(int::in, char::out) is semidet.
- % Converts an integer to its corresponding character. Aborts
- % if there isn't one.
+ % Converts an integer to its corresponding character.
+ % Throws an exception if there isn't one.
%
:- func det_from_int(int) = char.
:- pred det_from_int(int::in, char::out) is det.
diff --git a/library/deconstruct.m b/library/deconstruct.m
index 28c8c2519..6d5cf37ba 100644
--- a/library/deconstruct.m
+++ b/library/deconstruct.m
@@ -30,7 +30,7 @@
% concrete representation.
%
% The value `do_not_allow' means that in such circumstances the
- % predicate should abort.
+ % predicate should cause a runtime abort.
%
% The value `canonicalize' means that in such circumstances the
% predicate should return a constant giving the identity of the type,
@@ -130,7 +130,7 @@
% Given a data item, return the number of the functor,
% suitable for use by construct.construct, and the arity.
% Fail if the item does not have a discriminated union type.
- % Abort if the type has user-defined equality.
+ % Cause a runtime abort if the type has user-defined equality.
%
:- pred functor_number(T::in, functor_number_lex::out, int::out) is semidet.
@@ -139,7 +139,7 @@
% Given a data item, return the number of the functor,
% suitable for use by construct.construct, and the arity.
% Fail if the item does not have a discriminated union type.
- % Don't abort if the type has user-defined equality.
+ % Do not cause a runtime abort if the type has user-defined equality.
%
:- pred functor_number_cc(T::in, functor_number_lex::out,
int::out) is cc_nondet.
@@ -190,7 +190,7 @@
% det_arg(Data, NonCanon, Index, Argument)
%
% Same as arg/4, except that for cases where arg/4 would fail,
- % det_arg/4 will abort.
+ % det_arg/4 will throw an exception.
%
:- some [ArgT] pred det_arg(T, noncanon_handling, int, ArgT).
:- mode det_arg(in, in(do_not_allow), in, out) is det.
@@ -201,7 +201,7 @@
% det_named_arg(Data, NonCanon, Name, Argument)
%
% Same as named_arg/4, except that for cases where named_arg/4 would fail,
- % det_named_arg/4 will abort.
+ % det_named_arg/4 will throw an exception.
%
:- some [ArgT] pred det_named_arg(T, noncanon_handling, string, ArgT).
:- mode det_named_arg(in, in(do_not_allow), in, out) is det.
diff --git a/library/digraph.m b/library/digraph.m
index 912bf009c..0201f7067 100644
--- a/library/digraph.m
+++ b/library/digraph.m
@@ -63,7 +63,7 @@
:- pred search_key(digraph(T)::in, T::in, digraph_key(T)::out) is semidet.
% lookup_key returns the key associated with a vertex.
- % Aborts if the vertex is not in the graph.
+ % Throws an exception if the vertex is not in the graph.
%
:- func lookup_key(digraph(T), T) = digraph_key(T).
:- pred lookup_key(digraph(T)::in, T::in, digraph_key(T)::out) is det.
diff --git a/library/list.m b/library/list.m
index e696564d5..1a884cd7a 100644
--- a/library/list.m
+++ b/library/list.m
@@ -226,7 +226,7 @@
%
:- pred nth_member_search(list(T)::in, T::in, int::out) is semidet.
- % A deterministic version of nth_member_search, which aborts
+ % A deterministic version of nth_member_search, which throws an exception
% instead of failing if the element is not found in the list.
% NOTE_TO_IMPLEMENTORS XXX This pred is identical
% NOTE_TO_IMPLEMENTORS to det_index1_of_first_occurrence.
@@ -341,7 +341,7 @@
% det_replace_nth(List0, N, R) = List is true iff List is List0
% with N'th element replaced with R.
- % Aborts if N < 1 or if length of List0 < N.
+ % Throws an exception if N < 1 or if length of List0 < N.
% (Position numbers start from 1.)
%
:- func det_replace_nth(list(T), int, T) = list(T).
@@ -487,8 +487,8 @@
% det_split_list(N, List, Start, End):
%
- % A deterministic version of split_list, which aborts instead
- % of failing if `N' is not in 0 .. length(List).
+ % A deterministic version of split_list, which throws an exception
+ % instead of failing if `N' is not in 0 .. length(List).
%
:- pred det_split_list(int::in, list(T)::in, list(T)::out, list(T)::out)
is det.
@@ -507,8 +507,8 @@
%
:- pred last(list(T)::in, T::out) is semidet.
- % A deterministic version of last, which aborts instead of failing
- % if the input list is empty.
+ % A deterministic version of last, which throws an exception instead of
+ % failing if the input list is empty.
%
:- func det_last(list(T)) = T.
:- pred det_last(list(T)::in, T::out) is det.
@@ -518,8 +518,8 @@
%
:- pred split_last(list(T)::in, list(T)::out, T::out) is semidet.
- % A deterministic version of split_last, which aborts instead of
- % failing if the input list is empty.
+ % A deterministic version of split_last, which throws an exception
+ % instead of failing if the input list is empty.
%
:- pred det_split_last(list(T)::in, list(T)::out, T::out) is det.
@@ -559,7 +559,7 @@
% det_drop(N, List, End):
%
% `End' is the remainder of `List' after removing the first `N' elements.
- % Aborts if `N' is not in `0 .. length(List)'.
+ % Throws an exception if `N' is not in `0 .. length(List)'.
% See also: split_list.
%
:- pred det_drop(int::in, list(T)::in, list(T)::out) is det.
diff --git a/library/map.m b/library/map.m
index 2ddc35da6..a4b4bffc2 100644
--- a/library/map.m
+++ b/library/map.m
@@ -72,17 +72,19 @@
:- pred member(map(K, V)::in, K::out, V::out) is nondet.
- % Search map for key.
+ % Return the value associated with the given key in the map.
+ % Fail if the map does not contain that key.
%
:- func search(map(K, V), K) = V is semidet.
:- pred search(map(K, V)::in, K::in, V::out) is semidet.
- % Search map for key, but abort if search fails.
+ % Return the value associated with the given key in the map.
+ % Throw an exception if the map does not contain that key.
%
:- func lookup(map(K, V), K) = V.
:- pred lookup(map(K, V)::in, K::in, V::out) is det.
- % Search map for data.
+ % Search the map for key-value pairs with the given value.
%
:- pred inverse_search(map(K, V)::in, V::in, K::out) is nondet.
@@ -95,7 +97,7 @@
% Search for a key-value pair using the key. If there is no entry
% for the given key, returns the pair for the next lower key instead.
- % Aborts if there is no key with the given or lower value.
+ % Throws an exception if there is no key with the given or lower value.
%
:- pred lower_bound_lookup(map(K, V)::in, K::in, K::out, V::out) is det.
@@ -108,7 +110,7 @@
% Search for a key-value pair using the key. If there is no entry
% for the given key, returns the pair for the next higher key instead.
- % Aborts if there is no key with the given or higher value.
+ % Throws an exception if there is no key with the given or higher value.
%
:- pred upper_bound_lookup(map(K, V)::in, K::in, K::out, V::out) is det.
@@ -116,7 +118,7 @@
%
:- func max_key(map(K, V)) = K is semidet.
- % As above, but abort if there is no largest key.
+ % As above, but throw an exception if there is no largest key.
%
:- func det_max_key(map(K, V)) = K.
@@ -124,7 +126,7 @@
%
:- func min_key(map(K,V)) = K is semidet.
- % As above, but abort if there is no smallest key.
+ % As above, but throw an exception if there is no smallest key.
%
:- func det_min_key(map(K, V)) = K.
@@ -135,7 +137,7 @@
:- pred insert(K::in, V::in, map(K, V)::in, map(K, V)::out) is semidet.
% Insert a new key and corresponding value into a map.
- % Abort if the key already exists.
+ % Throw an exception if the key already exists.
%
:- func det_insert(map(K, V), K, V) = map(K, V).
:- pred det_insert(K::in, V::in, map(K, V)::in, map(K, V)::out) is det.
@@ -172,7 +174,7 @@
:- pred update(K::in, V::in, map(K, V)::in, map(K, V)::out) is semidet.
% Update the value corresponding to a given key
- % Abort if the key doesn't already exist.
+ % Throw an exception if the key doesn't already exist.
%
:- func det_update(map(K, V), K, V) = map(K, V).
:- pred det_update(K::in, V::in, map(K, V)::in, map(K, V)::out) is det.
@@ -193,8 +195,8 @@
:- pred transform_value(pred(V, V)::in(pred(in, out) is det), K::in,
map(K, V)::in, map(K, V)::out) is semidet.
- % Same as transform_value/4, but aborts instead of failing if the
- % key is not found.
+ % Same as transform_value/4, but throws an exception if the key is not
+ % found.
%
:- func det_transform_value(func(V) = V, K, map(K, V)) = map(K, V).
:- pred det_transform_value(pred(V, V)::in(pred(in, out) is det), K::in,
@@ -265,7 +267,8 @@
% Apply delete/3 to a sorted list of keys. The fact that the list
% is sorted may make this more efficient. (If the list is not sorted,
- % the result will be either an abort or incorrect output.)
+ % the predicate or function will either throw an exception or return
+ % incorrect output.)
%
:- func delete_sorted_list(map(K, V), list(K)) = map(K, V).
:- pred delete_sorted_list(list(K)::in, map(K, V)::in, map(K, V)::out)
@@ -277,7 +280,7 @@
:- pred remove(K::in, V::out, map(K, V)::in, map(K, V)::out) is semidet.
% Delete a key-value pair from a map and return the value.
- % Abort if the key is not present.
+ % Throw an exception if the key is not present.
%
:- pred det_remove(K::in, V::out, map(K, V)::in, map(K, V)::out) is det.
@@ -743,7 +746,7 @@
:- mode intersect(pred(in, in, out) is semidet, in, in, out) is semidet.
:- mode intersect(pred(in, in, out) is det, in, in, out) is det.
- % Calls intersect. Aborts if intersect fails.
+ % Calls intersect. Throws an exception if intersect fails.
%
:- func det_intersect(func(V, V) = V, map(K, V), map(K, V)) = map(K, V).
:- mode det_intersect(func(in, in) = out is semidet, in, in) = out is det.
@@ -779,7 +782,7 @@
:- mode union(pred(in, in, out) is semidet, in, in, out) is semidet.
:- mode union(pred(in, in, out) is det, in, in, out) is det.
- % Calls union. Aborts if union fails.
+ % Calls union. Throws an exception if union fails.
%
:- func det_union(func(V, V) = V, map(K, V), map(K, V)) = map(K, V).
:- mode det_union(func(in, in) = out is semidet, in, in) = out is det.
diff --git a/library/multi_map.m b/library/multi_map.m
index 5df4a66aa..f6b07cae2 100644
--- a/library/multi_map.m
+++ b/library/multi_map.m
@@ -65,14 +65,14 @@
% If the multi_map has an entry for the given key,
% succeed once for each of the corresponding values.
- % Otherwise, abort.
+ % Otherwise, throw an exception.
%
:- func lookup(multi_map(K, V), K) = list(V).
:- pred lookup(multi_map(K, V)::in, K::in, list(V)::out) is det.
% If the multi_map has an entry for the given key,
% succeed once for each of the corresponding values.
- % Otherwise, abort.
+ % Otherwise, throw an exception.
%
:- pred nondet_lookup(multi_map(K, V)::in, K::in, V::out) is nondet.
@@ -93,7 +93,7 @@
multi_map(K, V)::in, multi_map(K, V)::out) is semidet.
% Add the given key-value pair to the multi_map.
- % Abort if the key already exists.
+ % Throw an exception if the key already exists.
%
:- func det_insert(multi_map(K, V), K, V) = multi_map(K, V).
:- pred det_insert(K::in, V::in,
@@ -106,7 +106,7 @@
multi_map(K, V)::in, multi_map(K, V)::out) is semidet.
% Add the given key-value pair to the multi_map.
- % Abort if the key does not already exist.
+ % Throw an exception if the key does not already exist.
%
:- func det_update(multi_map(K, V), K, V) = multi_map(K, V).
:- pred det_update(K::in, V::in,
@@ -119,7 +119,7 @@
multi_map(K, V)::in, multi_map(K, V)::out) is semidet.
% Replace the list of values corresponding to the given key.
- % Aborts if the key does not already exist.
+ % Throws an exception if the key does not already exist.
%
:- func det_replace(multi_map(K, V), K, list(V)) = multi_map(K, V).
:- pred det_replace(K::in, list(V)::in,
@@ -166,7 +166,7 @@
% Delete a key from a multi_map and return the list of values
% previously corresponding to it.
- % Abort if the key is not present.
+ % Throw an exception if the key is not present.
%
:- pred det_remove(K::in, list(V)::out,
multi_map(K, V)::in, multi_map(K, V)::out) is det.
@@ -253,7 +253,7 @@
% Convert the corresponding elements of a list of keys and a
% list of values (which must be of the same length) to a multi_map.
% A key may occur more than once in the list of keys.
- % Abort if the two lists are not the same length.
+ % Throw an exception if the two lists are not the same length.
%
:- func from_corresponding_lists(list(K), list(V))
= multi_map(K, V).
@@ -263,8 +263,8 @@
% Convert the corresponding elements of a list of keys and a
% *list of lists* of values to a multi_map.
% A key may *not* occur more than once in the list of keys.
- % Abort if the two lists are not the same length, or if a key
- % does occur more than once in the list of keys.
+ % Throw an exception if the two lists are not the same length,
+ % or if a key does occur more than once in the list of keys.
%
:- func from_corresponding_list_lists(list(K), list(list(V)))
= multi_map(K, V).
diff --git a/library/psqueue.m b/library/psqueue.m
index c801b167f..dd2db0c96 100644
--- a/library/psqueue.m
+++ b/library/psqueue.m
@@ -72,7 +72,7 @@
:- pragma type_spec(insert/4, P = int).
% Insert key K with priority P into the given priority search queue.
- % Abort if the key already exists.
+ % Throw an exception if the key already exists.
%
:- func det_insert(psqueue(P, K), P, K) = psqueue(P, K).
:- pred det_insert(P::in, K::in, psqueue(P, K)::in, psqueue(P, K)::out) is det.
diff --git a/library/rbtree.m b/library/rbtree.m
index eb2b55416..e6ab37d8c 100644
--- a/library/rbtree.m
+++ b/library/rbtree.m
@@ -33,7 +33,7 @@
% fails if node to remove doesn't exist in the tree.
%
% lookup:
-% Aborts program if key looked up doesn't exist.
+% Throws an exception if key looked up doesn't exist.
% search:
% Fails if key looked up doesn't exist.
%
diff --git a/library/string.m b/library/string.m
index 67ffa342b..939a3cdf4 100644
--- a/library/string.m
+++ b/library/string.m
@@ -764,7 +764,8 @@
:- pred remove_suffix(string::in, string::in, string::out) is semidet.
% det_remove_suffix(String, Suffix) returns the same value as
- % remove_suffix, except it aborts if String does not end with Suffix.
+ % remove_suffix, except it throws an exception if String does not end
+ % with Suffix.
%
:- func det_remove_suffix(string, string) = string.
diff --git a/library/term.m b/library/term.m
index 2710d560e..26cc2f8e5 100644
--- a/library/term.m
+++ b/library/term.m
@@ -680,7 +680,7 @@
%
% Convert a list of terms which are all vars into a list of vars.
- % Abort (call error/1) if the list contains any non-variables.
+ % Throw an exception if the list contains any non-variables.
%
:- func term_list_to_var_list(list(term(T))) = list(var(T)).
diff --git a/library/tree234.m b/library/tree234.m
index 22d248ad9..0d30e4468 100644
--- a/library/tree234.m
+++ b/library/tree234.m
@@ -64,7 +64,7 @@
% Search for a key-value pair using the key. If there is no entry
% for the given key, returns the pair for the next lower key instead.
- % Aborts if there is no key with the given or lower value.
+ % Throws an exception if there is no key with the given or lower value.
%
:- pred lower_bound_lookup(tree234(K, V)::in, K::in, K::out, V::out)
is det.
@@ -78,7 +78,7 @@
% Search for a key-value pair using the key. If there is no entry
% for the given key, returns the pair for the next higher key instead.
- % Aborts if there is no key with the given or higher value.
+ % Throws an exception if there is no key with the given or higher value.
%
:- pred upper_bound_lookup(tree234(K, V)::in, K::in, K::out, V::out)
is det.
diff --git a/library/type_desc.m b/library/type_desc.m
index 57494c223..d20a33207 100644
--- a/library/type_desc.m
+++ b/library/type_desc.m
@@ -67,7 +67,7 @@
type_desc::out) is semidet.
% Convert a pseudo_type_desc describing a ground type to a type_desc.
- % If the pseudo_type_desc describes a non-ground type, abort.
+ % Throw an exception if the pseudo_type_desc describes a non-ground type.
%
:- func det_ground_pseudo_type_desc_to_type_desc(pseudo_type_desc) = type_desc.
@@ -202,8 +202,8 @@
% det_make_type(TypeCtor, TypeArgs):
%
% Returns the type formed by applying the specified type constructor
- % to the specified argument types. Aborts if the length of `TypeArgs'
- % is not the same as the arity of `TypeCtor'.
+ % to the specified argument types. Throws an exception if the length of
+ % `TypeArgs' is not the same as the arity of `TypeCtor'.
%
:- func det_make_type(type_ctor_desc, list(type_desc)) = type_desc.
diff --git a/library/univ.m b/library/univ.m
index 997e96ca7..7ac48a4ca 100644
--- a/library/univ.m
+++ b/library/univ.m
@@ -59,7 +59,7 @@
% det_univ_to_type(Univ, Object).
%
- % The same as the forwards mode of univ_to_type, but aborts
+ % The same as the forwards mode of univ_to_type, but throws an exception
% if univ_to_type fails.
%
:- pred det_univ_to_type(univ::in, T::out) is det.
diff --git a/library/varset.m b/library/varset.m
index 6abf2d975..a243e75d3 100644
--- a/library/varset.m
+++ b/library/varset.m
@@ -96,8 +96,8 @@
is det.
% Delete the names and values for a sorted list of variables.
- % (If the list is not sorted, the result will be either an abort
- % or incorrect output.)
+ % (If the list is not sorted, the predicate or function will
+ % either throw an exception of return incorrect output.)
%
:- func delete_sorted_vars(varset(T), list(var(T))) = varset(T).
:- pred delete_sorted_vars(list(var(T))::in,
--
2.14.1
More information about the reviews
mailing list