From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/digraph.xml | 395 ++++++++++++++++------------------------- 1 file changed, 151 insertions(+), 244 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 ad256e671f..0afc70ebe0 100644 --- a/lib/stdlib/doc/src/digraph.xml +++ b/lib/stdlib/doc/src/digraph.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -87,67 +87,79 @@ is a digraph that has no cycles.

+ + + + + + + + + + + + digraph() +

A digraph as returned by new/0,1.

 + + + edge() + + + + + + vertex() + + - add_edge(G, E, V1, V2, Label) -> edge() | {error, Reason} - add_edge(G, V1, V2, Label) -> edge() | {error, Reason} - add_edge(G, V1, V2) -> edge() | {error, Reason} + + + Add an edge to a digraph. - - G = digraph() - E = edge() - V1 = V2 = vertex() - Label = label() - Reason = {bad_edge, Path} | {bad_vertex, V} - Path = [vertex()] - + -

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

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

-

add_edge(G, V1, V2, Label) is +

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 + 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 - add_edge(G, V1, V2, []). +

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 - {error, {bad_vertex, V}} is - returned, V = V1 or - V = V2. + then {error, {bad_edge, Path}} is returned. If + either of V1 or V2 is not a vertex of the + digraph G, then + {error, {bad_vertex, V}} is + returned, V = V1 or + V = V2.

- add_vertex(G, V, Label) -> vertex() - add_vertex(G, V) -> vertex() - add_vertex(G) -> vertex() + + + Add or modify a vertex of a digraph. - - G = digraph() - V = vertex() - Label = label() - -

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

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

-

add_vertex(G, V) is equivalent to - add_vertex(G, 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 @@ -157,304 +169,227 @@ - del_edge(G, E) -> true + Delete an edge from a digraph. - - G = digraph() - E = edge() - -

Deletes the edge E from the digraph G. +

Deletes the edge E from the digraph G.

- del_edges(G, Edges) -> true + Delete edges from a digraph. - - G = digraph() - Edges = [edge()] - -

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

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

- del_path(G, V1, V2) -> true + Delete paths from a digraph. - - G = digraph() - V1 = V2 = vertex() - -

Deletes edges from the digraph G until there are no +

Deletes edges from the digraph G until there are no paths from the vertex - V1 to the vertex V2. + 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] + 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. + edges). Repeat until there is no path between V1 and + V2.

- del_vertex(G, V) -> true + Delete a vertex from a digraph. - - G = digraph() - V = vertex() - -

Deletes the vertex V from the digraph G. Any +

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

- del_vertices(G, Vertices) -> true + Delete vertices from a digraph. - - G = digraph() - Vertices = [vertex()] - -

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

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

- delete(G) -> true + Delete a digraph. - - G = 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 +

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.

- edge(G, E) -> {E, V1, V2, Label} | false + Return the vertices and the label of an edge of a digraph. - - G = digraph() - E = edge() - V1 = V2 = vertex() - Label = label() - -

Returns {E, V1, V2, Label} where - Label is the label +

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. + 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.

- edges(G) -> Edges + Return all edges of a digraph. - - G = digraph() - Edges = [edge()] - -

Returns a list of all edges of the digraph G, in +

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

- edges(G, V) -> Edges + Return the edges emanating from or incident on a vertex of a digraph. - - G = digraph() - V = vertex() - Edges = [edge()] -

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

+ or incident on V + of the digraph G, in some unspecified order.

 - get_cycle(G, V) -> Vertices | false + Find one cycle in a digraph. - - G = digraph() - V1 = V2 = vertex() - Vertices = [vertex()] -

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 + 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 + 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. + through V.

- get_path(G, V1, V2) -> Vertices | false + Find one path in a digraph. - - G = digraph() - V1 = V2 = vertex() - Vertices = [vertex()] -

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 + 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, +

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

- get_short_cycle(G, V) -> Vertices | false + Find one short cycle in a digraph. - - G = digraph() - V1 = V2 = vertex() - Vertices = [vertex()] -

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 - false if no simple cycle through V exists. + the vertex V of the 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]. + V is returned as the list [V, V].

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

- get_short_path(G, V1, V2) -> Vertices | false + Find one short path in a digraph. - - G = digraph() - V1 = V2 = vertex() - Vertices = [vertex()] -

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 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 +

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

- in_degree(G, V) -> integer() + Return the in-degree of a vertex of a digraph. - - G= digraph() - V = vertex() -

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

- in_edges(G, V) -> Edges + Return all edges incident on a vertex of a digraph. - - G = digraph() - V = vertex() - Edges = [edge()] -

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

- in_neighbours(G, V) -> Vertices + Return all in-neighbours of a vertex of a digraph. - - G = digraph() - V = vertex() - Vertices = [vertex()] -

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

- info(G) -> InfoList + Return information about a digraph. - - G = digraph() - InfoList = [{cyclicity, Cyclicity}, {memory, NoWords}, {protection, Protection}] - Cyclicity = cyclic | acyclic - Protection = protected | private - NoWords = integer() >= 0 - + +

Returns a list of {Tag, Value} pairs describing the - digraph G. The following pairs are returned: + 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.

 @@ -462,7 +397,7 @@ - new() -> digraph() + Return a protected empty digraph, where cycles are allowed.

Equivalent to new([]). @@ -470,15 +405,16 @@ - new(Type) -> digraph() + Create a new empty digraph. - - Type = [cyclic | acyclic | private | protected] - + + + +

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

+ properties according to the options in Type:

cyclic Allow cycles in the @@ -491,101 +427,72 @@ The digraph can be read and modified by the creating process only. -

If an unrecognized type option T is given or Type +

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

- no_edges(G) -> integer() >= 0 + Return the number of edges of the a digraph. - - G = digraph() - -

Returns the number of edges of the digraph G. +

Returns the number of edges of the digraph G.

- no_vertices(G) -> integer() >= 0 + Return the number of vertices of a digraph. - - G = digraph() - -

Returns the number of vertices of the digraph G. +

Returns the number of vertices of the digraph G.

- out_degree(G, V) -> integer() + Return the out-degree of a vertex of a digraph. - - G = digraph() - V = vertex() -

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

- out_edges(G, V) -> Edges + Return all edges emanating from a vertex of a digraph. - - G = digraph() - V = vertex() - Edges = [edge()] -

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

- out_neighbours(G, V) -> Vertices + Return all out-neighbours of a vertex of a digraph. - - G = digraph() - V = vertex() - Vertices = [vertex()] -

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

- vertex(G, V) -> {V, Label} | false + Return the label of a vertex of a digraph. - - G = digraph() - V = vertex() - Label = label() - -

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 the digraph G, or false if there + is no vertex V of the digraph G.

- vertices(G) -> Vertices + Return all vertices of a digraph. - - G = digraph() - Vertices = [vertex()] - -

Returns a list of all vertices of the digraph G, in +

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

-- cgit v1.2.3