From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/gb_sets.xml | 325 +++++++++++++++++++++++++---------------- 1 file changed, 196 insertions(+), 129 deletions(-) (limited to 'lib/stdlib/doc/src/gb_sets.xml') diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index 84609a0f7c..d677dd6f83 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -29,87 +29,75 @@ gb_sets - General Balanced Trees + General balanced trees. -

An implementation of ordered sets using Prof. Arne Andersson's - General Balanced Trees. This can be much more efficient than +

This module provides ordered sets using Prof. Arne Andersson's + General Balanced Trees. Ordered sets can be much more efficient than using ordered lists, for larger sets, but depends on the application.

+

This module considers two elements as different if and only if they do not compare equal (==).
- Complexity note -

The complexity on set operations is bounded by either O(|S|) or - O(|T| * log(|S|)), where S is the largest given set, depending + Complexity Note +

The complexity on set operations is bounded by either O(|S|) or + O(|T| * log(|S|)), where S is the largest given set, depending on which is fastest for any particular function call. For operating on sets of almost equal size, this implementation is about 3 times slower than using ordered-list sets directly. For sets of very different sizes, however, this solution can be - arbitrarily much faster; in practical cases, often between 10 - and 100 times. This implementation is particularly suited for + arbitrarily much faster; in practical cases, often + 10-100 times. This implementation is particularly suited for accumulating elements a few at a time, building up a large set - (more than 100-200 elements), and repeatedly testing for + (> 100-200 elements), and repeatedly testing for membership in the current set.

+

As with normal tree structures, lookup (membership testing), - insertion and deletion have logarithmic complexity.

+ insertion, and deletion have logarithmic complexity.

Compatibility -

All of the following functions in this module also exist - and do the same thing in the sets and ordsets +

The following functions in this module also exist and provides + the same functionality in the + sets(3) and + ordsets(3) modules. That is, by only changing the module name for each call, you can try out different set representations.

- -

add_element/2

+ add_element/2 - -

del_element/2

+ del_element/2 - -

filter/2

+ filter/2 - -

fold/3

+ fold/3 - -

from_list/1

+ from_list/1 - -

intersection/1

+ intersection/1 - -

intersection/2

+ intersection/2 - -

is_element/2

+ is_element/2 - -

is_set/1

+ is_set/1 - -

is_subset/2

+ is_subset/2 - -

new/0

+ new/0 - -

size/1

+ size/1 - -

subtract/2

+ subtract/2 - -

to_list/1

+ to_list/1 - -

union/1

+ union/1 - -

union/2

+ union/2
@@ -117,290 +105,369 @@ -

A GB set.

 +

A general balanced set.

 -

A GB set iterator.

 +

A general balanced set iterator.

 + - Add a (possibly existing) element to a set + Add a (possibly existing) element to a set.

Returns a new set formed from Set1 with - Element inserted. If Element is already an + Element inserted. If Element + is already an element in Set1, nothing is changed.

 + - Rebalance tree representation of a set + Rebalance tree representation of a set. -

Rebalances the tree representation of Set1. Note that - this is rarely necessary, but may be motivated when a large +

Rebalances the tree representation of Set1. + Notice that + this is rarely necessary, but can be motivated when a large number of elements have been deleted from the tree without - further insertions. Rebalancing could then be forced in order - to minimise lookup times, since deletion only does not + further insertions. Rebalancing can then be forced + to minimise lookup times, as deletion does not rebalance the tree.

 + + + + Remove a (possibly non-existing) element from a set. + +

Returns a new set formed from Set1 with + Element removed. If Element + is not an element + in Set1, nothing is changed.

+ + + - Remove an element from a set + Remove an element from a set.

Returns a new set formed from Set1 with - Element removed. Assumes that Element is present + Element removed. Assumes that + Element is present in Set1.

 + - - Remove a (possibly non-existing) element from a set + Remove a (possibly non-existing) element from a set.

Returns a new set formed from Set1 with - Element removed. If Element is not an element + Element removed. If Element + is not an element in Set1, nothing is changed.

 + - - Return the difference of two sets + Return the difference of two sets. -

Returns only the elements of Set1 which are not also - elements of Set2.

+

Returns only the elements of Set1 that are not + also elements of Set2.

 + - - Return an empty set + Return an empty set.

Returns a new empty set.

 + - Filter set elements + Filter set elements.

Filters elements in Set1 using predicate function Pred.

 + - Fold over set elements + Fold over set elements. -

Folds Function over every element in Set +

Folds Function over every element in + Set returning the final value of the accumulator.

 + - Convert a list into a set + Convert a list into a set.

Returns a set of the elements in List, where - List may be unordered and contain duplicates.

+ List can be unordered and contain duplicates.

 + - Make a set from an ordset list + Make a set from an ordset list. -

