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/digraph.xml | 536 +++++++++++++++++++++++------------------ 1 file changed, 297 insertions(+), 239 deletions(-) (limited to 'lib/stdlib/doc/src/digraph.xml') diff --git a/lib/stdlib/doc/src/digraph.xml b/lib/stdlib/doc/src/digraph.xml index 1bb8eef247..5332d7aba5 100644 --- a/lib/stdlib/doc/src/digraph.xml +++ b/lib/stdlib/doc/src/digraph.xml @@ -30,64 +30,92 @@ 2001-08-27 C - digraph.sgml + digraph.xml digraph - Directed Graphs + Directed graphs. -

The digraph module implements a version of labeled - directed graphs. What makes the graphs implemented here +

This module provides a version of labeled + directed graphs. What makes the graphs provided here non-proper directed graphs is that multiple edges between vertices are allowed. However, the customary definition of - directed graphs will be used in the text that follows. -

-

A directed graph (or just - "digraph") is a pair (V, E) of a finite set V of - vertices and a finite set E of - directed edges (or just "edges"). - The set of - edges E is a subset of V × V (the Cartesian - product of V with itself). In this module, V is allowed to be - empty; the so obtained unique digraph is called the - empty digraph. - Both vertices and edges are represented by unique Erlang terms. -

-

Digraphs can be annotated with additional information. Such - information may be attached to the vertices and to the edges of - the digraph. A digraph which has been annotated is called a - labeled digraph, and the information attached to a - vertex or an edge is called a - label. Labels are Erlang terms. -

-

An edge e = (v, w) is said to - emanate from vertex v and - to be incident on vertex w. - The out-degree of a vertex - is the number of edges emanating from that vertex. - The in-degree of a vertex - is the number of edges incident on that vertex. - If there is an edge emanating from v and incident on w, then w is - said to be an - out-neighbour of v, and v is said to be an - in-neighbour of w. - A path P from v[1] to v[k] - in a digraph (V, E) is a non-empty sequence - v[1], v[2], ..., v[k] of vertices in V such that - there is an edge (v[i],v[i+1]) in E for - 1 <= i < k. - The length of the path P is k-1. - P is simple if all - vertices are distinct, except that the first and the last vertices - may be the same. - P is a cycle if the length - of P is not zero and v[1] = v[k]. - A loop is a cycle of length one. - A simple cycle is a path - that is both a cycle and simple. - An acyclic digraph - is a digraph that has no cycles. -

+ directed graphs is used here.

+ + + +

A directed graph (or just + "digraph") is a pair (V, E) of a finite set V of + vertices and a finite set E of + directed edges (or just "edges"). + The set of edges E is a subset of V × V (the + Cartesian product of V with itself).

+

In this module, V is allowed to be empty. The so obtained unique + digraph is called the + empty digraph. Both + vertices and edges are represented by unique Erlang terms.

+ + +

Digraphs can be annotated with more information. Such information + can be attached to the vertices and to the edges of the digraph. An + annotated digraph is called a labeled digraph, and the + information attached to a vertex or an edge is called a + label. Labels are Erlang + terms.

+ + +

An edge e = (v, w) is said to + emanate from vertex v and to + be incident on vertex w.

+ + +

The out-degree of a vertex + is the number of edges emanating from that vertex.

+ + +

The in-degree of a vertex + is the number of edges incident on that vertex.

+ + +

If an edge is emanating from v and incident on w, then w is + said to be an + out-neighbor of v, and v is said to be an + in-neighbor of w.

+ + +

A path P from v[1] to v[k] + in a digraph (V, E) is a non-empty sequence + v[1], v[2], ..., v[k] of vertices in V such that + there is an edge (v[i],v[i+1]) in E for + 1 <= i < k.

+ + +

The length of path P is + k-1.

+ + +

Path P is simple if all + vertices are distinct, except that the first and the last vertices + can be the same.

+ + +

Path P is a cycle if the + length of P is not zero and v[1] = v[k].

+ + +

A loop is a cycle of length + one.

+ + +

A simple cycle is a path + that is both a cycle and simple.

+ + +

An acyclic digraph + is a digraph without cycles.

+ + + @@ -100,7 +128,8 @@ -

A digraph as returned by new/0,1.

 +

A digraph as returned by + new/0,1.

 edge() @@ -112,6 +141,7 @@ vertex() + @@ -120,291 +150,313 @@ Add an edge to a digraph. -

add_edge/5 creates (or modifies) the edge E - of the digraph G, using Label as the (new) - label of the edge. The +

add_edge/5 creates (or modifies) edge E + of digraph G, using Label as + the (new) label of the edge. The edge is emanating from - V1 and incident - on V2. Returns E. -

-

add_edge(G, V1, V2, Label) is - equivalent to + V1 and + incident + on V2. Returns E.

+

add_edge(G, V1, V2, Label) + is equivalent to add_edge(G, E, V1, V2, Label), where E is a created edge. The created edge is - represented by the term ['$e' | N], where N - is an integer >= 0. -

-

add_edge(G, V1, V2) is equivalent to + represented by term ['$e' | N], where N + is an integer >= 0.

+

add_edge(G, V1, V2) + is equivalent to add_edge(G, V1, V2, []). -

-

If the edge would create a cycle in - an acyclic digraph, - then {error, {bad_edge, Path}} is returned. If - either of V1 or V2 is not a vertex of the - digraph G, then +

+

If the edge would create a cycle in + an acyclic digraph, + {error, {bad_edge, Path}} is returned. + If either of V1 or V2 is not + a vertex of digraph G, {error, {bad_vertex, V}} is returned, V = V1 or - V = V2. -

+ V = V2.

 + Add or modify a vertex of a digraph. -

add_vertex/3 creates (or modifies) the vertex V - of the digraph G, using Label as the (new) +

add_vertex/3 creates (or modifies) vertex + V of digraph G, using + Label as the (new) label of the - vertex. Returns V. -

-

add_vertex(G, V) is equivalent to - add_vertex(G, V, []). -

+ vertex. Returns V.

+

add_vertex(G, V) is equivalent + to add_vertex(G, V, []). +

add_vertex/1 creates a vertex using the empty list as label, and returns the created vertex. The created vertex - is represented by the term ['$v' | N], - where N is an integer >= 0. -

+ is represented by term ['$v' | N], + where N is an integer >= 0.

 + Delete an edge from a digraph. -

Deletes the edge E from the digraph G. -

+

Deletes edge E from digraph + G.

 + Delete edges from a digraph. -

Deletes the edges in the list Edges from the digraph - G. -

+

Deletes the edges in list Edges from digraph + G.

 + Delete paths from a digraph. -

Deletes edges from the digraph G until there are no - paths from the vertex - V1 to the vertex V2. -

-

A sketch of the procedure employed: Find an arbitrary - simple path - v[1], v[2], ..., v[k] from V1 to - V2 in G. Remove all edges of - G emanating from v[i] - and incident to v[i+1] for - 1 <= i < k (including multiple - edges). Repeat until there is no path between V1 and - V2. -

+

Deletes edges from digraph G until there are no + paths from vertex + V1 to vertex V2.

+

A sketch of the procedure employed:

+ + +

Find an arbitrary + simple path + v[1], v[2], ..., v[k] from V1 + to V2 in G.

+ + +

Remove all edges of G + emanating from v[i] and + incident to v[i+1] for + 1 <= i < k (including multiple + edges).

+ + +

Repeat until there is no path between V1 + and V2.

+ + + Delete a vertex from a digraph. -

Deletes the vertex V from the digraph G. Any - edges emanating from - V or incident - on V are also deleted. -

+

Deletes vertex V from digraph + G. Any edges + emanating from + V or + incident + on V are also deleted.

 + Delete vertices from a digraph. -

Deletes the vertices in the list Vertices from the - digraph G. -

+