Turns an ordered-set list List into a set. The list - must not contain duplicates.

+

Turns an ordered-set list List into a set. + The list must not contain duplicates.

 + - Add a new element to a set + Add a new element to a set.

Returns a new set formed from Set1 with - Element inserted. Assumes that Element is not + Element inserted. Assumes that + Element is not present in Set1.

 + - - Return the intersection of two sets + + Return the intersection of a list of sets. -

Returns the intersection of Set1 and Set2.

+

Returns the intersection of the non-empty list of sets.

 + - - Return the intersection of a list of sets + + Return the intersection of two sets. -

Returns the intersection of the non-empty list of sets.

+

Returns the intersection of Set1 and + Set2.

 + - Check whether two sets are disjoint + Check whether two sets are disjoint.

Returns true if Set1 and Set2 are disjoint (have no elements in common), - and false otherwise.

+ otherwise false.

+ + + + + + Test for membership of a set. + +

Returns true if Element is an element of + Set, otherwise false.

 + - Test for empty set + Test for empty set. -

Returns true if Set is an empty set, and - false otherwise.

+

Returns true if Set is an empty set, + otherwise false.

 + - - Test for membership of a set + Test for membership of a set.

Returns true if Element is an element of Set, otherwise false.

 + - Test for a set + Test for a set.

Returns true if Term appears to be a set, otherwise false.

 + - Test for subset + Test for subset.

Returns true when every element of Set1 is also a member of Set2, otherwise false.

 + - Return an iterator for a set + Return an iterator for a set. -

Returns an iterator that can be used for traversing the - entries of Set; see next/1. The implementation +

Returns an iterator that can be used for traversing the entries of + Set; see + next/1. The implementation of this is very efficient; traversing the whole set using - next/1 is only slightly slower than getting the list - of all elements using to_list/1 and traversing that. + next/1 is only slightly slower than getting the list of all + elements using to_list/1 + and traversing that. The main advantage of the iterator approach is that it does not require the complete list of all elements to be built in memory at one time.

 + - Return an iterator for a set starting from a specified element + Return an iterator for a set starting from a specified element. +

Returns an iterator that can be used for traversing the - entries of Set; see next/1. + entries of Set; see + next/1. The difference as compared to the iterator returned by - iterator/1 is that the first element greater than + iterator/1 + is that the first element greater than or equal to Element is returned.

 + - Return largest element + Return largest element.

Returns the largest element in Set. Assumes that - Set is nonempty.

+ Set is not empty.

 + + + + Return an empty set. + +

Returns a new empty set.

+ + + - Traverse a set with an iterator + Traverse a set with an iterator. -

Returns {Element, Iter2} where Element is the - smallest element referred to by the iterator Iter1, +

Returns {Element, Iter2}, where + Element is the smallest element referred to by + iterator Iter1, and Iter2 is the new iterator to be used for traversing the remaining elements, or the atom none if no elements remain.

 + - Return a set with one element + Return a set with one element. -

Returns a set containing only the element Element.

+

Returns a set containing only element Element. +

+ - Return the number of elements in a set + Return the number of elements in a set.

Returns the number of elements in Set.

 + - Return smallest element + Return smallest element.

Returns the smallest element in Set. Assumes that - Set is nonempty.

+ Set is not empty.

 + + + + Return the difference of two sets. + +

Returns only the elements of Set1 that are not + also elements of Set2.

+ + + - Extract largest element + Extract largest element. -

Returns {Element, Set2}, where Element is the - largest element in Set1, and Set2 is this set - with Element deleted. Assumes that Set1 is - nonempty.

+

Returns {Element, Set2}, where + Element is the largest element in + Set1, and Set2 is this set + with Element deleted. Assumes that + Set1 is not empty.

 + - Extract smallest element + Extract smallest element. -

Returns {Element, Set2}, where Element is the - smallest element in Set1, and Set2 is this set - with Element deleted. Assumes that Set1 is - nonempty.

+

Returns {Element, Set2}, where + Element is the smallest element in + Set1, and Set2 is this set + with Element deleted. Assumes that + Set1 is not empty.

 + - Convert a set into a list + Convert a set into a list.

Returns the elements of Set as a list.

 + - - Return the union of two sets + + Return the union of a list of sets. -

Returns the merged (union) set of Set1 and - Set2.

+

Returns the merged (union) set of the list of sets.

 + - - Return the union of a list of sets + + Return the union of two sets. -

Returns the merged (union) set of the list of sets.

+

Returns the merged (union) set of Set1 and + Set2.
- SEE ALSO -

gb_trees(3), - ordsets(3), - sets(3)

+ See Also +

gb_trees(3), + ordsets(3), + sets(3)

-- cgit v1.2.3