Deletes the vertices in list Vertices from + digraph G.

 + Delete a digraph. -

Deletes the digraph G. This call is important - because digraphs are implemented with ETS. There is - no garbage collection of ETS tables. The digraph - will, however, be deleted if the process that created the - digraph terminates. -

+

Deletes digraph G. This call is important + as digraphs are implemented with ETS. There is + no garbage collection of ETS tables. However, the digraph + is deleted if the process that created the digraph terminates.

 + - Return the vertices and the label of an edge of a digraph. + Return the vertices and the label of an edge of a digraph. + -

Returns {E, V1, V2, Label} where - Label is the label - of the edge - E emanating from - V1 and incident on - V2 of the digraph G. - If there is no edge E of the - digraph G, then false is returned. -

+

Returns + {E, V1, V2, Label}, + where Label is the + label of edge + E emanating + from V1 and + incident on + V2 of digraph G. + If no edge E of + digraph G exists, false is returned.

 + Return all edges of a digraph. -

Returns a list of all edges of the digraph G, in - some unspecified order. -

+

Returns a list of all edges of digraph G, in + some unspecified order.

 + - Return the edges emanating from or incident on a vertex of a digraph. + Return the edges emanating from or incident on a vertex of + a digraph. -

Returns a list of all - edges emanating from - or incident on V - of the digraph G, in some unspecified order.

+

Returns a list of all + edges emanating from or + incident onV + of digraph G, in some unspecified order.

 + Find one cycle in a digraph. -

If there is - a simple cycle of - length two or more through the vertex - V, then the cycle is returned as a list - [V, ..., V] of vertices, otherwise if there - is a loop through - V, then the loop is returned as a list [V]. If - there are no cycles through V, then false is - returned. -

-

get_path/3 is used for finding a simple cycle - through V. -

+

If a simple cycle of + length two or more exists through vertex V, the + cycle is returned as a list + [V, ..., V] of vertices. + If a loop through + V exists, the loop is returned as a list + [V]. If no cycles through + V exist, false is returned.

+

get_path/3 is used + for finding a simple cycle through V.

 + Find one path in a digraph. -

Tries to find - a simple path from - the vertex V1 to the vertex - V2 of the digraph G. Returns the path as a - list [V1, ..., V2] of vertices, or - false if no simple path from V1 to V2 - of length one or more exists. -

-

The digraph G is traversed in a depth-first manner, - and the first path found is returned. -

+

Tries to find + a simple path from vertex + V1 to vertex V2 of digraph + G. Returns the path as a list + [V1, ..., V2] of vertices, + or false if no simple path from V1 to + V2 of length one or more exists.

+

Digraph G is traversed in a depth-first manner, + and the first found path is returned.

 + Find one short cycle in a digraph. -

Tries to find an as short as - possible simple cycle through - the vertex V of the digraph G. Returns the cycle - as a list [V, ..., V] of vertices, or +

Tries to find an as short as possible + simple cycle through + vertex V of digraph G. Returns the cycle + as a list [V, ..., V] + of vertices, or false if no simple cycle through V exists. - Note that a loop through - V is returned as the list [V, V]. -

-

get_short_path/3 is used for finding a simple cycle - through V. -

+ Notice that a loop through + V is returned as list + [V, V].

+

get_short_path/3 + is used for finding a simple cycle through V.

 + Find one short path in a digraph. -

Tries to find an as short as - possible simple path from - the vertex V1 to the vertex V2 of the digraph G. - Returns the path as a list [V1, ..., V2] of - vertices, or false if no simple path from V1 - to V2 of length one or more exists. -

-

The digraph G is traversed in a breadth-first - manner, and the first path found is returned. -

+

Tries to find an as short as possible + simple path from vertex + V1 to vertex V2 of digraph + G. Returns the path as a list + [V1, ..., V2] of + vertices, or false if no simple path from + V1 + to V2 of length one or more exists.

+

Digraph G is traversed in a breadth-first + manner, and the first found path is returned.

 + Return the in-degree of a vertex of a digraph. -

Returns the in-degree of the vertex - V of the digraph G. -

+

Returns the in-degree of + vertex V of digraph G.

 + - Return all edges incident on a vertex of a digraph. + Return all edges incident on a vertex of a digraph. -

Returns a list of all - edges incident on - V of the digraph G, in some unspecified order. -

+

Returns a list of all + edges incident on + V of digraph G, + in some unspecified order.

 + - Return all in-neighbours of a vertex of a digraph. + Return all in-neighbors of a vertex of a digraph. -

Returns a list of - all in-neighbours of - V of the digraph G, in some unspecified order. -

+

Returns a list of + all in-neighbors of + V of digraph G, + in some unspecified order.

 + Return information about a digraph. -

Returns a list of {Tag, Value} pairs describing the - digraph G. The following pairs are returned: -

+

Returns a list of {Tag, Value} pairs describing + digraph G. The following pairs are returned:

-

{cyclicity, Cyclicity}, where Cyclicity +

{cyclicity, Cyclicity}, where + Cyclicity is cyclic or acyclic, according to the options given to new.

 -

{memory, NoWords}, where NoWords is - the number of words allocated to the ETS tables.

+

{memory, NoWords}, where + NoWords is + the number of words allocated to the ETS tables.

 -

{protection, Protection}, where Protection +

{protection, Protection}, where + Protection is protected or private, according to the options given to new.

 + - Return a protected empty digraph, where cycles are allowed. + Return a protected empty digraph, where cycles are allowed. + -

Equivalent to new([]). -

+

Equivalent to new([]).

 + Create a new empty digraph. @@ -413,97 +465,103 @@ -

Returns - an empty digraph with - properties according to the options in Type:

+

Returns + an empty digraph with + properties according to the options in Type:

cyclic - Allow cycles in the - digraph (default). +

Allows cycles in the + digraph (default).

 acyclic - The digraph is to be kept acyclic. +

The digraph is to be kept + acyclic.

 protected - Other processes can read the digraph (default). +

Other processes can read the digraph (default).

 private - The digraph can be read and modified by the creating - process only. +

The digraph can be read and modified by the creating + process only.

 -

If an unrecognized type option T is given or Type - is not a proper list, there will be a badarg exception. -

+

If an unrecognized type option T is specified or + Type + is not a proper list, a badarg exception is raised.

 + - Return the number of edges of the a digraph. + Return the number of edges of a digraph. -

Returns the number of edges of the digraph G. -

+

Returns the number of edges of digraph G.

 + Return the number of vertices of a digraph. -

Returns the number of vertices of the digraph G. -

+

Returns the number of vertices of digraph G.

 + Return the out-degree of a vertex of a digraph. -

Returns the out-degree of the vertex - V of the digraph G. -

+

Returns the out-degree of + vertex V of digraph G.

 + - Return all edges emanating from a vertex of a digraph. + Return all edges emanating from a vertex of a digraph. + -

Returns a list of all - edges emanating from - V of the digraph G, in some unspecified order. -

+

Returns a list of all + edges emanating from + V of digraph G, + in some unspecified order.

 + - Return all out-neighbours of a vertex of a digraph. + Return all out-neighbors of a vertex of a digraph.

Returns a list of - all out-neighbours of - V of the digraph G, in some unspecified order. -

+ all out-neighbors of + V of digraph G, + in some unspecified order.

 + Return the label of a vertex of a digraph. -

Returns {V, Label} where Label is the +

Returns {V, Label}, + where Label is the label of the vertex - V of the digraph G, or false if there - is no vertex V of the digraph G. -

+ V of digraph G, + or false if no vertex V + of digraph G exists.

 + Return all vertices of a digraph. -

Returns a list of all vertices of the digraph G, in - some unspecified order. -

+

Returns a list of all vertices of digraph G, in + some unspecified order.
See Also -

digraph_utils(3), - ets(3)

+

digraph_utils(3), + ets(3)

-- cgit v1.2.3