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/compiler/doc/src/compile.xml | 2 +- lib/stdlib/doc/specs/.gitignore | 1 + lib/stdlib/doc/src/Makefile | 15 +- lib/stdlib/doc/src/array.xml | 177 ++--- lib/stdlib/doc/src/base64.xml | 35 +- lib/stdlib/doc/src/beam_lib.xml | 271 +++----- lib/stdlib/doc/src/binary.xml | 150 ++--- lib/stdlib/doc/src/c.xml | 127 ++-- lib/stdlib/doc/src/calendar.xml | 226 +++---- lib/stdlib/doc/src/dets.xml | 705 +++++++++----------- lib/stdlib/doc/src/dict.xml | 212 ++---- lib/stdlib/doc/src/digraph.xml | 395 +++++------ lib/stdlib/doc/src/digraph_utils.xml | 170 ++--- lib/stdlib/doc/src/epp.xml | 62 +- lib/stdlib/doc/src/erl_eval.xml | 153 +++-- lib/stdlib/doc/src/erl_expand_records.xml | 6 +- lib/stdlib/doc/src/erl_id_trans.xml | 6 +- lib/stdlib/doc/src/erl_internal.xml | 73 +-- lib/stdlib/doc/src/erl_lint.xml | 50 +- lib/stdlib/doc/src/erl_parse.xml | 122 ++-- lib/stdlib/doc/src/erl_pp.xml | 123 ++-- lib/stdlib/doc/src/erl_scan.xml | 362 +++++----- lib/stdlib/doc/src/ets.xml | 255 +++---- lib/stdlib/doc/src/file_sorter.xml | 266 ++++---- lib/stdlib/doc/src/filelib.xml | 89 +-- lib/stdlib/doc/src/filename.xml | 156 ++--- lib/stdlib/doc/src/gb_sets.xml | 288 +++----- lib/stdlib/doc/src/gb_trees.xml | 216 ++---- lib/stdlib/doc/src/gen_event.xml | 16 +- lib/stdlib/doc/src/io.xml | 354 ++++------ lib/stdlib/doc/src/io_lib.xml | 179 ++--- lib/stdlib/doc/src/lib.xml | 37 +- lib/stdlib/doc/src/lists.xml | 764 +++++++-------------- lib/stdlib/doc/src/log_mf_h.xml | 31 +- lib/stdlib/doc/src/math.xml | 2 +- lib/stdlib/doc/src/ms_transform.xml | 25 +- lib/stdlib/doc/src/orddict.xml | 213 ++---- lib/stdlib/doc/src/ordsets.xml | 153 ++--- lib/stdlib/doc/src/pg.xml | 55 +- lib/stdlib/doc/src/pool.xml | 46 +- lib/stdlib/doc/src/proc_lib.xml | 163 ++--- lib/stdlib/doc/src/proplists.xml | 210 ++---- lib/stdlib/doc/src/qlc.xml | 646 ++++++++---------- lib/stdlib/doc/src/queue.xml | 286 +++----- lib/stdlib/doc/src/random.xml | 50 +- lib/stdlib/doc/src/re.xml | 131 ++-- lib/stdlib/doc/src/regexp.xml | 152 ++--- lib/stdlib/doc/src/sets.xml | 153 ++--- lib/stdlib/doc/src/shell.xml | 37 +- lib/stdlib/doc/src/slave.xml | 60 +- lib/stdlib/doc/src/sofs.xml | 1021 ++++++++++++----------------- lib/stdlib/doc/src/specs.xml | 63 ++ lib/stdlib/doc/src/string.xml | 230 +++---- lib/stdlib/doc/src/supervisor.xml | 218 +++--- lib/stdlib/doc/src/supervisor_bridge.xml | 47 +- lib/stdlib/doc/src/sys.xml | 212 +++--- lib/stdlib/doc/src/timer.xml | 173 +++-- lib/stdlib/doc/src/unicode.xml | 174 ++--- lib/stdlib/doc/src/win32reg.xml | 98 +-- lib/stdlib/doc/src/zip.xml | 281 +++----- 60 files changed, 4347 insertions(+), 6646 deletions(-) create mode 100644 lib/stdlib/doc/specs/.gitignore create mode 100644 lib/stdlib/doc/src/specs.xml diff --git a/lib/compiler/doc/src/compile.xml b/lib/compiler/doc/src/compile.xml index f2af932aef..830c89ae84 100644 --- a/lib/compiler/doc/src/compile.xml +++ b/lib/compiler/doc/src/compile.xml @@ -68,7 +68,7 @@ to be an error if the module name in the source code is not the same as the basename of the output file.

-

Here follows first all elements of Options that in +

Here follows first all elements of Options that in some way control the behavior of the compiler.

basic_validation diff --git a/lib/stdlib/doc/specs/.gitignore b/lib/stdlib/doc/specs/.gitignore new file mode 100644 index 0000000000..322eebcb06 --- /dev/null +++ b/lib/stdlib/doc/specs/.gitignore @@ -0,0 +1 @@ +specs_*.xml diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index b558697d63..16e0a86e3b 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2010. All Rights Reserved. +# Copyright Ericsson AB 1997-2011. All Rights Reserved. # # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in @@ -125,18 +125,24 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf +SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) + +TOP_SPECS_FILE = specs.xml + # ---------------------------------------------------- # FLAGS # ---------------------------------------------------- XML_FLAGS += +SPECS_FLAGS = -I../../include -I../../../kernel/include + # ---------------------------------------------------- # Targets # ---------------------------------------------------- $(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ -docs: pdf html man +docs: man pdf html $(TOP_PDF_FILE): $(XML_FILES) @@ -155,8 +161,13 @@ clean clean_docs: rm -f $(MAN3DIR)/* rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f $(SPECDIR)/* rm -f errs core *~ +$(SPECDIR)/specs_erl_id_trans.xml: + escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + -o$(dir $@) -module erl_id_trans + # ---------------------------------------------------- # Release Target # ---------------------------------------------------- diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml index 5c3ac6a2a9..a79fcd487e 100644 --- a/lib/stdlib/doc/src/array.xml +++ b/lib/stdlib/doc/src/array.xml @@ -3,7 +3,7 @@
- 20072009 + 20072011 Ericsson AB. All Rights Reserved. @@ -82,19 +82,35 @@ the default value cannot be confused with the values of set entries.

%% allow accesses beyond the last set entry {'EXIT',{badarg,_}} = (catch array:set(18, true, A3)). {'EXIT',{badarg,_}} = (catch array:get(18, A3)). -
DATA TYPES - - -array() - -

A functional, extendible array. The representation is - not documented and is subject to change without notice. Note that - arrays cannot be directly compared for equality.

-
-
+ + + array() + +

A functional, extendible array. The representation is + not documented and is subject to change without notice. Note that + arrays cannot be directly compared for equality.

+
+
+ + + + + + + + + + + + + + + +
+ -default(Array::array()) -> term() + Get the value used for uninitialized entries. @@ -104,7 +120,7 @@ the default value cannot be confused with the values of set entries.

See also: new/2.

-fix(Array::array()) -> array() + Fix the size of the array. @@ -114,105 +130,100 @@ the default value cannot be confused with the values of set entries.

See also: relax/1.

-foldl(Function, InitialAcc::term(), Array::array()) -> term() + Fold the elements of the array using the given function and initial accumulator value. - -Function = (Index::integer(), Value::term(), Acc::term()) -> term() -

Fold the elements of the array using the given function and initial accumulator value. The elements are visited in order from the - lowest index to the highest. If Function is not a function, the + lowest index to the highest. If Function is not a function, the call fails with reason badarg.

See also: foldr/3, map/2, sparse_foldl/3.

-foldr(Function, InitialAcc::term(), Array::array()) -> term() + Fold the elements of the array right-to-left using the given function and initial accumulator value. - -Function = (Index::integer(), Value::term(), Acc::term()) -> term()

Fold the elements of the array right-to-left using the given function and initial accumulator value. The elements are visited in - order from the highest index to the lowest. If Function is not a + order from the highest index to the lowest. If Function is not a function, the call fails with reason badarg.

See also: foldl/3, map/2.

-from_list(List::list()) -> array() + Equivalent to from_list(List, undefined). -

Equivalent to from_list(List, undefined).

+

Equivalent to from_list(List, undefined).

-from_list(List::list(), Default::term()) -> array() + Convert a list to an extendible array. -

Convert a list to an extendible array. Default is used as the value - for uninitialized entries of the array. If List is not a proper list, +

Convert a list to an extendible array. Default is used as the value + for uninitialized entries of the array. If List is not a proper list, the call fails with reason badarg.

See also: new/2, to_list/1.

-from_orddict(Orddict::list()) -> array() + Equivalent to from_orddict(Orddict, undefined). -

Equivalent to from_orddict(Orddict, undefined).

+

Equivalent to from_orddict(Orddict, undefined).

-from_orddict(List::list(), Default::term()) -> array() + Convert an ordered list of pairs {Index, Value} to a corresponding extendible array.

Convert an ordered list of pairs {Index, Value} to a - corresponding extendible array. Default is used as the value for - uninitialized entries of the array. If List is not a proper, + corresponding extendible array. Default is used as the value for + uninitialized entries of the array. If Orddict is not a proper, ordered list of pairs whose first elements are nonnegative integers, the call fails with reason badarg.

See also: new/2, to_orddict/1.

-get(I::integer(), Array::array()) -> term() + Get the value of entry I. -

Get the value of entry I. If I is not a nonnegative - integer, or if the array has fixed size and I is larger than the +

Get the value of entry I. If I is not a nonnegative + integer, or if the array has fixed size and I is larger than the maximum index, the call fails with reason badarg.

If the array does not have fixed size, this function will return the - default value for any index I greater than size(Array)-1.

+ default value for any index I greater than size(Array)-1.

See also: set/3.

-is_array(X::term()) -> bool() + Returns true if X appears to be an array, otherwise false. -

Returns true if X appears to be an array, otherwise false. - Note that the check is only shallow; there is no guarantee that X +

Returns true if X appears to be an array, otherwise false. + Note that the check is only shallow; there is no guarantee that X is a well-formed array representation even if this function returns true.

-is_fix(Array::array()) -> bool() + Check if the array has fixed size. @@ -222,20 +233,18 @@ the default value cannot be confused with the values of set entries.

See also: fix/1.

-map(Function, Array::array()) -> array() + Map the given function onto each element of the array. - -Function = (Index::integer(), Value::term()) -> term()

Map the given function onto each element of the array. The elements are visited in order from the lowest index to the highest. - If Function is not a function, the call fails with reason badarg. + If Function is not a function, the call fails with reason badarg.

See also: foldl/3, foldr/3, sparse_map/2.

-new() -> array() + Create a new, extendible array with initial size zero. @@ -244,7 +253,7 @@ the default value cannot be confused with the values of set entries.

See also: new/1, new/2.

-new(Options::term()) -> array() + Create a new array according to the given options. @@ -253,10 +262,10 @@ the default value cannot be confused with the values of set entries.

the array is extendible and has initial size zero. Array indices start at 0.

-

Options is a single term or a list of terms, selected from the +

Options is a single term or a list of terms, selected from the following:

- N::integer() or {size, N::integer()} + N::integer() >= 0 or {size, N::integer() >= 0}

Specifies the initial size of the array; this also implies {fixed, true}. If N is not a nonnegative integer, the call fails with reason badarg.

@@ -283,19 +292,19 @@ cannot be changed once the array has been created.

See also: fix/1, from_list/2, get/2, new/0, new/2, set/3.

-new(Size::integer(), Options::term()) -> array() + Create a new array according to the given size and options.

Create a new array according to the given size and options. If - Size is not a nonnegative integer, the call fails with reason + Size is not a nonnegative integer, the call fails with reason badarg. By default, the array has fixed size. Note that any size - specifications in Options will override the Size parameter.

+ specifications in Options will override the Size parameter.

-

If Options is a list, this is simply equivalent to new([{size, - Size} | Options], otherwise it is equivalent to new([{size, Size} | - [Options]]. However, using this function directly is more efficient.

+

If Options is a list, this is simply equivalent to new([{size, + Size} | Options], otherwise it is equivalent to new([{size, Size} | + [Options]]. However, using this function directly is more efficient.

Example:

     array:new(100, {default,0})

creates a fixed-size array of size @@ -304,7 +313,7 @@ cannot be changed once the array has been created.

See also: new/1.

-relax(Array::array()) -> array() + Make the array resizable. @@ -313,24 +322,24 @@ cannot be changed once the array has been created.

See also: fix/1.

-reset(I::integer(), Array::array()) -> array() + Reset entry I to the default value for the array. -

Reset entry I to the default value for the array. - If the value of entry I is the default value the array will be +

Reset entry I to the default value for the array. + If the value of entry I is the default value the array will be returned unchanged. Reset will never change size of the array. Shrinking can be done explicitly by calling resize/2.

-

If I is not a nonnegative integer, or if the array has fixed size - and I is larger than the maximum index, the call fails with reason +

If I is not a nonnegative integer, or if the array has fixed size + and I is larger than the maximum index, the call fails with reason badarg; cf. set/3

See also: new/2, set/3.

-resize(Array::array()) -> array() + Change the size of the array to that reported by sparse_size/1. @@ -340,90 +349,84 @@ cannot be changed once the array has been created.

See also: resize/2, sparse_size/1.

-resize(Size::integer(), Array::array()) -> array() + Change the size of the array. -

Change the size of the array. If Size is not a nonnegative +

Change the size of the array. If Size is not a nonnegative integer, the call fails with reason badarg. If the given array has fixed size, the resulting array will also have fixed size.

-set(I::integer(), Value::term(), Array::array()) -> array() + Set entry I of the array to Value. -

Set entry I of the array to Value. If I is not a - nonnegative integer, or if the array has fixed size and I is larger +

Set entry I of the array to Value. If I is not a + nonnegative integer, or if the array has fixed size and I is larger than the maximum index, the call fails with reason badarg.

-

If the array does not have fixed size, and I is greater than - size(Array)-1, the array will grow to size I+1. +

If the array does not have fixed size, and I is greater than + size(Array)-1, the array will grow to size I+1.

See also: get/2, reset/2.

-size(Array::array()) -> integer() + Get the number of entries in the array.

Get the number of entries in the array. Entries are numbered - from 0 to size(Array)-1; hence, this is also the index of the first + from 0 to size(Array)-1; hence, this is also the index of the first entry that is guaranteed to not have been previously set.

See also: set/3, sparse_size/1.

-sparse_foldl(Function, InitialAcc::term(), Array::array()) -> term() + Fold the elements of the array using the given function and initial accumulator value, skipping default-valued entries. - -Function = (Index::integer(), Value::term(), Acc::term()) -> term()

Fold the elements of the array using the given function and initial accumulator value, skipping default-valued entries. The elements are visited in order from the lowest index to the highest. - If Function is not a function, the call fails with reason badarg. + If Function is not a function, the call fails with reason badarg.

See also: foldl/3, sparse_foldr/3.

-sparse_foldr(Function, InitialAcc::term(), Array::array()) -> term() + Fold the elements of the array right-to-left using the given function and initial accumulator value, skipping default-valued entries. - -Function = (Index::integer(), Value::term(), Acc::term()) -> term()

Fold the elements of the array right-to-left using the given function and initial accumulator value, skipping default-valued entries. The elements are visited in order from the highest index to - the lowest. If Function is not a function, the call fails with + the lowest. If Function is not a function, the call fails with reason badarg.

See also: foldr/3, sparse_foldl/3.

-sparse_map(Function, Array::array()) -> array() + Map the given function onto each element of the array, skipping default-valued entries. - -Function = (Index::integer(), Value::term()) -> term()

Map the given function onto each element of the array, skipping default-valued entries. The elements are visited in order from the - lowest index to the highest. If Function is not a function, the + lowest index to the highest. If Function is not a function, the call fails with reason badarg.

See also: map/2.

-sparse_size(A::array()) -> integer() + Get the number of entries in the array up until the last non-default valued entry. @@ -436,7 +439,7 @@ cannot be changed once the array has been created.

See also: resize/1, size/1.

-sparse_to_list(Array::array()) -> list() + Converts the array to a list, skipping default-valued entries. @@ -446,7 +449,7 @@ cannot be changed once the array has been created.

See also: to_list/1.

-sparse_to_orddict(Array::array()) -> [{Index::integer(), Value::term()}] + Convert the array to an ordered list of pairs {Index, Value}, skipping default-valued entries. @@ -458,7 +461,7 @@ cannot be changed once the array has been created.

See also: to_orddict/1.

-to_list(Array::array()) -> list() + Converts the array to a list. @@ -468,7 +471,7 @@ cannot be changed once the array has been created.

See also: from_list/2, sparse_to_list/1.

-to_orddict(Array::array()) -> [{Index::integer(), Value::term()}] + Convert the array to an ordered list of pairs {Index, Value}. diff --git a/lib/stdlib/doc/src/base64.xml b/lib/stdlib/doc/src/base64.xml index d3fd7a843b..bfe8494a73 100644 --- a/lib/stdlib/doc/src/base64.xml +++ b/lib/stdlib/doc/src/base64.xml @@ -4,7 +4,7 @@
- 20072009 + 20072011 Ericsson AB. All Rights Reserved. @@ -33,32 +33,33 @@

Implements base 64 encode and decode, see RFC2045.

+ + + + + - encode(Data) -> Base64 - encode_to_string(Data) -> Base64String + + Encodes data into base64. - - Data = string() | binary() - Base64 = binary() - Base64String = string() - + + +

Encodes a plain ASCII string into base64. The result will be 33% larger than the data.

- decode(Base64) -> Data - decode_to_string(Base64) -> DataString - mime_decode(Base64) -> Data - mime_decode_to_string(Base64) -> DataString + + + + Decodes a base64 encoded string to data. - - Base64 = string() | binary() - Data = binary() - DataString = string() - + + +

Decodes a base64 encoded string to plain ASCII. See RFC4648. mime_decode/1 and mime_decode_to_string/1 diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index adc411e272..013e94c393 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -4,7 +4,7 @@

- 20002010 + 20002011 Ericsson AB. All Rights Reserved. @@ -154,70 +154,78 @@ -
- DATA TYPES - -beam() -> Module | Filename | binary() - Module = atom() - Filename = string() | atom() -

Each of the functions described below accept either the module - name, the filename, or a binary containing the beam module.

- -chunkdata() = {ChunkId, DataB} | {ChunkName, DataT} - ChunkId = chunkid() - DataB = binary() - {ChunkName, DataT} = - {abstract_code, AbstractCode} - | {attributes, [{Attribute, [AttributeValue]}]} - | {compile_info, [{InfoKey, [InfoValue]}]} - | {exports, [{Function, Arity}]} - | {labeled_exports, [{Function, Arity, Label}]} - | {imports, [{Module, Function, Arity}]} - | {indexed_imports, [{Index, Module, Function, Arity}]} - | {locals, [{Function, Arity}]}]} - | {labeled_locals, [{Function, Arity, Label}]}]} - | {atoms, [{integer(), atom()}]} - AbstractCode = {AbstVersion, Forms} | no_abstract_code - AbstVersion = atom() - Attribute = atom() - AttributeValue = term() - Module = Function = atom() - Arity = int() - Label = int() -

It is not checked that the forms conform to the abstract format - indicated by AbstVersion. no_abstract_code means - that the "Abst" chunk is present, but empty.

-

The list of attributes is sorted on Attribute, and each - attribute name occurs once in the list. The attribute values - occur in the same order as in the file. The lists of functions - are also sorted.

- -chunkid() = "Abst" | "Attr" | "CInf" - | "ExpT" | "ImpT" | "LocT" - | "Atom" + + + + +

Each of the functions described below accept either the + module name, the filename, or a binary containing the beam + module.

+
+
+ + + +

The list of attributes is sorted on Attribute + (in attrib_entry()), and each + attribute name occurs once in the list. The attribute values + occur in the same order as in the file. The lists of functions + are also sorted.

+
+
+ + + +

"Abst" | "Attr" | "CInf" | "ExpT" | "ImpT" | "LocT" | "Atom"

+
+
+ + + + + + +

It is not checked that the forms conform to the abstract format + indicated by AbstVersion. no_abstract_code means + that the "Abst" chunk is present, but empty.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-chunkname() = abstract_code | attributes | compile_info - | exports | labeled_exports - | imports | indexed_imports - | locals | labeled_locals - | atoms - -chunkref() = chunkname() | chunkid()
-
- chunks(Beam, [ChunkRef]) -> {ok, {Module, [ChunkData]}} | {error, beam_lib, Reason} + Read selected chunks from a BEAM file or binary - - Beam = beam() - ChunkRef = chunkref() - Module = atom() - ChunkData = chunkdata() - Reason = {unknown_chunk, Filename, atom()} -   | {key_missing_or_invalid, Filename, abstract_code} -   | Reason1 -- see info/1 -  Filename = string() -

Reads chunk data for selected chunks refs. The order of the returned list of chunk data is determined by the order @@ -225,43 +233,26 @@ chunkref() = chunkname() | chunkid() - chunks(Beam, [ChunkRef], [Option]) -> {ok, {Module, [ChunkResult]}} | {error, beam_lib, Reason} + Read selected chunks from a BEAM file or binary - - Beam = beam() - ChunkRef = chunkref() - Module = atom() - Option = allow_missing_chunks - ChunkResult = {chunkref(), ChunkContents} | {chunkref(), missing_chunk} - Reason = {missing_chunk, Filename, atom()} -   | {key_missing_or_invalid, Filename, abstract_code} -   | Reason1 -- see info/1 -  Filename = string() -

Reads chunk data for selected chunks refs. The order of the returned list of chunk data is determined by the order of the list of chunks references.

-

By default, if any requested chunk is missing in Beam, +

By default, if any requested chunk is missing in Beam, an error tuple is returned. However, if the option allow_missing_chunks has been given, a result will be returned even if chunks are missing. In the result list, any missing chunks will be represented as - {ChunkRef,missing_chunk}. + {ChunkRef,missing_chunk}. Note, however, that if the "Atom" chunk if missing, that is considered a fatal error and the return value will be an error tuple.

- version(Beam) -> {ok, {Module, [Version]}} | {error, beam_lib, Reason} + Read the BEAM file's module version - - Beam = beam() - Module = atom() - Version = term() - Reason -- see chunks/2 -

Returns the module version(s). A version is defined by the module attribute -vsn(Vsn). If this attribute is @@ -282,51 +273,30 @@ chunkref() = chunkname() | chunkid() - md5(Beam) -> {ok, {Module, MD5}} | {error, beam_lib, Reason} + Read the BEAM file's module version - - Beam = beam() - Module = atom() - MD5 = binary() - Reason -- see chunks/2 -

Calculates an MD5 redundancy check for the code of the module (compilation date and other attributes are not included).

- info(Beam) -> [{Item, Info}] | {error, beam_lib, Reason1} + Information about a BEAM file - - Beam = beam() - Item, Info -- see below - Reason1 = {chunk_too_big, Filename, ChunkId, ChunkSize, FileSize} -   | {invalid_beam_file, Filename, Pos} -   | {invalid_chunk, Filename, ChunkId} -   | {missing_chunk, Filename, ChunkId} -   | {not_a_beam_file, Filename} -   | {file_error, Filename, Posix} -  Filename = string() -  ChunkId = chunkid() -  ChunkSize = FileSize = int() -  Pos = int() -  Posix = posix() -- see file(3) -

Returns a list containing some information about a BEAM file as tuples {Item, Info}:

- {file, Filename} | {binary, Binary} + {file, Filename} | {binary, Binary}

The name (string) of the BEAM file, or the binary from which the information was extracted.

- {module, Module} + {module, Module}

The name (atom) of the module.

- {chunks, [{ChunkId, Pos, Size}]} + {chunks, [{ChunkId, Pos, Size}]}

For each chunk, the identifier (string) and the position and size of the chunk data, in bytes.

@@ -335,17 +305,9 @@ chunkref() = chunkname() | chunkid()
- cmp(Beam1, Beam2) -> ok | {error, beam_lib, Reason} + Compare two BEAM files - - Beam1 = Beam2 = beam() - Reason = {modules_different, Module1, Module2} -   | {chunks_different, ChunkId} -   | different_chunks -   | Reason1 -- see info/1 -  Module1 = Module2 = atom() -  ChunkId = chunkid() - +

Compares the contents of two BEAM files. If the module names are the same, and all chunks except for the "CInf" chunk @@ -356,34 +318,23 @@ chunkref() = chunkname() | chunkid() - cmp_dirs(Dir1, Dir2) -> {Only1, Only2, Different} | {error, beam_lib, Reason1} + Compare the BEAM files in two directories - - Dir1 = Dir2 = string() | atom() - Different = [{Filename1, Filename2}] - Only1 = Only2 = [Filename] - Filename = Filename1 = Filename2 = string() - Reason1 = {not_a_directory, term()} | -- see info/1 -

The cmp_dirs/2 function compares the BEAM files in two directories. Only files with extension ".beam" are - compared. BEAM files that exist in directory Dir1 - (Dir2) only are returned in Only1 - (Only2). BEAM files that exist on both directories but + compared. BEAM files that exist in directory Dir1 + (Dir2) only are returned in Only1 + (Only2). BEAM files that exist on both directories but are considered different by cmp/2 are returned as - pairs {Filename1, Filename2} where - Filename1 (Filename2) exists in directory - Dir1 (Dir2).

+ pairs {Filename1, Filename2} where + Filename1 (Filename2) exists in directory + Dir1 (Dir2).

- diff_dirs(Dir1, Dir2) -> ok | {error, beam_lib, Reason1} + Compare the BEAM files in two directories - - Dir1 = Dir2 = string() | atom() - Reason1 = {not_a_directory, term()} | -- see info/1 -

The diff_dirs/2 function compares the BEAM files in two directories the way cmp_dirs/2 does, but names of @@ -392,13 +343,8 @@ chunkref() = chunkname() | chunkid() - strip(Beam1) -> {ok, {Module, Beam2}} | {error, beam_lib, Reason1} + Removes chunks not needed by the loader from a BEAM file - - Beam1 = Beam2 = beam() - Module = atom() - Reason1 -- see info/1 -

The strip/1 function removes all chunks from a BEAM file except those needed by the loader. In particular, @@ -406,15 +352,8 @@ chunkref() = chunkname() | chunkid() - strip_files(Files) -> {ok, [{Module, Beam2}]} | {error, beam_lib, Reason1} + Removes chunks not needed by the loader from BEAM files - - Files = [Beam1] -  Beam1 = beam() - Module = atom() - Beam2 = beam() - Reason1 -- see info/1 -

The strip_files/1 function removes all chunks except those needed by the loader from BEAM files. In particular, @@ -424,30 +363,20 @@ chunkref() = chunkname() | chunkid() - strip_release(Dir) -> {ok, [{Module, Filename]}} | {error, beam_lib, Reason1} + Removes chunks not needed by the loader from all BEAM files of a release - - Dir = string() | atom() - Module = atom() - Filename = string() - Reason1 = {not_a_directory, term()} | -- see info/1 -

The strip_release/1 function removes all chunks except those needed by the loader from the BEAM files of a - release. Dir should be the installation root + release. Dir should be the installation root directory. For example, the current OTP release can be stripped with the call beam_lib:strip_release(code:root_dir()).

- format_error(Reason) -> Chars + Return an English description of a BEAM read error reply - - Reason -- see other functions - Chars = [char() | Chars] -

Given the error returned by any function in this module, the function format_error returns a descriptive string @@ -456,12 +385,11 @@ chunkref() = chunkname() | chunkid() - crypto_key_fun(CryptoKeyFun) -> ok | {error, Reason} + Register a fun that provides a crypto key - - CryptoKeyFun = fun() -- see below - Reason = badfun | exists | term() - + + +

The crypto_key_fun/1 function registers a unary fun that will be called if beam_lib needs to read an @@ -495,11 +423,8 @@ chunkref() = chunkname() | chunkid() - clear_crypto_key_fun() -> {ok, Result} + Unregister the current crypto key fun - - Result = undefined | term() -

Unregisters the crypto key fun and terminates the process holding it, started by crypto_key_fun/1.

diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml index c81023862e..88ce77e0d0 100644 --- a/lib/stdlib/doc/src/binary.xml +++ b/lib/stdlib/doc/src/binary.xml @@ -5,7 +5,7 @@
2009 - 2010 + 2011 Ericsson AB, All Rights Reserved @@ -53,37 +53,35 @@ module.

- - -
- DATA TYPES - - cp() - - Opaque data-type representing a compiled search-pattern. Guaranteed to be a tuple() - to allow programs to distinguish it from non precompiled search patterns. - - - part() = {Start,Length} - Start = int() - Length = int() - - A representaion of a part (or range) in a binary. Start is a + + + +

Opaque data-type representing a compiled + search-pattern. Guaranteed to be a tuple() to allow programs to + distinguish it from non precompiled search patterns.

+
+
+ + +

A representaion of a part (or range) in a binary. Start is a zero-based offset into a binary() and Length is the length of that part. As input to functions in this module, a reverse part specification is allowed, constructed with a negative Length, so that the part of the binary begins at Start + Length and is -Length long. This is useful for referencing the last N bytes of a binary as {size(Binary), -N}. The functions - in this module always return part()'s with positive Length. - -

+ in this module always return part()'s with positive Length.

+ + + - at(Subject, Pos) -> int() + at(Subject, Pos) -> byte() Returns the byte at a specific position in a binary Subject = binary() - Pos = int() >= 0 + Pos = integer() >= 0 @@ -95,7 +93,7 @@ - bin_to_list(Subject) -> list() + bin_to_list(Subject) -> [byte()] Convert a binary to a list of integers Subject = binary() @@ -105,7 +103,7 @@ - bin_to_list(Subject, PosLen) -> list() + bin_to_list(Subject, PosLen) -> [byte()] Convert a binary to a list of integers Subject = binary() @@ -113,7 +111,7 @@ -

Converts Subject to a list of int()s, each representing +

Converts Subject to a list of byte()s, each representing the value of one byte. The part() denotes which part of the binary() to convert. Example:

@@ -126,12 +124,12 @@
- bin_to_list(Subject, Pos, Len) -> list() + bin_to_list(Subject, Pos, Len) -> [byte()] Convert a binary to a list of integers Subject = binary() - Pos = int() - Len = int() + Pos = integer() >= 0 + Len = integer() >= 0

The same as bin_to_list(Subject,{Pos,Len}).

@@ -185,7 +183,7 @@ Duplicates a binary N times and creates a new Subject = binary() - N = int() >= 0 + N = integer() >= 0

Creates a binary with the content of Subject duplicated N times.

@@ -211,7 +209,7 @@ Decode a whole binary into an integer of arbitrary size Subject = binary() - Unsigned = int() >= 0 + Unsigned = integer() >= 0

The same as decode_unsigned(Subject,big).

@@ -223,12 +221,12 @@ Subject = binary() Endianess = big | little - Unsigned = int() >= 0 + Unsigned = integer() >= 0

Converts the binary digit representation, in big or little - endian, of a positive integer in Subject to an Erlang int().

+ endian, of a positive integer in Subject to an Erlang integer().

Example:

@@ -242,7 +240,7 @@ encode_unsigned(Unsigned) -> binary() Encodes an unsigned integer into the minimal binary - Unsigned = int() >= 0 + Unsigned = integer() >= 0

The same as encode_unsigned(Unsigned,big).

@@ -252,7 +250,7 @@ encode_unsigned(Unsigned,Endianess) -> binary() Encodes an unsigned integer into the minimal binary - Unsigned = int() >= 0 + Unsigned = integer() >= 0 Endianess = big | little @@ -270,7 +268,7 @@
- first(Subject) -> int() + first(Subject) -> byte() Returns the first byte of a binary Subject = binary() @@ -283,7 +281,7 @@ - last(Subject) -> int() + last(Subject) -> byte() Returns the last byte of a binary Subject = binary() @@ -306,7 +304,7 @@ - longest_common_prefix(Binaries) -> int() + longest_common_prefix(Binaries) -> integer() >= 0 Returns length of longest common prefix for a set of binaries Binaries = [ binary() ] @@ -327,7 +325,7 @@ - longest_common_suffix(Binaries) -> int() + longest_common_suffix(Binaries) -> integer() >= 0 Returns length of longest common suffix for a set of binaries Binaries = [ binary() ] @@ -450,7 +448,7 @@ [{1,4}] -

The result shows that <<bcde">> is selected instead of the +

The result shows that <<"bcde">> is selected instead of the shorter match <<"bc">> (which would have given raise to one more match,<<"de">>). This corresponds to the behavior of posix regular expressions (and programs like awk), but is not @@ -506,15 +504,15 @@ Extracts a part of a binary Subject = binary() - Pos = int() - Len = int() + Pos = integer() >= 0 + Len = integer() >= 0

The same as part(Subject, {Pos, Len}).

- referenced_byte_size(binary()) -> int() + referenced_byte_size(binary()) -> integer() >= 0 Determines the size of the actual binary pointed out by a sub-binary @@ -581,42 +579,28 @@ store(Binary, GBSet) -> - replace(Subject,Pattern,Replacement) -> Result + Replaces bytes in a binary according to a pattern - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Replacement = binary() - Result = binary() - -

The same as replace(Subject,Pattern,Replacement,[]).

+

The same as replace(Subject,Pattern,Replacement,[]).

- replace(Subject,Pattern,Replacement,Options) -> Result + Replaces bytes in a binary according to a pattern - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Replacement = binary() - Result = binary() - Options = [ Option ] - Option = global | {scope, part()} | {insert_replaced, InsPos} - InsPos = OnePos | [ OnePos ] - OnePos = int() =< byte_size(Replacement) - + An integer() =< byte_size(Replacement) +

Constructs a new binary by replacing the parts in - Subject matching Pattern with the content of - Replacement.

+ Subject matching Pattern with the content of + Replacement.

-

If the matching sub-part of Subject giving raise to the +

If the matching sub-part of Subject giving raise to the replacement is to be inserted in the result, the option - {insert_replaced, InsPos} will insert the matching part into - Replacement at the given position (or positions) before actually - inserting Replacement into the Subject. Example:

+ {insert_replaced, InsPos} will insert the matching part into + Replacement at the given position (or positions) before actually + inserting Replacement into the Subject. Example:

1> binary:replace(<<"abcde">>,<<"b">>,<<"[]">>,[{insert_replaced,1}]). @@ -632,42 +616,30 @@ store(Binary, GBSet) -> <<"a[b-b]c[d-d]e">> -

If any position given in InsPos is greater than the size of the replacement binary, a badarg exception is raised.

+

If any position given in InsPos is greater than the size of the replacement binary, a badarg exception is raised.

The options global and {scope, part()} work as for split/3. The return type is always a binary().

-

For a description of Pattern, see compile_pattern/1.

+

For a description of Pattern, see compile_pattern/1.

- split(Subject,Pattern) -> Parts + Splits a binary according to a pattern - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Parts = [ binary() ] - -

The same as split(Subject, Pattern, []).

+

The same as split(Subject, Pattern, []).

- split(Subject,Pattern,Options) -> Parts + Splits a binary according to a pattern - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Parts = [ binary() ] - Options = [ Option ] - Option = {scope, part()} | trim | global - -

Splits Binary into a list of binaries based on Pattern. If +

Splits Subject into a list of binaries based on Pattern. If the option global is not given, only the first occurrence of - Pattern in Subject will give rise to a split.

+ Pattern in Subject will give rise to a split.

-

The parts of Pattern actually found in Subject are not included in the result.

+

The parts of Pattern actually found in Subject are not included in the result.

Example:

@@ -696,7 +668,7 @@ store(Binary, GBSet) -> global -

Repeats the split until the Subject is +

Repeats the split until the Subject is exhausted. Conceptually the global option makes split work on the positions returned by matches/3, while it normally @@ -716,12 +688,12 @@ store(Binary, GBSet) ->

The return type is always a list of binaries that are all - referencing Subject. This means that the data in Subject is not - actually copied to new binaries and that Subject cannot be + referencing Subject. This means that the data in Subject is not + actually copied to new binaries and that Subject cannot be garbage collected until the results of the split are no longer referenced.

-

For a description of Pattern, see compile_pattern/1.

+

For a description of Pattern, see compile_pattern/1.

diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml index 19e3ac1f08..ddae388a1b 100644 --- a/lib/stdlib/doc/src/c.xml +++ b/lib/stdlib/doc/src/c.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -39,43 +39,33 @@ - bt(Pid) -> void() + Stack backtrace for a process - - Pid = pid() -

Stack backtrace for a process. Equivalent to - erlang:process_display(Pid, backtrace).

+ erlang:process_display(Pid, backtrace).

- c(File) -> {ok, Module} | error - c(File, Options) -> {ok, Module} | error + + Compile and load code in a file - - File = name() -- see filename(3) - Options = [Opt] -- see compile:file/2 -

c/1,2 compiles and then purges and loads the code for - a file. Options defaults to []. Compilation is + a file. Options defaults to []. Compilation is equivalent to:

-compile:file(File, Options ++ [report_errors, report_warnings]) +compile:file(File, Options ++ [report_errors, report_warnings])

Note that purging the code means that any processes lingering in old code for the module are killed without warning. See code/3 for more information.

- cd(Dir) -> void() + Change working directory - - Dir = name() -- see filename(3) - -

Changes working directory to Dir, which may be a +

Changes working directory to Dir, which may be a relative name, and then prints the name of the new working directory.

@@ -84,14 +74,14 @@ compile:file(File, Options ++ [report_errors, report_warnings])
       
     
     
-      flush() -> void()
+      
       Flush any messages sent to the shell
       
         

Flushes any messages sent to the shell.

- help() -> void() + Help information

Displays help information: all valid shell internal commands, @@ -99,8 +89,8 @@ compile:file(File, Options ++ [report_errors, report_warnings]) - i() -> void() - ni() -> void() + + Information about the system

i/0 displays information about the system, listing @@ -109,26 +99,20 @@ compile:file(File, Options ++ [report_errors, report_warnings]) - i(X, Y, Z) -> void() + Information about pid <X.Y.Z> - - X = Y = Z = int() -

Displays information about a process, Equivalent to - process_info(pid(X, Y, Z)), but location transparent.

+ process_info(pid(X, Y, Z)), but location transparent.

- l(Module) -> void() + Load or reload module - - Module = atom() -

Purges and loads, or reloads, a module by calling - code:purge(Module) followed by - code:load_file(Module).

+ code:purge(Module) followed by + code:load_file(Module).

Note that purging the code means that any processes lingering in old code for the module are killed without warning. See code/3 for more information.

@@ -136,35 +120,33 @@ compile:file(File, Options ++ [report_errors, report_warnings])
lc(Files) -> ok - Compile a list of files Files = [File] -  File = name() -- see filename(3) + File = file:filename() + + Compile a list of files

Compiles a list of files by calling compile:file(File, [report_errors, report_warnings]) for each File in Files.

- ls() -> void() + List files in the current directory

Lists files in the current directory.

- ls(Dir) -> void() + List files in a directory - - Dir = name() -- see filename(3) - -

Lists files in directory Dir.

+

Lists files in directory Dir.

- m() -> void() + Which modules are loaded

Displays information about the loaded modules, including @@ -172,84 +154,67 @@ compile:file(File, Options ++ [report_errors, report_warnings]) - m(Module) -> void() + Information about a module - - Module = atom() - -

Displays information about Module.

+

Displays information about Module.

- memory() -> [{Type, Size}] + Memory allocation information - - Type, Size -- see erlang:memory/0 -

Memory allocation information. Equivalent to - erlang:memory/0.

+ erlang:memory/0 + .

- memory(Type) -> Size - memory([Type]) -> [{Type, Size}] + + Memory allocation information - - Type, Size -- see erlang:memory/0 -

Memory allocation information. Equivalent to - erlang:memory/1.

+ erlang:memory/1 + .

- nc(File) -> {ok, Module} | error - nc(File, Options) -> {ok, Module} | error + + Compile and load code in a file on all nodes - - File = name() -- see filename(3) - Options = [Opt] -- see compile:file/2 -

Compiles and then loads the code for a file on all nodes. - Options defaults to []. Compilation is equivalent to:

+ Options defaults to []. Compilation is equivalent to:

-compile:file(File, Opts ++ [report_errors, report_warnings]) +compile:file(File, Options ++ [report_errors, report_warnings])
- nl(Module) -> void() + Load module on all nodes - - Module = atom() - -

Loads Module on all nodes.

+

Loads Module on all nodes.

- pid(X, Y, Z) -> pid() + Convert X,Y,Z to a pid - - X = Y = Z = int() - -

Converts X, Y, Z to the pid +

Converts X, Y, Z to the pid ]]>. This function should only be used when debugging.

- pwd() -> void() + Print working directory

Prints the name of the working directory.

- q() -> void() + Quit - shorthand for init:stop()

This function is shorthand for init:stop(), that is, @@ -257,8 +222,8 @@ compile:file(File, Opts ++ [report_errors, report_warnings]) - regs() -> void() - nregs() -> void() + + Information about registered processes

regs/0 displays information about all registered diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml index 075c7f9c78..4876b37127 100644 --- a/lib/stdlib/doc/src/calendar.xml +++ b/lib/stdlib/doc/src/calendar.xml @@ -73,100 +73,125 @@ week number.

-
- DATA TYPES - -date() = {Year, Month, Day} - Year = int() - Month = 1..12 - Day = 1..31 -Year cannot be abbreviated. Example: 93 denotes year 93, not 1993. -Valid range depends on the underlying OS. -The date tuple must denote a valid date. + + + + + + + + + + + + +

Year cannot be abbreviated. Example: 93 denotes year + 93, not 1993. Valid range depends on the underlying OS. The + date tuple must denote a valid date.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

See erlang:now/0.

+
+
+ + + + + + +
-time() = {Hour, Minute, Second} - Hour = 0..23 - Minute = Second = 0..59
-
- date_to_gregorian_days(Date) -> Days - date_to_gregorian_days(Year, Month, Day) -> Days + + + + + + Compute the number of days from year 0 up to the given date - - Date = date() - Days = int() -

This function computes the number of gregorian days starting with year 0 and ending at the given date.

- datetime_to_gregorian_seconds({Date, Time}) -> Seconds + Compute the number of seconds from year 0 up to the given date and time - - Date = date() - Time = time() - Seconds = int() -

This function computes the number of gregorian seconds starting with year 0 and ending at the given date and time.

- day_of_the_week(Date) -> DayNumber - day_of_the_week(Year, Month, Day) -> DayNumber + + Compute the day of the week - - Date = date() - DayNumber = 1..7 - + + + + -

This function computes the day of the week given Year, - Month and Day. The return value denotes the day +

This function computes the day of the week given Year, + Month and Day. The return value denotes the day of the week as 1: Monday, 2: Tuesday, and so on.

- gregorian_days_to_date(Days) -> Date + Compute the date given the number of gregorian days - - Days = int() - Date = date() -

This function computes the date given the number of gregorian days.

- gregorian_seconds_to_datetime(Seconds) -> {Date, Time} + Compute the date given the number of gregorian days - - Seconds = int() - Date = date() - Time = time() -

This function computes the date and time from the given number of gregorian seconds.

- is_leap_year(Year) -> bool() + Check if a year is a leap year

This function checks if a year is a leap year.

- iso_week_number() -> IsoWeekNumber + Compute the iso week number for the actual date - - IsoWeekNumber = {int(), int()} -

This function returns the tuple {Year, WeekNum} representing the iso week number for the actual date. For determining the @@ -174,42 +199,34 @@ time() = {Hour, Minute, Second} - iso_week_number(Date) -> IsoWeekNumber + Compute the iso week number for the given date - - Date = date() - IsoWeekNumber = {int(), int()} -

This function returns the tuple {Year, WeekNum} representing the iso week number for the given date.

- last_day_of_the_month(Year, Month) -> int() + Compute the number of days in a month

This function computes the number of days in a month.

- local_time() -> {Date, Time} + Compute local time - - Date = date() - Time = time() -

This function returns the local time reported by the underlying operating system.

- local_time_to_universal_time({Date1, Time1}) -> {Date2, Time2} + Convert from local time to universal time (deprecated)

This function converts from local time to Universal - Coordinated Time (UTC). Date1 must refer to a local + Coordinated Time (UTC). DateTime1 must refer to a local date after Jan 1, 1970.

This function is deprecated. Use @@ -222,15 +239,11 @@ time() = {Hour, Minute, Second} - local_time_to_universal_time_dst({Date1, Time1}) -> [{Date, Time}] + Convert from local time to universal time(s) - - Date1 = Date = date() - Time1 = Time = time() -

This function converts from local time to Universal - Coordinated Time (UTC). Date1 must refer to a local + Coordinated Time (UTC). DateTime1 must refer to a local date after Jan 1, 1970.

The return value is a list of 0, 1 or 2 possible UTC times:

@@ -258,65 +271,48 @@ time() = {Hour, Minute, Second}
- now_to_local_time(Now) -> {Date, Time} + Convert now to local date and time - - Now -- see erlang:now/0 - Date = date() - Time = time() -

This function returns local date and time converted from the return value from erlang:now().

- now_to_universal_time(Now) -> {Date, Time} - now_to_datetime(Now) -> {Date, Time} + + Convert now to date and time - - Now -- see erlang:now/0 - Date = date() - Time = time() -

This function returns Universal Coordinated Time (UTC) converted from the return value from erlang:now().

- seconds_to_daystime(Seconds) -> {Days, Time} + Compute days and time from seconds - - Seconds = Days = int() - Time = time() -

This function transforms a given number of seconds into days, - hours, minutes, and seconds. The Time part is always - non-negative, but Days is negative if the argument - Seconds is.

+ hours, minutes, and seconds. The Time part is always + non-negative, but Days is negative if the argument + Seconds is.

- seconds_to_time(Seconds) -> Time + Compute time from seconds - - Seconds = int() < 86400 - Time = time() - +

This function computes the time from the given number of - seconds. Seconds must be less than the number of + seconds. Seconds must be less than the number of seconds per day (86400).

- time_difference(T1, T2) -> {Days, Time} + Compute the difference between two times (deprecated) -

This function returns the difference between two {Date, Time} tuples. T2 should refer to an epoch later - than T1.

+

This function returns the difference between two {Date, Time} tuples. T2 should refer to an epoch later + than T1.

This function is obsolete. Use the conversion functions for gregorian days and seconds instead.

@@ -324,24 +320,17 @@ time() = {Hour, Minute, Second}
- time_to_seconds(Time) -> Seconds + Compute the number of seconds since midnight up to the given time - - Time = time() - Seconds = int() - +

This function computes the number of seconds since midnight up to the specified time.

- universal_time() -> {Date, Time} + Compute universal time - - Date = date() - Time = time() -

This function returns the Universal Coordinated Time (UTC) reported by the underlying operating system. Local time is @@ -349,25 +338,22 @@ time() = {Hour, Minute, Second} - universal_time_to_local_time({Date1, Time1}) -> {Date2, Time2} + Convert from universal time to local time - - Date1 = Date2 = date() - Time1 = Time2 = time() -

This function converts from Universal Coordinated Time (UTC) - to local time. Date1 must refer to a date after Jan 1, + to local time. DateTime must refer to a date after Jan 1, 1970.

- valid_date(Date) -> bool() - valid_date(Year, Month, Day) -> bool() + + + + + + Check if a date is valid - - Date = date() -

This function checks if a date is a valid.

diff --git a/lib/stdlib/doc/src/dets.xml b/lib/stdlib/doc/src/dets.xml index b002af6616..2512c84e18 100644 --- a/lib/stdlib/doc/src/dets.xml +++ b/lib/stdlib/doc/src/dets.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -100,50 +100,99 @@ the process with the error tuple). If given badly formed arguments, all functions exit the process with a badarg message.

-

Types

-
-access() = read | read_write
-auto_save() = infinity | int()
-bindings_cont() = tuple()
-bool() = true | false
-file() = string()
-int() = integer() >= 0
-keypos() = integer() >= 1
-name() = atom() | reference()
-no_slots() = integer() >= 0 | default
-object() = tuple()
-object_cont() = tuple()
-select_cont() = tuple()
-type() = bag | duplicate_bag | set
-version() = 8 | 9 | default    
+ + + + + + + + + + +

Opaque continuation used by + match/1 and + match/3.

+
+
+ + + +

Opaque continuation used by + bchunk/2.

+
+
+ + + + + + +

Match specifications, see the match specification + documentation in the ERTS User's Guide and ms_transform(3).

+
+
+ + + + + + + + + +

Opaque continuation used by + match_object/1 and + match_object/3.

+
+
+ + + +

See ets:match/2 for a + description of patterns.

+
+
+ + + +

Opaque continuation used by + select/1 and + select/3.

+
+
+ + + + + + + + + +
- all() -> [Name] + Return a list of the names of all open Dets tables on this node. - - Name = name() -

Returns a list of the names of all open tables on this node.

- bchunk(Name, Continuation) -> {Continuation2, Data} | '$end_of_table' | {error, Reason} + Return a chunk of objects stored in a Dets table. - - Name = name() - Continuation = start | cont() - Continuation2 = cont() - Data = binary() | tuple() -

Returns a list of objects stored in a table. The exact representation of the returned objects is not public. The lists of data can be used for initializing a table by giving the value bchunk to the format option of the - init_table/3 function. The Mnesia application uses this + init_table/3 + function. The Mnesia application uses this function for copying open tables.

Unless the table is protected using safe_fixtable/2, calls to bchunk/2 may not work as expected if @@ -151,24 +200,23 @@ version() = 8 | 9 | default

The first time bchunk/2 is called, an initial continuation, the atom start, must be provided.

The bchunk/2 function returns a tuple - {Continuation2, Data}, where Data is a list of - objects. Continuation2 is another continuation which is + {Continuation2, Data}, + where Data is a list of + objects. Continuation2 is another continuation + which is to be passed on to a subsequent call to bchunk/2. With a series of calls to bchunk/2 it is possible to extract all objects of the table.

bchunk/2 returns '$end_of_table' when all - objects have been returned, or {error, Reason} if an - error occurs. + objects have been returned, or {error, Reason} + if an error occurs.

- close(Name) -> ok | {error, Reason} + Close a Dets table. - - Name = name() -

Closes a table. Only processes that have opened a table are allowed to close it. @@ -180,22 +228,16 @@ version() = 8 | 9 | default - delete(Name, Key) -> ok | {error, Reason} + Delete all objects with a given key from a Dets table. - - Name = name() - -

Deletes all objects with the key Key from the table - Name.

+

Deletes all objects with the key Key from + the table Name.

- delete_all_objects(Name) -> ok | {error, Reason} + Delete all objects from a Dets table. - - Name = name() -

Deletes all objects from a table in almost constant time. However, if the table if fixed, delete_all_objects(T) @@ -203,12 +245,8 @@ version() = 8 | 9 | default - delete_object(Name, Object) -> ok | {error, Reason} + Delete a given object from a Dets table. - - Name = name() - Object = object() -

Deletes all instances of a given object from a table. If a table is of type bag or duplicate_bag, the @@ -218,18 +256,15 @@ version() = 8 | 9 | default - first(Name) -> Key | '$end_of_table' + Return the first key stored in a Dets table. - - Key = term() - Name = name() - -

Returns the first key stored in the table Name +

Returns the first key stored in the table Name according to the table's internal order, or '$end_of_table' if the table is empty.

Unless the table is protected using safe_fixtable/2, - subsequent calls to next/2 may not work as expected if + subsequent calls to next/2 + may not work as expected if concurrent updates are made to the table.

Should an error occur, the process is exited with an error tuple {error, Reason}. The reason for not returning the @@ -243,107 +278,78 @@ version() = 8 | 9 | default - foldl(Function, Acc0, Name) -> Acc1 | {error, Reason} - Fold a function over a Dets table. - - Function = fun(Object, AccIn) -> AccOut - Acc0 = Acc1 = AccIn = AccOut = term() - Name = name() - Object = object() - - -

Calls Function on successive elements of the table - Name together with an extra argument AccIn. The - order in which the elements of the table are traversed is - unspecified. Function must return a new accumulator - which is passed to the next call. Acc0 is returned if - the table is empty.

-
-
- - foldr(Function, Acc0, Name) -> Acc1 | {error, Reason} + + Fold a function over a Dets table. - - Function = fun(Object, AccIn) -> AccOut - Acc0 = Acc1 = AccIn = AccOut = term() - Name = name() - Object = object() - -

Calls Function on successive elements of the table - Name together with an extra argument AccIn. The +

Calls Function on successive elements of + the table Name together with an extra argument + AccIn. The order in which the elements of the table are traversed is - unspecified. Function must return a new accumulator - which is passed to the next call. Acc0 is returned if + unspecified. Function must return a new + accumulator which is passed to the next call. + Acc0 is returned if the table is empty.

- from_ets(Name, EtsTab) -> ok | {error, Reason} + Replace the objects of a Dets table with the objects of an Ets table. - - Name = name() - EtsTab = - see ets(3) - - -

Deletes all objects of the table Name and then - inserts all the objects of the Ets table EtsTab. The - order in which the objects are inserted is not specified. +

Deletes all objects of the table Name and then + inserts all the objects of the Ets table EtsTab. + The order in which the objects are inserted is not specified. Since ets:safe_fixtable/2 is called the Ets table must be public or owned by the calling process.

- info(Name) -> InfoList | undefined + Return information about a Dets table. - - Name = name() - InfoList = [{Item, Value}] - -

Returns information about the table Name as a list of - {Item, Value} tuples:

+

Returns information about the table Name + as a list of tuples:

-

{file_size, int()}, the size of the file in +

{file_size, integer() >= 0}, the size of the file in bytes.

-

{filename, file()}, the name of the file - where objects are stored.

+

{filename, file:name()}, + the name of the file where objects are stored.

-

{keypos, keypos()}, the position of the - key.

+

{keypos, keypos()} + , the position of the key.

-

{size, int()}, the number of objects stored +

{size, integer() >= 0}, the number of objects stored in the table.

-

{type, type()}, the type of the table.

+

{type, type()}, + the type of the table.

- info(Name, Item) -> Value | undefined + Return the information associated with a given item for a Dets table. - - Name = name() - -

Returns the information associated with Item for the - table Name. In addition to the {Item, Value} +

Returns the information associated with Item + for the table Name. + In addition to the {Item, Value} pairs defined for info/1, the following items are allowed:

-

{access, access()}, the access mode.

+

{access, access()} + , the access mode.

-

{auto_save, auto_save()}, the auto save - interval.

+

{auto_save, + auto_save()}, the auto save interval.

{bchunk_format, binary()}, an opaque binary @@ -362,21 +368,22 @@ version() = 8 | 9 | default erlang:phash2/1 BIF is used.

-

{memory, int()}, the size of the file in +

{memory, integer() >= 0}, the size of the file in bytes. The same value is associated with the item file_size.

-

{no_keys, int()}, the number of different +

{no_keys, integer >= 0()}, the number of different keys stored in the table. Only available for version 9 tables.

-

{no_objects, int()}, the number of objects +

{no_objects, integer >= 0()}, the number of objects stored in the table.

-

{no_slots, {Min, Used, Max}}, the number of +

{no_slots, {Min, Used, Max}}, + the number of slots of the table. Min is the minimum number of slots, Used is the number of currently used slots, and Max is the maximum number of slots. Only @@ -387,7 +394,7 @@ version() = 8 | 9 | default handles requests to the Dets table.

-

{ram_file, bool()}, whether the table is +

{ram_file, boolean()}, whether the table is kept in RAM.

@@ -399,32 +406,28 @@ version() = 8 | 9 | default table is not fixed, SafeFixed is the atom false.

-

{version, int()}, the version of the format - of the table.

+

{version, integer(), the version of the format of + the table.

- init_table(Name, InitFun [, Options]) -> ok | {error, Reason} + + Replace all objects of a Dets table. - - Name = atom() - InitFun = fun(Arg) -> Res - Arg = read | close - Res = end_of_input | {[object()], InitFun} | {Data, InitFun} | term() - Data = binary() | tuple() - -

Replaces the existing objects of the table Name with - objects created by calling the input function InitFun, +

Replaces the existing objects of the table Name + with objects created by calling the input function + InitFun, see below. The reason for using this function rather than calling insert/2 is that of efficiency. It should be noted that the input functions are called by the process that handles requests to the Dets table, not by the calling process.

When called with the argument read the function - InitFun is assumed to return end_of_input when + InitFun is assumed to return + end_of_input when there is no more input, or {Objects, Fun}, where Objects is a list of objects and Fun is a new input function. Any other value Value is returned as an error @@ -448,7 +451,8 @@ version() = 8 | 9 | default item no_slots. See also the min_no_slots option below.

-

The Options argument is a list of {Key, Val} +

The Options argument is a list of + {Key, Val} tuples where the following values are allowed:

@@ -461,87 +465,68 @@ version() = 8 | 9 | default

{format, Format}. Specifies the format of the - objects returned by the function InitFun. If + objects returned by the function InitFun. If Format is term (the default), - InitFun is assumed to return a list of tuples. If - Format is bchunk, InitFun is - assumed to return Data as returned by - bchunk/2. This option overrides the + InitFun is assumed to return a list of tuples. If + Format is bchunk, InitFun is + assumed to return Data as returned by + bchunk/2. + This option overrides the min_no_slots option.

- insert(Name, Objects) -> ok | {error, Reason} + Insert one or more objects into a Dets table. - - Name = name() - Objects = object() | [object()] - -

Inserts one or more objects into the table Name. If - there already exists an object with a key matching the key of +

Inserts one or more objects into the table Name. + If there already exists an object with a key matching the key of some of the given objects and the table type is set, the old object will be replaced.

- insert_new(Name, Objects) -> Bool + Insert one or more objects into a Dets table. - - Name = name() - Objects = object() | [object()] - Bool = bool() - -

Inserts one or more objects into the table Name. If - there already exists some object with a key matching the key +

Inserts one or more objects into the table Name. + If there already exists some object with a key matching the key of any of the given objects the table is not updated and false is returned, otherwise the objects are inserted and true returned.

- is_compatible_bchunk_format(Name, BchunkFormat) -> Bool + Test compatibility of a table's chunk data. - - Name = name() - BchunkFormat = binary() - Bool = bool() -

Returns true if it would be possible to initialize - the table Name, using init_table/3 with the + the table Name, using + init_table/3 + with the option {format, bchunk}, with objects read with - bchunk/2 from some table T such that calling + bchunk/2 from some + table T such that calling info(T, bchunk_format) returns BchunkFormat.

- is_dets_file(FileName) -> Bool | {error, Reason} + Test for a Dets table. - - FileName = file() - Bool = bool() - -

Returns true if the file FileName is a Dets - table, false otherwise.

+

Returns true if the file Filename + is a Dets table, false otherwise.

- lookup(Name, Key) -> [Object] | {error, Reason} + Return all objects with a given key stored in a Dets table. - - Key = term() - Name = name() - Object = object() - -

Returns a list of all objects with the key Key - stored in the table Name. For example:

+

Returns a list of all objects with the key Key + stored in the table Name. For example:

 2> dets:open_file(abc, [{type, bag}]).
 {ok,abc}
@@ -562,71 +547,57 @@ ok
       
     
     
-      match(Continuation) -> {[Match], Continuation2} | '$end_of_table' | {error, Reason}
+      
       Match a chunk of objects stored in a Dets table and return a list of variable bindings.
-      
-        Continuation = Continuation2 = bindings_cont()
-        Match = [term()]
-      
       
         

Matches some objects stored in a table and returns a non-empty list of the bindings that match a given pattern in some unspecified order. The table, the pattern, and the number of objects that are matched are all defined by - Continuation, which has been returned by a prior call - to match/1 or match/3.

+ Continuation, which has been returned by a prior + call to match/1 or match/3.

When all objects of the table have been matched, '$end_of_table' is returned.

- match(Name, Pattern) -> [Match] | {error, Reason} + Match the objects stored in a Dets table and return a list of variable bindings. - - Name = name() - Pattern = tuple() - Match = [term()] - -

Returns for each object of the table Name that - matches Pattern a list of bindings in some unspecified - order. See ets(3) for a +

Returns for each object of the table Name that + matches Pattern a list of bindings in some unspecified + order. See ets:match/2 for a description of patterns. If the keypos'th element of - Pattern is unbound, all objects of the table are + Pattern is unbound, all objects of the table are matched. If the keypos'th element is bound, only the objects with the right key are matched.

- match(Name, Pattern, N) -> {[Match], Continuation} | '$end_of_table' | {error, Reason} + Match the first chunk of objects stored in a Dets table and return a list of variable bindings. - - Name = name() - Pattern = tuple() - N = default | int() - Match = [term()] - Continuation = bindings_cont() - -

Matches some or all objects of the table Name and +

Matches some or all objects of the table Name and returns a non-empty list of the bindings that match - Pattern in some unspecified order. See ets(3) for a description of - patterns.

+ Pattern in some unspecified order. + See ets:match/2 for a + description of patterns.

A tuple of the bindings and a continuation is returned, unless the table is empty, in which case '$end_of_table' is returned. The continuation is to be used when matching further objects by calling - match/1.

-

If the keypos'th element of Pattern is bound, all - objects of the table are matched. If the keypos'th element is - unbound, all objects of the table are matched, N + match/1.

+

If the keypos'th element of Pattern is bound, + all objects of the table are matched. If the keypos'th element is + unbound, all objects of the table are matched, N objects at a time, until at least one object matches or the end of the table has been reached. The default, indicated by - giving N the value default, is to let the number + giving N the value default, + is to let the number of objects vary depending on the sizes of the objects. If - Name is a version 9 table, all objects with the same + Name is a version 9 table, all objects with the same key are always matched at the same time which implies that - more than N objects may sometimes be matched. + more than N objects may sometimes be matched.

The table should always be protected using safe_fixtable/2 before calling match/3, or @@ -634,15 +605,11 @@ ok - match_delete(Name, Pattern) -> ok | {error, Reason} + Delete all objects that match a given pattern from a Dets table. - - Name = name() - Pattern = tuple() - -

Deletes all objects that match Pattern from the - table Name. +

Deletes all objects that match Pattern from the + table Name. See ets:match/2 for a description of patterns.

If the keypos'th element of Pattern is bound, @@ -650,17 +617,13 @@ ok - match_object(Continuation) -> {[Object], Continuation2} | '$end_of_table' | {error, Reason} + Match a chunk of objects stored in a Dets table and return a list of objects. - - Continuation = Continuation2 = object_cont() - Object = object() -

Returns a non-empty list of some objects stored in a table that match a given pattern in some unspecified order. The table, the pattern, and the number of objects that are matched - are all defined by Continuation, which has been + are all defined by Continuation, which has been returned by a prior call to match_object/1 or match_object/3.

When all objects of the table have been matched, @@ -668,20 +631,17 @@ ok - match_object(Name, Pattern) -> [Object] | {error, Reason} + Match the objects stored in a Dets table and return a list of objects. - - Name = name() - Pattern = tuple() - Object = object() - -

Returns a list of all objects of the table Name that - match Pattern in some unspecified order. See ets(3) for a description of patterns. +

Returns a list of all objects of the table Name that + match Pattern in some unspecified order. + See ets:match/2 for a + description of patterns.

-

If the keypos'th element of Pattern is +

If the keypos'th element of Pattern is unbound, all objects of the table are matched. If the - keypos'th element of Pattern is bound, only the + keypos'th element of Pattern is bound, only the objects with the right key are matched.

Using the match_object functions for traversing all objects of a table is more efficient than calling @@ -689,34 +649,28 @@ ok - match_object(Name, Pattern, N) -> {[Object], Continuation} | '$end_of_table' | {error, Reason} + Match the first chunk of objects stored in a Dets table and return a list of objects. - - Name = name() - Pattern = tuple() - N = default | int() - Object = object() - Continuation = object_cont() - -

Matches some or all objects stored in the table Name +

Matches some or all objects stored in the table Name and returns a non-empty list of the objects that match - Pattern in some unspecified order. See ets(3) for a description of - patterns.

+ Pattern in some unspecified order. + See ets:match/2 for a + description of patterns.

A list of objects and a continuation is returned, unless the table is empty, in which case '$end_of_table' is returned. The continuation is to be used when matching further objects by calling match_object/1.

-

If the keypos'th element of Pattern is bound, all +

If the keypos'th element of Pattern is bound, all objects of the table are matched. If the keypos'th element is - unbound, all objects of the table are matched, N + unbound, all objects of the table are matched, N objects at a time, until at least one object matches or the end of the table has been reached. The default, indicated by - giving N the value default, is to let the number + giving N the value default, is to let the number of objects vary depending on the sizes of the objects. If - Name is a version 9 table, all matching objects with + Name is a version 9 table, all matching objects with the same key are always returned in the same reply which - implies that more than N objects may sometimes be returned. + implies that more than N objects may sometimes be returned.

The table should always be protected using safe_fixtable/2 before calling match_object/3, @@ -724,43 +678,31 @@ ok - member(Name, Key) -> Bool | {error, Reason} + Test for occurrence of a key in a Dets table. - - Name = name() - Key = term() - Bool = bool() -

Works like lookup/2, but does not return the objects. The function returns true if one or more - elements of the table has the key Key, false + elements of the table has the key Key, false otherwise.

- next(Name, Key1) -> Key2 | '$end_of_table' + Return the next key in a Dets table. - - Name = name() - Key1 = Key2 = term() - -

Returns the key following Key1 in the table - Name according to the table's internal order, or +

Returns the key following Key1 in the table + Name according to the table's internal order, or '$end_of_table' if there is no next key.

Should an error occur, the process is exited with an error tuple {error, Reason}.

-

Use first/1 to find the first key in the table.

+

Use first/1 to find + the first key in the table.

- open_file(Filename) -> {ok, Reference} | {error, Reason} + Open an existing Dets table. - - FileName = file() - Reference = reference() -

Opens an existing table. If the table has not been properly closed, it will be repaired. The returned reference is to be @@ -769,15 +711,12 @@ ok - open_file(Name, Args) -> {ok, Name} | {error, Reason} + Open a Dets table. - - Name = atom() -

Opens a table. An empty Dets table is created if no file exists.

-

The atom Name is the name of the table. The table +

The atom Name is the name of the table. The table name must be provided in all subsequent operations on the table. The name can be used by other processes as well, and several process can share one table. @@ -786,18 +725,20 @@ ok name and arguments, then the table will have two users. If one user closes the table, it still remains open until the second user closes the table.

-

The Args argument is a list of {Key, Val} +

The Args argument is a list of {Key, Val} tuples where the following values are allowed:

-

{access, access()}. It is possible to open +

{access, + access()}. It is possible to open existing tables in read-only mode. A table which is opened in read-only mode is not subjected to the automatic file reparation algorithm if it is later opened after a crash. The default value is read_write.

-

{auto_save, auto_save()}, the auto save +

{auto_save, + auto_save()}, the auto save interval. If the interval is an integer Time, the table is flushed to disk whenever it is not accessed for Time milliseconds. A table that has been flushed @@ -807,15 +748,18 @@ ok is 180000 (3 minutes).

-

{estimated_no_objects, int()}. Equivalent to the +

{estimated_no_objects, + no_slots()}. Equivalent to the min_no_slots option.

-

{file, file()}, the name of the file to be +

{file, + file:name()}, the name of the file to be opened. The default value is the name of the table.

-

{max_no_slots, no_slots()}, the maximum number +

{max_no_slots, + no_slots()}, the maximum number of slots that will be used. The default value as well as the maximal value is 32 M. Note that a higher value may increase the fragmentation of the table, and conversely, @@ -824,14 +768,16 @@ ok 9 tables.

-

{min_no_slots, no_slots()}. Application +

{min_no_slots, + no_slots()}. Application performance can be enhanced with this flag by specifying, when the table is created, the estimated number of different keys that will be stored in the table. The default value as well as the minimum value is 256.

-

{keypos, keypos()}, the position of the +

{keypos, + keypos()}, the position of the element of each object to be used as key. The default value is 1. The ability to explicitly state the key position is most convenient when we want to store Erlang @@ -839,7 +785,7 @@ ok name of the record type.

-

{ram_file, bool()}, whether the table is to +

{ram_file, boolean()}, whether the table is to be kept in RAM. Keeping the table in RAM may sound like an anomaly, but can enhance the performance of applications which open a table, insert a set of objects, and then @@ -849,7 +795,7 @@ ok

{repair, Value}. Value can be either - a bool() or the atom force. The flag + a boolean() or the atom force. The flag specifies whether the Dets server should invoke the automatic file reparation algorithm. The default is true. If false is specified, there is no @@ -868,11 +814,12 @@ ok already open.

-

{type, type()}, the type of the table. The - default value is set.

+

{type, type()}, + the type of the table. The default value is set.

-

{version, version()}, the version of the format +

{version, + version()}, the version of the format used for the table. The default value is 9. Tables on the format used before OTP R8 can be created by giving the value 8. A version 8 table can be converted to @@ -883,12 +830,8 @@ ok - pid2name(Pid) -> {ok, Name} | undefined + Return the name of the Dets table handled by a pid. - - Name = name() - Pid = pid() -

Returns the name of the table given the pid of a process that handles requests to a table, or undefined if @@ -897,12 +840,8 @@ ok - repair_continuation(Continuation, MatchSpec) -> Continuation2 + Repair a continuation from select/1 or select/3. - - Continuation = Continuation2 = select_cont() - MatchSpec = match_spec() -

This function can be used to restore an opaque continuation returned by select/3 or select/1 if the @@ -932,14 +871,11 @@ ok - safe_fixtable(Name, Fix) + Fix a Dets table for safe traversal. - - Name = name() - Fix = bool() - -

If Fix is true, the table Name is +

If Fix is true, the table + Name is fixed (once more) by the calling process, otherwise the table is released. The table is also released when a fixing process terminates. @@ -961,17 +897,13 @@ ok - select(Continuation) -> {Selection, Continuation2} | '$end_of_table' | {error, Reason} + Apply a match specification to some objects stored in a Dets table. - - Continuation = Continuation2 = select_cont() - Selection = [term()] -

Applies a match specification to some objects stored in a table and returns a non-empty list of the results. The table, the match specification, and the number of objects - that are matched are all defined by Continuation, + that are matched are all defined by Continuation, which has been returned by a prior call to select/1 or select/3.

When all objects of the table have been matched, @@ -979,20 +911,15 @@ ok - select(Name, MatchSpec) -> Selection | {error, Reason} + Apply a match specification to all objects stored in a Dets table. - - Name = name() - MatchSpec = match_spec() - Selection = [term()] -

Returns the results of applying the match specification - MatchSpec to all or some objects stored in the table - Name. The order of the objects is not specified. See + MatchSpec to all or some objects stored in the table + Name. The order of the objects is not specified. See the ERTS User's Guide for a description of match specifications.

-

If the keypos'th element of MatchSpec is +

If the keypos'th element of MatchSpec is unbound, the match specification is applied to all objects of the table. If the keypos'th element is bound, the match specification is applied to the objects with the right key(s) @@ -1004,19 +931,12 @@ ok - select(Name, MatchSpec, N) -> {Selection, Continuation} | '$end_of_table' | {error, Reason} + Apply a match specification to the first chunk of objects stored in a Dets table. - - Name = name() - MatchSpec = match_spec() - N = default | int() - Selection = [term()] - Continuation = select_cont() -

Returns the results of applying the match specification - MatchSpec to some or all objects stored in the table - Name. The order of the objects is not specified. See + MatchSpec to some or all objects stored in the table + Name. The order of the objects is not specified. See the ERTS User's Guide for a description of match specifications.

A tuple of the results of applying the match specification @@ -1024,18 +944,18 @@ ok in which case '$end_of_table' is returned. The continuation is to be used when matching further objects by calling select/1.

-

If the keypos'th element of MatchSpec is bound, the +

If the keypos'th element of MatchSpec is bound, the match specification is applied to all objects of the table with the right key(s). If the keypos'th element of - MatchSpec is unbound, the match specification is - applied to all objects of the table, N objects at a + MatchSpec is unbound, the match specification is + applied to all objects of the table, N objects at a time, until at least one object matches or the end of the table has been reached. The default, indicated by giving - N the value default, is to let the number of + N the value default, is to let the number of objects vary depending on the sizes of the objects. If - Name is a version 9 table, all objects with the same + Name is a version 9 table, all objects with the same key are always handled at the same time which implies that the - match specification may be applied to more than N objects. + match specification may be applied to more than N objects.

The table should always be protected using safe_fixtable/2 before calling select/3, or @@ -1043,48 +963,35 @@ ok - select_delete(Name, MatchSpec) -> N | {error, Reason} + Delete all objects that match a given pattern from a Dets table. - - Name = name() - MatchSpec = match_spec() - N = int() - -

Deletes each object from the table Name such that - applying the match specification MatchSpec to the +

Deletes each object from the table Name such that + applying the match specification MatchSpec to the object returns the value true. See the ERTS User's Guide for a description of match specifications. Returns the number of deleted objects.

-

If the keypos'th element of MatchSpec is +

If the keypos'th element of MatchSpec is bound, the match specification is applied to the objects with the right key(s) only.

- slot(Name, I) -> '$end_of_table' | [Object] | {error, Reason} + Return the list of objects associated with a slot of a Dets table. - - Name = name() - I = int() - Object = object() -

The objects of a table are distributed among slots, starting with slot 0 and ending with slot n. This function returns the list of objects associated with slot - I. If I is greater than n '$end_of_table' - is returned.

+ I. If I is greater than n + '$end_of_table' is returned.

- sync(Name) -> ok | {error, Reason} + Ensure that all updates made to a Dets table are written to disk. - - Name = name() - -

Ensures that all updates made to the table Name are +

Ensures that all updates made to the table Name are written to disk. This also applies to tables which have been opened with the ram_file flag set to true. In this case, the contents of the RAM file are flushed to @@ -1095,25 +1002,17 @@ ok - table(Name [, Options]) -> QueryHandle + + Return a QLC query handle. - - Name = name() - QueryHandle = - a query handle, see qlc(3) - - Options = [Option] | Option - Option = {n_objects, Limit} | {traverse, TraverseMethod} - Limit = default | integer() >= 1 - TraverseMethod = first_next | select | {select, MatchSpec} - MatchSpec = match_spec() - -

-Returns a QLC (Query List +

+ Returns a QLC (Query List Comprehension) query handle. The module qlc implements a query language aimed mainly at Mnesia but Ets tables, Dets tables, and lists are also recognized by qlc as sources of data. Calling dets:table/1,2 is the - means to make the Dets table Name usable to qlc.

+ means to make the Dets table Name usable to qlc.

When there are only simple restrictions on the key position qlc uses dets:lookup/2 to look up the keys, but when that is not possible the whole table is traversed. The @@ -1137,7 +1036,8 @@ Returns a QLC (Query List specification that matches all objects.

-

{select, MatchSpec}. As for select +

{select, + match_spec()}. As for select the table is traversed by calling dets:select/3 and dets:select/1. The difference is that the match specification is explicitly given. This is how to @@ -1166,35 +1066,23 @@ true

- to_ets(Name, EtsTab) -> EtsTab | {error, Reason} + Insert all objects of a Dets table into an Ets table. - - Name = name() - EtsTab = - see ets(3) - - -

Inserts the objects of the Dets table Name into the - Ets table EtsTab. The order in which the objects are +

Inserts the objects of the Dets table Name into the + Ets table EtsTab. The order in which the objects are inserted is not specified. The existing objects of the Ets table are kept unless overwritten.

- traverse(Name, Fun) -> Return | {error, Reason} + Apply a function to all or some objects stored in a Dets table. - - Fun = fun(Object) -> FunReturn - FunReturn = continue | {continue, Val} | {done, Value} - Val = Value = term() - Name = name() - Object = object() - Return = [term()] - -

Applies Fun to each object stored in the table - Name in some unspecified order. Different actions are - taken depending on the return value of Fun. The - following Fun return values are allowed:

+

Applies Fun to each object stored in the table + Name in some unspecified order. Different actions are + taken depending on the return value of Fun. The + following Fun return values are allowed:

continue @@ -1206,35 +1094,31 @@ fun(X) -> io:format("~p~n", [X]), continue end. {continue, Val} -

Continue the traversal and accumulate Val. The +

Continue the traversal and accumulate Val. The following function is supplied in order to collect all objects of a table in a list:

 fun(X) -> {continue, X} end.            
- {done, Value} + {done, Value} -

Terminate the traversal and return [Value | Acc].

+

Terminate the traversal and return [Value | Acc].

-

Any other value returned by Fun terminates the +

Any other value returned by Fun terminates the traversal and is immediately returned.

- update_counter(Name, Key, Increment) -> Result + Update a counter object stored in a Dets table. - - Name = name() - Key = term() - Increment = {Pos, Incr} | Incr - Pos = Incr = Result = integer() - -

Updates the object with key Key stored in the table - Name of type set by adding Incr to the - element at the Pos:th position. The new counter value +

Updates the object with key Key stored in the + table Name of type set by adding + Incr to the + element at the Pos:th position. + The new counter value is returned. If no position is specified, the element directly following the key is updated.

This functions provides a way of updating a counter, @@ -1252,4 +1136,3 @@ fun(X) -> {continue, X} end. qlc(3)

- diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index 0cc76e0c78..b01acd02bf 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -39,174 +39,120 @@ they do not compare equal (==).

-
- DATA TYPES - -dictionary() - as returned by new/0 -
+ + + dict() +

Dictionary as returned by new/0.

+
+
- append(Key, Value, Dict1) -> Dict2 + Append a value to keys in a dictionary - - Key = Value = term() - Dict1 = Dict2 = dictionary() - -

This function appends a new Value to the current list - of values associated with Key.

-
+

This function appends a new Value to the current list + of values associated with Key.

+
- append_list(Key, ValList, Dict1) -> Dict2 + Append new values to keys in a dictionary - - ValList = [Value] - Key = Value = term() - Dict1 = Dict2 = dictionary() - -

This function appends a list of values ValList to - the current list of values associated with Key. An +

This function appends a list of values ValList to + the current list of values associated with Key. An exception is generated if the initial value associated with - Key is not a list of values.

+ Key is not a list of values.

- erase(Key, Dict1) -> Dict2 + Erase a key from a dictionary - - Key = term() - Dict1 = Dict2 = dictionary() -

This function erases all items with a given key from a dictionary.

- fetch(Key, Dict) -> Value + Look-up values in a dictionary - - Key = Value = term() - Dict = dictionary() - -

This function returns the value associated with Key - in the dictionary Dict. fetch assumes that - the Key is present in the dictionary and an exception - is generated if Key is not in the dictionary.

+

This function returns the value associated with Key + in the dictionary Dict. fetch assumes that + the Key is present in the dictionary and an exception + is generated if Key is not in the dictionary.

- fetch_keys(Dict) -> Keys + Return all keys in a dictionary - - Dict = dictionary() - Keys = [term()] -

This function returns a list of all keys in the dictionary.

- filter(Pred, Dict1) -> Dict2 + Choose elements which satisfy a predicate - - Pred = fun(Key, Value) -> bool() -  Key = Value = term() - Dict1 = Dict2 = dictionary() - -

Dict2 is a dictionary of all keys and values in - Dict1 for which Pred(Key, Value) is true.

+

Dict2 is a dictionary of all keys and values in + Dict1 for which Pred(Key, Value) is true.

- find(Key, Dict) -> {ok, Value} | error + Search for a key in a dictionary - - Key = Value = term() - Dict = dictionary() -

This function searches for a key in a dictionary. Returns - {ok, Value} where Value is the value associated - with Key, or error if the key is not present in + {ok, Value} where Value is the value associated + with Key, or error if the key is not present in the dictionary.

- fold(Fun, Acc0, Dict) -> Acc1 + Fold a function over a dictionary - - Fun = fun(Key, Value, AccIn) -> AccOut - Key = Value = term() - Acc0 = Acc1 = AccIn = AccOut = term() - Dict = dictionary() - -

Calls Fun on successive keys and values of - Dict together with an extra argument Acc - (short for accumulator). Fun must return a new - accumulator which is passed to the next call. Acc0 is +

Calls Fun on successive keys and values of + Dict together with an extra argument Acc + (short for accumulator). Fun must return a new + accumulator which is passed to the next call. Acc0 is returned if the list is empty. The evaluation order is undefined.

- from_list(List) -> Dict + Convert a list of pairs to a dictionary - - List = [{Key, Value}] - Dict = dictionary() - -

This function converts the Key - Value list - List to a dictionary.

+

This function converts the Key - Value list + List to a dictionary.

- is_key(Key, Dict) -> bool() + Test if a key is in a dictionary - - Key = term() - Dict = dictionary() - -

This function tests if Key is contained in - the dictionary Dict.

+

This function tests if Key is contained in + the dictionary Dict.

- map(Fun, Dict1) -> Dict2 + Map a function over a dictionary - - Fun = fun(Key, Value1) -> Value2 -  Key = Value1 = Value2 = term() - Dict1 = Dict2 = dictionary() - -

map calls Func on successive keys and values - of Dict to return a new value for each key. +

map calls Fun on successive keys and values + of Dict1 to return a new value for each key. The evaluation order is undefined.

- merge(Fun, Dict1, Dict2) -> Dict3 + Merge two dictionaries - - Fun = fun(Key, Value1, Value2) -> Value -  Key = Value1 = Value2 = Value3 = term() - Dict1 = Dict2 = Dict3 = dictionary() - -

merge merges two dictionaries, Dict1 and - Dict2, to create a new dictionary. All the Key - - Value pairs from both dictionaries are included in +

merge merges two dictionaries, Dict1 and + Dict2, to create a new dictionary. All the Key + - Value pairs from both dictionaries are included in the new dictionary. If a key occurs in both dictionaries then - Fun is called with the key and both values to return a + Fun is called with the key and both values to return a new value. merge could be defined as:

merge(Fun, D1, D2) -> @@ -217,75 +163,52 @@ merge(Fun, D1, D2) ->
- new() -> dictionary() + Create a dictionary

This function creates a new dictionary.

- size(Dict) -> int() + Return the number of elements in a dictionary - - Dict = dictionary() - -

Returns the number of elements in a Dict.

+

Returns the number of elements in a Dict.

- store(Key, Value, Dict1) -> Dict2 + Store a value in a dictionary - - Key = Value = term() - Dict1 = Dict2 = dictionary() - -

This function stores a Key - Value pair in a - dictionary. If the Key already exists in Dict1, - the associated value is replaced by Value.

+

This function stores a Key - Value pair in a + dictionary. If the Key already exists in Dict1, + the associated value is replaced by Value.

- to_list(Dict) -> List + Convert a dictionary to a list of pairs - - Dict = dictionary() - List = [{Key, Value}] -

This function converts the dictionary to a list representation.

- update(Key, Fun, Dict1) -> Dict2 + Update a value in a dictionary - - Key = term() - Fun = fun(Value1) -> Value2 -  Value1 = Value2 = term() - Dict1 = Dict2 = dictionary() - -

Update a value in a dictionary by calling Fun on +

Update a value in a dictionary by calling Fun on the value to get a new value. An exception is generated if - Key is not present in the dictionary.

+ Key is not present in the dictionary.

- update(Key, Fun, Initial, Dict1) -> Dict2 + Update a value in a dictionary - - Key = Initial = term() - Fun = fun(Value1) -> Value2 -  Value1 = Value2 = term() - Dict1 = Dict2 = dictionary() - -

Update a value in a dictionary by calling Fun on - the value to get a new value. If Key is not present - in the dictionary then Initial will be stored as +

Update a value in a dictionary by calling Fun on + the value to get a new value. If Key is not present + in the dictionary then Initial will be stored as the first value. For example append/3 could be defined as:

@@ -294,17 +217,12 @@ append(Key, Val, D) ->
- update_counter(Key, Increment, Dict1) -> Dict2 + Increment a value in a dictionary - - Key = term() - Increment = number() - Dict1 = Dict2 = dictionary() - -

Add Increment to the value associated with Key - and store this value. If Key is not present in - the dictionary then Increment will be stored as +

Add Increment to the value associated with Key + and store this value. If Key is not present in + the dictionary then Increment will be stored as the first value.

This could be defined as:

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(GV1V2Label) is equivalent to - add_edge(G, E, V1, V2, Label), - where E is a created edge. The created edge is + add_edge(GEV1V2Label), + 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(GV1V2) is equivalent to + add_edge(GV1V2, []).

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(GV) is equivalent to + add_vertex(GV, []).

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 {EV1V2Label} 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 [VV].

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 {VLabel} 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.

diff --git a/lib/stdlib/doc/src/digraph_utils.xml b/lib/stdlib/doc/src/digraph_utils.xml index 4b137456b3..e44632bfd2 100644 --- a/lib/stdlib/doc/src/digraph_utils.xml +++ b/lib/stdlib/doc/src/digraph_utils.xml @@ -4,7 +4,7 @@
- 20002009 + 20002011 Ericsson AB. All Rights Reserved. @@ -119,49 +119,43 @@ considering all edges undirected.

+ + + digraph() +

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

+
+
- arborescence_root(Digraph) -> no | {yes, Root} + Check if a digraph is an arborescence. - - Digraph = digraph() - Root = vertex() - - -

Returns {yes, Root} if Root is +

Returns {yes, Root} if Root is the root of the arborescence - Digraph, no otherwise. + Digraph, no otherwise.

- components(Digraph) -> [Component] + Return the components of a digraph. - - Digraph = digraph() - Component = [vertex()] -

Returns a list of connected components. Each component is represented by its vertices. The order of the vertices and the order of the components are arbitrary. Each vertex of the digraph - Digraph occurs in exactly one component. + Digraph occurs in exactly one component.

- condensation(Digraph) -> CondensedDigraph + Return a condensed graph of a digraph. - - Digraph = CondensedDigraph = digraph() -

Creates a digraph where the vertices are the strongly connected - components of Digraph as returned by + components of Digraph as returned by strong_components/1. If X and Y are strongly connected components, and there exist vertices x and y in X and Y respectively such that there is an @@ -169,7 +163,7 @@ and incident on y, then an edge emanating from X and incident on Y is created.

-

The created digraph has the same type as Digraph. +

The created digraph has the same type as Digraph. All vertices and edges have the default label [].

@@ -181,12 +175,8 @@
- cyclic_strong_components(Digraph) -> [StrongComponent] + Return the cyclic strong components of a digraph. - - Digraph = digraph() - StrongComponent = [vertex()] -

Returns a list of strongly connected components. @@ -194,67 +184,50 @@ by its vertices. The order of the vertices and the order of the components are arbitrary. Only vertices that are included in some cycle in - Digraph are returned, otherwise the returned list is + Digraph are returned, otherwise the returned list is equal to that returned by strong_components/1.

- is_acyclic(Digraph) -> bool() + Check if a digraph is acyclic. - - Digraph = digraph() -

Returns true if and only if the digraph - Digraph is acyclic.

+ Digraph is acyclic.

- is_arborescence(Digraph) -> bool() + Check if a digraph is an arborescence. - - Digraph = digraph() -

Returns true if and only if the digraph - Digraph is + Digraph is an arborescence.

- is_tree(Digraph) -> bool() + Check if a digraph is a tree. - - Digraph = digraph() -

Returns true if and only if the digraph - Digraph is + Digraph is a tree.

- loop_vertices(Digraph) -> Vertices + Return the vertices of a digraph included in some loop. - - Digraph = digraph() - Vertices = [vertex()] - -

Returns a list of all vertices of Digraph that are +

Returns a list of all vertices of Digraph that are included in some loop.

- postorder(Digraph) -> Vertices + Return the vertices of a digraph in post-order. - - Digraph = digraph() - Vertices = [vertex()] - -

Returns all vertices of the digraph Digraph. The +

Returns all vertices of the digraph Digraph. The order is given by a depth-first traversal of the digraph, collecting visited @@ -266,14 +239,10 @@ - preorder(Digraph) -> Vertices + Return the vertices of a digraph in pre-order. - - Digraph = digraph() - Vertices = [vertex()] - -

Returns all vertices of the digraph Digraph. The +

Returns all vertices of the digraph Digraph. The order is given by a depth-first traversal of the digraph, collecting visited @@ -281,119 +250,94 @@ - reachable(Vertices, Digraph) -> Vertices + Return the vertices reachable from some vertices of a digraph. - - Digraph = digraph() - Vertices = [vertex()] -

Returns an unsorted list of digraph vertices such that for each vertex in the list, there is - a path in Digraph from some - vertex of Vertices to the vertex. In particular, + a path in Digraph from some + vertex of Vertices to the vertex. In particular, since paths may have length zero, the vertices of - Vertices are included in the returned list. + Vertices are included in the returned list.

- reachable_neighbours(Vertices, Digraph) -> Vertices + Return the neighbours reachable from some vertices of a digraph. - - Digraph = digraph() - Vertices = [vertex()] -

Returns an unsorted list of digraph vertices such that for each vertex in the list, there is - a path in Digraph of length - one or more from some vertex of Vertices to the + a path in Digraph of length + one or more from some vertex of Vertices to the vertex. As a consequence, only those vertices - of Vertices that are included in + of Vertices that are included in some cycle are returned.

- reaching(Vertices, Digraph) -> Vertices + Return the vertices that reach some vertices of a digraph. - - Digraph = digraph() - Vertices = [vertex()] -

Returns an unsorted list of digraph vertices such that for each vertex in the list, there is a path from the vertex to some - vertex of Vertices. In particular, since paths may have - length zero, the vertices of Vertices are included in + vertex of Vertices. In particular, since paths may have + length zero, the vertices of Vertices are included in the returned list.

- reaching_neighbours(Vertices, Digraph) -> Vertices + Return the neighbours that reach some vertices of a digraph. - - Digraph = digraph() - Vertices = [vertex()] -

Returns an unsorted list of digraph vertices such that for each vertex in the list, there is a path of length one or more - from the vertex to some vertex of Vertices. As a consequence, - only those vertices of Vertices that are included in + from the vertex to some vertex of Vertices. As a consequence, + only those vertices of Vertices that are included in some cycle are returned.

- strong_components(Digraph) -> [StrongComponent] + Return the strong components of a digraph. - - Digraph = digraph() - StrongComponent = [vertex()] -

Returns a list of strongly connected components. Each strongly component is represented by its vertices. The order of the vertices and the order of the components are arbitrary. Each vertex of the digraph - Digraph occurs in exactly one strong component. + Digraph occurs in exactly one strong component.

- subgraph(Digraph, Vertices [, Options]) -> Subgraph + + Return a subgraph of a digraph. - - Digraph = Subgraph = digraph() - Options = [{type, SubgraphType}, {keep_labels, bool()}] - SubgraphType = inherit | type() - Vertices = [vertex()] -

Creates a maximal subgraph of Digraph having - as vertices those vertices of Digraph that are - mentioned in Vertices. + as vertices those vertices of Digraph that are + mentioned in Vertices.

If the value of the option type is inherit, - which is the default, then the type of Digraph is used + which is the default, then the type of Digraph is used for the subgraph as well. Otherwise the option value of type is used as argument to digraph:new/1.

If the value of the option keep_labels is true, which is the default, then the labels of vertices and edges - of Digraph are used for the subgraph as well. If the value + of Digraph are used for the subgraph as well. If the value is false, then the default label, [], is used for the subgraph's vertices and edges.

-

subgraph(Digraph, Vertices) is equivalent to - subgraph(Digraph, Vertices, []). +

subgraph(Digraph, Vertices) is equivalent to + subgraph(Digraph, Vertices, []).

There will be a badarg exception if any of the arguments are invalid. @@ -401,16 +345,12 @@ - topsort(Digraph) -> Vertices | false + Return a topological sorting of the vertices of a digraph. - - Digraph = digraph() - Vertices = [vertex()] -

Returns a topological ordering of the vertices of the digraph - Digraph if such an ordering exists, false + Digraph if such an ordering exists, false otherwise. For each vertex in the returned list, there are no out-neighbours that occur earlier in the list.

diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml index e6b48b270a..488499581f 100644 --- a/lib/stdlib/doc/src/epp.xml +++ b/lib/stdlib/doc/src/epp.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -38,65 +38,61 @@ by compile to preprocess macros and include files before the actual parsing takes place.

+ + + + + + +

Handle to the epp server.

+
+
- open(FileName, IncludePath) -> {ok,Epp} | {error, ErrorDescriptor} - open(FileName, IncludePath, PredefMacros) -> {ok,Epp} | {error, ErrorDescriptor} + + Open a file for preprocessing - - FileName = atom() | string() - IncludePath = [DirectoryName] - DirectoryName = atom() | string() - PredefMacros = [{atom(),term()}] - Epp = pid() -- handle to the epp server - ErrorDescriptor = term() -

Opens a file for preprocessing.

- close(Epp) -> ok + Close the preprocessing of the file associated with Epp - - Epp = pid() -- handle to the epp server -

Closes the preprocessing of a file.

- parse_erl_form(Epp) -> {ok, AbsForm} | {eof, Line} | {error, ErrorInfo} + Return the next Erlang form from the opened Erlang source file - - Epp = pid() - AbsForm = term() - Line = integer() - ErrorInfo = see separate description below. -

Returns the next Erlang form from the opened Erlang source file. - The tuple {eof, Line} is returned at end-of-file. The first + The tuple {eof, Line} is returned at end-of-file. The first form corresponds to an implicit attribute -file(File,1)., where File is the name of the file.

- parse_file(FileName,IncludePath,PredefMacro) -> {ok,[Form]} | {error,OpenError} - Preprocesse and parse an Erlang source file - - FileName = atom() | string() - IncludePath = [DirectoryName] - DirectoryName = atom() | string() - PredefMacros = [{atom(),term()}] - Form = term() -- same as returned by erl_parse:parse_form - + + Preprocess and parse an Erlang source file

Preprocesses and parses an Erlang source file. - Note that the tuple {eof, Line} returned at end-of-file is + Note that the tuple {eof, Line} returned at end-of-file is included as a "form".

+ + + Format an error descriptor + +

Takes an ErrorDescriptor and returns + a string which + describes the error or warning. This function is usually + called implicitly when processing an ErrorInfo + structure (see below).

+
+
diff --git a/lib/stdlib/doc/src/erl_eval.xml b/lib/stdlib/doc/src/erl_eval.xml index 62af23c5eb..c95494bf25 100644 --- a/lib/stdlib/doc/src/erl_eval.xml +++ b/lib/stdlib/doc/src/erl_eval.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -36,63 +36,108 @@

This module provides an interpreter for Erlang expressions. The expressions are in the abstract syntax as returned by - erl_parse, the Erlang parser, or a call to - io:parse_erl_exprs/2.

+ erl_parse, + the Erlang parser, or + io.

+ + + + + + + A binding structure. + + + + + + +

As returned by + erl_parse:parse_exprs/1 or + + io:parse_erl_exprs/2.

+
+ + + + + + + + + + + + + + +

Further described + below.

+
+
+ + + + + + + + +

Further described + below.

+
+
+ + + +
- exprs(Expressions, Bindings) -> {value, Value, NewBindings} - exprs(Expressions, Bindings, LocalFunctionHandler) -> {value, Value, NewBindings} - exprs(Expressions, Bindings, LocalFunctionHandler, NonlocalFunctionHandler) -> {value, Value, NewBindings} + + + Evaluate expressions - - Expressions = as returned by erl_parse or io:parse_erl_exprs/2 - Bindings = as returned by bindings/1 - LocalFunctionHandler = {value, Func} | {eval, Func} | none - NonlocalFunctionHandler = {value, Func} | none - -

Evaluates Expressions with the set of bindings - Bindings, where Expressions is a sequence of +

Evaluates Expressions with the set of bindings + Bindings, where Expressions + is a sequence of expressions (in abstract syntax) of a type which may be - returned by io:parse_erl_exprs/2. See below for an + returned by + io:parse_erl_exprs/2. See below for an explanation of how and when to use the arguments - LocalFunctionHandler and NonlocalFunctionHandler. + LocalFunctionHandler and + NonLocalFunctionHandler.

-

Returns {value, Value, NewBindings}

+

Returns {value, Value, NewBindings} +

- expr(Expression, Bindings) -> { value, Value, NewBindings } - expr(Expression, Bindings, LocalFunctionHandler) -> { value, Value, NewBindings } - expr(Expression, Bindings, LocalFunctionHandler, NonlocalFunctionHandler) -> { value, Value, NewBindings } - expr(Expression, Bindings, LocalFunctionHandler, NonlocalFunctionHandler, ReturnFormat) -> { value, Value, NewBindings } | Value + + + + Evaluate expression - - Expression = as returned by io:parse_erl_form/2, for example - Bindings = as returned by bindings/1 - LocalFunctionHandler = {value, Func} | {eval, Func} | none - NonlocalFunctionHandler = {value, Func} | none - ReturnFormat = value | none - -

Evaluates Expression with the set of bindings - Bindings. Expression is an expression (in - abstract syntax) of a type which may be returned by - io:parse_erl_form/2. See below for an explanation of +

Evaluates Expression with the set of bindings + Bindings. Expression + is an expression in + abstract syntax. See below for an explanation of how and when to use the arguments - LocalFunctionHandler and - NonlocalFunctionHandler. + LocalFunctionHandler and + NonLocalFunctionHandler.

-

Returns {value, Value, NewBindings} by default. But - if the ReturnFormat is value only the Value - is returned.

+

Returns {value, Value, + NewBindings} by default. But if the + ReturnFormat is value only + the Value is returned.

- expr_list(ExpressionList, Bindings) -> {ValueList, NewBindings} - expr_list(ExpressionList, Bindings, LocalFunctionHandler) -> {ValueList, NewBindings} - expr_list(ExpressionList, Bindings, LocalFunctionHandler, NonlocalFunctionHandler) -> {ValueList, NewBindings} + + + Evaluate a list of expressions

Evaluates a list of expressions in parallel, using the same @@ -100,18 +145,19 @@ merge the bindings returned from each evaluation. This function is useful in the LocalFunctionHandler. See below.

-

Returns {ValueList, NewBindings}.

+

Returns {ValueList, NewBindings}. +

- new_bindings() -> BindingStruct + Return a bindings structure

Returns an empty binding structure.

- bindings(BindingStruct) -> Bindings + Return bindings

Returns the list of bindings contained in the binding @@ -119,25 +165,28 @@ - binding(Name, BindingStruct) -> Binding + Return bindings -

Returns the binding of Name in BindingStruct.

+

Returns the binding of Name + in BindingStruct.

- add_binding(Name, Value, Bindings) -> BindingStruct + Add a binding -

Adds the binding Name = Value to Bindings. +

Adds the binding Name = Value + to BindingStruct. Returns an updated binding structure.

- del_binding(Name, Bindings) -> BindingStruct + Delete a binding -

Removes the binding of Name in Bindings. +

Removes the binding of Name + in BindingStruct. Returns an updated binding structure.

@@ -145,7 +194,8 @@
Local Function Handler -

During evaluation of a function, no calls can be made to local +

+ During evaluation of a function, no calls can be made to local functions. An undefined function error would be generated. However, the optional argument LocalFunctionHandler may be used to define a function @@ -191,7 +241,8 @@ Func(Name, Arguments, Bindings)

Non-local Function Handler -

The optional argument NonlocalFunctionHandler may be +

+ The optional argument NonlocalFunctionHandler may be used to define a function which is called in the following cases: a functional object (fun) is called; a built-in function is called; a function is called using the M:F syntax, where M diff --git a/lib/stdlib/doc/src/erl_expand_records.xml b/lib/stdlib/doc/src/erl_expand_records.xml index c93248493f..8ead438b31 100644 --- a/lib/stdlib/doc/src/erl_expand_records.xml +++ b/lib/stdlib/doc/src/erl_expand_records.xml @@ -39,12 +39,8 @@ - module(AbsForms, CompileOptions) -> AbsForms + Expand all records in a module - - AbsForms = [term()] - CompileOptions = [term()] -

Expands all records in a module. The returned module has no references to records, neither attributes nor code.

diff --git a/lib/stdlib/doc/src/erl_id_trans.xml b/lib/stdlib/doc/src/erl_id_trans.xml index cfb18ec131..18cc2460f9 100644 --- a/lib/stdlib/doc/src/erl_id_trans.xml +++ b/lib/stdlib/doc/src/erl_id_trans.xml @@ -5,7 +5,7 @@
1996 - 2010 + 2011 Ericsson AB, All Rights Reserved @@ -48,8 +48,8 @@ parse_transform(Forms, Options) -> Forms Transform Erlang forms - Forms = [erlang_form()] - Options = [compiler_options()] + Forms = [erl_parse:abstract_form()] + Options = [compile:option()]

Performs an identity transformation on Erlang forms, as an example.

diff --git a/lib/stdlib/doc/src/erl_internal.xml b/lib/stdlib/doc/src/erl_internal.xml index 732d77c3ae..b8d5ad73b3 100644 --- a/lib/stdlib/doc/src/erl_internal.xml +++ b/lib/stdlib/doc/src/erl_internal.xml @@ -42,112 +42,75 @@ - bif(Name, Arity) -> bool() + Test for an Erlang BIF - - Name = atom() - Arity = integer() - -

Returns true if Name/Arity is an Erlang BIF +

Returns true if Name/Arity is an Erlang BIF which is automatically recognized by the compiler, otherwise false.

- guard_bif(Name, Arity) -> bool() + Test for an Erlang BIF allowed in guards - - Name = atom() - Arity = integer() - -

Returns true if Name/Arity is an Erlang BIF +

Returns true if Name/Arity is an Erlang BIF which is allowed in guards, otherwise false.

- type_test(Name, Arity) -> bool() + Test for a valid type test - - Name = atom() - Arity = integer() - -

Returns true if Name/Arity is a valid Erlang +

Returns true if Name/Arity is a valid Erlang type test, otherwise false.

- arith_op(OpName, Arity) -> bool() + Test for an arithmetic operator - - OpName = atom() - Arity = integer() - -

Returns true if OpName/Arity is an arithmetic +

Returns true if OpName/Arity is an arithmetic operator, otherwise false.

- bool_op(OpName, Arity) -> bool() + Test for a Boolean operator - - OpName = atom() - Arity = integer() - -

Returns true if OpName/Arity is a Boolean +

Returns true if OpName/Arity is a Boolean operator, otherwise false.

- comp_op(OpName, Arity) -> bool() + Test for a comparison operator - - OpName = atom() - Arity = integer() - -

Returns true if OpName/Arity is a comparison +

Returns true if OpName/Arity is a comparison operator, otherwise false.

- list_op(OpName, Arity) -> bool() + Test for a list operator - - OpName = atom() - Arity = integer() - -

Returns true if OpName/Arity is a list +

Returns true if OpName/Arity is a list operator, otherwise false.

- send_op(OpName, Arity) -> bool() + Test for a send operator - - OpName = atom() - Arity = integer() - -

Returns true if OpName/Arity is a send +

Returns true if OpName/Arity is a send operator, otherwise false.

- op_type(OpName, Arity) -> Type + Return operator type - - OpName = atom() - Arity = integer() - Type = arith | bool | comp | list | send - -

Returns the Type of operator that OpName/Arity +

Returns the Type of operator that OpName/Arity belongs to, or generates a function_clause error if it is not an operator at all.

diff --git a/lib/stdlib/doc/src/erl_lint.xml b/lib/stdlib/doc/src/erl_lint.xml index 8639d678fa..b7fbdd8799 100644 --- a/lib/stdlib/doc/src/erl_lint.xml +++ b/lib/stdlib/doc/src/erl_lint.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -60,29 +60,30 @@ functions separately unless you have written your own Erlang compiler.

+ + + + + + + + - module(AbsForms) -> {ok,Warnings} | {error,Errors,Warnings} - module(AbsForms, FileName) -> {ok,Warnings} | {error,Errors,Warnings} - module(AbsForms, FileName, CompileOptions) -> {ok,Warnings} | {error,Errors,Warnings} + + + Check a module for errors - - AbsForms = [term()] - FileName = FileName2 = atom() | string() - Warnings = Errors = [{Filename2,[ErrorInfo]}] - ErrorInfo = see separate description below. - CompileOptions = [term()] -

This function checks all the forms in a module for errors. It returns:

- {ok,Warnings} + {ok,Warnings}

There were no errors in the module.

- {error,Errors,Warnings} + {error,Errors,Warnings}

There were errors in the module.

@@ -93,14 +94,14 @@ elements of Options that control the warnings are only described in compile(3).

-

The AbsForms of a module which comes from a file +

The AbsForms of a module which comes from a file that is read through epp, the Erlang pre-processor, can come from many files. This means that any references to errors must include the file name (see epp(3), or parser erl_parse(3)). The warnings and errors returned have the following format:

- [{FileName2,[ErrorInfo]}] + [{FileName2,[ErrorInfo]}]

The errors and warnings are listed in the order in which they are encountered in the forms. This means that the errors from one file may be split into different entries in @@ -108,27 +109,20 @@ - is_guard_test(Expr) -> bool() + Test for a guard test - - Expr = term() - -

This function tests if Expr is a legal guard test. - Expr is an Erlang term representing the abstract form +

This function tests if Expr is a legal guard test. + Expr is an Erlang term representing the abstract form for the expression. erl_parse:parse_exprs(Tokens) can - be used to generate a list of Expr.

+ be used to generate a list of Expr.

- format_error(ErrorDescriptor) -> Chars + Format an error descriptor - - ErrorDescriptor = errordesc() - Chars = [char() | Chars] - -

Takes an ErrorDescriptor and returns a string which +

Takes an ErrorDescriptor and returns a string which describes the error or warning. This function is usually called implicitly when processing an ErrorInfo structure (see below).

diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml index 18b592deea..bafc2e0746 100644 --- a/lib/stdlib/doc/src/erl_parse.xml +++ b/lib/stdlib/doc/src/erl_parse.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -36,31 +36,51 @@

This module is the basic Erlang parser which converts tokens into the abstract form of either forms (i.e., top-level constructs), - expressions, or terms. The Abstract Format is described in the ERTS - User's Guide. + expressions, or terms. The Abstract Format is described in the + ERTS User's Guide. Note that a token list must end with the dot token in order to be acceptable to the parse functions (see erl_scan(3)).

+ + + +

Parse tree for Erlang clause.

+
+
+ + +

Parse tree for Erlang expression.

+
+
+ + +

Parse tree for Erlang form.

+
+
+ + + + + + + + + +
- parse_form(Tokens) -> {ok, AbsForm} | {error, ErrorInfo} + Parse an Erlang form - - Tokens = [Token] - Token = {Tag,Line} | {Tag,Line,term()} - Tag = atom() - AbsForm = term() - ErrorInfo = see section Error Information below. - -

This function parses Tokens as if it were a form. It returns:

+

This function parses Tokens as if it were + a form. It returns:

- {ok, AbsForm} + {ok, AbsForm} -

The parsing was successful. AbsForm is the +

The parsing was successful. AbsForm is the abstract form of the parsed form.

- {error, ErrorInfo} + {error, ErrorInfo}

An error occurred.

@@ -68,25 +88,18 @@
- parse_exprs(Tokens) -> {ok, Expr_list} | {error, ErrorInfo} + Parse Erlang expressions - - Tokens = [Token] - Token = {Tag,Line} | {Tag,Line,term()} - Tag = atom() - Expr_list = [AbsExpr] - AbsExpr = term() - ErrorInfo = see section Error Information below. - -

This function parses Tokens as if it were a list of expressions. It returns:

+

This function parses Tokens as if it were + a list of expressions. It returns:

- {ok, Expr_list} + {ok, ExprList} -

The parsing was successful. Expr_list is a +

The parsing was successful. ExprList is a list of the abstract forms of the parsed expressions.

- {error, ErrorInfo} + {error, ErrorInfo}

An error occurred.

@@ -94,21 +107,15 @@
- parse_term(Tokens) -> {ok, Term} | {error, ErrorInfo} + Parse an Erlang term - - Tokens = [Token] - Token = {Tag,Line} | {Tag,Line,term()} - Tag = atom() - Term = term() - ErrorInfo = see section Error Information below. - -

This function parses Tokens as if it were a term. It returns:

+

This function parses Tokens as if it were + a term. It returns:

- {ok, Term} + {ok, Term} -

The parsing was successful. Term is +

The parsing was successful. Term is the Erlang term corresponding to the token list.

{error, ErrorInfo} @@ -122,7 +129,8 @@ format_error(ErrorDescriptor) -> Chars Format an error descriptor - ErrorDescriptor = errordesc() + ErrorDescriptor = error_description() Chars = [char() | Chars] @@ -133,44 +141,32 @@
- tokens(AbsTerm) -> Tokens - tokens(AbsTerm, MoreTokens) -> Tokens + + Generate a list of tokens for an expression - - Tokens = MoreTokens = [Token] - Token = {Tag,Line} | {Tag,Line,term()} - Tag = atom() - AbsTerm = term() - ErrorInfo = see section Error Information below. -

This function generates a list of tokens representing the abstract - form AbsTerm of an expression. Optionally, it appends - Moretokens.

+ form AbsTerm of an expression. Optionally, it + appends MoreTokens.

- normalise(AbsTerm) -> Data + Convert abstract form to an Erlang term - - AbsTerm = Data = term() - -

Converts the abstract form AbsTerm of a term into a +

Converts the abstract form AbsTerm of a + term into a conventional Erlang data structure (i.e., the term itself). This is the inverse of abstract/1.

- abstract(Data) -> AbsTerm + Convert an Erlang term into an abstract form - - Data = AbsTerm = term() - -

Converts the Erlang data structure Data into an - abstract form of type AbsTerm. This is the inverse of - normalise/1.

+

Converts the Erlang data structure Data into an + abstract form of type AbsTerm. + This is the inverse of normalise/1.

diff --git a/lib/stdlib/doc/src/erl_pp.xml b/lib/stdlib/doc/src/erl_pp.xml index 1fdda48893..57b5828bcd 100644 --- a/lib/stdlib/doc/src/erl_pp.xml +++ b/lib/stdlib/doc/src/erl_pp.xml @@ -43,125 +43,88 @@

All functions can have an optional argument which specifies a hook that is called if an attempt is made to print an unknown form.

+ + + + +

The optional argument + HookFunction, shown in the functions described below, + defines a function which is called when an unknown form occurs where there + should be a valid expression.

+ +

If HookFunction is equal to none there is no hook + function.

+ +

The called hook function should return a (possibly deep) list + of characters. expr/4 + is useful in a hook. +

+

If CurrentIndentation is negative, there will be no line + breaks and only a space is used as a separator.

+
+
+
- form(Form) -> DeepCharList - form(Form, HookFunction) -> DeepCharList + + Pretty print a form - - Form = term() - HookFunction = see separate description below. - DeepCharList = [char()|DeepCharList] -

Pretty prints a - Form which is an abstract form of a type which is - returned by erl_parse:parse_form.

+ Form which is an abstract form of a type which is + returned by + erl_parse:parse_form/1.

- attribute(Attribute) -> DeepCharList - attribute(Attribute, HookFunction) -> DeepCharList + + Pretty print an attribute - - Attribute = term() - HookFunction = see separate description below. - DeepCharList = [char()|DeepCharList] -

The same as form, but only for the attribute - Attribute.

+ Attribute.

- function(Function) -> DeepCharList - function(Function, HookFunction) -> DeepCharList + + Pretty print a function - - Function = term() - HookFunction = see separate description below. - DeepCharList = [char()|DeepCharList] -

The same as form, but only for the function - Function.

+ Function.

- guard(Guard) -> DeepCharList - guard(Guard, HookFunction) -> DeepCharList + + Pretty print a guard - - Form = term() - HookFunction = see separate description below. - DeepCharList = [char()|DeepCharList] -

The same as form, but only for the guard test - Guard.

+ Guard.

- exprs(Expressions) -> DeepCharList - exprs(Expressions, HookFunction) -> DeepCharList - exprs(Expressions, Indent, HookFunction) -> DeepCharList + + + Pretty print Expressions - - Expressions = term() - HookFunction = see separate description below. - Indent = integer() - DeepCharList = [char()|DeepCharList] -

The same as form, but only for the sequence of - expressions in Expressions.

+ expressions in Expressions.

- expr(Expression) -> DeepCharList - expr(Expression, HookFunction) -> DeepCharList - expr(Expression, Indent, HookFunction) -> DeepCharList - expr(Expression, Indent, Precedence, HookFunction) ->-> DeepCharList + + + + Pretty print one Expression - - Expression = term() - HookFunction = see separate description below. - Indent = integer() - Precedence = - DeepCharList = [char()|DeepCharList] -

This function prints one expression. It is useful for implementing hooks (see below).

-
- Unknown Expression Hooks -

The optional argument HookFunction, shown in the functions described above, defines a function which is called when an unknown form occurs where there - should be a valid expression. It can have the following formats:

- - Function - -

The hook function is called by:

- -Function(Expr, - CurrentIndentation, - CurrentPrecedence, - HookFunction) -
- none - -

There is no hook function

-
-
-

The called hook function should return a (possibly deep) list - of characters. expr/4 is useful in a hook. -

-

If CurrentIndentation is negative, there will be no line - breaks and only a space is used as a separator.

-
-
Bugs

It should be possible to have hook functions for unknown forms diff --git a/lib/stdlib/doc/src/erl_scan.xml b/lib/stdlib/doc/src/erl_scan.xml index 1199c34f0f..54240dea19 100644 --- a/lib/stdlib/doc/src/erl_scan.xml +++ b/lib/stdlib/doc/src/erl_scan.xml @@ -4,7 +4,7 @@

- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -37,56 +37,96 @@

This module contains functions for tokenizing characters into Erlang tokens.

-
- DATA TYPES - -category() = atom() -column() = integer() > 0 -line() = integer() -location() = line() | {line(), column()} -reserved_word_fun() -> fun(atom()) -> bool() -set_attribute_fun() -> fun(term()) -> term() -symbol() = atom() | float() | integer() | string() -token() = {category(), attributes()} | {category(), attributes(), symbol()} -attributes() = line() | list() | tuple() -
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - string(String) -> Return - string(String, StartLocation) -> Return - string(String, StartLocation, Options) -> Return + + + Scan a string and return the Erlang tokens - - String = string() - Return = {ok, Tokens, EndLocation} | Error - Tokens = [token()] - Error = {error, ErrorInfo, EndLocation} - StartLocation = EndLocation = location() - Options = Option | [Option] - Option = {reserved_word_fun,reserved_word_fun()} - | return_comments | return_white_spaces | return - | text - -

Takes the list of characters String and tries to - scan (tokenize) them. Returns {ok, Tokens, EndLocation}, - where Tokens are the Erlang tokens from - String. EndLocation is the first location - after the last token.

-

{error, ErrorInfo, EndLocation} is returned if an - error occurs. EndLocation is the first location after +

Takes the list of characters String and tries to + scan (tokenize) them. Returns {ok, Tokens, + EndLocation}, + where Tokens are the Erlang tokens from + String. EndLocation + is the first location after the last token.

+

{error, ErrorInfo, ErrorLocation} + is returned if an error occurs. + ErrorLocation is the first location after the erroneous token.

-

string(String) is equivalent to - string(String, 1), and string(String, - StartLocation) is equivalent to string(String, - StartLocation, []).

-

StartLocation indicates the initial location when - scanning starts. If StartLocation is a line - attributes() as well as EndLocation and - ErrorLocation will be lines. If - StartLocation is a pair of a line and a column +

string(String) is equivalent to + string(String, 1), and + string(String, + StartLocation) is equivalent to + string(String, + StartLocation, []).

+

StartLocation indicates the initial location + when scanning starts. If StartLocation is a line + attributes() as well as EndLocation and + ErrorLocation will be lines. If + StartLocation is a pair of a line and a column attributes() takes the form of an opaque compound - data type, and EndLocation and ErrorLocation + data type, and EndLocation and + ErrorLocation will be pairs of a line and a column. The token attributes contain information about the column and the line where the token begins, as well as the text of the @@ -134,148 +174,130 @@ attributes() = line() | list() | tuple() - tokens(Continuation, CharSpec, StartLocation) -> Return - tokens(Continuation, CharSpec, StartLocation, Options) -> Return + + + + + An opaque continuation Re-entrant scanner - - Continuation = [] | Continuation1 - Return = {done, Result, LeftOverChars} | {more, Continuation1} - LeftOverChars = CharSpec - CharSpec = string() | eof - Continuation1 = tuple() - Result = {ok, Tokens, EndLocation} | {eof, EndLocation} | Error - Tokens = [token()] - Error = {error, ErrorInfo, EndLocation} - StartLocation = EndLocation = location() - Options = Option | [Option] - Option = {reserved_word_fun,reserved_word_fun()} - | return_comments | return_white_spaces | return - | text -

This is the re-entrant scanner which scans characters until a dot ('.' followed by a white space) or eof has been reached. It returns:

- {done, Result, LeftOverChars} + {done, Result, LeftOverChars} +

This return indicates that there is sufficient input - data to get a result. Result is:

+ data to get a result. Result is:

- {ok, Tokens, EndLocation} + {ok, Tokens, EndLocation} + -

The scanning was successful. Tokens is the - list of tokens including dot.

+

The scanning was successful. Tokens + is the list of tokens including dot.

{eof, EndLocation}

End of file was encountered before any more tokens.

- {error, ErrorInfo, EndLocation} + {error, ErrorInfo, EndLocation} + -

An error occurred. LeftOverChars is the remaining - characters of the input data, +

An error occurred. LeftOverChars + is the remaining characters of the input data, starting from EndLocation.

- {more, Continuation1} + {more, Continuation1}

More data is required for building a term. - Continuation1 must be passed in a new call to + Continuation1 must be passed in a new call to tokens/3,4 when more data is available.

-

The CharSpec eof signals end of file. - LeftOverChars will then take the value eof as - well.

-

tokens(Continuation, CharSpec, StartLocation) is - equivalent to tokens(Continuation, CharSpec, - StartLocation, []).

+

The CharSpec eof signals end of file. + LeftOverChars will then take the value eof + as well.

+

tokens(Continuation, CharSpec, + StartLocation) is equivalent to + tokens(Continuation, CharSpec, + StartLocation, []).

See string/3 for a description of the various options.

- reserved_word(Atom) -> bool() + Test for a reserved word - - Atom = atom() - -

Returns true if Atom is an Erlang reserved - word, otherwise false.

+

Returns true if Atom is an Erlang + reserved word, otherwise false.

- token_info(Token) -> TokenInfo + Return information about a token - - Token = token() - TokenInfo = [TokenInfoTuple] - TokenInfoTuple = {TokenItem, Info} - TokenItem = atom() - Info = term() -

Returns a list containing information about the token - Token. The order of the TokenInfoTuples is not - defined. The following TokenItems are returned: - category, column, length, - line, symbol, and text. See Token. The order of the + TokenInfoTuples is not + defined. See token_info/2 for information about specific - TokenInfoTuples.

+ TokenInfoTuples.

Note that if token_info(Token, TokenItem) returns - undefined for some TokenItem in the list above, the - item is not included in TokenInfo.

+ undefined for some TokenItem, the + item is not included in TokenInfo.

- token_info(Token, TokenItemSpec) -> TokenInfo + + + + Return information about a token - - Token = token() - TokenItemSpec = TokenItem | [TokenItem] - TokenInfo = TokenInfoTuple | undefined | [TokenInfoTuple] - TokenInfoTuple = {TokenItem, Info} - TokenItem = atom() - Info = term() -

Returns a list containing information about the token - Token. If TokenItemSpec is a single - TokenItem, the returned value is the corresponding + Token. If one single + TokenItem is given the returned value is + the corresponding TokenInfoTuple, or undefined if the - TokenItem has no value. If TokenItemSpec is a - list of - TokenItem, the result is a list of - TokenInfoTuple. The TokenInfoTuples will - appear with the corresponding - TokenItems in the same order as the TokenItems - appeared in the list of TokenItems. TokenItems - with no value are not included in the list of - TokenInfoTuple.

-

The following TokenInfoTuples with corresponding - TokenItems are valid:

+ TokenItem has no value. If a list of + TokenItems is given the result is a list of + TokenInfoTuple. The + TokenInfoTuples will + appear with the corresponding TokenItems in + the same order as the TokenItems + appear in the list of TokenItems. + TokenItems with no value are not included + in the list of TokenInfoTuple.

+

The following TokenInfoTuples with corresponding + TokenItems are valid:

- {category, category()} + {category, + category()}

The category of the token.

- {column, column()} + {column, + column()}

The column where the token begins.

{length, integer() > 0}

The length of the token's text.

- {line, line()} + {line, + line()}

The line where the token begins.

- {location, location()} + {location, + location()}

The line and column where the token begins, or just the line if the column unknown.

- {symbol, symbol()} + {symbol, + symbol()}

The token's symbol.

{text, string()} @@ -285,70 +307,59 @@ attributes() = line() | list() | tuple()
- attributes_info(Attributes) -> AttributesInfo + Return information about token attributes - - Attributes = attributes() - AttributesInfo = [AttributeInfoTuple] - AttributeInfoTuple = {AttributeItem, Info} - AttributeItem = atom() - Info = term() -

Returns a list containing information about the token - attributes Attributes. The order of the - AttributeInfoTuples is not defined. The following - AttributeItems are returned: - column, length, line, and text. + attributes Attributes. The order of the + AttributeInfoTuples is not defined. See attributes_info/2 for information about specific - AttributeInfoTuples.

+ AttributeInfoTuples.

Note that if attributes_info(Token, AttributeItem) returns undefined for some AttributeItem in the list above, the item is not included in - AttributesInfo.

+ AttributesInfo.

- attributes_info(Attributes, AttributeItemSpec) -> AttributesInfo + + Return information about a token attributes - - Attributes = attributes() - AttributeItemSpec = AttributeItem | [AttributeItem] - AttributesInfo = AttributeInfoTuple | undefined - | [AttributeInfoTuple] - AttributeInfoTuple = {AttributeItem, Info} - AttributeItem = atom() - Info = term() - +

Returns a list containing information about the token - attributes Attributes. If AttributeItemSpec is - a single AttributeItem, the returned value is the - corresponding AttributeInfoTuple, or undefined - if the AttributeItem has no value. If - AttributeItemSpec is a list of - AttributeItem, the result is a list of - AttributeInfoTuple. The AttributeInfoTuples - will appear with the corresponding AttributeItems in - the same order as the AttributeItems appeared in the - list of AttributeItems. AttributeItems with no + attributes Attributes. If one single + AttributeItem is given the returned value is the + corresponding AttributeInfoTuple, + or undefined if the AttributeItem + has no value. If a list of AttributeItem + is given the result is a list of + AttributeInfoTuple. + The AttributeInfoTuples + will appear with the corresponding AttributeItems + in the same order as the AttributeItems + appear in the list of AttributeItems. + AttributeItems with no value are not included in the list of - AttributeInfoTuple.

-

The following AttributeInfoTuples with corresponding - AttributeItems are valid:

+ AttributeInfoTuple.

+

The following AttributeInfoTuples with + corresponding AttributeItems are valid:

- {column, column()} + {column, + column()}

The column where the token begins.

{length, integer() > 0}

The length of the token's text.

- {line, line()} + {line, + line()}

The line where the token begins.

- {location, location()} + {location, + location()}

The line and column where the token begins, or just the line if the column unknown.

@@ -359,29 +370,22 @@ attributes() = line() | list() | tuple()
- set_attribute(AttributeItem, Attributes, SetAttributeFun) -> AttributesInfo + Set a token attribute value - - AttributeItem = line - Attributes = attributes() - SetAttributeFun = set_attribute_fun() -

Sets the value of the line attribute of the token - attributes Attributes.

-

The SetAttributeFun is called with the value of + attributes Attributes.

+

The SetAttributeFun is called with the value of the line attribute, and is to return the new value of the line attribute.

- format_error(ErrorDescriptor) -> string() + Format an error descriptor - - ErrorDescriptor = errordesc() - -

Takes an ErrorDescriptor and returns a string which +

Takes an ErrorDescriptor and returns + a string which describes the error or warning. This function is usually called implicitly when processing an ErrorInfo structure (see below).

diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 746f94d3f4..8c952708c5 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -126,15 +126,30 @@ ERTS User's Guide.

-
- DATA TYPES - -match_spec() - a match specification, see above - -tid() - a table identifier, as returned by new/2 -
+ + + continuation() + +

Opaque continuation used by + select/1 and + select/3.

+
+
+ + +

A match specification, see above.

+
+ + + + + + + + +

A table identifier, as returned by new/2.

+
+
all() -> [Tab] @@ -197,37 +212,25 @@ tid() - file2tab(Filename) -> {ok,Tab} | {error,Reason} + Read an ETS table from a file. - - Filename = string() | atom() - Tab = tid() | atom() - Reason = term() -

Reads a file produced by tab2file/2 or tab2file/3 and creates the - corresponding table Tab.

-

Equivalent to file2tab(Filename,[]).

+ corresponding table Tab.

+

Equivalent to file2tab(Filename, []).

- file2tab(Filename,Options) -> {ok,Tab} | {error,Reason} + Read an ETS table from a file. - - Filename = string() | atom() - Tab = tid() | atom() - Options = [Option] - Option = {verify, bool()} - Reason = term() -

Reads a file produced by tab2file/2 or tab2file/3 and creates the - corresponding table Tab.

-

The currently only supported option is {verify,bool()}. If + corresponding table Tab.

+

The currently only supported option is {verify,boolean()}. If verification is turned on (by means of specifying {verify,true}), the function utilizes whatever information is present in the file to assert that the @@ -271,70 +274,52 @@ tid() - foldl(Function, Acc0, Tab) -> Acc1 + Fold a function over an ETS table - - Function = fun(A, AccIn) -> AccOut - Tab = tid() | atom() - Acc0 = Acc1 = AccIn = AccOut = term() - -

Acc0 is returned if the table is empty. +

Acc0 is returned if the table is empty. This function is similar to lists:foldl/3. The order in which the elements of the table are traversed is unspecified, except for tables of type ordered_set, for which they are traversed first to last.

-

If Function inserts objects into the table, or another +

If Function inserts objects into the table, or another process inserts objects into the table, those objects may (depending on key ordering) be included in the traversal.

- foldr(Function, Acc0, Tab) -> Acc1 + Fold a function over an ETS table - - Function = fun(A, AccIn) -> AccOut - Tab = tid() | atom() - Acc0 = Acc1 = AccIn = AccOut = term() - -

Acc0 is returned if the table is empty. +

Acc0 is returned if the table is empty. This function is similar to lists:foldr/3. The order in which the elements of the table are traversed is unspecified, except for tables of type ordered_set, for which they are traversed last to first.

-

If Function inserts objects into the table, or another +

If Function inserts objects into the table, or another process inserts objects into the table, those objects may (depending on key ordering) be included in the traversal.

- from_dets(Tab, DetsTab) -> true + Fill an ETS table with objects from a Dets table. - - Tab = tid() | atom() - DetsTab = atom() -

Fills an already created ETS table with the objects in the - already opened Dets table named DetsTab. The existing + already opened Dets table named DetsTab. The existing objects of the ETS table are kept unless overwritten.

Throws a badarg error if any of the tables does not exist or the dets table is not open.

- fun2ms(LiteralFun) -> MatchSpec + Pseudo function that transforms fun syntax to a match_spec. - - LiteralFun -- see below - MatchSpec = match_spec() -

Pseudo function that by means of a parse_transform - translates LiteralFun typed as parameter in the + translates LiteralFun typed as parameter in the function call to a match_spec. With "literal" is meant that the fun needs to textually be written @@ -342,7 +327,7 @@ tid() variable which in turn is passed to the function).

The parse transform is implemented in the module ms_transform and the source must include the - file ms_transform.hrl in stdlib for this + file ms_transform.hrl in STDLIB for this pseudo function to work. Failing to include the hrl file in the source will result in a runtime error, not a compile time ditto. The include file is easiest included by adding @@ -422,20 +407,17 @@ Error: fun containing local Erlang function calls - i() -> ok + Display information about all ETS tables on tty.

Displays information about all ETS tables on tty.

- i(Tab) -> ok + Browse an ETS table on tty. - - Tab = tid() | atom() - -

Browses the table Tab on tty.

+

Browses the table Tab on tty.

@@ -454,7 +436,7 @@ Error: fun containing local Erlang function calls correct type, this function fails with reason badarg.

- Item=memory, Value=int()

+ Item=memory, Value=integer()

The number of words allocated to the table.
Item=owner, Value=pid()

@@ -466,7 +448,7 @@ Error: fun containing local Erlang function calls Item=name, Value=atom()

The name of the table.
- Item=size, Value=int()

+ Item=size, Value=integer()

The number of objects inserted in the table.
Item=node, Value=atom()

@@ -479,7 +461,7 @@ Error: fun containing local Erlang function calls Item=type, Value=set|ordered_set|bag|duplicate_bag

The table type.
- Item=keypos, Value=int()

+ Item=keypos, Value=integer()

The key position.
Item=protection, Value=public|protected|private

@@ -536,25 +518,19 @@ Error: fun containing local Erlang function calls
- init_table(Name, InitFun) -> true + Replace all objects of an ETS table. - - Name = atom() - InitFun = fun(Arg) -> Res - Arg = read | close - Res = end_of_input | {[object()], InitFun} | term() - -

Replaces the existing objects of the table Tab with - objects created by calling the input function InitFun, +

Replaces the existing objects of the table Tab with + objects created by calling the input function InitFun, see below. This function is provided for compatibility with the dets module, it is not more efficient than filling a table by using ets:insert/2.

When called with the argument read the function - InitFun is assumed to return end_of_input when - there is no more input, or {Objects, Fun}, where - Objects is a list of objects and Fun is a new + InitFun is assumed to return end_of_input when + there is no more input, or {Objects, Fun}, where + Objects is a list of objects and Fun is a new input function. Any other value Value is returned as an error {error, {init_fun, Value}}. Each input function will be called exactly once, and should an error occur, the last @@ -594,7 +570,7 @@ Error: fun containing local Erlang function calls - insert_new(Tab, ObjectOrObjects) -> bool() + insert_new(Tab, ObjectOrObjects) -> boolean() Insert an object into an ETS table if the key is not already present. Tab = tid() | atom() @@ -615,7 +591,7 @@ Error: fun containing local Erlang function calls - is_compiled_ms(Term) -> bool() + is_compiled_ms(Term) -> boolean() Checks if an Erlang term is the result of ets:match_spec_compile Term = term() @@ -708,7 +684,7 @@ ets:is_compiled_ms(Broken). Tab = tid() | atom() Key = term() - Pos = int() + Pos = integer() Elem = term() | [term()] @@ -802,15 +778,11 @@ ets:is_compiled_ms(Broken). - match_delete(Tab, Pattern) -> true + Delete all objects which match a given pattern from an ETS table. - - Tab = tid() | atom() - Pattern = tuple() - -

Deletes all objects which match the pattern Pattern - from the table Tab. See match/2 for a +

Deletes all objects which match the pattern Pattern + from the table Tab. See match/2 for a description of patterns.

@@ -957,8 +929,8 @@ ets:select(Table,MatchSpec),  Option = Type | Access | named_table | {keypos,Pos} | {heir,pid(),HeirData} | {heir,none} | Tweaks   Type = set | ordered_set | bag | duplicate_bag   Access = public | protected | private -   Tweaks = {write_concurrency,bool()} | {read_concurrency,bool()} | compressed -   Pos = int() +   Tweaks = {write_concurrency,boolean()} | {read_concurrency,boolean()} | compressed +   Pos = integer()   HeirData = term() @@ -1050,7 +1022,7 @@ ets:select(Table,MatchSpec), -

{write_concurrency,bool()} +

{write_concurrency,boolean()} Performance tuning. Default is false, in which case an operation that mutates (writes to) the table will obtain exclusive access, blocking any concurrent access of the same table until finished. @@ -1074,7 +1046,7 @@ ets:select(Table,MatchSpec), -

{read_concurrency,bool()} +

{read_concurrency,boolean()} Performance tuning. Default is false. When set to true, the table is optimized for concurrent read operations. When this option is enabled on a runtime system with @@ -1160,12 +1132,8 @@ ets:select(Table,MatchSpec), - repair_continuation(Continuation, MatchSpec) -> Continuation + Repair a continuation from ets:select/1 or ets:select/3 that has passed through external representation - - Continuation = term() - MatchSpec = match_spec() -

This function can be used to restore an opaque continuation returned by ets:select/3 or ets:select/1 if the @@ -1551,7 +1519,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> Return all objects in a given slot of an ETS table. Tab = tid() | atom() - I = int() + I = integer() Object = tuple() @@ -1572,32 +1540,19 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> - tab2file(Tab, Filename) -> ok | {error,Reason} + Dump an ETS table to a file. - - Tab = tid() | atom() - Filename = string() | atom() - Reason = term() - -

Dumps the table Tab to the file Filename.

-

Equivalent to tab2file(Tab, Filename,[])

+

Dumps the table Tab to the file Filename.

+

Equivalent to tab2file(Tab, Filename,[])

- tab2file(Tab, Filename, Options) -> ok | {error,Reason} + Dump an ETS table to a file. - - Tab = tid() | atom() - Filename = string() | atom() - Options = [Option] - Option = {extended_info, [ExtInfo]} - ExtInfo = object_count | md5sum - Reason = term() - -

Dumps the table Tab to the file Filename.

+

Dumps the table Tab to the file Filename.

When dumping the table, certain information about the table is dumped to a header at the beginning of the dump. This information contains data about the table type, @@ -1634,26 +1589,15 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> - tab2list(Tab) -> [Object] + Return a list of all objects in an ETS table. - - Tab = tid() | atom() - Object = tuple() - -

Returns a list of all objects in the table Tab.

+

Returns a list of all objects in the table Tab.

- tabfile_info(Filename) -> {ok, TableInfo} | {error, Reason} + Return a list of all objects in an ETS table. - - Filename = string() | atom() - TableInfo = [InfoItem] - InfoItem = {InfoTag, term()} - InfoTag = name | type | protection | named_table | keypos | size | extended_info | version - Reason = term() -

Returns information about the table dumped to file by tab2file/2 or @@ -1699,7 +1643,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> one or more of the atoms object_count and md5sum. version - A tuple {Major,Minor} containing the major and + A tuple {Major,Minor} containing the major and minor version of the file format for ets table dumps. This version field was added beginning with stdlib-1.5.1, files dumped with older versions will return {0,0} in this @@ -1712,20 +1656,11 @@ is_integer(X), is_integer(Y), X + Y < 4711]]> - table(Tab [, Options]) -> QueryHandle + + Return a QLC query handle. - - Tab = tid() | atom() - QueryHandle = - a query handle, see qlc(3) - - Options = [Option] | Option - Option = {n_objects, NObjects} | {traverse, TraverseMethod} - NObjects = default | integer() > 0 - TraverseMethod = first_next | last_prev | select | {select, MatchSpec} - MatchSpec = match_spec() - -

-Returns a QLC (Query List +

Returns a QLC (Query List Comprehension) query handle. The module qlc implements a query language aimed mainly at Mnesia but ETS tables, Dets tables, and lists are also recognized by QLC as sources of @@ -1760,7 +1695,7 @@ Returns a QLC (Query List that matches all objects.

-

{select, MatchSpec}. As for select +

{select, MatchSpec}. As for select the table is traversed by calling ets:select/3 and ets:select/1. The difference is that the match_spec is explicitly given. This is how to state @@ -1788,41 +1723,31 @@ true - test_ms(Tuple, MatchSpec) -> {ok, Result} | {error, Errors} + Test a match_spec for use in ets:select/2. - - Tuple = tuple() - MatchSpec = match_spec() - Result = term() - Errors = [{warning|error, string()}] -

This function is a utility to test a match_spec used in calls to ets:select/2. The function both tests - MatchSpec for "syntactic" correctness and runs the - match_spec against the object Tuple. If the match_spec - contains errors, the tuple {error, Errors} is returned - where Errors is a list of natural language + MatchSpec for "syntactic" correctness and runs the + match_spec against the object Tuple. If the match_spec + contains errors, the tuple {error, Errors} is returned + where Errors is a list of natural language descriptions of what was wrong with the match_spec. If the match_spec is syntactically OK, the function returns - {ok,Term} where Term is what would have been + {ok,Result} where Result is what would have been the result in a real ets:select/2 call or false - if the match_spec does not match the object Tuple.

+ if the match_spec does not match the object Tuple.

This is a useful debugging and test tool, especially when writing complicated ets:select/2 calls.

- to_dets(Tab, DetsTab) -> DetsTab + Fill a Dets table with objects from an ETS table. - - Tab = tid() | atom() - DetsTab = atom() -

Fills an already created/opened Dets table with the objects - in the already opened ETS table named Tab. The Dets + in the already opened ETS table named Tab. The Dets table is emptied before the objects are inserted.

@@ -1835,7 +1760,7 @@ true Tab = tid() | atom() Key = term() UpdateOp = {Pos,Incr} | {Pos,Incr,Threshold,SetValue} - Pos = Incr = Threshold = SetValue = Result = int() + Pos = Incr = Threshold = SetValue = Result = integer()

This function provides an efficient way to update one or more @@ -1897,7 +1822,7 @@ true Tab = tid() | atom() Key = Value = term() - Pos = int() + Pos = integer()

This function provides an efficient way to update one or more diff --git a/lib/stdlib/doc/src/file_sorter.xml b/lib/stdlib/doc/src/file_sorter.xml index ccb32659a0..a6b3633066 100644 --- a/lib/stdlib/doc/src/file_sorter.xml +++ b/lib/stdlib/doc/src/file_sorter.xml @@ -4,7 +4,7 @@

- 20012010 + 20012011 Ericsson AB. All Rights Reserved. @@ -89,7 +89,7 @@ considerably. The keysort, keymerge and keycheck functions do not accept ordering functions. - {unique, bool()}. When sorting or merging files, + {unique, boolean()}. When sorting or merging files, only the first of a sequence of terms that compare equal (==) is output if this option is set to true. The default value is false which implies that all terms that @@ -112,7 +112,7 @@ overwritten. Temporary files are deleted unless some uncaught EXIT signal occurs. - {compressed, bool()}. Temporary files and the + {compressed, boolean()}. Temporary files and the output file may be compressed. The default value false implies that written files are not compressed. Regardless of the value of the compressed @@ -128,39 +128,6 @@ merged at a time. This option should rarely be needed. -

To summarize, here is the syntax of the options:

- - -

Options = [Option] | Option

-
- -

Option = {header, HeaderLength} | {format, Format} | {order, Order} | {unique, bool()} | {tmpdir, TempDirectory} | {compressed, bool()} | {size, Size} | {no_files, NoFiles}

-
- -

HeaderLength = int() > 0

-
- -

Format = binary_term | term | binary | FormatFun

-
- -

FormatFun = fun(Binary) -> Term

-
- -

Order = ascending | descending | OrderFun

-
- -

OrderFun = fun(Term, Term) -> bool()

-
- -

TempDirectory = "" | file_name()

-
- -

Size = int() >= 0

-
- -

NoFiles = int() > 1

-
-

As an alternative to sorting files, a function of one argument can be given as input. When called with the argument read the function is assumed to return end_of_input or @@ -234,8 +201,8 @@ output(L) -> occurs are:

-

bad_object, {bad_object, FileName}. - Applying the format function failed for some binary, +

bad_object, {bad_object, FileName}. + Applying the format function failed for some binary, or the key(s) could not be extracted from some term.

@@ -243,148 +210,181 @@ output(L) -> to read some term.

-

{file_error, FileName, Reason2}. See - file(3) for an explanation of Reason2.

+

{file_error, FileName, file:posix()}. See + file(3) for an explanation of file:posix().

-

{premature_eof, FileName}. End-of-file was +

{premature_eof, FileName}. End-of-file was encountered inside some binary term.

-

Types

-
-Binary = binary()
-FileName = file_name()
-FileNames = [FileName]
-ICommand = read | close
-IReply = end_of_input | {end_of_input, Value} | {[Object], Infun} | InputReply
-Infun = fun(ICommand) -> IReply
-Input = FileNames | Infun
-InputReply = Term
-KeyPos = int() > 0 | [int() > 0]
-OCommand = {value, Value} | [Object] | close
-OReply = Outfun | OutputReply
-Object = Term | Binary
-Outfun = fun(OCommand) -> OReply
-Output = FileName | Outfun
-OutputReply = Term
-Term = term()
-Value = Term
+ + + +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +
+
+
+ - sort(FileName) -> Reply - sort(Input, Output) -> Reply - sort(Input, Output, Options) -> Reply + Sort terms on files. - - Reply = ok | {error, Reason} | InputReply | OutputReply - -

Sorts terms on files. -

-

sort(FileName) is equivalent to - sort([FileName], FileName). -

-

sort(Input, Output) is equivalent to - sort(Input, Output, []). -

-

+

Sorts terms on files. sort(FileName) is equivalent + to sort([FileName], FileName).

+
+
+ + + + Sort terms on files. + +

Sorts terms on files. sort(Input, Output) is + equivalent to sort(Input, Output, []).

+
+
+ + + Sort terms on files by key. + +

Sorts tuples on files. keysort(N, FileName) is + equivalent to keysort(N, [FileName], FileName).

- keysort(KeyPos, FileName) -> Reply - keysort(KeyPos, Input, Output) -> Reply - keysort(KeyPos, Input, Output, Options) -> Reply + + Sort terms on files by key. - - Reply = ok | {error, Reason} | InputReply | OutputReply -

Sorts tuples on files. The sort is performed on the - element(s) mentioned in KeyPos. If two tuples - compare equal (==) on one element, next element according to - KeyPos is compared. The sort is stable. -

-

keysort(N, FileName) is equivalent to - keysort(N, [FileName], FileName). -

+ element(s) mentioned in KeyPos. If two + tuples compare equal (==) on one element, next + element according to KeyPos + is compared. The sort is stable.

keysort(N, Input, Output) is equivalent to - keysort(N, Input, Output, []). -

-

+ keysort(N, Input, Output, []).

- merge(FileNames, Output) -> Reply - merge(FileNames, Output, Options) -> Reply + + Merge terms on files. - - Reply = ok | {error, Reason} | OutputReply -

Merges terms on files. Each input file is assumed to be - sorted. -

+ sorted.

merge(FileNames, Output) is equivalent to - merge(FileNames, Output, []). -

+ merge(FileNames, Output, []).

- keymerge(KeyPos, FileNames, Output) -> Reply - keymerge(KeyPos, FileNames, Output, Options) -> Reply + + Merge terms on files by key. - - Reply = ok | {error, Reason} | OutputReply -

Merges tuples on files. Each input file is assumed to be - sorted on key(s). -

+ sorted on key(s).

keymerge(KeyPos, FileNames, Output) is equivalent - to keymerge(KeyPos, FileNames, Output, []). -

-

+ to keymerge(KeyPos, FileNames, Output, []).

- check(FileName) -> Reply - check(FileNames, Options) -> Reply + + Check whether terms on files are sorted. - - Reply = {ok, [Result]} | {error, Reason} - Result = {FileName, TermPosition, Term} - TermPosition = int() > 1 -

Checks files for sortedness. If a file is not sorted, the first out-of-order element is returned. The first term on a - file has position 1. -

+ file has position 1.

check(FileName) is equivalent to - check([FileName], []). -

+ check([FileName], []).

- keycheck(KeyPos, FileName) -> CheckReply - keycheck(KeyPos, FileNames, Options) -> Reply + + Check whether terms on files are sorted by key. - - Reply = {ok, [Result]} | {error, Reason} - Result = {FileName, TermPosition, Term} - TermPosition = int() > 1 -

Checks files for sortedness. If a file is not sorted, the first out-of-order element is returned. The first term on a - file has position 1. -

+ file has position 1.

keycheck(KeyPos, FileName) is equivalent - to keycheck(KeyPos, [FileName], []). -

-

+ to keycheck(KeyPos, [FileName], []).

diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index fab68ae77c..f3079c7337 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -41,62 +41,46 @@

For more information about raw file names, see the file module.

-
- DATA TYPES - -filename() = string() | atom() | DeepList | RawFilename - DeepList = [char() | atom() | DeepList] - RawFilename = binary() - If VM is in unicode filename mode, string() and char() are allowed to be > 255. - RawFilename is a filename not subject to Unicode translation, meaning that it - can contain characters not conforming to the Unicode encoding expected from the - filesystem (i.e. non-UTF-8 characters although the VM is started in Unicode - filename mode). -dirname() = filename() -
+ + + + + + + + - ensure_dir(Name) -> ok | {error, Reason} + Ensure that all parent directories for a file or directory exist. - - Name = filename() | dirname() - Reason = posix() -- see file(3) -

The ensure_dir/1 function ensures that all parent - directories for the given file or directory name Name + directories for the given file or directory name Name exist, trying to create them if necessary.

Returns ok if all parent directories already exist - or could be created, or {error, Reason} if some parent + or could be created, or {error, Reason} if some parent directory does not exist and could not be created for some reason.

- file_size(Filename) -> integer() + Return the size in bytes of the file.

The file_size function returns the size of the given file.

- fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut + Fold over all files matching a regular expression. - - Dir = dirname() - RegExp = regular_expression_string() - Recursive = true|false - Fun = fun(F, AccIn) -> AccOut - AccIn = AccOut = term() -

The fold_files/5 function folds the function - Fun over all (regular) files F in the - directory Dir that match the regular expression RegExp + Fun over all (regular) files F in the + directory Dir that match the regular expression RegExp (see the re module for a description of the allowed regular expressions). - If Recursive is true all sub-directories to Dir + If Recursive is true all sub-directories to Dir are processed. The regular expression matching is done on just the filename without the directory part.

@@ -114,44 +98,32 @@ dirname() = filename()
- is_dir(Name) -> true | false + Test whether Name refer to a directory or not - - Name = filename() | dirname() - -

The is_dir/1 function returns true if Name +

The is_dir/1 function returns true if Name refers to a directory, and false otherwise.

- is_file(Name) -> true | false + Test whether Name refer to a file or directory. - - Name = filename() | dirname() - -

The is_file/1 function returns true if Name +

The is_file/1 function returns true if Name refers to a file or a directory, and false otherwise.

- is_regular(Name) -> true | false + Test whether Name refer to a (regular) file. - - Name = filename() - -

The is_regular/1 function returns true if Name +

The is_regular/1 function returns true if Name refers to a file (regular file), and false otherwise.

- last_modified(Name) -> {{Year,Month,Day},{Hour,Min,Sec}} | 0 + Return the local date and time when a file was last modified. - - Name = filename() | dirname() -

The last_modified/1 function returns the date and time the given file or directory was last modified, or 0 if the file @@ -159,14 +131,11 @@ dirname() = filename() - wildcard(Wildcard) -> list() + Match filenames using Unix-style wildcards. - - Wildcard = filename() | dirname() -

The wildcard/1 function returns a list of all files - that match Unix-style wildcard-string Wildcard.

+ that match Unix-style wildcard-string Wildcard.

The wildcard string looks like an ordinary filename, except that certain "wildcard characters" are interpreted in a special way. The following characters are special: @@ -226,15 +195,11 @@ dirname() = filename() - wildcard(Wildcard, Cwd) -> list() + Match filenames using Unix-style wildcards starting at a specified directory. - - Wildcard = filename() | dirname() - Cwd = dirname() -

The wildcard/2 function works like wildcard/1, - except that instead of the actual working directory, Cwd + except that instead of the actual working directory, Cwd will be used.

diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index cdee6e4a81..bc3a616d39 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -4,7 +4,7 @@
- 19972010 + 19972011 Ericsson AB. All Rights Reserved. @@ -47,28 +47,12 @@ file:native_name_encoding/0, a raw file name will also be returned. For example filename:join/1 provided with a path component being a binary (and also not being possible to interpret under the current native file name encoding) will result in a raw file name being returned (the join operation will have been performed of course). For more information about raw file names, see the file module.

-
- DATA TYPES - -name() = string() | atom() | DeepList | RawFilename - DeepList = [char() | atom() | DeepList] - RawFilename = binary() - If VM is in unicode filename mode, string() and char() are allowed to be > 255. - RawFilename is a filename not subject to Unicode translation, meaning that it - can contain characters not conforming to the Unicode encoding expected from the - filesystem (i.e. non-UTF-8 characters although the VM is started in Unicode - filename mode). - -
- absname(Filename) -> string() + Convert a filename to an absolute name, relative the working directory - - Filename = name() - -

Converts a relative Filename and returns an absolute +

Converts a relative Filename and returns an absolute name. No attempt is made to create the shortest absolute name, because this can give incorrect results on file systems which allow links.

@@ -95,44 +79,33 @@ name() = string() | atom() | DeepList | RawFilename
- absname(Filename, Dir) -> string() + Convert a filename to an absolute name, relative a specified directory - - Filename = name() - Dir = string() -

This function works like absname/1, except that the directory to which the file name should be made relative - is given explicitly in the Dir argument.

+ is given explicitly in the Dir argument.

- absname_join(Dir, Filename) -> string() + Join an absolute directory with a relative filename - - Dir = string() - Filename = name() -

Joins an absolute directory with a relative filename. Similar to join/2, but on platforms with tight restrictions on raw filename length and no support for symbolic links (read: VxWorks), leading parent directory - components in Filename are matched against trailing - directory components in Dir so they can be removed + components in Filename are matched against trailing + directory components in Dir so they can be removed from the result - minimizing its length.

- basename(Filename) -> string() + Return the last component of a filename - - Filename = name() - -

Returns the last component of Filename, or - Filename itself if it does not contain any directory +

Returns the last component of Filename, or + Filename itself if it does not contain any directory separators.

 5> filename:basename("foo").
@@ -144,14 +117,11 @@ name() = string() | atom() | DeepList | RawFilename
       
     
     
-      basename(Filename, Ext) -> string()
+      
       Return the last component of a filename, stripped of the specified extension
-      
-        Filename = Ext = name()
-      
       
-        

Returns the last component of Filename with the - extension Ext stripped. This function should be used +

Returns the last component of Filename with the + extension Ext stripped. This function should be used to remove a specific extension which might, or might not, be there. Use rootname(basename(Filename)) to remove an extension that exists, but you are not sure which one it is.

@@ -169,13 +139,10 @@ name() = string() | atom() | DeepList | RawFilename
- dirname(Filename) -> string() + Return the directory part of a path name - - Filename = name() - -

Returns the directory part of Filename.

+

Returns the directory part of Filename.

 13> filename:dirname("/usr/src/kalle.erl").
 "/usr/src"
@@ -187,13 +154,10 @@ name() = string() | atom() | DeepList | RawFilename
       
     
     
-      extension(Filename) -> string()
+      
       Return the file extension
-      
-        Filename = name()
-      
       
-        

Returns the file extension of Filename, including +

Returns the file extension of Filename, including the period. Returns an empty string if there is no extension.

 15> filename:extension("foo.erl").
@@ -203,11 +167,8 @@ name() = string() | atom() | DeepList | RawFilename
       
     
     
-      flatten(Filename) -> string()
+      
       Convert a filename to a flat string
-      
-        Filename = name()
-      
       
         

Converts a possibly deep list filename consisting of characters and atoms into the corresponding flat string @@ -215,14 +176,11 @@ name() = string() | atom() | DeepList | RawFilename - join(Components) -> string() + Join a list of filename components with directory separators - - Components = [string()] - -

Joins a list of file name Components with directory - separators. If one of the elements of Components +

Joins a list of file name Components with directory + separators. If one of the elements of Components includes an absolute path, for example "/xxx", the preceding elements, if any, are removed from the result.

The result is "normalized":

@@ -242,24 +200,18 @@ name() = string() | atom() | DeepList | RawFilename
- join(Name1, Name2) -> string() + Join two filename components with directory separators - - Name1 = Name2 = string() -

Joins two file name components with directory separators. - Equivalent to join([Name1, Name2]).

+ Equivalent to join([Name1, Name2]).

- nativename(Path) -> string() + Return the native form of a file path - - Path = string() - -

Converts Path to a form accepted by the command shell +

Converts Path to a form accepted by the command shell and native applications on the current platform. On Windows, forward slashes is converted to backward slashes. On all platforms, the name is normalized as done by join/1.

@@ -272,7 +224,7 @@ name() = string() | atom() | DeepList | RawFilename
- pathtype(Path) -> absolute | relative | volumerelative + Return the type of a path

Returns the type of path, one of absolute, @@ -302,16 +254,13 @@ name() = string() | atom() | DeepList | RawFilename - rootname(Filename) -> string() - rootname(Filename, Ext) -> string() + + Remove a filename extension - - Filename = Ext = name() -

Remove a filename extension. rootname/2 works as rootname/1, except that the extension is removed only - if it is Ext.

+ if it is Ext.

 20> filename:rootname("/beam.src/kalle").
 /beam.src/kalle"
@@ -324,15 +273,11 @@ name() = string() | atom() | DeepList | RawFilename
       
     
     
-      split(Filename) -> Components
+      
       Split a filename into its path components
-      
-        Filename = name()
-        Components = [string()]
-      
       
         

Returns a list whose elements are the path components of - Filename.

+ Filename.

 24> filename:split("/usr/local/bin").
 ["/","usr","local","bin"]
@@ -343,47 +288,38 @@ name() = string() | atom() | DeepList | RawFilename
       
     
     
-      find_src(Beam) -> {SourceFile, Options} | {error,{ErrorReason,Module}}
-      find_src(Beam, Rules) -> {SourceFile, Options} | {error,{ErrorReason,Module}}
+      
+      
       Find the filename and compiler options for a module
-      
-        Beam = Module | Filename
-         Module = atom()
-         Filename = string() | atom()
-        SourceFile = string()
-        Options = [Opt]
-         Opt = {i, string()} | {outdir, string()} | {d, atom()}
-	ErrorReason = non_existing | preloaded | interpreted
-      
       
         

Finds the source filename and compiler options for a module. The result can be fed to compile:file/2 in order to compile the file again.

-

The Beam argument, which can be a string or an atom, +

The Beam argument, which can be a string or an atom, specifies either the module name or the path to the source code, with or without the ".erl" extension. In either case, the module must be known by the code server, i.e. - code:which(Module) must succeed.

-

Rules describes how the source directory can be found, + code:which(Module) must succeed.

+

Rules describes how the source directory can be found, when the object code directory is known. It is a list of - tuples {BinSuffix, SourceSuffix} and is interpreted + tuples {BinSuffix, SourceSuffix} and is interpreted as follows: If the end of the directory name where the object - is located matches BinSuffix, then the source code - directory has the same name, but with BinSuffix - replaced by SourceSuffix. Rules defaults to:

+ is located matches BinSuffix, then the source code + directory has the same name, but with BinSuffix + replaced by SourceSuffix. Rules defaults to:

[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]

If the source file is found in the resulting directory, then the function returns that location together with - Options. Otherwise, the next rule is tried, and so on.

+ Options. Otherwise, the next rule is tried, and so on.

-

The function returns {SourceFile, Options} if it succeeds. - SourceFile is the absolute path to the source file - without the ".erl" extension. Options include +

The function returns {SourceFile, Options} if it succeeds. + SourceFile is the absolute path to the source file + without the ".erl" extension. Options include the options which are necessary to recompile the file with compile:file/2, but excludes options such as report or verbose which do not change the way - code is generated. The paths in the {outdir, Path} + code is generated. The paths in the {outdir, Path} and {i, Path} options are guaranteed to be absolute.

diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index 60d8bcbfa3..38de51322f 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -4,7 +4,7 @@
- 20012010 + 20012011 Ericsson AB. All Rights Reserved. @@ -114,34 +114,32 @@
-
- DATA TYPES - -gb_set() = a GB set -
+ + + gb_set() +

A GB set.

+
+ + +

A GB set iterator.

+
+
- add(Element, Set1) -> Set2 - add_element(Element, Set1) -> Set2 + + Add a (possibly existing) element to a gb_set - - Element = term() - Set1 = Set2 = gb_set() - -

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

+

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

- balance(Set1) -> Set2 + Rebalance tree representation of a gb_set - - Set1 = Set2 = gb_set() - -

Rebalances the tree representation of Set1. Note that +

Rebalances the tree representation of Set1. Note that this is rarely necessary, but may be motivated when a large number of elements have been deleted from the tree without further insertions. Rebalancing could then be forced in order @@ -150,208 +148,144 @@ gb_set() = a GB set - delete(Element, Set1) -> Set2 + Remove an element from a gb_set - - Element = term() - Set1 = Set2 = gb_set() - -

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

+

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

- delete_any(Element, Set1) -> Set2 - del_element(Element, Set1) -> Set2 + + Remove a (possibly non-existing) element from a gb_set - - Element = term() - Set1 = Set2 = gb_set() - -

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

+

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

- difference(Set1, Set2) -> Set3 - subtract(Set1, Set2) -> Set3 + + Return the difference of two gb_sets - - Set1 = Set2 = Set3 = gb_set() - -

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

+

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

- empty() -> Set - new() -> Set + + Return an empty gb_set - - Set = gb_set() -

Returns a new empty gb_set.

- filter(Pred, Set1) -> Set2 + Filter gb_set elements - - Pred = fun (E) -> bool() -  E = term() - Set1 = Set2 = gb_set() - -

Filters elements in Set1 using predicate function - Pred.

+

Filters elements in Set1 using predicate function + Pred.

- fold(Function, Acc0, Set) -> Acc1 + Fold over gb_set elements - - Function = fun (E, AccIn) -> AccOut - Acc0 = Acc1 = AccIn = AccOut = term() -  E = term() - Set = gb_set() - -

Folds Function over every element in Set +

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

- from_list(List) -> Set + Convert a list into a gb_set - - List = [term()] - Set = gb_set() - -

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

+

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

- from_ordset(List) -> Set + Make a gb_set from an ordset list - - List = [term()] - Set = gb_set() - -

Turns an ordered-set list List into a gb_set. The list +

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

- insert(Element, Set1) -> Set2 + Add a new element to a gb_set - - Element = term() - Set1 = Set2 = gb_set() - -

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

+

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

- intersection(Set1, Set2) -> Set3 + Return the intersection of two gb_sets - - Set1 = Set2 = Set3 = gb_set() - -

Returns the intersection of Set1 and Set2.

+

Returns the intersection of Set1 and Set2.

- intersection(SetList) -> Set + Return the intersection of a list of gb_sets - - SetList = [gb_set()] - Set = gb_set() -

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

- is_disjoint(Set1, Set2) -> bool() + Check whether two gb_sets are disjoint - - Set1 = Set2 = gb_set() - -

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

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

- is_empty(Set) -> bool() + Test for empty gb_set - - Set = gb_set() - -

Returns true if Set is an empty set, and +

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

- is_member(Element, Set) -> bool() - is_element(Element, Set) -> bool() + + Test for membership of a gb_set - - Element = term() - Set = gb_set() - -

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

+

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

- is_set(Term) -> bool() + Test for a gb_set - - Term = term() - -

Returns true if Set appears to be a gb_set, +

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

- is_subset(Set1, Set2) -> bool() + Test for subset - - Set1 = Set2 = gb_set() - -

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

+

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

- iterator(Set) -> Iter + Return an iterator for a gb_set - - Set = gb_set() - Iter = term() -

Returns an iterator that can be used for traversing the - entries of Set; see next/1. The implementation + 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. @@ -361,118 +295,84 @@ gb_set() = a GB set - largest(Set) -> term() + Return largest element - - Set = gb_set() - -

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

+

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

- next(Iter1) -> {Element, Iter2} | none + Traverse a gb_set with an iterator - - Iter1 = Iter2 = Element = term() - -

Returns {Element, Iter2} where Element is the - smallest element referred to by the iterator Iter1, - and Iter2 is the new iterator to be used for +

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

- singleton(Element) -> gb_set() + Return a gb_set with one element - - Element = term() - -

Returns a gb_set containing only the element Element.

+

Returns a gb_set containing only the element Element.

- size(Set) -> int() + Return the number of elements in a gb_set - - Set = gb_set() - -

Returns the number of elements in Set.

+

Returns the number of elements in Set.

- smallest(Set) -> term() + Return smallest element - - Set = gb_set() - -

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

+

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

- take_largest(Set1) -> {Element, Set2} + Extract largest element - - Set1 = Set2 = gb_set() - Element = term() - -

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

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

- take_smallest(Set1) -> {Element, Set2} + Extract smallest element - - Set1 = Set2 = gb_set() - Element = term() - -

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

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

- to_list(Set) -> List + Convert a gb_set into a list - - Set = gb_set() - List = [term()] - -

Returns the elements of Set as a list.

+

Returns the elements of Set as a list.

- union(Set1, Set2) -> Set3 + Return the union of two gb_sets - - Set1 = Set2 = Set3 = gb_set() - -

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

+

Returns the merged (union) gb_set of Set1 and + Set2.

- union(SetList) -> Set + Return the union of a list of gb_sets - - SetList = [gb_set()] - Set = gb_set() -

Returns the merged (union) gb_set of the list of gb_sets.

diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 94f40c28bd..65c866efbe 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -4,7 +4,7 @@
- 20012010 + 20012011 Ericsson AB. All Rights Reserved. @@ -57,20 +57,22 @@ trees. Behaviour is logarithmic (as it should be).

-
- DATA TYPES - -gb_tree() = a GB tree -
+ + + gb_tree() +

A GB tree.

+
+ + +

A GB tree iterator.

+
+
- balance(Tree1) -> Tree2 + Rebalance a tree - - Tree1 = Tree2 = gb_tree() - -

Rebalances Tree1. Note that this is rarely necessary, +

Rebalances Tree1. Note that this is rarely necessary, but may be motivated when a large number of nodes have been deleted from the tree without further insertions. Rebalancing could then be forced in order to minimise lookup times, since @@ -78,139 +80,97 @@ gb_tree() = a GB tree - delete(Key, Tree1) -> Tree2 + Remove a node from a tree - - Key = term() - Tree1 = Tree2 = gb_tree() - -

Removes the node with key Key from Tree1; +

Removes the node with key Key from Tree1; returns new tree. Assumes that the key is present in the tree, crashes otherwise.

- delete_any(Key, Tree1) -> Tree2 + Remove a (possibly non-existing) node from a tree - - Key = term() - Tree1 = Tree2 = gb_tree() - -

Removes the node with key Key from Tree1 if +

Removes the node with key Key from Tree1 if the key is present in the tree, otherwise does nothing; returns new tree.

- empty() -> Tree + Return an empty tree - - Tree = gb_tree() -

Returns a new empty tree

- enter(Key, Val, Tree1) -> Tree2 + Insert or update key with value in a tree - - Key = Val = term() - Tree1 = Tree2 = gb_tree() - -

Inserts Key with value Val into Tree1 if +

Inserts Key with value Val into Tree1 if the key is not present in the tree, otherwise updates - Key to value Val in Tree1. Returns the + Key to value Val in Tree1. Returns the new tree.

- from_orddict(List) -> Tree + Make a tree from an orddict - - List = [{Key, Val}] -  Key = Val = term() - Tree = gb_tree() - -

Turns an ordered list List of key-value tuples into a +

Turns an ordered list List of key-value tuples into a tree. The list must not contain duplicate keys.

- get(Key, Tree) -> Val + Look up a key in a tree, if present - - Key = Val = term() - Tree = gb_tree() - -

Retrieves the value stored with Key in Tree. +

Retrieves the value stored with Key in Tree. Assumes that the key is present in the tree, crashes otherwise.

- lookup(Key, Tree) -> {value, Val} | none + Look up a key in a tree - - Key = Val = term() - Tree = gb_tree() - -

Looks up Key in Tree; returns - {value, Val}, or none if Key is not +

Looks up Key in Tree; returns + {value, Val}, or none if Key is not present.

- insert(Key, Val, Tree1) -> Tree2 + Insert a new key and value in a tree - - Key = Val = term() - Tree1 = Tree2 = gb_tree() - -

Inserts Key with value Val into Tree1; +

Inserts Key with value Val into Tree1; returns the new tree. Assumes that the key is not present in the tree, crashes otherwise.

- is_defined(Key, Tree) -> bool() + Test for membership of a tree - - Tree = gb_tree() - -

Returns true if Key is present in Tree, +

Returns true if Key is present in Tree, otherwise false.

- is_empty(Tree) -> bool() + Test for empty tree - - Tree = gb_tree() - -

Returns true if Tree is an empty tree, and +

Returns true if Tree is an empty tree, and false otherwise.

- iterator(Tree) -> Iter + Return an iterator for a tree - - Tree = gb_tree() - Iter = term() -

Returns an iterator that can be used for traversing the - entries of Tree; see next/1. The implementation + entries of Tree; see next/1. The implementation of this is very efficient; traversing the whole tree using next/1 is only slightly slower than getting the list of all elements using to_list/1 and traversing that. @@ -220,141 +180,99 @@ gb_tree() = a GB tree - keys(Tree) -> [Key] + Return a list of the keys in a tree - - Tree = gb_tree() - Key = term() - -

Returns the keys in Tree as an ordered list.

+

Returns the keys in Tree as an ordered list.

- largest(Tree) -> {Key, Val} + Return largest key and value - - Tree = gb_tree() - Key = Val = term() - -

Returns {Key, Val}, where Key is the largest - key in Tree, and Val is the value associated +

Returns {Key, Val}, where Key is the largest + key in Tree, and Val is the value associated with this key. Assumes that the tree is nonempty.

- map(Function, Tree1) -> Tree2 + Return largest key and value - - Function = fun(K, V1) -> V2 - Tree1 = Tree2 = gb_tree() - -

maps the function F(K, V1) -> V2 to all key-value pairs - of the tree Tree1 and returns a new tree Tree2 with the same set of keys - as Tree1 and the new set of values V2.

+

Maps the function F(K, V1) -> V2 to all key-value pairs + of the tree Tree1 and returns a new tree Tree2 with the same set of keys + as Tree1 and the new set of values V2.

- next(Iter1) -> {Key, Val, Iter2} | none + Traverse a tree with an iterator - - Iter1 = Iter2 = Key = Val = term() - -

Returns {Key, Val, Iter2} where Key is the - smallest key referred to by the iterator Iter1, and - Iter2 is the new iterator to be used for +

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

- size(Tree) -> int() + Return the number of nodes in a tree - - Tree = gb_tree() - -

Returns the number of nodes in Tree.

+

Returns the number of nodes in Tree.

- smallest(Tree) -> {Key, Val} + Return smallest key and value - - Tree = gb_tree() - Key = Val = term() - -

Returns {Key, Val}, where Key is the smallest - key in Tree, and Val is the value associated +

Returns {Key, Val}, where Key is the smallest + key in Tree, and Val is the value associated with this key. Assumes that the tree is nonempty.

- take_largest(Tree1) -> {Key, Val, Tree2} + Extract largest key and value - - Tree1 = Tree2 = gb_tree() - Key = Val = term() - -

Returns {Key, Val, Tree2}, where Key is the - largest key in Tree1, Val is the value - associated with this key, and Tree2 is this tree with +

Returns {Key, Val, Tree2}, where Key is the + largest key in Tree1, Val is the value + associated with this key, and Tree2 is this tree with the corresponding node deleted. Assumes that the tree is nonempty.

- take_smallest(Tree1) -> {Key, Val, Tree2} + Extract smallest key and value - - Tree1 = Tree2 = gb_tree() - Key = Val = term() - -

Returns {Key, Val, Tree2}, where Key is the - smallest key in Tree1, Val is the value - associated with this key, and Tree2 is this tree with +

Returns {Key, Val, Tree2}, where Key is the + smallest key in Tree1, Val is the value + associated with this key, and Tree2 is this tree with the corresponding node deleted. Assumes that the tree is nonempty.

- to_list(Tree) -> [{Key, Val}] + Convert a tree into a list - - Tree = gb_tree() - Key = Val = term() -

Converts a tree into an ordered list of key-value tuples.

- update(Key, Val, Tree1) -> Tree2 + Update a key to new value in a tree - - Key = Val = term() - Tree1 = Tree2 = gb_tree() - -

Updates Key to value Val in Tree1; +

Updates Key to value Val in Tree1; returns the new tree. Assumes that the key is present in the tree.

- values(Tree) -> [Val] + Return a list of the values in a tree - - Tree = gb_tree() - Val = term() - -

Returns the values in Tree as an ordered list, sorted +

Returns the values in Tree as an ordered list, sorted by their corresponding keys. Duplicates are not removed.

diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 2234a62ac3..24bcb419fe 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -100,6 +100,20 @@ gen_event:stop -----> Module:terminate/2 the specified event manager does not exist or if bad arguments are given.

+ + + + + + + + + + + + + + start_link() -> Result diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index 41e3e92c59..af9c75d546 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -43,7 +43,7 @@

As of R13A, data supplied to the put_chars function should be in the - chardata() format described below. This means that programs + unicode:chardata() format. This means that programs supplying binaries to this function need to convert them to UTF-8 before trying to output the data on an io_device().

@@ -64,76 +64,84 @@ -
- DATA TYPES - -io_device() - as returned by file:open/2, a process handling IO protocols - - -unicode_binary() = binary() with characters encoded in UTF-8 coding standard -unicode_char() = integer() representing valid unicode codepoint - -chardata() = charlist() | unicode_binary() + + + + +

Either standard_io, standard_error, a + registered name, or a pid handling IO protocols (returned from + file:open/2).

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Whatever the I/O-server sends.

+
+
-charlist() = [unicode_char() | unicode_binary() | charlist()] - a unicode_binary is allowed as the tail of the list
-
- columns() -> {ok,int()} | {error, enotsup} - columns(IoDevice) -> {ok,int()} | {error, enotsup} + + Get the number of columns of a device - - IoDevice = io_device() -

Retrieves the number of columns of the - IoDevice (i.e. the width of a terminal). The function + IoDevice (i.e. the width of a terminal). The function only succeeds for terminal devices, for all other devices the function returns {error, enotsup}

- put_chars(IoData) -> ok - put_chars(IoDevice, IoData) -> ok + + Write a list of characters - - IoDevice = io_device() - IoData = chardata() - -

Writes the characters of IoData to the io_server() - (IoDevice).

+

Writes the characters of CharData to the io_server() + (IoDevice).

- nl() -> ok - nl(IoDevice) -> ok + + Write a newline - - IoDevice = io_device() - -

Writes new line to the standard output (IoDevice).

+

Writes new line to the standard output (IoDevice).

- get_chars(Prompt, Count) -> Data | eof - get_chars(IoDevice, Prompt, Count) -> Data | eof + + Read a specified number of characters - - IoDevice = io_device() - Prompt = atom() | string() - Count = int() - Data = [ unicode_char() ] | unicode_binary() - -

Reads Count characters from standard input - (IoDevice), prompting it with Prompt. It +

Reads Count characters from standard input + (IoDevice), prompting it with Prompt. It returns:

- Data + Data

The input characters. If the device supports Unicode, the data may represent codepoints larger than 255 (the @@ -145,7 +153,7 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]

End of file was encountered.

- {error,Reason} + {error,Reason}

Other (rare) error condition, for instance {error,estale} if reading from an NFS file system.

@@ -154,19 +162,14 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
- get_line(Prompt) -> Data | eof | {error,Reason} - get_line(IoDevice, Prompt) -> Data | eof | {error,Reason} + + Read a line - - IoDevice = io_device() - Prompt = atom() | string() - Data = [ unicode_char() ] | unicode_binary() - -

Reads a line from the standard input (IoDevice), - prompting it with Prompt. It returns:

+

Reads a line from the standard input (IoDevice), + prompting it with Prompt. It returns:

- Data + Data

The characters in the line terminated by a LF (or end of file). If the device supports Unicode, @@ -179,7 +182,7 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]

End of file was encountered.

- {error,Reason} + {error,Reason}

Other (rare) error condition, for instance {error,estale} if reading from an NFS file system.

@@ -188,15 +191,9 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
- getopts() -> Opts - getopts(IoDevice) -> Opts + + Get the supported options and values from an I/O-server - - IoDevice = io_device() - Opts = [Opt] -   Opt = {atom(),Value} -   Value = term() -

This function requests all available options and their current values for a specific io_device(). Example:

@@ -216,18 +213,11 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
       
     
     
-      setopts(Opts) -> ok | {error, Reason}
-      setopts(IoDevice, Opts) -> ok | {error, Reason}
+      
+      
       Set options
-      
-        IoDevice = io_device()
-        Opts = [Opt]
-          Opt = atom() | {atom(),Value}
-	  Value = term()
-        Reason = term()
-      
       
-        

Set options for the io_device() (IoDevice).

+

Set options for the io_device() (IoDevice).

Possible options and values vary depending on the actual io_device(). For a list of supported options and their current values @@ -236,17 +226,17 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]

The options and values supported by the current OTP io_devices are:

- binary, list or {binary, bool()} + binary, list or {binary, boolean()}

If set in binary mode (binary or {binary,true}), the io_server() sends binary data (encoded in UTF-8) as answers to the get_line, get_chars and, if possible, get_until requests (see the I/O protocol description in STDLIB User's Guide for details). The immediate effect is that get_chars/2,3 and get_line/1,2 return UTF-8 binaries instead of lists of chars for the affected device.

By default, all io_devices in OTP are set in list mode, but the io functions can handle any of these modes and so should other, user written, modules behaving as clients to I/O-servers.

This option is supported by the standard shell (group.erl), the 'oldshell' (user.erl) and the file I/O servers.

- {echo, bool()} + {echo, boolean()}

Denotes if the terminal should echo input. Only supported for the standard shell I/O-server (group.erl)

- {expand_fun, fun()} + {expand_fun, expand_fun()}

Provide a function for tab-completion (expansion) like the erlang shell. This function is called @@ -288,35 +278,24 @@ charlist() = [unicode_char() | unicode_binary() | charlist()] - write(Term) -> ok - write(IoDevice, Term) -> ok + + Write a term - - IoDevice = io_device() - Term = term() - -

Writes the term Term to the standard output - (IoDevice).

+

Writes the term Term to the standard output + (IoDevice).

- read(Prompt) -> Result - read(IoDevice, Prompt) -> Result + + Read a term - - IoDevice = io_device() - Prompt = atom() | string() - Result = {ok, Term} | eof | {error, ErrorInfo} -  Term = term() -  ErrorInfo -- see section Error Information below - -

Reads a term Term from the standard input - (IoDevice), prompting it with Prompt. It +

Reads a term Term from the standard input + (IoDevice), prompting it with Prompt. It returns:

- {ok, Term} + {ok, Term}

The parsing was successful.

@@ -324,7 +303,7 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]

End of file was encountered.

- {error, ErrorInfo} + {error, ErrorInfo}

The parsing failed.

@@ -332,31 +311,22 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
- read(IoDevice, Prompt, StartLine) -> Result + Read a term - - IoDevice = io_device() - Prompt = atom() | string() - StartLine = int() - Result = {ok, Term, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine} -  Term = term() -  EndLine = int() -  ErrorInfo -- see section Error Information below - -

Reads a term Term from IoDevice, prompting it - with Prompt. Reading starts at line number - StartLine. It returns:

+

Reads a term Term from IoDevice, prompting it + with Prompt. Reading starts at line number + StartLine. It returns:

- {ok, Term, EndLine} + {ok, Term, EndLine}

The parsing was successful.

- {eof, EndLine} + {eof, EndLine}

End of file was encountered.

- {error, ErrorInfo, EndLine} + {error, ErrorInfo, ErrorLine}

The parsing failed.

@@ -364,24 +334,19 @@ charlist() = [unicode_char() | unicode_binary() | charlist()]
- fwrite(Format) -> - fwrite(Format, Data) -> ok - fwrite(IoDevice, Format, Data) -> ok - format(Format) -> - format(Format, Data) -> ok - format(IoDevice, Format, Data) -> ok + + + + + + Write formatted output - - IoDevice = io_device() - Format = atom() | string() | binary() - Data = [term()] - -

Writes the items in Data ([]) on the standard - output (IoDevice) in accordance with Format. - Format contains plain characters which are copied to +

Writes the items in Data ([]) on the standard + output (IoDevice) in accordance with Format. + Format contains plain characters which are copied to the output device, and control sequences for formatting, see - below. If Format is an atom or a binary, it is first + below. If Format is an atom or a binary, it is first converted to a list with the aid of atom_to_list/1 or binary_to_list/1.

@@ -474,7 +439,7 @@ ok

Prints the argument with the string syntax. The argument is, if no Unicode translation modifier is present, an - I/O list, a binary, or an atom. If the Unicode translation modifier ('t') is in effect, the argument is chardata(), meaning that binaries are in UTF-8. The characters + I/O list, a binary, or an atom. If the Unicode translation modifier ('t') is in effect, the argument is unicode:chardata(), meaning that binaries are in UTF-8. The characters are printed without quotes. The string is first truncated by the given precision and then padded and justified to the given field width. The default precision is the field width.

@@ -673,23 +638,15 @@ ok
- fread(Prompt, Format) -> Result - fread(IoDevice, Prompt, Format) -> Result + + Read formatted input - - IoDevice = io_device() - Prompt = atom() | string() - Format = string() - Result = {ok, Terms} | eof | {error, What} -  Terms = [term()] -  What = term() - -

Reads characters from the standard input (IoDevice), - prompting it with Prompt. Interprets the characters in - accordance with Format. Format contains control +

Reads characters from the standard input (IoDevice), + prompting it with Prompt. Interprets the characters in + accordance with Format. Format contains control sequences which directs the interpretation of the input.

-

Format may contain:

+

Format may contain:

White space characters (SPACE, TAB and NEWLINE) which @@ -803,19 +760,19 @@ Prompt> <Character beyond latin1 range not printable in this medium>

It returns:

- {ok, Terms} + {ok, Terms} -

The read was successful and Terms is the list +

The read was successful and Terms is the list of successfully matched and read items.

eof

End of file was encountered.

- {error, What} + {error, What}

The read operation failed and the parameter - What gives a hint about the error.

+ What gives a hint about the error.

@@ -834,33 +791,21 @@ enter>: alan : joe
- rows() -> {ok,int()} | {error, enotsup} - rows(IoDevice) -> {ok,int()} | {error, enotsup} + + Get the number of rows of a device - - IoDevice = io_device() -

Retrieves the number of rows of the - IoDevice (i.e. the height of a terminal). The function + IoDevice (i.e. the height of a terminal). The function only succeeds for terminal devices, for all other devices the function returns {error, enotsup}

- scan_erl_exprs(Prompt) -> - scan_erl_exprs(Prompt, StartLine) -> Result - scan_erl_exprs(IoDevice, Prompt, StartLine) -> Result + + + Read and tokenize Erlang expressions - - IoDevice = io_device() - Prompt = atom() | string() - StartLine = int() - Result = {ok, Tokens, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine} -  Tokens -- see erl_scan(3) -  EndLine = int() -  ErrorInfo -- see section Error Information below -

Reads data from the standard input (IoDevice), prompting it with Prompt. Reading starts at line number @@ -876,7 +821,7 @@ enter>: alan : joe

End of file was encountered.

- {error, ErrorInfo, EndLine} + {error, ErrorInfo, ErrorLine}

An error occurred.

@@ -892,23 +837,14 @@ enter>1.0er.
- scan_erl_form(Prompt) -> - scan_erl_form(Prompt, StartLine) -> Result - scan_erl_form(IoDevice, Prompt, StartLine) -> Result + + + Read and tokenize an Erlang form - - IoDevice = io_device() - Prompt = atom() | string() - StartLine = int() - Result = {ok, Tokens, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine} -  Tokens -- see erl_scan(3) -  EndLine = int() -  ErrorInfo -- see section Error Information below - -

Reads data from the standard input (IoDevice), - prompting it with Prompt. Starts reading at line number - StartLine (1). The data is tokenized as if it were an +

Reads data from the standard input (IoDevice), + prompting it with Prompt. Starts reading at line number + StartLine (1). The data is tokenized as if it were an Erlang form - one of the valid Erlang expressions in an Erlang source file - until a final '.' is reached. This last token is also returned. The return values are the @@ -916,27 +852,19 @@ enter>1.0er. - parse_erl_exprs(Prompt) -> - parse_erl_exprs(Prompt, StartLine) -> Result - parse_erl_exprs(IoDevice, Prompt, StartLine) -> Result + + + + Read, tokenize and parse Erlang expressions - - IoDevice = io_device() - Prompt = atom() | string() - StartLine = int() - Result = {ok, Expr_list, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine} -  Expr_list -- see erl_parse(3) -  EndLine = int() -  ErrorInfo -- see section Error Information below - -

Reads data from the standard input (IoDevice), - prompting it with Prompt. Starts reading at line number - StartLine (1). The data is tokenized and parsed as if +

Reads data from the standard input (IoDevice), + prompting it with Prompt. Starts reading at line number + StartLine (1). The data is tokenized and parsed as if it were a sequence of Erlang expressions until a final '.' is reached. It returns:

- {ok, Expr_list, EndLine} + {ok, ExprList, EndLine}

The parsing was successful.

@@ -944,7 +872,7 @@ enter>1.0er.

End of file was encountered.

- {error, ErrorInfo, EndLine} + {error, ErrorInfo, ErrorLine}

An error occurred.

@@ -960,23 +888,15 @@ enter>abc("hey".
- parse_erl_form(Prompt) -> - parse_erl_form(Prompt, StartLine) -> Result - parse_erl_form(IoDevice, Prompt, StartLine) -> Result + + + + Read, tokenize and parse an Erlang form - - IoDevice = io_device() - Prompt = atom() | string() - StartLine = int() - Result = {ok, AbsForm, EndLine} | {eof, EndLine} | {error, ErrorInfo, EndLine} -  AbsForm -- see erl_parse(3) -  EndLine = int() -  ErrorInfo -- see section Error Information below - -

Reads data from the standard input (IoDevice), - prompting it with Prompt. Starts reading at line number - StartLine (1). The data is tokenized and parsed as if +

Reads data from the standard input (IoDevice), + prompting it with Prompt. Starts reading at line number + StartLine (1). The data is tokenized and parsed as if it were an Erlang form - one of the valid Erlang expressions in an Erlang source file - until a final '.' is reached. It returns:

@@ -989,7 +909,7 @@ enter>abc("hey".

End of file was encountered.

- {error, ErrorInfo, EndLine} + {error, ErrorInfo, ErrorLine}

An error occurred.

diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 399f968c5f..506c1792f1 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -38,14 +38,22 @@ flattening deep lists.

-
- DATA TYPES - -chars() = [char() | chars()] -
+ + + + + + +

A continuation as returned by fread/3.

+
+
+ + + +
- nl() -> chars() + Write a newline

Returns a character list which represents a new line @@ -53,16 +61,12 @@ chars() = [char() | chars()] - write(Term) -> - write(Term, Depth) -> chars() + + Write a term - - Term = term() - Depth = int() - -

Returns a character list which represents Term. The - Depth (-1) argument controls the depth of the +

Returns a character list which represents Term. The + Depth (-1) argument controls the depth of the structures written. When the specified depth is reached, everything below this level is replaced by "...". For example:

@@ -74,36 +78,26 @@ chars() = [char() | chars()]
- print(Term) -> - print(Term, Column, LineLength, Depth) -> chars() + + Pretty print a term - - Term = term() - Column = LineLenght = Depth = int() -

Also returns a list of characters which represents - Term, but breaks representations which are longer than + Term, but breaks representations which are longer than one line into many lines and indents each line sensibly. It also tries to detect and output lists of printable characters - as strings. Column is the starting column (1), - LineLength the maximum line length (80), and - Depth (-1) the maximum print depth.

+ as strings. Column is the starting column (1), + LineLength the maximum line length (80), and + Depth (-1) the maximum print depth.

- fwrite(Format, Data) -> - format(Format, Data) -> chars() | UnicodeList + + Write formatted output - - Format = atom() | string() | binary() - Data = [term()] - UnicodeList = [Unicode] - Unicode = int() representing valid unicode codepoint - -

Returns a character list which represents Data - formatted in accordance with Format. See +

Returns a character list which represents Data + formatted in accordance with Format. See io:fwrite/1,2,3 for a detailed description of the available formatting options. A fault is generated if there is an error in the format string or @@ -119,42 +113,32 @@ chars() = [char() | chars()] - fread(Format, String) -> Result + Read formatted input - - Format = String = string() - Result = {ok, InputList, LeftOverChars} | {more, RestFormat, Nchars, InputStack} | {error, What} -  InputList = chars() -  LeftOverChars = string() -  RestFormat = string() -  Nchars = int() -  InputStack = chars() -  What = term() - -

Tries to read String in accordance with the control - sequences in Format. See +

Tries to read String in accordance with the control + sequences in Format. See io:fread/3 for a detailed description of the available formatting options. It is - assumed that String contains whole lines. It returns:

+ assumed that String contains whole lines. It returns:

- {ok, InputList, LeftOverChars} + {ok, InputList, LeftOverChars} -

The string was read. InputList is the list of +

The string was read. InputList is the list of successfully matched and read items, and - LeftOverChars are the input characters not used.

+ LeftOverChars are the input characters not used.

- {more, RestFormat, Nchars, InputStack} + {more, RestFormat, Nchars, InputStack}

The string was read, but more input is needed in order - to complete the original format string. RestFormat - is the remaining format string, NChars the number - of characters scanned, and InputStack is the + to complete the original format string. RestFormat + is the remaining format string, Nchars the number + of characters scanned, and InputStack is the reversed list of inputs matched up to that point.

- {error, What} + {error, What} -

The read operation failed and the parameter What +

The read operation failed and the parameter What gives a hint about the error.

@@ -165,17 +149,8 @@ chars() = [char() | chars()]
- fread(Continuation, String, Format) -> Return + Re-entrant formatted reader - - Continuation = see below - String = Format = string() - Return = {done, Result, LeftOverChars} | {more, Continuation} -  Result = {ok, InputList} | eof | {error, What} -   InputList = chars() -   What = term()() -  LeftOverChars = string() -

This is the re-entrant formatted reader. The continuation of the first call to the functions must be []. Refer to @@ -184,114 +159,92 @@ chars() = [char() | chars()] re-entrant input scheme works.

The function returns:

- {done, Result, LeftOverChars} + {done, Result, LeftOverChars}

The input is complete. The result is one of the following:

- {ok, InputList} + {ok, InputList} -

The string was read. InputList is the list of +

The string was read. InputList is the list of successfully matched and read items, and - LeftOverChars are the remaining characters.

+ LeftOverChars are the remaining characters.

eof

End of file has been encountered. - LeftOverChars are the input characters not + LeftOverChars are the input characters not used.

- {error, What} + {error, What} -

An error occurred and the parameter What gives +

An error occurred and the parameter What gives a hint about the error.

- {more, Continuation} + {more, Continuation}

More data is required to build a term. - Continuation must be passed to fread/3, + Continuation must be passed to fread/3, when more data becomes available.

- write_atom(Atom) -> chars() + Write an atom - - Atom = atom() -

Returns the list of characters needed to print the atom - Atom.

+ Atom.

- write_string(String) -> chars() + Write a string - - String = string() - -

Returns the list of characters needed to print String +

Returns the list of characters needed to print String as a string.

- write_char(Integer) -> chars() + Write a character - - Integer = int() -

Returns the list of characters needed to print a character constant in the ISO-latin-1 character set.

- indentation(String, StartIndent) -> int() + Indentation after printing string - - String = string() - StartIndent = int() - -

Returns the indentation if String has been printed, - starting at StartIndent.

+

Returns the indentation if String has been printed, + starting at StartIndent.

- char_list(Term) -> bool() + Test for a list of characters - - Term = term() - -

Returns true if Term is a flat list of +

Returns true if Term is a flat list of characters in the ISO-latin-1 range, otherwise it returns false.

- deep_char_list(Term) -> bool() + Test for a deep list of characters - - Term = term() - -

Returns true if Term is a, possibly deep, list +

Returns true if Term is a, possibly deep, list of characters in the ISO-latin-1 range, otherwise it returns false.

- printable_list(Term) -> bool() + Test for a list of printable ISO-latin-1 characters - - Term = term() - -

Returns true if Term is a flat list of +

Returns true if Term is a flat list of printable ISO-latin-1 characters, otherwise it returns false.

diff --git a/lib/stdlib/doc/src/lib.xml b/lib/stdlib/doc/src/lib.xml index 046add48e8..19fb827cbf 100644 --- a/lib/stdlib/doc/src/lib.xml +++ b/lib/stdlib/doc/src/lib.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -37,27 +37,23 @@ - flush_receive() -> void() + Flush messages

Flushes the message buffer of the current process.

- error_message(Format, Args) -> ok + Print error message - - Format = atom() | string() | binary() - Args = [term()] - -

Prints error message Args in accordance with - Format. Similar to io:format/2, see +

Prints error message Args in accordance with + Format. Similar to io:format/2, see io(3).

- progname() -> atom() + Return name of Erlang start script

Returns the name of the script that started the current @@ -65,37 +61,24 @@ - nonl(String1) -> String2 + Remove last newline - - String1 = String2 = string() -

Removes the last newline character, if any, in - String1.

+ String1.

- send(To, Msg) + Send a message - - To = pid() | Name | {Name,Node} -  Name = Node = atom() - Msg = term() -

This function to makes it possible to send a message using the apply/3 BIF.

- sendw(To, Msg) + Send a message and wait for an answer - - To = pid() | Name | {Name,Node} -  Name = Node = atom() - Msg = term() -

As send/2, but waits for an answer. It is implemented as follows:

diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml index 92c4eb4f4c..6f3ed7af98 100644 --- a/lib/stdlib/doc/src/lists.xml +++ b/lib/stdlib/doc/src/lists.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -60,58 +60,41 @@ - all(Pred, List) -> bool() + Return true if all elements in the list satisfyPred - - Pred = fun(Elem) -> bool() -  Elem = term() - List = [term()] - -

Returns true if Pred(Elem) returns - true for all elements Elem in List, +

Returns true if Pred(Elem) returns + true for all elements Elem in List, otherwise false.

- any(Pred, List) -> bool() + Return true if any of the elements in the list satisfiesPred - - Pred = fun(Elem) -> bool() -  Elem = term() - List = [term()] - -

Returns true if Pred(Elem) returns - true for at least one element Elem in - List.

+

Returns true if Pred(Elem) returns + true for at least one element Elem in + List.

- append(ListOfLists) -> List1 + Append a list of lists - - ListOfLists = [List] - List = List1 = [term()] -

Returns a list in which all the sub-lists of - ListOfLists have been appended. For example:

+ ListOfLists have been appended. For example:

 > lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).
 [1,2,3,a,b,4,5,6]
- append(List1, List2) -> List3 + Append two lists - - List1 = List2 = List3 = [term()] - -

Returns a new list List3 which is made from - the elements of List1 followed by the elements of - List2. For example:

+

Returns a new list List3 which is made from + the elements of List1 followed by the elements of + List2. For example:

 > lists:append("abc", "def").
 "abcdef"
@@ -119,15 +102,11 @@
- concat(Things) -> string() + Concatenate a list of atoms - - Things = [Thing] -  Thing = atom() | integer() | float() | string() -

Concatenates the text representation of the elements - of Things. The elements of Things can be atoms, + of Things. The elements of Things can be atoms, integers, floats or strings.

 > lists:concat([doc, '/', file, '.', 3]).
@@ -135,87 +114,59 @@
       
     
     
-      delete(Elem, List1) -> List2
+      
       Delete an element from a list
-      
-        Elem = term()
-        List1 = List2 = [term()]
-      
       
-        

Returns a copy of List1 where the first element - matching Elem is deleted, if there is such an +

Returns a copy of List1 where the first element + matching Elem is deleted, if there is such an element.

- dropwhile(Pred, List1) -> List2 + Drop elements from a list while a predicate is true - - Pred = fun(Elem) -> bool() -  Elem = term() - List1 = List2 = [term()] - -

Drops elements Elem from List1 while - Pred(Elem) returns true and returns +

Drops elements Elem from List1 while + Pred(Elem) returns true and returns the remaining list.

- duplicate(N, Elem) -> List + Make N copies of element - - N = int() - Elem = term() - List = [term()] - -

Returns a list which contains N copies of the term - Elem. For example:

+

Returns a list which contains N copies of the term + Elem. For example:

 > lists:duplicate(5, xx).
 [xx,xx,xx,xx,xx]
- filter(Pred, List1) -> List2 + Choose elements which satisfy a predicate - - Pred = fun(Elem) -> bool() -  Elem = term() - List1 = List2 = [term()] - -

List2 is a list of all elements Elem in - List1 for which Pred(Elem) returns +

List2 is a list of all elements Elem in + List1 for which Pred(Elem) returns true.

- flatlength(DeepList) -> int() + Length of flattened deep list - - DeepList = [term() | DeepList] - -

Equivalent to length(flatten(DeepList)), but more +

Equivalent to length(flatten(DeepList)), but more efficient.

- flatmap(Fun, List1) -> List2 + Map and flatten in one pass - - Fun = fun(A) -> [B] - List1 = [A] - List2 = [B] -  A = B = term() - -

Takes a function from As to lists of Bs, and a - list of As (List1) and produces a list of - Bs by applying the function to every element in - List1 and appending the resulting lists.

+

Takes a function from As to lists of Bs, and a + list of As (List1) and produces a list of + Bs by applying the function to every element in + List1 and appending the resulting lists.

That is, flatmap behaves as if it had been defined as follows:

@@ -228,43 +179,29 @@ flatmap(Fun, List1) ->
- flatten(DeepList) -> List + Flatten a deep list - - DeepList = [term() | DeepList] - List = [term()] - -

Returns a flattened version of DeepList.

+

Returns a flattened version of DeepList.

- flatten(DeepList, Tail) -> List + Flatten a deep list - - DeepList = [term() | DeepList] - Tail = List = [term()] - -

Returns a flattened version of DeepList with the tail - Tail appended.

+

Returns a flattened version of DeepList with the tail + Tail appended.

- foldl(Fun, Acc0, List) -> Acc1 + Fold a function over a list - - Fun = fun(Elem, AccIn) -> AccOut -  Elem = term() - Acc0 = Acc1 = AccIn = AccOut = term() - List = [term()] - -

Calls Fun(Elem, AccIn) on successive elements A - of List, starting with AccIn == Acc0. - Fun/2 must return a new accumulator which is passed to +

Calls Fun(Elem, AccIn) on successive elements A + of List, starting with AccIn == Acc0. + Fun/2 must return a new accumulator which is passed to the next call. The function returns the final value of - the accumulator. Acc0 is returned if the list is empty. + the accumulator. Acc0 is returned if the list is empty. For example:

 > lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).
@@ -274,14 +211,8 @@ flatmap(Fun, List1) ->
       
     
     
-      foldr(Fun, Acc0, List) -> Acc1
+      
       Fold a function over a list
-      
-        Fun = fun(Elem, AccIn) -> AccOut
-         Elem = term()
-        Acc0 = Acc1 = AccIn = AccOut = term()
-        List = [term()]
-      
       
         

Like foldl/3, but the list is traversed from right to left. For example:

@@ -297,33 +228,23 @@ flatmap(Fun, List1) ->
- foreach(Fun, List) -> void() + Apply a function to each element of a list - - Fun = fun(Elem) -> void() -  Elem = term() - List = [term()] - -

Calls Fun(Elem) for each element Elem in - List. This function is used for its side effects and +

Calls Fun(Elem) for each element Elem in + List. This function is used for its side effects and the evaluation order is defined to be the same as the order of the elements in the list.

- keydelete(Key, N, TupleList1) -> TupleList2 + Delete an element from a list of tuples - - Key = term() - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = [Tuple] -  Tuple = tuple() - + 1..tuple_size(Tuple) -

Returns a copy of TupleList1 where the first - occurrence of a tuple whose Nth element compares equal to - Key is deleted, if there is such a tuple.

+

Returns a copy of TupleList1 where the first + occurrence of a tuple whose Nth element compares equal to + Key is deleted, if there is such a tuple.

@@ -343,19 +264,14 @@ flatmap(Fun, List1) -> - keymap(Fun, N, TupleList1) -> TupleList2 + Map a function over a list of tuples - - Fun = fun(Term1) -> Term2 -  Term1 = Term2 = term() - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = [tuple()] - + 1..tuple_size(Tuple)

Returns a list of tuples where, for each tuple in - TupleList1, the Nth element Term1 of the tuple + TupleList1, the Nth element Term1 of the tuple has been replaced with the result of calling - Fun(Term1).

+ Fun(Term1).

Examples:

 > Fun = fun(Atom) -> atom_to_list(Atom) end.
@@ -365,7 +281,7 @@ flatmap(Fun, List1) ->
       
     
     
-      keymember(Key, N, TupleList) -> bool()
+      keymember(Key, N, TupleList) -> boolean()
       Test for membership of a list of tuples
       
         Key = term()
@@ -380,37 +296,28 @@ flatmap(Fun, List1) ->
       
     
     
-      keymerge(N, TupleList1, TupleList2) -> TupleList3
+      
       Merge two key-sorted lists of tuples
-      
-        N = 1..tuple_size(Tuple)
-        TupleList1 = TupleList2 = TupleList3 = [Tuple]
-         Tuple = tuple()
-      
+      1..tuple_size(Tuple)
       
-        

Returns the sorted list formed by merging TupleList1 - and TupleList2. The merge is performed on - the Nth element of each tuple. Both TupleList1 and - TupleList2 must be key-sorted prior to evaluating this +

Returns the sorted list formed by merging TupleList1 + and TupleList2. The merge is performed on + the Nth element of each tuple. Both TupleList1 and + TupleList2 must be key-sorted prior to evaluating this function. When two tuples compare equal, the tuple from - TupleList1 is picked before the tuple from - TupleList2.

+ TupleList1 is picked before the tuple from + TupleList2.

- keyreplace(Key, N, TupleList1, NewTuple) -> TupleList2 + Replace an element in a list of tuples - - Key = term() - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = [Tuple] - NewTuple = Tuple = tuple() - + 1..tuple_size(Tuple) -

Returns a copy of TupleList1 where the first - occurrence of a T tuple whose Nth element - compares equal to Key is replaced with - NewTuple, if there is such a tuple T.

+

Returns a copy of TupleList1 where the first + occurrence of a T tuple whose Nth element + compares equal to Key is replaced with + NewTuple, if there is such a tuple T.

@@ -433,95 +340,63 @@ flatmap(Fun, List1) -> - keysort(N, TupleList1) -> TupleList2 + Sort a list of tuples - - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = [Tuple] -  Tuple = tuple() - + 1..tuple_size(Tuple)

Returns a list containing the sorted elements of the list - TupleList1. Sorting is performed on the Nth + TupleList1. Sorting is performed on the Nth element of the tuples. The sort is stable.

- keystore(Key, N, TupleList1, NewTuple) -> TupleList2 + Store an element in a list of tuples - - Key = term() - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = [Tuple] - NewTuple = Tuple = tuple() - - -

Returns a copy of TupleList1 where the first - occurrence of a tuple T whose Nth element - compares equal to Key is replaced with - NewTuple, if there is such a tuple T. If there - is no such tuple T a copy of TupleList1 where - [NewTuple] has been appended to the end is + 1..tuple_size(Tuple) + +

Returns a copy of TupleList1 where the first + occurrence of a tuple T whose Nth element + compares equal to Key is replaced with + NewTuple, if there is such a tuple T. If there + is no such tuple T a copy of TupleList1 where + [NewTuple] has been appended to the end is returned.

- keytake(Key, N, TupleList1) -> {value, Tuple, TupleList2} - | false + Extract an element from a list of tuples - - Key = term() - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = [Tuple] - Tuple = tuple() - + 1..tuple_size(Tuple) -

Searches the list of tuples TupleList1 for a tuple - whose Nth element compares equal to Key. - Returns {value, Tuple, TupleList2} if such a tuple is - found, otherwise false. TupleList2 is a copy - of TupleList1 where the first occurrence of - Tuple has been removed.

+

Searches the list of tuples TupleList1 for a tuple + whose Nth element compares equal to Key. + Returns {value, Tuple, TupleList2} if such a tuple is + found, otherwise false. TupleList2 is a copy + of TupleList1 where the first occurrence of + Tuple has been removed.

- last(List) -> Last + Return last element in a list - - List = [term()], length(List) > 0 - Last = term() - -

Returns the last element in List.

+

Returns the last element in List.

- map(Fun, List1) -> List2 + Map a function over a list - - Fun = fun(A) -> B - List1 = [A] - List2 = [B] -  A = B = term() - -

Takes a function from As to Bs, and a list of - As and produces a list of Bs by applying +

Takes a function from As to Bs, and a list of + As and produces a list of Bs by applying the function to every element in the list. This function is used to obtain the return values. The evaluation order is implementation dependent.

- mapfoldl(Fun, Acc0, List1) -> {List2, Acc1} + Map and fold in one pass - - Fun = fun(A, AccIn) -> {B, AccOut} - Acc0 = Acc1 = AccIn = AccOut = term() - List1 = [A] - List2 = [B] -  A = B = term() -

mapfoldl combines the operations of map/2 and foldl/3 into one pass. An example, summing @@ -533,35 +408,24 @@ flatmap(Fun, List1) -> - mapfoldr(Fun, Acc0, List1) -> {List2, Acc1} + Map and fold in one pass - - Fun = fun(A, AccIn) -> {B, AccOut} - Acc0 = Acc1 = AccIn = AccOut = term() - List1 = [A] - List2 = [B] -  A = B = term() -

mapfoldr combines the operations of map/2 and foldr/3 into one pass.

- max(List) -> Max + Return maximum element of a list - - List = [term()], length(List) > 0 - Max = term() - -

Returns the first element of List that compares +

Returns the first element of List that compares greater than or equal to all other elements of - List.

+ List.

- member(Elem, List) -> bool() + member(Elem, List) -> boolean() Test for membership of a list Elem = term() @@ -573,112 +437,84 @@ flatmap(Fun, List1) -> - merge(ListOfLists) -> List1 + Merge a list of sorted lists - - ListOfLists = [List] - List = List1 = [term()] -

Returns the sorted list formed by merging all the sub-lists - of ListOfLists. All sub-lists must be sorted prior to + of ListOfLists. All sub-lists must be sorted prior to evaluating this function. When two elements compare equal, the element from the sub-list with the lowest position in - ListOfLists is picked before the other element.

+ ListOfLists is picked before the other element.

- merge(List1, List2) -> List3 + Merge two sorted lists - - List1 = List2 = List3 = [term()] - -

Returns the sorted list formed by merging List1 and - List2. Both List1 and List2 must be +

Returns the sorted list formed by merging List1 and + List2. Both List1 and List2 must be sorted prior to evaluating this function. When two elements - compare equal, the element from List1 is picked - before the element from List2.

+ compare equal, the element from List1 is picked + before the element from List2.

- merge(Fun, List1, List2) -> List3 + Merge two sorted list - - Fun = fun(A, B) -> bool() - List1 = [A] - List2 = [B] - List3 = [A | B] -  A = B = term() - -

Returns the sorted list formed by merging List1 and - List2. Both List1 and List2 must be +

Returns the sorted list formed by merging List1 and + List2. Both List1 and List2 must be sorted according to the ordering function - Fun prior to evaluating this function. Fun(A, - B) should return true if A compares less - than or equal to B in the ordering, false + Fun prior to evaluating this function. Fun(A, + B) should return true if A compares less + than or equal to B in the ordering, false otherwise. When two elements compare equal, the element from - List1 is picked before the element from - List2.

+ List1 is picked before the element from + List2.

- merge3(List1, List2, List3) -> List4 + Merge three sorted lists - - List1 = List2 = List3 = List4 = [term()] - -

Returns the sorted list formed by merging List1, - List2 and List3. All of List1, - List2 and List3 must be sorted prior to +

Returns the sorted list formed by merging List1, + List2 and List3. All of List1, + List2 and List3 must be sorted prior to evaluating this function. When two elements compare equal, - the element from List1, if there is such an element, + the element from List1, if there is such an element, is picked before the other element, otherwise the element - from List2 is picked before the element from - List3.

+ from List2 is picked before the element from + List3.

- min(List) -> Min + Return minimum element of a list - - List = [term()], length(List) > 0 - Min = term() - -

Returns the first element of List that compares +

Returns the first element of List that compares less than or equal to all other elements of - List.

+ List.

- nth(N, List) -> Elem + Return the Nth element of a list - - N = 1..length(List) - List = [term()] - Elem = term() - + 1..length(List) -

Returns the Nth element of List. For example:

+

Returns the Nth element of List. For example:

 > lists:nth(3, [a, b, c, d, e]).
 c
- nthtail(N, List1) -> Tail + Return the Nth tail of a list - - N = 0..length(List1) - List1 = Tail = [term()] - + 0..length(List) -

Returns the Nth tail of List, that is, the sublist of - List starting at N+1 and continuing up to +

Returns the Nth tail of List, that is, the sublist of + List starting at N+1 and continuing up to the end of the list. For example:

 > lists:nthtail(3, [a, b, c, d, e]).
@@ -692,18 +528,13 @@ c
- partition(Pred, List) -> {Satisfying, NonSatisfying} + Partition a list into two lists based on a predicate - - Pred = fun(Elem) -> bool() -  Elem = term() - List = Satisfying = NonSatisfying = [term()] - -

Partitions List into two lists, where the first list - contains all elements for which Pred(Elem) returns +

Partitions List into two lists, where the first list + contains all elements for which Pred(Elem) returns true, and the second list contains all elements for - which Pred(Elem) returns false.

+ which Pred(Elem) returns false.

Examples:

 > lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).
@@ -715,24 +546,18 @@ c
- prefix(List1, List2) -> bool() + Test for list prefix - - List1 = List2 = [term()] - -

Returns true if List1 is a prefix of - List2, otherwise false.

+

Returns true if List1 is a prefix of + List2, otherwise false.

- reverse(List1) -> List2 + Reverse a list - - List1 = List2 = [term()] - -

Returns a list with the top level elements in List1 +

Returns a list with the elements in List1 in reverse order.

@@ -743,7 +568,7 @@ c
List1 = Tail = List2 = [term()] -

Returns a list with the top level elements in List1 +

Returns a list with the elements in List1 in reverse order, with the tail Tail appended. For example:

@@ -752,22 +577,18 @@ c
- seq(From, To) -> Seq - seq(From, To, Incr) -> Seq + + Generate a sequence of integers - - From = To = Incr = int() - Seq = [int()] - -

Returns a sequence of integers which starts with From - and contains the successive results of adding Incr to - the previous element, until To has been reached or - passed (in the latter case, To is not an element of - the sequence). Incr defaults to 1.

-

Failure: If and Incr - is positive, or if To>From-Incr and Incr is - negative, or if Incr==0 and From/=To.

+

Returns a sequence of integers which starts with From + and contains the successive results of adding Incr to + the previous element, until To has been reached or + passed (in the latter case, To is not an element of + the sequence). Incr defaults to 1.

+

Failure: If To<From-Incr and Incr + is positive, or if To>From-Incr and Incr is + negative, or if Incr==0 and From/=To.

The following equalities hold for all sequences:

length(lists:seq(From, To)) == To-From+1 @@ -787,57 +608,41 @@ length(lists:seq(From, To, Incr)) == (To-From+Incr) div Incr
- sort(List1) -> List2 + Sort a list - - List1 = List2 = [term()] -

Returns a list containing the sorted elements of - List1.

+ List1.

- sort(Fun, List1) -> List2 + Sort a list - - Fun = fun(Elem1, Elem2) -> bool() -  Elem1 = Elem2 = term() - List1 = List2 = [term()] -

Returns a list containing the sorted elements of - List1, according to the List1, according to the ordering function - Fun. Fun(A, B) should return true if - A compares less than or equal to B in the + Fun. Fun(A, B) should return true if + A compares less than or equal to B in the ordering, false otherwise.

- split(N, List1) -> {List2, List3} + Split a list into two lists - - N = 0..length(List1) - List1 = List2 = List3 = [term()] - + 0..length(List1) -

Splits List1 into List2 and List3. - List2 contains the first N elements and - List3 the rest of the elements (the Nth tail).

+

Splits List1 into List2 and List3. + List2 contains the first N elements and + List3 the rest of the elements (the Nth tail).

- splitwith(Pred, List) -> {List1, List2} + Split a list into two lists based on a predicate - - Pred = fun(Elem) -> bool() -  Elem = term() - List = List1 = List2 = [term()] - -

Partitions List into two lists according to - Pred. splitwith/2 behaves as if it is defined +

Partitions List into two lists according to + Pred. splitwith/2 behaves as if it is defined as follows:

splitwith(Pred, List) -> @@ -853,31 +658,23 @@ splitwith(Pred, List) ->
- sublist(List1, Len) -> List2 + Return a sub-list of a certain length, starting at the first position - - List1 = List2 = [term()] - Len = int() - -

Returns the sub-list of List1 starting at position 1 - and with (max) Len elements. It is not an error for - Len to exceed the length of the list -- in that case +

Returns the sub-list of List1 starting at position 1 + and with (max) Len elements. It is not an error for + Len to exceed the length of the list -- in that case the whole list is returned.

- sublist(List1, Start, Len) -> List2 + Return a sub-list starting at a given position and with a given number of elements - - List1 = List2 = [term()] - Start = 1..(length(List1)+1) - Len = int() - + 1..(length(List1)+1) -

Returns the sub-list of List1 starting at Start - and with (max) Len elements. It is not an error for - Start+Len to exceed the length of the list.

+

Returns the sub-list of List1 starting at Start + and with (max) Len elements. It is not an error for + Start+Len to exceed the length of the list.

 > lists:sublist([1,2,3,4], 2, 2).
 [2,3]
@@ -888,15 +685,12 @@ splitwith(Pred, List) ->
       
     
     
-      subtract(List1, List2) -> List3
+      
       Subtract the element in one list from another list
-      
-        List1 = List2 = List3 = [term()]
-      
       
-        

Returns a new list List3 which is a copy of - List1, subjected to the following procedure: for each - element in List2, its first occurrence in List1 +

Returns a new list List3 which is a copy of + List1, subjected to the following procedure: for each + element in List2, its first occurrence in List1 is deleted. For example:

 > lists:subtract("123212", "212").
@@ -911,151 +705,112 @@ splitwith(Pred, List) ->
       
     
     
-      suffix(List1, List2) -> bool()
+      
       Test for list suffix
       
-        

Returns true if List1 is a suffix of - List2, otherwise false.

+

Returns true if List1 is a suffix of + List2, otherwise false.

- sum(List) -> number() + Return sum of elements in a list - - List = [number()] - -

Returns the sum of the elements in List.

+

Returns the sum of the elements in List.

- takewhile(Pred, List1) -> List2 + Take elements from a list while a predicate is true - - Pred = fun(Elem) -> bool() -  Elem = term() - List1 = List2 = [term()] - -

Takes elements Elem from List1 while - Pred(Elem) returns true, that is, +

Takes elements Elem from List1 while + Pred(Elem) returns true, that is, the function returns the longest prefix of the list for which all elements satisfy the predicate.

- ukeymerge(N, TupleList1, TupleList2) -> TupleList3 + Merge two key-sorted lists of tuples, removing duplicates - - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = TupleList3 = [Tuple] -  Tuple = tuple() - + 1..tuple_size(Tuple) -

Returns the sorted list formed by merging TupleList1 - and TupleList2. The merge is performed on the - Nth element of each tuple. Both TupleList1 and - TupleList2 must be key-sorted without duplicates +

Returns the sorted list formed by merging TupleList1 + and TupleList2. The merge is performed on the + Nth element of each tuple. Both TupleList1 and + TupleList2 must be key-sorted without duplicates prior to evaluating this function. When two tuples compare - equal, the tuple from TupleList1 is picked and the - one from TupleList2 deleted.

+ equal, the tuple from TupleList1 is picked and the + one from TupleList2 deleted.

- ukeysort(N, TupleList1) -> TupleList2 + Sort a list of tuples, removing duplicates - - N = 1..tuple_size(Tuple) - TupleList1 = TupleList2 = [Tuple] -  Tuple = tuple() - + 1..tuple_size(Tuple)

Returns a list containing the sorted elements of the list - TupleList1 where all but the first tuple of the + TupleList1 where all but the first tuple of the tuples comparing equal have been deleted. Sorting is - performed on the Nth element of the tuples.

+ performed on the Nth element of the tuples.

- umerge(ListOfLists) -> List1 + Merge a list of sorted lists, removing duplicates - - ListOfLists = [List] - List = List1 = [term()] -

Returns the sorted list formed by merging all the sub-lists - of ListOfLists. All sub-lists must be sorted and + of ListOfLists. All sub-lists must be sorted and contain no duplicates prior to evaluating this function. When two elements compare equal, the element from the - sub-list with the lowest position in ListOfLists is + sub-list with the lowest position in ListOfLists is picked and the other one deleted.

- umerge(List1, List2) -> List3 + Merge two sorted lists, removing duplicates - - List1 = List2 = List3 = [term()] - -

Returns the sorted list formed by merging List1 and - List2. Both List1 and List2 must be +

Returns the sorted list formed by merging List1 and + List2. Both List1 and List2 must be sorted and contain no duplicates prior to evaluating this function. When two elements compare equal, the element from - List1 is picked and the one from List2 + List1 is picked and the one from List2 deleted.

- umerge(Fun, List1, List2) -> List3 + Merge two sorted lists, removing duplicates - - Fun = fun(A, B) -> bool() - List1 = [A] - List2 = [B] - List3 = [A | B] -  A = B = term() - -

Returns the sorted list formed by merging List1 and - List2. Both List1 and List2 must be +

Returns the sorted list formed by merging List1 and + List2. Both List1 and List2 must be sorted according to the ordering function Fun and contain no duplicates prior to evaluating - this function. Fun(A, B) should return true if - A compares less than or equal to B in the + this function. Fun(A, B) should return true if + A compares less than or equal to B in the ordering, false otherwise. When two elements compare equal, the element from - List1 is picked and the one from List2 + List1 is picked and the one from List2 deleted.

- umerge3(List1, List2, List3) -> List4 + Merge three sorted lists, removing duplicates - - List1 = List2 = List3 = List4 = [term()] - -

Returns the sorted list formed by merging List1, - List2 and List3. All of List1, - List2 and List3 must be sorted and contain no +

Returns the sorted list formed by merging List1, + List2 and List3. All of List1, + List2 and List3 must be sorted and contain no duplicates prior to evaluating this function. When two - elements compare equal, the element from List1 is + elements compare equal, the element from List1 is picked if there is such an element, otherwise the element - from List2 is picked, and the other one deleted.

+ from List2 is picked, and the other one deleted.

- unzip(List1) -> {List2, List3} + Unzip a list of two-tuples into two lists - - List1 = [{X, Y}] - List2 = [X] - List3 = [Y] -  X = Y = term() -

"Unzips" a list of two-tuples into two lists, where the first list contains the first element of each tuple, and the second @@ -1063,15 +818,8 @@ splitwith(Pred, List) -> - unzip3(List1) -> {List2, List3, List4} + Unzip a list of three-tuples into three lists - - List1 = [{X, Y, Z}] - List2 = [X] - List3 = [Y] - List4 = [Z] -  X = Y = Z = term() -

"Unzips" a list of three-tuples into three lists, where the first list contains the first element of each tuple, @@ -1080,44 +828,30 @@ splitwith(Pred, List) -> - usort(List1) -> List2 + Sort a list, removing duplicates - - List1 = List2 = [term()] -

Returns a list containing the sorted elements of - List1 where all but the first element of the elements + List1 where all but the first element of the elements comparing equal have been deleted.

- usort(Fun, List1) -> List2 + Sort a list, removing duplicates - - Fun = fun(Elem1, Elem2) -> bool() -  Elem1 = Elem2 = term() - List1 = List2 = [term()] -

Returns a list which contains the sorted elements of - List1 where all but the first element of the elements + List1 where all but the first element of the elements comparing equal according to the ordering function - Fun have been deleted. Fun(A, B) should return + Fun have been deleted. Fun(A, B) should return true if A compares less than or equal to B in the ordering, false otherwise.

- zip(List1, List2) -> List3 + Zip two lists into a list of two-tuples - - List1 = [X] - List2 = [Y] - List3 = [{X, Y}] -  X = Y = term() -

"Zips" two lists of equal length into one list of two-tuples, where the first element of each tuple is taken from the first @@ -1126,15 +860,8 @@ splitwith(Pred, List) -> - zip3(List1, List2, List3) -> List4 + Zip three lists into a list of three-tuples - - List1 = [X] - List2 = [Y] - List3 = [Z] - List3 = [{X, Y, Z}] -  X = Y = Z = term() -

"Zips" three lists of equal length into one list of three-tuples, where the first element of each tuple is taken @@ -1145,20 +872,13 @@ splitwith(Pred, List) -> - zipwith(Combine, List1, List2) -> List3 + Zip two lists into one list according to a fun - - Combine = fun(X, Y) -> T - List1 = [X] - List2 = [Y] - List3 = [T] -  X = Y = T = term() -

Combine the elements of two lists of equal length into one - list. For each pair X, Y of list elements from the two + list. For each pair X, Y of list elements from the two lists, the element in the result list will be - Combine(X, Y).

+ Combine(X, Y).

zipwith(fun(X, Y) -> {X,Y} end, List1, List2) is equivalent to zip(List1, List2).

Example:

@@ -1168,21 +888,13 @@ splitwith(Pred, List) ->
- zipwith3(Combine, List1, List2, List3) -> List4 + Zip three lists into one list according to a fun - - Combine = fun(X, Y, Z) -> T - List1 = [X] - List2 = [Y] - List3 = [Z] - List4 = [T] -  X = Y = Z = T = term() -

Combine the elements of three lists of equal length into one - list. For each triple X, Y, Z of list elements from + list. For each triple X, Y, Z of list elements from the three lists, the element in the result list will be - Combine(X, Y, Z).

+ Combine(X, Y, Z).

zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3) is equivalent to zip3(List1, List2, List3).

Examples:

diff --git a/lib/stdlib/doc/src/log_mf_h.xml b/lib/stdlib/doc/src/log_mf_h.xml
index f8e11339a7..f2b09b58eb 100644
--- a/lib/stdlib/doc/src/log_mf_h.xml
+++ b/lib/stdlib/doc/src/log_mf_h.xml
@@ -43,28 +43,27 @@
       report files 1, 2, .....
       

+ + + +

Term to be sent to + gen_event:add_handler/3.

+
+
- init(Dir, MaxBytes, MaxFiles) - init(Dir, MaxBytes, MaxFiles, Pred) -> Args + + Initiate the event handler - - Dir = string() - MaxBytes = integer() - MaxFiles = 0 < integer() < 256 - Pred = fun(Event) -> boolean() - Event = term() - Args = args() -

Initiates the event handler. This function returns - Args, which should be used in a call to - gen_event:add_handler(EventMgr, log_mf_h, Args). + Args, which should be used in a call to + gen_event:add_handler(EventMgr, log_mf_h, Args).

-

Dir specifies which directory to use for the log - files. MaxBytes specifies the size of each individual - file. MaxFiles specifies how many files are - used. Pred is a predicate function used to filter the +

Dir specifies which directory to use for the log + files. MaxBytes specifies the size of each individual + file. MaxFiles specifies how many files are + used. Pred is a predicate function used to filter the events. If no predicate function is specified, all events are logged.

diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index 02e4d6e495..518457d5d8 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -45,7 +45,7 @@ - pi() -> float() + A useful number

A useful number.

diff --git a/lib/stdlib/doc/src/ms_transform.xml b/lib/stdlib/doc/src/ms_transform.xml index ba9f89685b..f81f8bda96 100644 --- a/lib/stdlib/doc/src/ms_transform.xml +++ b/lib/stdlib/doc/src/ms_transform.xml @@ -4,7 +4,7 @@
- 20022010 + 20022011 Ericsson AB. All Rights Reserved. @@ -599,12 +599,9 @@ ets:select(Table, [{{'$1',test,'$2'},[],['$_']}]). - parse_transform(Forms,_Options) -> Forms + Transforms Erlang abstract format containing calls to ets/dbg:fun2ms into literal match specifications. - - Forms = Erlang abstract code format, see the erl_parse module description - _Options = Option list, required but not used - + Option list, required but not used.

Implements the actual transformation at compile time. This function is called by the compiler to do the source code @@ -617,29 +614,21 @@ ets:select(Table, [{{'$1',test,'$2'},[],['$_']}]). - transform_from_shell(Dialect,Clauses,BoundEnvironment) -> term() + Used when transforming fun's created in the shell into match_specifications. - - Dialect = ets | dbg - Clauses = Erlang abstract form for a single fun - BoundEnvironment = [{atom(), term()}, ...], list of variable bindings in the shell environment - + List of variable bindings in the shell environment.

Implements the actual transformation when the fun2ms functions are called from the shell. In this case the abstract form is for one single fun (parsed by the Erlang shell), and all imported variables should be in the key-value list passed - as BoundEnvironment. The result is a term, normalized, + as BoundEnvironment. The result is a term, normalized, i.e. not in abstract format.

- format_error(Errcode) -> ErrMessage + Error formatting function as required by the parse_transform interface. - - Errcode = term() - ErrMessage = string() -

Takes an error code returned by one of the other functions in the module and creates a textual description of the diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 1b8b74534b..319083d35b 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -46,176 +46,123 @@ (==).

-
- DATA TYPES - -ordered_dictionary() - as returned by new/0 -
+ + + +

As returned by new/0.

+
+
+ - append(Key, Value, Orddict1) -> Orddict2 + Append a value to keys in a dictionary - - Key = Value = term() - Orddict1 = Orddict2 = ordered_dictionary() - -

This function appends a new Value to the current list - of values associated with Key. An exception is - generated if the initial value associated with Key is +

This function appends a new Value to the current list + of values associated with Key. An exception is + generated if the initial value associated with Key is not a list of values.

- append_list(Key, ValList, Orddict1) -> Orddict2 + Append new values to keys in a dictionary - - ValList = [Value] - Key = Value = term() - Orddict1 = Orddict2 = ordered_dictionary() - -

This function appends a list of values ValList to - the current list of values associated with Key. An +

This function appends a list of values ValList to + the current list of values associated with Key. An exception is generated if the initial value associated with - Key is not a list of values.

+ Key is not a list of values.

- erase(Key, Orddict1) -> Orddict2 + Erase a key from a dictionary - - Key = term() - Orddict1 = Orddict2 = ordered_dictionary() -

This function erases all items with a given key from a dictionary.

- fetch(Key, Orddict) -> Value + Look-up values in a dictionary - - Key = Value = term() - Orddict = ordered_dictionary() - -

This function returns the value associated with Key - in the dictionary Orddict. fetch assumes that - the Key is present in the dictionary and an exception - is generated if Key is not in the dictionary.

+

This function returns the value associated with Key + in the dictionary Orddict. fetch assumes that + the Key is present in the dictionary and an exception + is generated if Key is not in the dictionary.

- fetch_keys(Orddict) -> Keys + Return all keys in a dictionary - - Orddict = ordered_dictionary() - Keys = [term()] -

This function returns a list of all keys in the dictionary.

- filter(Pred, Orddict1) -> Orddict2 + Choose elements which satisfy a predicate - - Pred = fun(Key, Value) -> bool() -  Key = Value = term() - Orddict1 = Orddict2 = ordered_dictionary() - -

Orddict2 is a dictionary of all keys and values in - Orddict1 for which Pred(Key, Value) is true.

+

Orddict2 is a dictionary of all keys and values in + Orddict1 for which Pred(Key, Value) is true.

- find(Key, Orddict) -> {ok, Value} | error + Search for a key in a dictionary - - Key = Value = term() - Orddict = ordered_dictionary() -

This function searches for a key in a dictionary. Returns - {ok, Value} where Value is the value associated - with Key, or error if the key is not present in + {ok, Value} where Value is the value associated + with Key, or error if the key is not present in the dictionary.

- fold(Fun, Acc0, Orddict) -> Acc1 + Fold a function over a dictionary - - Fun = fun(Key, Value, AccIn) -> AccOut - Key = Value = term() - Acc0 = Acc1 = AccIn = AccOut = term() - Orddict = ordered_dictionary() - -

Calls Fun on successive keys and values of - Orddict together with an extra argument Acc - (short for accumulator). Fun must return a new - accumulator which is passed to the next call. Acc0 is +

Calls Fun on successive keys and values of + Orddict together with an extra argument Acc + (short for accumulator). Fun must return a new + accumulator which is passed to the next call. Acc0 is returned if the list is empty. The evaluation order is undefined.

- from_list(List) -> Orddict + Convert a list of pairs to a dictionary - - List = [{Key, Value}] - Orddict = ordered_dictionary() - -

This function converts the Key - Value list - List to a dictionary.

+

This function converts the Key - Value list + List to a dictionary.

- is_key(Key, Orddict) -> bool() + Test if a key is in a dictionary - - Key = term() - Orddict = ordered_dictionary() - -

This function tests if Key is contained in - the dictionary Orddict.

+

This function tests if Key is contained in + the dictionary Orddict.

- map(Fun, Orddict1) -> Orddict2 + Map a function over a dictionary - - Fun = fun(Key, Value1) -> Value2 -  Key = Value1 = Value2 = term() - Orddict1 = Orddict2 = ordered_dictionary() - -

map calls Func on successive keys and values - of Orddict to return a new value for each key. +

map calls Fun on successive keys and values + of Orddict1 to return a new value for each key. The evaluation order is undefined.

- merge(Fun, Orddict1, Orddict2) -> Orddict3 + Merge two dictionaries - - Fun = fun(Key, Value1, Value2) -> Value -  Key = Value1 = Value2 = Value3 = term() - Orddict1 = Orddict2 = Orddict3 = ordered_dictionary() - -

merge merges two dictionaries, Orddict1 and - Orddict2, to create a new dictionary. All the Key - - Value pairs from both dictionaries are included in +

merge merges two dictionaries, Orddict1 and + Orddict2, to create a new dictionary. All the Key + - Value pairs from both dictionaries are included in the new dictionary. If a key occurs in both dictionaries then - Fun is called with the key and both values to return a + Fun is called with the key and both values to return a new value. merge could be defined as:

merge(Fun, D1, D2) -> @@ -226,75 +173,52 @@ merge(Fun, D1, D2) ->
- new() -> ordered_dictionary() + Create a dictionary

This function creates a new dictionary.

- size(Orddict) -> int() + Return the number of elements in an ordered dictionary - - Orddict = ordered_dictionary() - -

Returns the number of elements in an Orddict.

+

Returns the number of elements in an Orddict.

- store(Key, Value, Orddict1) -> Orddict2 + Store a value in a dictionary - - Key = Value = term() - Orddict1 = Orddict2 = ordered_dictionary() - -

This function stores a Key - Value pair in a - dictionary. If the Key already exists in Orddict1, - the associated value is replaced by Value.

+

This function stores a Key - Value pair in a + dictionary. If the Key already exists in Orddict1, + the associated value is replaced by Value.

- to_list(Orddict) -> List + Convert a dictionary to a list of pairs - - Orddict = ordered_dictionary() - List = [{Key, Value}] -

This function converts the dictionary to a list representation.

- update(Key, Fun, Orddict1) -> Orddict2 + Update a value in a dictionary - - Key = term() - Fun = fun(Value1) -> Value2 -  Value1 = Value2 = term() - Orddict1 = Orddict2 = ordered_dictionary() - -

Update a value in a dictionary by calling Fun on +

Update a value in a dictionary by calling Fun on the value to get a new value. An exception is generated if - Key is not present in the dictionary.

+ Key is not present in the dictionary.

- update(Key, Fun, Initial, Orddict1) -> Orddict2 + Update a value in a dictionary - - Key = Initial = term() - Fun = fun(Value1) -> Value2 -  Value1 = Value2 = term() - Orddict1 = Orddict2 = ordered_dictionary() - -

Update a value in a dictionary by calling Fun on - the value to get a new value. If Key is not present - in the dictionary then Initial will be stored as +

Update a value in a dictionary by calling Fun on + the value to get a new value. If Key is not present + in the dictionary then Initial will be stored as the first value. For example append/3 could be defined as:

@@ -303,17 +227,12 @@ append(Key, Val, D) ->
- update_counter(Key, Increment, Orddict1) -> Orddict2 + Increment a value in a dictionary - - Key = term() - Increment = number() - Orddict1 = Orddict2 = ordered_dictionary() - -

Add Increment to the value associated with Key - and store this value. If Key is not present in - the dictionary then Increment will be stored as +

Add Increment to the value associated with Key + and store this value. If Key is not present in + the dictionary then Increment will be stored as the first value.

This could be defined as:

diff --git a/lib/stdlib/doc/src/ordsets.xml b/lib/stdlib/doc/src/ordsets.xml index a20ab2d879..1e26fc2022 100644 --- a/lib/stdlib/doc/src/ordsets.xml +++ b/lib/stdlib/doc/src/ordsets.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -45,202 +45,141 @@ different if and only if they do not compare equal (==).

-
- DATA TYPES - -ordered_set() - as returned by new/0 -
+ + + +

As returned by new/0.

+
+
- new() -> Ordset + Return an empty set - - Ordset = ordered_set() -

Returns a new empty ordered set.

- is_set(Ordset) -> bool() + Test for an Ordset - - Ordset = term() - -

Returns true if Ordset is an ordered set of +

Returns true if Ordset is an ordered set of elements, otherwise false.

- size(Ordset) -> int() + Return the number of elements in a set - - Ordset = term() - -

Returns the number of elements in Ordset.

+

Returns the number of elements in Ordset.

- to_list(Ordset) -> List + Convert an Ordsetinto a list - - Ordset = ordered_set() - List = [term()] - -

Returns the elements of Ordset as a list.

+

Returns the elements of Ordset as a list.

- from_list(List) -> Ordset + Convert a list into an Ordset - - List = [term()] - Ordset = ordered_set() - -

Returns an ordered set of the elements in List.

+

Returns an ordered set of the elements in List.

- is_element(Element, Ordset) -> bool() + Test for membership of an Ordset - - Element = term() - Ordset = ordered_set() - -

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

+

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

- add_element(Element, Ordset1) -> Ordset2 + Add an element to an Ordset - - Element = term() - Ordset1 = Ordset2 = ordered_set() - -

Returns a new ordered set formed from Ordset1 with - Element inserted.

+

Returns a new ordered set formed from Ordset1 with + Element inserted.

- del_element(Element, Ordset1) -> Ordset2 + Remove an element from an Ordset - - Element = term() - Ordset1 = Ordset2 = ordered_set() - -

Returns Ordset1, but with Element removed.

+

Returns Ordset1, but with Element removed.

- union(Ordset1, Ordset2) -> Ordset3 + Return the union of two Ordsets - - Ordset1 = Ordset2 = Ordset3 = ordered_set() - -

Returns the merged (union) set of Ordset1 and - Ordset2.

+

Returns the merged (union) set of Ordset1 and + Ordset2.

- union(OrdsetList) -> Ordset + Return the union of a list of Ordsets - - OrdsetList = [ordered_set()] - Ordset = ordered_set() -

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

- intersection(Ordset1, Ordset2) -> Ordset3 + Return the intersection of two Ordsets - - Ordset1 = Ordset2 = Ordset3 = ordered_set() - -

Returns the intersection of Ordset1 and - Ordset2.

+

Returns the intersection of Ordset1 and + Ordset2.

- intersection(OrdsetList) -> Ordset + Return the intersection of a list of Ordsets - - OrdsetList = [ordered_set()] - Ordset = ordered_set() -

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

- is_disjoint(Ordset1, Ordset2) -> bool() + Check whether two Ordsets are disjoint - - Ordset1 = Ordset2 = ordered_set() - -

Returns true if Ordset1 and - Ordset2 are disjoint (have no elements in common), +

Returns true if Ordset1 and + Ordset2 are disjoint (have no elements in common), and false otherwise.

- subtract(Ordset1, Ordset2) -> Ordset3 + Return the difference of two Ordsets - - Ordset1 = Ordset2 = Ordset3 = ordered_set() - -

Returns only the elements of Ordset1 which are not - also elements of Ordset2.

+

Returns only the elements of Ordset1 which are not + also elements of Ordset2.

- is_subset(Ordset1, Ordset2) -> bool() + Test for subset - - Ordset1 = Ordset2 = ordered_set() - -

Returns true when every element of Ordset1 is - also a member of Ordset2, otherwise false.

+

Returns true when every element of Ordset1 is + also a member of Ordset2, otherwise false.

- fold(Function, Acc0, Ordset) -> Acc1 + Fold over set elements - - Function = fun (E, AccIn) -> AccOut - Acc0 = Acc1 = AccIn = AccOut = term() - Ordset = ordered_set() - -

Fold Function over every element in Ordset +

Fold Function over every element in Ordset returning the final value of the accumulator.

- filter(Pred, Ordset1) -> Set2 + Filter set elements - - Pred = fun (E) -> bool() - Set1 = Set2 = ordered_set() - -

Filter elements in Set1 with boolean function - Fun.

+

Filter elements in Ordset1 with boolean function + Pred.

diff --git a/lib/stdlib/doc/src/pg.xml b/lib/stdlib/doc/src/pg.xml index b174d4f7d4..c56db8c6e6 100644 --- a/lib/stdlib/doc/src/pg.xml +++ b/lib/stdlib/doc/src/pg.xml @@ -51,77 +51,56 @@ - create(PgName) -> ok | {error, Reason} + Create an empty group - - PgName = term() - Reason = already_created | term() - -

Creates an empty group named PgName on the current +

Creates an empty group named PgName on the current node.

- create(PgName, Node) -> ok | {error, Reason} + Create an empty group on another node - - PgName = term() - Node = node() - Reason = already_created | term() - -

Creates an empty group named PgName on the node - Node.

+

Creates an empty group named PgName on the node + Node.

- join(PgName, Pid) -> Members + Join a pid to a process group - - PgName = term() - Pid = pid() - Members = [pid()] - -

Joins the pid Pid to the process group PgName. +

Joins the pid Pid to the process group + PgName. Returns a list of all old members of the group.

- send(PgName, Msg) -> void() + Send a message to all members of a process group - - PgName = Msg = term() -

Sends the tuple {pg_message, From, PgName, Msg} to - all members of the process group PgName.

-

Failure: {badarg, {PgName, Msg}} if PgName is + all members of the process group PgName.

+

Failure: {badarg, {PgName, Msg}} + if PgName is not a process group (a globally registered name).

- esend(PgName, Msg) -> void() + Send a message to all members of a process group, except ourselves - - PgName = Msg = term() -

Sends the tuple {pg_message, From, PgName, Msg} to - all members of the process group PgName, except + all members of the process group PgName, except ourselves.

-

Failure: {badarg, {PgName, Msg}} if PgName is +

Failure: {badarg, {PgName, Msg}} + if PgName is not a process group (a globally registered name).

- members(PgName) -> Members + Return a list of all members of a process group - - PgName = term() - Members = [pid()] -

Returns a list of all members of the process group PgName.

diff --git a/lib/stdlib/doc/src/pool.xml b/lib/stdlib/doc/src/pool.xml index 2b890352eb..39a79e5dc5 100644 --- a/lib/stdlib/doc/src/pool.xml +++ b/lib/stdlib/doc/src/pool.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -48,23 +48,19 @@ - start(Name) -> - start(Name, Args) -> Nodes + + >Start a new pool - - Name = atom() - Args = string() - Nodes = [node()] -

Starts a new pool. The file .hosts.erlang is read to find host names where the pool nodes can be started. See section Files below. The start-up procedure fails if the file is not found.

The slave nodes are started with slave:start/2,3, - passing along Name and, if provided, Args. - Name is used as the first part of the node names, - Args is used to specify command line arguments. See + passing along Name and, if provided, + Args. + Name is used as the first part of the node names, + Args is used to specify command line arguments. See slave(3).

Access rights must be set so that all nodes in the pool have the authority to access each other.

@@ -73,59 +69,45 @@
- attach(Node) -> already_attached | attached + Ensure that a pool master is running - - Node = node() -

This function ensures that a pool master is running and - includes Node in the pool master's pool of nodes.

+ includes Node in the pool master's pool of nodes.

- stop() -> stopped + Stop the pool and kill all the slave nodes

Stops the pool and kills all the slave nodes.

- get_nodes() -> Nodes + Return a list of the current member nodes of the pool - - Nodes = [node()] -

Returns a list of the current member nodes of the pool.

- pspawn(Mod, Fun, Args) -> pid() + Spawn a process on the pool node with expected lowest future load - - Mod = Fun = atom() - Args = [term()] -

Spawns a process on the pool node which is expected to have the lowest future load.

- pspawn_link(Mod, Fun, Args) -> pid() + Spawn and link to a process on the pool node with expected lowest future load - - Mod = Fun = atom() - Args = [term()] -

Spawn links a process on the pool node which is expected to have the lowest future load.

- get_node() -> node() + Return the node with the expected lowest future load

Returns the node with the expected lowest future load.

diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index 791001cb52..abc17c4a91 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -60,19 +60,33 @@ information regarding other processes which terminate as a result of this process terminating.

+ + + + +

See + erlang:spawn_opt/2,3,4,5.

+
+
+ + + + + + +
- spawn(Fun) -> pid() - spawn(Node, Fun) -> pid() - spawn(Module, Function, Args) -> pid() - spawn(Node, Module, Function, Args) -> pid() + + + + Spawn a new process. - - Node = node() - Fun = fun() -> void() - Module = Function = atom() - Args = [term()] - + + + + +

Spawns a new process and initializes it as described above. The process is spawned using the @@ -80,17 +94,16 @@ - spawn_link(Fun) -> pid() - spawn_link(Node, Fun) -> pid() - spawn_link(Module, Function, Args) -> pid() - spawn_link(Node, Module, Function, Args) -> pid() + + + + Spawn and link to a new process. - - Node = node() - Fun = fun() -> void() - Module = Function = atom() - Args = [term()] - + + + + +

Spawns a new process and initializes it as described above. The process is spawned using the @@ -99,18 +112,17 @@ - spawn_opt(Fun, SpawnOpts) -> pid() - spawn_opt(Node, Fun, SpawnOpts) -> pid() - spawn_opt(Module, Function, Args, SpawnOpts) -> pid() - spawn_opt(Node, Module, Func, Args, SpawnOpts) -> pid() + + + + Spawn a new process with given options. - - Node = node() - Fun = fun() -> void() - Module = Function = atom() - Args = [term()] - SpawnOpts -- see erlang:spawn_opt/2,3,4,5 - + + + + + +

Spawns a new process and initializes it as described above. The process is spawned using the @@ -124,20 +136,13 @@ - start(Module, Function, Args) -> Ret - start(Module, Function, Args, Time) -> Ret - start(Module, Function, Args, Time, SpawnOpts) -> Ret - start_link(Module, Function, Args) -> Ret - start_link(Module, Function, Args, Time) -> Ret - start_link(Module, Function, Args, Time, SpawnOpts) -> Ret + + + + + + Start a new process synchronously. - - Module = Function = atom() - Args = [term()] - Time = int() >= 0 | infinity - SpawnOpts -- see erlang:spawn_opt/2,3,4,5 - Ret = term() | {error, Reason} -

Starts a new process synchronously. Spawns the process and waits for it to start. When the process has started, it @@ -148,13 +153,13 @@ function. At this time, Ret is returned.

If the start_link/3,4,5 function is used and the process crashes before it has called init_ack/1,2, - {error, Reason} is returned if the calling process + {error, Reason} is returned if the calling process traps exits.

-

If Time is specified as an integer, this function - waits for Time milliseconds for the new process to call +

If Time is specified as an integer, this function + waits for Time milliseconds for the new process to call init_ack, or {error, timeout} is returned, and the process is killed.

-

The SpawnOpts argument, if given, will be passed +

The SpawnOpts argument, if given, will be passed as the last argument to the spawn_opt/2,3,4,5 BIF.

Using the spawn option monitor is currently not @@ -164,17 +169,13 @@ - init_ack(Parent, Ret) -> void() - init_ack(Ret) -> void() + + Used by a process when it has started. - - Parent = pid() - Ret = term() -

This function must used by a process that has been started by a start[_link]/3,4,5 - function. It tells Parent that the process has + function. It tells Parent that the process has initialized itself, has started, or has failed to initialize itself.

The init_ack/1 function uses the parent value @@ -205,40 +206,30 @@ init(Parent) -> - format(CrashReport) -> string() + Format a crash report. - - CrashReport = term() -

This function can be used by a user defined event handler to format a crash report. The crash report is sent using - error_logger:error_report(crash_report, CrashReport). + error_logger:error_report(crash_report, CrashReport). That is, the event to be handled is of the format - {error_report, GL, {Pid, crash_report, CrashReport}} + {error_report, GL, {Pid, crash_report, CrashReport}} where GL is the group leader pid of the process Pid which sent the crash report.

- initial_call(Process) -> {Module,Function,Args} | false + Extract the initial call of a proc_libspawned process. - - Process = pid() | {X,Y,Z} | ProcInfo -  X = Y = Z = int() -  ProcInfo = term() - Module = Function = atom() - Args = [atom()] -

Extracts the initial call of a process that was started using one of the spawn or start functions described above. - Process can either be a pid, an integer tuple (from + Process can either be a pid, an integer tuple (from which a pid can be created), or the process information of a process Pid fetched through an erlang:process_info(Pid) function call.

-

The list Args no longer contains the actual arguments, +

The list Args no longer contains the actual arguments, but the same number of atoms as the number of arguments; the first atom is always 'Argument__1', the second 'Argument__2', and so on. The reason is that the argument list could waste a significant @@ -256,23 +247,15 @@ init(Parent) -> - translate_initial_call(Process) -> {Module,Function,Arity} | Fun + Extract and translate the initial call of a proc_libspawned process. - - Process = pid() | {X,Y,Z} | ProcInfo -  X = Y = Z = int() -  ProcInfo = term() - Module = Function = atom() - Arity = int() - Fun = fun() -> void() -

This function is used by the c:i/0 and c:regs/0 functions in order to present process information.

Extracts the initial call of a process that was started using one of the spawn or start functions described above, - and translates it to more useful information. Process + and translates it to more useful information. Process can either be a pid, an integer tuple (from which a pid can be created), or the process information of a process Pid fetched through an erlang:process_info(Pid) @@ -280,15 +263,15 @@ init(Parent) ->

If the initial call is to one of the system defined behaviors such as gen_server or gen_event, it is translated to more useful information. If a gen_server - is spawned, the returned Module is the name of - the callback module and Function is init + is spawned, the returned Module is the name of + the callback module and Function is init (the function that initiates the new server).

A supervisor and a supervisor_bridge are also gen_server processes. In order to return information that this process is a supervisor and the name of the - call-back module, Module is supervisor and - Function is the name of the supervisor callback - module. Arity is 1 since the init/1 + call-back module, Module is supervisor and + Function is the name of the supervisor callback + module. Arity is 1 since the init/1 function is called initially in the callback module.

By default, {proc_lib,init_p,5} is returned if no information about the initial call can be found. It is @@ -297,12 +280,8 @@ init(Parent) -> - hibernate(Module, Function, Args) + Hibernate a process until a message is sent to it - - Module = Function = atom() - Args = [term()] -

This function does the same as (and does call) the BIF hibernate/3, diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml index 9f1c5b24ad..225c5e97eb 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -4,7 +4,7 @@

- 20022010 + 20022011 Ericsson AB. All Rights Reserved. @@ -48,14 +48,15 @@ words, numbers are compared literally rather than by value, so that, for instance, 1 and 1.0 are different keys.

+ + + + + - append_values(Key, List) -> List + - - Key = term() - List = [term()] -

Similar to get_all_values/2, but each value is wrapped in a list unless it is already itself a list, and the @@ -65,11 +66,8 @@ - compact(List) -> List + - - List = [term()] -

Minimizes the representation of all entries in the list. This is equivalent to .

@@ -77,33 +75,24 @@
- delete(Key, List) -> List + - - Key = term() - List = [term()] - -

Deletes all entries associated with Key from - List.

+

Deletes all entries associated with Key from + List.

- expand(Expansions, List) -> List + - - Key = term() - Expansions = [{Property,[term()]}] - Property = atom() | tuple() -

Expands particular properties to corresponding sets of - properties (or other terms). For each pair {Property, Expansion} in Expansions, if E is - the first entry in List with the same key as - Property, and E and Property + properties (or other terms). For each pair {Property, Expansion} in Expansions, if E is + the first entry in List with the same key as + Property, and E and Property have equivalent normal forms, then E is replaced with - the terms in Expansion, and any following entries with - the same key are deleted from List.

+ the terms in Expansion, and any following entries with + the same key are deleted from List.

For example, the following expressions all return [fie, bar, baz, fum]:

expand([{foo, [bar, baz]}], @@ -120,103 +109,75 @@

Note that if the original property term is to be preserved in the result when expanded, it must be included in the expansion list. The inserted terms are not expanded recursively. If - Expansions contains more than one property with the same + Expansions contains more than one property with the same key, only the first occurrence is used.

See also: normalize/2.

- get_all_values(Key, List) -> [term()] + - - Key = term() - List = [term()] -

Similar to get_value/2, but returns the list of values for all entries {Key, Value} in - List. If no such entry exists, the result is the empty + List. If no such entry exists, the result is the empty list.

See also: get_value/2.

- get_bool(Key, List) -> bool() + - - Key = term() - List = [term()] -

Returns the value of a boolean key/value option. If - lookup(Key, List) would yield {Key, true}, + lookup(Key, List) would yield {Key, true}, this function returns true; otherwise false is returned.

See also: get_value/2, lookup/2.

- get_keys(List) -> [term()] + - - List = [term()] - -

Returns an unordered list of the keys used in List, +

Returns an unordered list of the keys used in List, not containing duplicates.

- get_value(Key, List) -> term() + - - Key = term() - List = [term()] - -

Equivalent to get_value(Key, List, undefined).

+

Equivalent to get_value(Key, List, undefined).

- get_value(Key, List, Default) -> term() + - - Key = term() - Default = term() - List = [term()] -

Returns the value of a simple key/value property in - List. If lookup(Key, List) would yield - {Key, Value}, this function returns the corresponding - Value, otherwise Default is returned.

+ List. If lookup(Key, List) would yield + {Key, Value}, this function returns the corresponding + Value, otherwise Default is returned.

See also: get_all_values/2, get_bool/2, get_value/2, lookup/2.

- is_defined(Key, List) -> bool() + - - Key = term() - List = [term()] - -

Returns true if List contains at least - one entry associated with Key, otherwise +

Returns true if List contains at least + one entry associated with Key, otherwise false is returned.

- lookup(Key, List) -> none | tuple() + - - Key = term() - List = [term()] - -

Returns the first entry associated with Key in - List, if one exists, otherwise returns +

Returns the first entry associated with Key in + List, if one exists, otherwise returns none. For an atom A in the list, the tuple {A, true} is the entry associated with A.

See also: get_bool/2, get_value/2, @@ -224,34 +185,20 @@ - lookup_all(Key, List) -> [tuple()] + - - Key = term() - List = [term()] - -

Returns the list of all entries associated with Key - in List. If no such entry exists, the result is the +

Returns the list of all entries associated with Key + in List. If no such entry exists, the result is the empty list.

See also: lookup/2.

- normalize(List, Stages) -> List + - - List = [term()] - Stages = [Operation] - Operation = {aliases, Aliases} | {negations, Negations} | {expand, Expansions} - Aliases = [{Key, Key}] - Negations = [{Key, Key}] - Key = term() - Expansions = [{Property, [term()]}] - Property = atom() | tuple() - -

Passes List through a sequence of +

Passes List through a sequence of substitution/expansion stages. For an aliases operation, the function substitute_aliases/2 is applied using the given list of aliases; for a negations operation, @@ -270,51 +217,37 @@ - property(Property) -> Property + - - Property = atom() | tuple() -

Creates a normal form (minimal) representation of a property. If - Property is {Key, true} where Key is + Property is {Key, true} where Key is an atom, this returns Key, otherwise the whole term - Property is returned.

+ Property is returned.

See also: property/2.

- property(Key, Value) -> Property + - - Key = term() - Value = term() - Property = atom() | tuple() -

Creates a normal form (minimal) representation of a simple - key/value property. Returns Key if Value is - true and Key is an atom, otherwise a tuple - {Key, Value} is returned.

+ key/value property. Returns Key if Value is + true and Key is an atom, otherwise a tuple + {Key, Value} is returned.

See also: property/1.

- split(List, Keys) -> {Lists, Rest} + - - List = [term()] - Keys = [term()] - Lists = [[term()]] - Rest = [term()] - -

Partitions List into a list of sublists and a - remainder. Lists contains one sublist for each key in - Keys, in the corresponding order. The relative order of +

Partitions List into a list of sublists and a + remainder. Lists contains one sublist for each key in + Keys, in the corresponding order. The relative order of the elements in each sublist is preserved from the original - List. Rest contains the elements in - List that are not associated with any of the given keys, + List. Rest contains the elements in + List that are not associated with any of the given keys, also with their original relative order preserved.

Example: split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])

@@ -323,19 +256,14 @@
- substitute_aliases(Aliases, List) -> List + - - Aliases = [{Key, Key}] - Key = term() - List = [term()] -

Substitutes keys of properties. For each entry in - List, if it is associated with some key K1 - such that {K1, K2} occurs in Aliases, the - key of the entry is changed to Key2. If the same - K1 occurs more than once in Aliases, only + List, if it is associated with some key K1 + such that {K1, K2} occurs in Aliases, the + key of the entry is changed to K2. If the same + K1 occurs more than once in Aliases, only the first occurrence is used.

Example: substitute_aliases([{color, colour}], L) will replace all tuples {color, ...} in L @@ -345,24 +273,19 @@ - substitute_negations(Negations, List) -> List + - - Negations = [{Key, Key}] - Key = term() - List = [term()] -

Substitutes keys of boolean-valued properties and simultaneously negates their values. For each entry in - List, if it is associated with some key K1 - such that {K1, K2} occurs in Negations, then + List, if it is associated with some key K1 + such that {K1, K2} occurs in Negations, then if the entry was {K1, true} it will be replaced with {K2, false}, otherwise it will be replaced with {K2, true}, thus changing the name of the option and simultaneously negating the value given by get_bool(List). If the same K1 occurs more - than once in Negations, only the first occurrence is + than once in Negations, only the first occurrence is used.

Example: substitute_negations([{no_foo, foo}], L) will replace any atom no_foo or tuple @@ -374,13 +297,10 @@ - unfold(List) -> List + - - List = [term()] - -

Unfolds all occurrences of atoms in List to tuples +

Unfolds all occurrences of atoms in List to tuples {Atom, true}.

diff --git a/lib/stdlib/doc/src/qlc.xml b/lib/stdlib/doc/src/qlc.xml index da24ee9914..6a45ade447 100644 --- a/lib/stdlib/doc/src/qlc.xml +++ b/lib/stdlib/doc/src/qlc.xml @@ -4,7 +4,7 @@
- 20042009 + 20042011 Ericsson AB. All Rights Reserved. @@ -45,7 +45,9 @@ tables. Typical QLC tables are ETS, Dets, and Mnesia tables. There is also support for user defined tables, see the Implementing a QLC - table section. A query is stated using + table section. + A query is stated using Query List Comprehensions (QLCs). The answers to a query are determined by data in QLC tables that fulfill the constraints expressed by the QLCs of the query. QLCs are similar @@ -55,10 +57,11 @@ fact, in the absence of optimizations and options such as cache and unique (see below), every QLC free of QLC tables evaluates to the same list of answers as the - identical ordinary list comprehension.

+ identical ordinary list comprehension.

While ordinary list comprehensions evaluate to lists, calling - qlc:q/1,2 returns a Query + qlc:q/1,2 returns a Query Handle. To obtain all the answers to a query, qlc:eval/1,2 should be called with the query handle as first argument. Query handles are essentially @@ -69,7 +72,8 @@ Code replacement is described in the Erlang Reference Manual. The list of answers can also be traversed in - chunks by use of a Query Cursor. Query cursors are + chunks by use of a Query Cursor. Query cursors are created by calling qlc:cursor/1,2 with a query handle as first argument. Query cursors are essentially Erlang processes. @@ -226,75 +230,6 @@

-
Common data types - - -

QueryCursor = {qlc_cursor, term()}

-
-

QueryHandle = {qlc_handle, term()}

-
-

QueryHandleOrList = QueryHandle | list()

-
-

Answers = [Answer]

-
-

Answer = term()

-
-

AbstractExpression =  - parse trees - for Erlang expressions, see the abstract format - documentation in the ERTS User's Guide -

-
-

MatchExpression =  - - match specifications, see the match specification - documentation in the ERTS User's Guide and ms_transform(3) -

-
-

SpawnOptions = default | spawn_options()

-
-

SortOptions = [SortOption] | SortOption

-
-

SortOption = {compressed, bool()} - | {no_files, NoFiles} - | {order, Order} - | {size, Size} - | {tmpdir, TempDirectory} - | {unique, bool()}  - - see file_sorter(3) -

-
-

Order = ascending | descending | OrderFun

-
-

OrderFun = fun(term(), term()) -> bool()

-
-

TempDirectory = "" | filename()

-
-

Size = int() > 0

-
-

NoFiles = int() > 1

-
-

KeyPos = int() > 0 | [int() > 0]

-
-

MaxListSize = int() >= 0

-
-

bool() = true | false

-
-

Cache = ets | list | no

-
-

TmpFileUsage = allowed | not_allowed | info_msg - | warning_msg | error_msg

-
-

filename() =  - see filename(3) -

-
-

spawn_options() =  - see erlang(3) -

-
- -
- -
-
Getting started

As already mentioned @@ -679,34 +614,105 @@ ets:match_spec_run(ets:lookup(86033, {2,2}),

+ + + +

Parse trees for Erlang expression, see the abstract format + documentation in the ERTS User's Guide.

+
+ + + + + + + + + + + +

Match specification, see the match specification + documentation in the ERTS User's Guide and ms_transform(3).

+
+ + +

Actually an integer > 1.

+
+ + + + + + + + + + + + + + +

A query cursor.

+
+
+ + +

A query handle.

+
+
+ + + + + +

A literal + query + list comprehension.

+
+ + + + + + + + +

See file_sorter(3).

+
+ + + + + +

+
+
+ - append(QHL) -> QH + Return a query handle. - - QHL = [QueryHandleOrList] - QH = QueryHandle -

Returns a query handle. When evaluating the query handle - QH all answers to the first query handle in - QHL is returned followed by all answers to the rest - of the query handles in QHL.

+ QH all answers to the first query handle in + QHL are returned followed by all answers + to the rest of the query handles in QHL.

- append(QH1, QH2) -> QH3 + Return a query handle. - - QH1 = QH2 = QueryHandleOrList - QH3 = QueryHandle -

Returns a query handle. When evaluating the query handle - QH3 all answers to QH1 are returned followed - by all answers to QH2.

+ QH3 all answers to + QH1 are returned followed by all answers + to QH2.

append(QH1, QH2) is equivalent to append([QH1, QH2]).

@@ -714,17 +720,9 @@ ets:match_spec_run(ets:lookup(86033, {2,2}),
- cursor(QueryHandleOrList [, Options]) -> QueryCursor + + Create a query cursor. - - Options = [Option] | Option - Option = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {spawn_options, SpawnOptions} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all -

Creates a query cursor and makes the calling process the owner of the cursor. The @@ -746,11 +744,13 @@ ets:match_spec_run(ets:lookup(86033, {2,2}), [{b,1},{b,2}] 4> qlc:delete_cursor(QC). ok +

cursor(QH) is equivalent to + cursor(QH, []).

- delete_cursor(QueryCursor) -> ok + Delete a query cursor.

Deletes a query cursor. Only the owner of the cursor can @@ -759,19 +759,11 @@ ok - eval(QueryHandleOrList [, Options]) -> Answers | Error - e(QueryHandleOrList [, Options]) -> Answers + + + + Return all answers to a query. - - Options = [Option] | Option - Option = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all - Error = {error, module(), Reason} - Reason = - as returned by file_sorter(3) - -

Evaluates a query handle in the calling process and collects all answers in a list.

@@ -780,47 +772,39 @@ ok 1> QH = qlc:q([{X,Y} || X <- [a,b], Y <- [1,2]]), qlc:eval(QH). [{a,1},{a,2},{b,1},{b,2}] +

eval(QH) is equivalent to + eval(QH, []).

- fold(Function, Acc0, QueryHandleOrList [, Options]) -> - Acc1 | Error + + Fold a function over the answers to a query. - - Function = fun(Answer, AccIn) -> AccOut - Acc0 = Acc1 = AccIn = AccOut = term() - Options = [Option] | Option - Option = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all - Error = {error, module(), Reason} - Reason = - as returned by file_sorter(3) - - -

Calls Function on successive answers to the query - handle together with an extra argument AccIn. The - query handle and the function are evaluated in the calling - process. Function must return a new accumulator which - is passed to the next call. Acc0 is returned if there - are no answers to the query handle.

+

Calls Function on successive answers to + the query handle together with an extra argument + AccIn. The query handle and the function + are evaluated in the calling process. + Function must return a new accumulator + which is passed to the next call. + Acc0 is returned if there are no answers + to the query handle.

 1> QH = [1,2,3,4,5,6],
 qlc:fold(fun(X, Sum) -> X + Sum end, 0, QH).
 21
+

fold(Function, Acc0, + QH) is equivalent to + fold(Function, Acc0, + QH, []).

- format_error(Error) -> Chars + Return an English description of a an error tuple. - - Error = {error, module(), term()} - Chars = [char() | Chars] -

Returns a descriptive string in English of an error tuple returned by some of the functions of the qlc module @@ -830,25 +814,9 @@ ok - info(QueryHandleOrList [, Options]) -> Info + + Return code describing a query handle. - - Options = [Option] | Option - Option = EvalOption | ReturnOption - EvalOption = {cache_all, Cache} | cache_all - | {max_list_size, MaxListSize} - | {tmpdir_usage, TmpFileUsage} - | {tmpdir, TempDirectory} - | {unique_all, bool()} | unique_all - ReturnOption = {depth, Depth} - | {flat, bool()} - | {format, Format} - | {n_elements, NElements} - Depth = infinity | int() >= 0 - Format = abstract_code | string - NElements = infinity | int() > 0 - Info = AbstractExpression | string() -

Returns information about a query handle. The information describes the simplifications @@ -879,18 +847,18 @@ ok io:format("~s~n", [qlc:info(QH, unique_all)]). begin V1 = - qlc:q([ + qlc:q([ SQV || SQV <- [x,y] ], [{unique,true}]), V2 = - qlc:q([ + qlc:q([ SQV || SQV <- [a,b] ], [{unique,true}]), - qlc:q([ + qlc:q([ {X,Y} || X <- V1, Y <- V2 @@ -913,19 +881,19 @@ end io:format("~s~n", [qlc:info(Q)]). begin V1 = - qlc:q([ + qlc:q([ P0 || P0 = {W,Y} <- ets:table(17) ]), V2 = - qlc:q([ + qlc:q([ [G1|G2] || G2 <- V1, G1 <- ets:table(16), element(2, G1) =:= element(1, G2) ], [{join,lookup}]), - qlc:q([ + qlc:q([ {X,Z,W} || [{X,Z}|{W,Y}] <- V2 ]) @@ -936,44 +904,43 @@ end method chosen. A convention is used for lookup join: the first generator (G2) is the one traversed, the second one (G1) is the table where constants are looked up.

+ +

info(QH) is equivalent to + info(QH, []).

- keysort(KeyPos, QH1 [, SortOptions]) -> QH2 + + Return a query handle. - - QH1 = QueryHandleOrList - QH2 = QueryHandle -

Returns a query handle. When evaluating the query handle - QH2 the answers to the query handle QH1 are - sorted by QH2 the answers to the query handle + QH1 are sorted by file_sorter:keysort/4 according to the options.

-

The sorter will use temporary files only if QH1 does - not evaluate to a list and the size of the binary - representation of the answers exceeds Size bytes, - where Size is the value of the size option.

+

The sorter will use temporary files only if + QH1 does not evaluate to a list and the + size of the binary representation of the answers exceeds + Size bytes, where Size is the value of the + size option.

+ +

keysort(KeyPos, QH1) + is equivalent to + keysort(KeyPos, QH1, []).

- next_answers(QueryCursor [, NumberOfAnswers]) -> - Answers | Error + + Return some or all answers to a query. - - NumberOfAnswers = all_remaining | int() > 0 - Error = {error, module(), Reason} - Reason = - as returned by file_sorter(3) - -

Returns some or all of the remaining answers to a query - cursor. Only the owner of Cursor can retrieve - answers.

- + cursor. Only the owner of QueryCursor can + retrieve answers.

The optional argument NumberOfAnswersdetermines the maximum number of answers returned. The default value is 10. If less than the requested number of answers is @@ -983,21 +950,9 @@ end - q(QueryListComprehension [, Options]) -> QueryHandle + + Return a handle for a query list comprehension. - - QueryListComprehension =  - - literal query listcomprehension - - Options = [Option] | Option - Option = {max_lookup, MaxLookup} - | {cache, Cache} | cache - | {join, Join} - | {lookup, Lookup} - | {unique, bool()} | unique - MaxLookup = int() >= 0 | infinity - Join = any | lookup | merge | nested_loop - Lookup = bool() | any -

Returns a query handle for a query list comprehension. The query list comprehension must be the @@ -1024,7 +979,7 @@ end

 ...
-A = [X || {X} <- [{1},{2}]], 
+A = [X || {X} <- [{1},{2}]],
 QH = qlc:q(A),
 ...
@@ -1034,6 +989,9 @@ QH = qlc:q(A), list comprehension"); the shell process stops with a badarg reason.

+

q(QLC) is equivalent to + q(QLC, []).

+

The {cache, ets} option can be used to cache the answers to a query list comprehension. The answers are stored in one ETS table for each cached query list @@ -1092,26 +1050,26 @@ QH = qlc:q(A), io:format("~s~n", [qlc:info(Q)]). begin V1 = - qlc:q([ + qlc:q([ P0 || P0 = {X,Z} <- qlc:keysort(1, [{a,1},{b,4},{c,6}], []) ]), V2 = - qlc:q([ + qlc:q([ P0 || P0 = {W,Y} <- qlc:keysort(2, [{2,a},{3,b},{4,c}], []) ]), V3 = - qlc:q([ + qlc:q([ [G1|G2] || G1 <- V1, G2 <- V2, element(1, G1) == element(2, G2) ], [{join,merge},{cache,list}]), - qlc:q([ + qlc:q([ {A,X,Z,W} || A <- [a,b,c], [{X,Z}|{W,Y}] <- V3, @@ -1170,7 +1128,7 @@ ets:match_spec_run( elements of the key {X, Y} are compared separately.

The {lookup, true} option can be used to ensure - that the qlc module will look up constants in some + that the qlc module will look up constants in some QLC table. If there are more than one QLC table among the generators' list expressions, constants have to be looked up in at least one @@ -1190,7 +1148,7 @@ ets:match_spec_run( {join, nested_loop} invokes the method of matching every pair of objects from two handles. The last method is mostly very slow. The evaluation of the query - fails if the qlc module cannot carry out the chosen + fails if the qlc module cannot carry out the chosen join method. The default value is any which means that some fast join method will be used if possible.

@@ -1198,47 +1156,33 @@ ets:match_spec_run(
- sort(QH1 [, SortOptions]) -> QH2 + + Return a query handle. - - QH1 = QueryHandleOrList - QH2 = QueryHandle -

Returns a query handle. When evaluating the query handle - QH2 the answers to the query handle QH1 are - sorted by QH2 the answers to the query handle + QH1 are sorted by file_sorter:sort/3 according to the options.

-

The sorter will use temporary files only if QH1 does - not evaluate to a list and the size of the binary - representation of the answers exceeds Size bytes, - where Size is the value of the size option.

+

The sorter will use temporary files only if + QH1 does not evaluate to a list and the + size of the binary representation of the answers exceeds + Size bytes, where Size is the value of the + size option.

+ +

sort(QH1) is equivalent to + sort(QH1, []).

+
- string_to_handle(QueryString [, Options [, Bindings]]) -> - QueryHandle | Error + + + Return a handle for a query list comprehension. - - QueryString = string() - Options = [Option] | Option - Option = {max_lookup, MaxLookup} - | {cache, Cache} | cache - | {join, Join} - | {lookup, Lookup} - | {unique, bool()} | unique - MaxLookup = int() >= 0 | infinity - Join = any | lookup | merge | nested_loop - Lookup = bool() | any - Bindings = - as returned by - erl_eval:bindings/1 - - Error = {error, module(), Reason} - Reason =  - ErrorInfo as returned by - erl_scan:string/1 or erl_parse:parse_exprs/1 - -

A string version of qlc:q/1,2. When the query handle is evaluated the fun created by the parse transform is @@ -1253,57 +1197,24 @@ ets:match_spec_run( qlc:eval(QH). [2,3,4] +

string_to_handle(QueryString) + is equivalent to + string_to_handle(QueryString, []).

+ +

string_to_handle(QueryString, + Options) + is equivalent to + string_to_handle(QueryString, + Options, erl_eval:new_bindings()).

+

This function is probably useful mostly when called from outside of Erlang, for instance from a driver written in C.

- table(TraverseFun, Options) -> QueryHandle + Return a query handle for a table. - - TraverseFun = TraverseFun0 | TraverseFun1 - TraverseFun0 = fun() -> TraverseResult - TraverseFun1 = fun(MatchExpression) -> TraverseResult - TraverseResult = Objects | term() - Objects = [] | [term() | ObjectList] - ObjectList = TraverseFun0 | Objects - Options = [Option] | Option - Option = {format_fun, FormatFun} - | {info_fun, InfoFun} - | {lookup_fun, LookupFun} - | {parent_fun, ParentFun} - | {post_fun, PostFun} - | {pre_fun, PreFun} - | {key_equality, KeyComparison} - FormatFun = undefined | fun(SelectedObjects) -> FormatedTable - SelectedObjects = all - | {all, NElements, DepthFun} - | {match_spec, MatchExpression} - | {lookup, Position, Keys} - | {lookup, Position, Keys, NElements, DepthFun} - NElements = infinity | int() > 0 - DepthFun = fun(term()) -> term() - FormatedTable = {Mod, Fun, Args} - | AbstractExpression - | character_list() - InfoFun = undefined | fun(InfoTag) -> InfoValue - InfoTag = indices | is_unique_objects | keypos | num_of_objects - InfoValue = undefined | term() - LookupFun = undefined | fun(Position, Keys) -> LookupResult - LookupResult = [term()] | term() - ParentFun = undefined | fun() -> ParentFunValue - PostFun = undefined | fun() -> void() - PreFun = undefined | fun([PreArg]) -> void() - PreArg = {parent_value, ParentFunValue} | {stop_fun, StopFun} - ParentFunValue = undefined | term() - StopFun = undefined | fun() -> void() - KeyComparison = '=:=' | '==' - Position = int() > 0 - Keys = [term()] - Mod = Fun = atom() - Args = [term()] -

Returns a query handle for a QLC table. In Erlang/OTP there is support for ETS, Dets and @@ -1315,77 +1226,90 @@ ets:match_spec_run( as well as properties of the table are handled by callback functions provided as options to qlc:table/2.

-

The callback function TraverseFun is used for - traversing the table. It is to return a list of objects - terminated by either [] or a nullary fun to be used - for traversing the not yet traversed objects of the table. - Any other return value is immediately returned as value of - the query evaluation. Unary TraverseFuns are to - accept a match specification as argument. The match - specification is created by the parse transform by analyzing - the pattern of the generator calling qlc:table/2 and - filters using variables introduced in the pattern. If the - parse transform cannot find a match specification equivalent - to the pattern and filters, TraverseFun will be - called with a match specification returning every object. - Modules that can utilize match specifications for optimized +

The callback function TraverseFun is + used for traversing the table. It is to return a list of + objects terminated by either [] or a nullary fun to + be used for traversing the not yet traversed objects of the + table. Any other return value is immediately returned as + value of the query evaluation. Unary + TraverseFuns are to accept a match + specification as argument. The match specification is + created by the parse transform by analyzing the pattern of + the generator calling qlc:table/2 and filters using + variables introduced in the pattern. If the parse transform + cannot find a match specification equivalent to the pattern + and filters, TraverseFun will be called + with a match specification returning every object. Modules + that can utilize match specifications for optimized traversal of tables should call qlc:table/2 with a - unary TraverseFun while other modules can provide a - nullary TraverseFun. ets:table/2 is an example - of the former; gb_table:table/1 in the Implementing a QLC - table section is an example of the latter.

- -

PreFun is a unary callback function that is called - once before the table is read for the first time. If the - call fails, the query evaluation fails. Similarly, the - nullary callback function PostFun is called once - after the table was last read. The return value, which is - caught, is ignored. If PreFun has been called for a - table, PostFun is guaranteed to be called for that - table, even if the evaluation of the query fails for some - reason. The order in which pre (post) functions for + unary + TraverseFun while other modules can + provide a nullary + TraverseFun. ets:table/2 is an + example of the former; gb_table:table/1 in the + Implementing a + QLC table section is an example of the latter.

+ +

PreFun is a unary callback function + that is called once before the table is read for the first + time. If the call fails, the query evaluation fails. + Similarly, the nullary callback function + PostFun is called once after the table + was last read. The return value, which is caught, is + ignored. If PreFun has been called for a + table, + PostFun is guaranteed to be called for + that table, even if the evaluation of the query fails for + some reason. The order in which pre (post) functions for different tables are evaluated is not specified. Other table - access than reading, such as calling InfoFun, is - assumed to be OK at any time. The argument PreArgs is - a list of tagged values. Currently there are two tags, + access than reading, such as calling + InfoFun, is assumed to be OK at any + time. The argument PreArgs is a list of + tagged values. Currently there are two tags, parent_value and stop_fun, used by Mnesia for managing transactions. The value of parent_value is - the value returned by ParentFun, or undefined - if there is no ParentFun. ParentFun is called - once just before the call of PreFun in the context of - the process calling eval, fold, or + the value returned by ParentFun, or + undefined if there is no ParentFun. + ParentFun is called once just before the + call of + PreFun in the context of the process + calling + eval, fold, or cursor. The value of stop_fun is a nullary fun that deletes the cursor if called from the parent, or undefined if there is no cursor.

The binary callback - function LookupFun is used for looking up objects in - the table. The first argument Position is the key - position or an indexed position and the second argument - Keys is a sorted list of unique values. The return - value is to be a list of all objects (tuples) such that the - element at Position is a member of Keys. Any - other return value is immediately returned as value of the - query evaluation. LookupFun is called instead of + function LookupFun is used for looking + up objects in the table. The first argument + Position is the key position or an + indexed position and the second argument + Keys is a sorted list of unique values. + The return value is to be a list of all objects (tuples) + such that the element at Position is a member of + Keys. Any other return value is + immediately returned as value of the query evaluation. + LookupFun is called instead of traversing the table if the parse transform at compile time can find out that the filters match and compare the element - at Position in such a way that only Keys need - to be looked up in order to find all potential answers. The - key position is obtained by calling InfoFun(keypos) - and the indexed positions by calling - InfoFun(indices). If the key position can be used for - lookup it is always chosen, otherwise the indexed position - requiring the least number of lookups is chosen. If there is - a tie between two indexed positions the one occurring first - in the list returned by InfoFun is chosen. Positions - requiring more than max_lookup lookups are - ignored.

- -

The unary callback function InfoFun is to return - information about the table. undefined should be - returned if the value of some tag is unknown:

+ at Position in such a way that only + Keys need to be looked up in order to + find all potential answers. The key position is obtained by + calling + InfoFun(keypos) and the indexed + positions by calling + InfoFun(indices). If the key position + can be used for lookup it is always chosen, otherwise the + indexed position requiring the least number of lookups is + chosen. If there is a tie between two indexed positions the + one occurring first in the list returned by + InfoFun is chosen. Positions requiring + more than max_lookup + lookups are ignored.

+ +

The unary callback function InfoFun is + to return information about the table. undefined + should be returned if the value of some tag is unknown:

indices. Returns a list of indexed @@ -1406,20 +1330,22 @@ ets:match_spec_run( -

The unary callback function FormatFun is used by - qlc:info/1,2 for - displaying the call that created the table's query handle. - The default value, undefined, means that +

The unary callback function FormatFun + is used by qlc:info/1,2 + for displaying the call that created the table's query + handle. The default value, undefined, means that info/1,2 displays a call to '$MOD':'$FUN'/0. - It is up to FormatFun to present the selected objects - of the table in a suitable way. However, if a character list - is chosen for presentation it must be an Erlang expression - that can be scanned and parsed (a trailing dot will be added - by qlc:info though). FormatFun is called with - an argument that describes the selected objects based on - optimizations done as a result of analyzing the filters of - the QLC where the call to qlc:table/2 occurs. The - possible values of the argument are:

+ It is up to FormatFun to present the + selected objects of the table in a suitable way. However, if + a character list is chosen for presentation it must be an + Erlang expression that can be scanned and parsed (a trailing + dot will be added by qlc:info though). + FormatFun is called with an argument + that describes the selected objects based on optimizations + done as a result of analyzing the filters of the QLC where + the call to + qlc:table/2 occurs. The possible values of the + argument are:

{lookup, Position, Keys, NElements, DepthFun}. @@ -1443,10 +1369,12 @@ ets:match_spec_run( can be used for limiting the size of terms; calling DepthFun(Term) substitutes '...' for parts of Term below the depth specified by the info/1,2 - option depth. If calling FormatFun with an - argument including NElements and DepthFun - fails, FormatFun is called once again with an - argument excluding NElements and DepthFun + option depth. If calling + FormatFun with an argument including + NElements and DepthFun fails, + FormatFun is called once again with an + argument excluding + NElements and DepthFun ({lookup, Position, Keys} or all).

@@ -1458,7 +1386,7 @@ ets:match_spec_run(

See ets(3), dets(3) and - mnesia(3) + mnesia(3) for the various options recognized by table/1,2 in respective module.

@@ -1472,12 +1400,12 @@ ets:match_spec_run( Erlang Reference Manual, erl_eval(3), - erlang(3), + erlang(3), ets(3), - file(3), - error_logger(3), + file(3), + error_logger(3), file_sorter(3), - mnesia(3), + mnesia(3), Programming Examples, shell(3)

diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml index 5ada1c2c57..383f52d10d 100644 --- a/lib/stdlib/doc/src/queue.xml +++ b/lib/stdlib/doc/src/queue.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -88,122 +88,94 @@ Original API + + + queue() +

As returned by new/0.

+
+
+ - new() -> Q + Create an empty queue - - Q = queue() -

Returns an empty queue.

- is_queue(Term) -> true | false + Test if a term is a queue - - Term = term() - -

Tests if Q is a queue and returns true if so and +

Tests if Term is a queue and returns true if so and false otherwise.

- is_empty(Q) -> true | false + Test if a queue is empty - - Q = queue() - -

Tests if Q is empty and returns true if so and +

Tests if Q is empty and returns true if so and false otherwise.

- len(Q) -> N + Get the length of a queue - - Q = queue() - N = integer() - -

Calculates and returns the length of queue Q.

+

Calculates and returns the length of queue Q.

- in(Item, Q1) -> Q2 + Insert an item at the rear of a queue - - Item = term() - Q1 = Q2 = queue() - -

Inserts Item at the rear of queue Q1. - Returns the resulting queue Q2.

+

Inserts Item at the rear of queue Q1. + Returns the resulting queue Q2.

- in_r(Item, Q1) -> Q2 + Insert an item at the front of a queue - - Item = term() - Q1 = Q2 = queue() - -

Inserts Item at the front of queue Q1. - Returns the resulting queue Q2.

+

Inserts Item at the front of queue Q1. + Returns the resulting queue Q2.

- out(Q1) -> Result + Remove the front item from a queue - - Result = {{value, Item}, Q2} | {empty, Q1} - Q1 = Q2 = queue() - -

Removes the item at the front of queue Q1. Returns the - tuple {{value, Item}, Q2}, where Item is the - item removed and Q2 is the resulting queue. If Q1 is - empty, the tuple {empty, Q1} is returned.

+

Removes the item at the front of queue Q1. Returns the + tuple {{value, Item}, Q2}, where Item is the + item removed and Q2 is the resulting queue. If Q1 is + empty, the tuple {empty, Q1} is returned.

- out_r(Q1) -> Result + Remove the rear item from a queue - - Result = {{value, Item}, Q2} | {empty, Q1} - Q1 = Q2 = queue() - -

Removes the item at the rear of the queue Q1. Returns the - tuple {{value, Item}, Q2}, where Item is the - item removed and Q2 is the new queue. If Q1 is - empty, the tuple {empty, Q1} is returned.

+

Removes the item at the rear of the queue Q1. Returns the + tuple {{value, Item}, Q2}, where Item is the + item removed and Q2 is the new queue. If Q1 is + empty, the tuple {empty, Q1} is returned.

- from_list(L) -> queue() + Convert a list to a queue - - L = list() - -

Returns a queue containing the items in L in the +

Returns a queue containing the items in L in the same order; the head item of the list will become the front item of the queue.

- to_list(Q) -> list() + Convert a queue to a list - - Q = queue() -

Returns a list of the items in the queue in the same order; the front item of the queue will become the head of the list.

@@ -211,57 +183,43 @@
- reverse(Q1) -> Q2 + Reverse a queue - - Q1 = Q2 = queue() - -

Returns a queue Q2 that contains the items of - Q1 in the reverse order.

+

Returns a queue Q2 that contains the items of + Q1 in the reverse order.

- split(N, Q1) -> {Q2,Q3} + Split a queue in two - - N = integer() - Q1 = Q2 = Q3 = queue() - -

Splits Q1 in two. The N front items - are put in Q2 and the rest in Q3

+

Splits Q1 in two. The N front items + are put in Q2 and the rest in Q3

- join(Q1, Q2) -> Q3 + Join two queues - - Q1 = Q2 = Q3 = queue() - -

Returns a queue Q3 that is the result of joining - Q1 and Q2 with Q1 in front of - Q2.

+

Returns a queue Q3 that is the result of joining + Q1 and Q2 with Q1 in front of + Q2.

- filter(Fun, Q1) -> Q2 + Filter a queue - - Fun = fun(Item) -> bool() | list() - Q1 = Q2 = queue() - -

Returns a queue Q2 that is the result of calling - Fun(Item) on all items in Q1, +

Returns a queue Q2 that is the result of calling + Fun(Item) on all items in Q1, in order from front to rear.

-

If Fun(Item) returns true, Item +

If Fun(Item) returns true, Item is copied to the result queue. If it returns false, - Item is not copied. If it returns a list + Item is not copied. If it returns a list the list elements are inserted instead of Item in the result queue.

-

So, Fun(Item) returning [Item] is thereby +

So, Fun(Item) returning [Item] is thereby semantically equivalent to returning true, just as returning [] is semantically equivalent to returning false. But returning a list builds @@ -269,15 +227,11 @@ - member(Item, Q) -> bool() + Test if an item is in a queue - - Item = term() - Q = queue() - -

Returns true if Item matches some element - in Q, otherwise false.

+

Returns true if Item matches some element + in Q, otherwise false.

@@ -290,77 +244,53 @@ - get(Q) -> Item + Return the front item of a queue - - Item = term() - Q = queue() - -

Returns Item at the front of queue Q.

-

Fails with reason empty if Q is empty.

+

Returns Item at the front of queue Q.

+

Fails with reason empty if Q is empty.

- get_r(Q) -> Item + Return the rear item of a queue - - Item = term() - Q = queue() - -

Returns Item at the rear of queue Q.

-

Fails with reason empty if Q is empty.

+

Returns Item at the rear of queue Q.

+

Fails with reason empty if Q is empty.

- drop(Q1) -> Q2 + Remove the front item from a queue - - Item = term() - Q1 = Q2 = queue() - -

Returns a queue Q2 that is the result of removing - the front item from Q1.

-

Fails with reason empty if Q1 is empty.

+

Returns a queue Q2 that is the result of removing + the front item from Q1.

+

Fails with reason empty if Q1 is empty.

- drop_r(Q1) -> Q2 + Remove the rear item from a queue - - Item = term() - Q1 = Q2 = queue() - -

Returns a queue Q2 that is the result of removing - the rear item from Q1.

-

Fails with reason empty if Q1 is empty.

+

Returns a queue Q2 that is the result of removing + the rear item from Q1.

+

Fails with reason empty if Q1 is empty.

- peek(Q) -> {value,Item} | empty + Return the front item of a queue - - Item = term() - Q = queue() - -

Returns the tuple {value, Item} where Item is the - front item of Q, or empty if Q1 is empty.

+

Returns the tuple {value, Item} where Item is the + front item of Q, or empty if Q is empty.

- peek_r(Q) -> {value,Item} | empty + Return the rear item of a queue - - Item = term() - Q = queue() - -

Returns the tuple {value, Item} where Item is the - rear item of Q, or empty if Q1 is empty.

+

Returns the tuple {value, Item} where Item is the + rear item of Q, or empty if Q is empty.

@@ -372,80 +302,56 @@ - cons(Item, Q1) -> Q2 + Insert an item at the head of a queue - - Item = term() - Q1 = Q2 = queue() - -

Inserts Item at the head of queue Q1. Returns - the new queue Q2.

+

Inserts Item at the head of queue Q1. Returns + the new queue Q2.

- head(Q) -> Item + Return the item at the head of a queue - - Item = term() - Q = queue() - -

Returns Item from the head of queue Q.

-

Fails with reason empty if Q is empty.

+

Returns Item from the head of queue Q.

+

Fails with reason empty if Q is empty.

- tail(Q1) -> Q2 + Remove the head item from a queue - - Item = term() - Q1 = Q2 = queue() - -

Returns a queue Q2 that is the result of removing - the head item from Q1.

-

Fails with reason empty if Q1 is empty.

+

Returns a queue Q2 that is the result of removing + the head item from Q1.

+

Fails with reason empty if Q1 is empty.

- snoc(Q1, Item) -> Q2 + Insert an item at the tail of a queue - - Item = term() - Q1 = Q2 = queue() - -

Inserts Item as the tail item of queue Q1. Returns - the new queue Q2.

+

Inserts Item as the tail item of queue Q1. Returns + the new queue Q2.

- daeh(Q) -> Item - last(Q) -> Item + + Return the tail item of a queue - - Item = term() - Q = queue() - -

Returns the tail item of queue Q.

-

Fails with reason empty if Q is empty.

+

Returns the tail item of queue Q.

+

Fails with reason empty if Q is empty.

- liat(Q1) -> Q2 - init(Q1) -> Q2 - lait(Q1) -> Q2 + + + Remove the tail item from a queue - - Item = term() - Q1 = Q2 = queue() - -

Returns a queue Q2 that is the result of removing - the tail item from Q1.

-

Fails with reason empty if Q1 is empty.

+

Returns a queue Q2 that is the result of removing + the tail item from Q1.

+

Fails with reason empty if Q1 is empty.

The name lait/1 is a misspelling - do not use it anymore.

diff --git a/lib/stdlib/doc/src/random.xml b/lib/stdlib/doc/src/random.xml index dcc6d756e1..93affc3191 100644 --- a/lib/stdlib/doc/src/random.xml +++ b/lib/stdlib/doc/src/random.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -49,9 +49,15 @@ strong. If a strong cryptographic random number generator is needed for example crypto:rand_bytes/1 could be used instead.

+ + + +

The state.

+
+
- seed() -> ran() + Seeds random number generation with default values

Seeds random number generation with default (fixed) values @@ -59,11 +65,8 @@ - seed(A1, A2, A3) -> undefined | ran() + Seeds random number generator - - A1 = A2 = A3 = integer() -

Seeds random number generation with integer values in the process dictionary, and returns the old state.

@@ -76,26 +79,23 @@
- seed({A1, A2, A3}) -> undefined | ran() + Seeds random number generator - - A1 = A2 = A3 = integer() -

- seed({A1, A2, A3}) is equivalent to seed(A1, A2, A3). + seed({A1, A2, A3}) is equivalent to seed(A1, A2, A3).

- seed0() -> ran() + Return default state for random number generation

Returns the default state.

- uniform()-> float() + Return a random float

Returns a random float uniformly distributed between 0.0 @@ -103,39 +103,29 @@ - uniform(N) -> integer() + Return a random integer - - N = integer() - -

Given an integer N >= 1, uniform/1 returns a +

Given an integer N >= 1, uniform/1 returns a random integer uniformly distributed between 1 and - N, updating the state in the process dictionary.

+ N, updating the state in the process dictionary.

- uniform_s(State0) -> {float(), State1} + Return a random float - - State0 = State1 = ran() -

Given a state, uniform_s/1returns a random float uniformly distributed between 0.0 and 1.0, and a new state.

- uniform_s(N, State0) -> {integer(), State1} + Return a random integer - - N = integer() - State0 = State1 = ran() - -

Given an integer N >= 1 and a state, uniform_s/2 +

Given an integer N >= 1 and a state, uniform_s/2 returns a random integer uniformly distributed between 1 and - N, and a new state.

+ N, and a new state.

diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 9091035392..b8db55fc26 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -59,28 +59,24 @@ -
- DATA TYPES - - iodata() = iolist() | binary() - iolist() = [char() | binary() | iolist()] - - a binary is allowed as the tail of the list - - unicode_binary() = binary() with characters encoded in UTF-8 coding standard - unicode_char() = integer() representing a valid unicode codepoint - - chardata() = charlist() | unicode_binary() - - charlist() = [unicode_char() | unicode_binary() | charlist()] - - a unicode_binary is allowed as the tail of the list - - - mp() = Opaque datatype containing a compiled regular expression. - - The mp() is guaranteed to be a tuple() having the atom + + + + +

Opaque datatype containing a compiled regular expression. + The mp() is guaranteed to be a tuple() having the atom 're_pattern' as its first element, to allow for matching in guards. The arity of the tuple() or the content of the other fields - may change in future releases. -

+ may change in future releases.

+ + + + + + + + + compile(Regexp) -> {ok, MP} | {error, ErrSpec} @@ -96,14 +92,14 @@ compile(Regexp,Options) -> {ok, MP} | {error, ErrSpec} Compile a regular expression into a match program - Regexp = iodata() | charlist() + Regexp = iodata() | io:charlist() Options = [ Option ] Option = unicode | anchored | caseless | dollar_endonly | dotall | extended | firstline | multiline | no_auto_capture | dupnames | ungreedy | {newline, NLSpec}| bsr_anycrlf | bsr_unicode - NLSpec = cr | crlf | lf | anycrlf | any - MP = mp() + NLSpec = nl_spec() + MP = mp() ErrSpec = {ErrString, Position} ErrString = string() - Position = int() + Position = non_neg_integer()

This function compiles a regular expression with the syntax @@ -116,7 +112,7 @@ time one wants to match.

When the unicode option is given, the regular expression should be given as a valid unicode charlist(), otherwise as any valid iodata().

-

The options have the following meanings:

+

The options have the following meanings:

unicode The regular expression is given as a unicode charlist() and the resulting regular expression code is to be run against a valid unicode charlist() subject. @@ -173,10 +169,10 @@ This option makes it possible to include comments inside complicated patterns. N run(Subject,RE) -> {match, Captured} | nomatch Match a subject against regular expression and capture subpatterns - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() + Subject = iodata() | io:charlist() + RE = mp() | iodata() | io:charlist() Captured = [ CaptureData ] - CaptureData = {int(),int()} + CaptureData = {integer(),integer()}

The same as run(Subject,RE,[]).

@@ -186,18 +182,19 @@ This option makes it possible to include comments inside complicated patterns. N run(Subject,RE,Options) -> {match, Captured} | match | nomatch Match a subject against regular expression and capture subpatterns - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() + Subject = iodata() | io:charlist() + RE = mp() | iodata() | io:charlist() Options = [ Option ] - Option = anchored | global | notbol | noteol | notempty | {offset, int()} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {capture, ValueSpec} | {capture, ValueSpec, Type} | CompileOpt + Option = anchored | global | notbol | noteol | notempty | {offset, integer() >= 0} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {capture, ValueSpec} | {capture, ValueSpec, Type} | CompileOpt Type = index | list | binary ValueSpec = all | all_but_first | first | none | ValueList ValueList = [ ValueID ] - ValueID = int() | string() | atom() - CompileOpt = see compile/2 above - NLSpec = cr | crlf | lf | anycrlf | any + ValueID = integer() | string() | atom() + CompileOpt = compile_option() + See compile/2 above. + NLSpec = nl_spec() Captured = [ CaptureData ] | [ [ CaptureData ] ... ] - CaptureData = {int(),int()} | ListConversionData | binary() + CaptureData = {integer(),integer()} | ListConversionData | binary() ListConversionData = string() | {error, string(), binary()} | {incomplete, string(), binary()} @@ -217,7 +214,7 @@ This option makes it possible to include comments inside complicated patterns. N

If the regular expression is previously compiled, the option list can only contain the options anchored, global, notbol, noteol, - notempty, {offset, int()}, {newline, + notempty, {offset, integer() >= 0}, {newline, NLSpec} and {capture, ValueSpec}/{capture, ValueSpec, Type}. Otherwise all options valid for the re:compile/2 function are allowed as well. Options @@ -360,7 +357,7 @@ This option makes it possible to include comments inside complicated patterns. N behavior of the dollar metacharacter. It does not affect \Z or \z. - {offset, int()} + {offset, integer() >= 0} Start matching at the offset (position) given in the subject string. The offset is zero-based, so that the default is @@ -503,42 +500,27 @@ This option makes it possible to include comments inside complicated patterns. N - replace(Subject,RE,Replacement) -> iodata() | charlist() + Match a subject against regular expression and replace matching elements with Replacement - - Subject = iodata() | charlist() - RE = mp() | iodata() - Replacement = iodata() | charlist() - -

The same as replace(Subject,RE,Replacement,[]).

+

The same as replace(Subject,RE,Replacement,[]).

- replace(Subject,RE,Replacement,Options) -> iodata() | charlist() | binary() | list() + Match a subject against regular expression and replace matching elements with Replacement - - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() - Replacement = iodata() | charlist() - Options = [ Option ] - Option = anchored | global | notbol | noteol | notempty | {offset, int()} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {return, ReturnType} | CompileOpt - ReturnType = iodata | list | binary - CompileOpt = see compile/2 above - NLSpec = cr | crlf | lf | anycrlf | any - -

Replaces the matched part of the Subject string with the contents of Replacement.

+

Replaces the matched part of the Subject string with the contents of Replacement.

The permissible options are the same as for re:run/3, except that the capture option is not allowed. - Instead a {return, ReturnType} is present. The default return type is iodata, constructed in a + Instead a {return, ReturnType} is present. The default return type is iodata, constructed in a way to minimize copying. The iodata result can be used directly in many i/o-operations. If a flat list() is desired, specify {return, list} and if a binary is preferred, specify {return, binary}.

As in the re:run/3 function, an mp() compiled - with the unicode option requires the Subject to be + with the unicode option requires the Subject to be a Unicode charlist(). If compilation is done implicitly and the unicode compilation option is given to this - function, both the regular expression and the Subject + function, both the regular expression and the Subject should be given as valid Unicode charlist()s.

The replacement string can contain the special character @@ -565,34 +547,17 @@ This option makes it possible to include comments inside complicated patterns. N - split(Subject,RE) -> SplitList + Split a string by tokens specified as a regular expression - - Subject = iodata() | charlist() - RE = mp() | iodata() - SplitList = [ iodata() | charlist() ] - -

The same as split(Subject,RE,[]).

+

The same as split(Subject,RE,[]).

- split(Subject,RE,Options) -> SplitList + Split a string by tokens specified as a regular expression - - Subject = iodata() | charlist() - RE = mp() | iodata() | charlist() - Options = [ Option ] - Option = anchored | global | notbol | noteol | notempty | {offset, int()} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {return, ReturnType} | {parts, NumParts} | group | trim | CompileOpt - NumParts = int() | infinity - ReturnType = iodata | list | binary - CompileOpt = see compile/2 above - NLSpec = cr | crlf | lf | anycrlf | any - SplitList = [ RetData ] | [ GroupedRetData ] - GroupedRetData = [ RetData ] - RetData = iodata() | charlist() | binary() | list() - + See compile/2 above.

This function splits the input into parts by finding tokens according to the regular expression supplied.

@@ -602,10 +567,10 @@ This option makes it possible to include comments inside complicated patterns. N of the string is removed from the output.

As in the re:run/3 function, an mp() compiled - with the unicode option requires the Subject to be + with the unicode option requires the Subject to be a Unicode charlist(). If compilation is done implicitly and the unicode compilation option is given to this - function, both the regular expression and the Subject + function, both the regular expression and the Subject should be given as valid Unicode charlist()s.

The result is given as a list of "strings", the @@ -722,7 +687,7 @@ This option makes it possible to include comments inside complicated patterns. N

Summary of options not previously described for the re:run/3 function:

- {return,ReturnType} + {return,ReturnType}

Specifies how the parts of the original string are presented in the result list. The possible types are:

iodata diff --git a/lib/stdlib/doc/src/regexp.xml b/lib/stdlib/doc/src/regexp.xml index 8c4191c88f..35d8e1c3f8 100644 --- a/lib/stdlib/doc/src/regexp.xml +++ b/lib/stdlib/doc/src/regexp.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -40,176 +40,150 @@

This module contains functions for regular expression matching and substitution.

+ + + + + + +

Internal representation of a regular expression.

+
+
- match(String, RegExp) -> MatchRes + Match a regular expression - - String = RegExp = string() - MatchRes = {match,Start,Length} | nomatch | {error,errordesc()} - Start = Length = integer() - -

Finds the first, longest match of the regular expression RegExp in String. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:

+

Finds the first, longest match of the regular expression RegExp in String. This function searches for the longest possible match and returns the first one found if there are several expressions of the same length. It returns as follows:

- {match,Start,Length} + {match,Start,Length} -

if the match succeeded. Start is the starting - position of the match, and Length is the length of +

if the match succeeded. Start is the starting + position of the match, and Length is the length of the matching string.

nomatch

if there were no matching characters.

- {error,Error} + {error,Error} -

if there was an error in RegExp.

+

if there was an error in RegExp.

- first_match(String, RegExp) -> MatchRes + Match a regular expression - - String = RegExp = string() - MatchRes = {match,Start,Length} | nomatch | {error,errordesc()} - Start = Length = integer() - -

Finds the first match of the regular expression RegExp in String. This call is +

Finds the first match of the regular expression RegExp in String. This call is usually faster than match and it is also a useful way to ascertain that a match exists. It returns as follows:

- {match,Start,Length} + {match,Start,Length} -

if the match succeeded. Start is the starting - position of the match and Length is the length of +

if the match succeeded. Start is the starting + position of the match and Length is the length of the matching string.

nomatch

if there were no matching characters.

- {error,Error} + {error,Error} -

if there was an error in RegExp.

+

if there was an error in RegExp.

- matches(String, RegExp) -> MatchRes + Match a regular expression - - String = RegExp = string() - MatchRes = {match, Matches} | {error, errordesc()} - Matches = list() -

Finds all non-overlapping matches of the - expression RegExp in String. + expression RegExp in String. It returns as follows:

- {match, Matches} + {match, Matches}

if the regular expression was correct. - The list will be empty if there was no match. Each element in the list looks like {Start, Length}, where Start is the starting position of the match, and Length is the length of the matching string.

+ The list will be empty if there was no match. Each element in the list looks like {Start, Length}, where Start is the starting position of the match, and Length is the length of the matching string.

- {error,Error} + {error,Error} -

if there was an error in RegExp.

+

if there was an error in RegExp.

- sub(String, RegExp, New) -> SubRes + Substitute the first occurrence of a regular expression - - String = RegExp = New = string() - SubRes = {ok,NewString,RepCount} | {error,errordesc()} - RepCount = integer() - -

Substitutes the first occurrence of a substring matching RegExp in String with the string New. A in the string New is replaced by the matched substring of String. puts a literal into the replacement string. It returns as follows:

+

Substitutes the first occurrence of a substring matching RegExp in String with the string New. A in the string New is replaced by the matched substring of String. puts a literal into the replacement string. It returns as follows:

- {ok,NewString,RepCount} + {ok,NewString,RepCount} -

if RegExp is correct. RepCount is the number of replacements which have been made +

if RegExp is correct. RepCount is the number of replacements which have been made (this will be either 0 or 1).

- {error, Error} + {error, Error} -

if there is an error in RegExp.

+

if there is an error in RegExp.

- gsub(String, RegExp, New) -> SubRes + Substitute all occurrences of a regular expression - - String = RegExp = New = string() - SubRes = {ok,NewString,RepCount} | {error,errordesc()} - RepCount = integer() -

The same as sub, except that all non-overlapping occurrences of a substring matching - RegExp in String are replaced by the string New. It returns:

+ RegExp in String are replaced by the string New. It returns:

- {ok,NewString,RepCount} + {ok,NewString,RepCount} -

if RegExp is correct. RepCount is the number of replacements which have been made.

+

if RegExp is correct. RepCount is the number of replacements which have been made.

- {error, Error} + {error, Error} -

if there is an error in RegExp.

+

if there is an error in RegExp.

- split(String, RegExp) -> SplitRes + Split a string into fields - - String = RegExp = string() - SubRes = {ok,FieldList} | {error,errordesc()} - Fieldlist = [string()] - -

String is split into fields (sub-strings) by the - regular expression RegExp.

+

String is split into fields (sub-strings) by the + regular expression RegExp.

If the separator expression is " " (a single space), then the fields are separated by blanks and/or tabs and leading and trailing blanks and tabs are discarded. For all other values of the separator, leading and trailing blanks and tabs are not discarded. It returns:

- {ok, FieldList} + {ok, FieldList}

to indicate that the string has been split up into the fields of - FieldList.

+ FieldList.

- {error, Error} + {error, Error} -

if there is an error in RegExp.

+

if there is an error in RegExp.

- sh_to_awk(ShRegExp) -> AwkRegExp + Convert an shregular expression into an AWKone - - ShRegExp AwkRegExp = string() - SubRes = {ok,NewString,RepCount} | {error,errordesc()} - RepCount = integer() -

Converts the sh type regular expression - ShRegExp into a full AWK regular + ShRegExp into a full AWK regular expression. Returns the converted regular expression string. sh expressions are used in the shell for matching file names and have the following special @@ -236,40 +210,32 @@ - parse(RegExp) -> ParseRes + Parse a regular expression - - RegExp = string() - ParseRes = {ok,RE} | {error,errordesc()} - -

Parses the regular expression RegExp and builds the +

Parses the regular expression RegExp and builds the internal representation used in the other regular expression functions. Such representations can be used in all of the other functions instead of a regular expression string. This is more efficient when the same regular expression is used in many strings. It returns:

- {ok, RE}if RegExpis correct and REis the internal representation. + {ok, RE} -

+

if RegExp is correct and RE is the internal representation.

- {error, Error}if there is an error in RegExpString. + {error, Error} -

+

if there is an error in RegExp.

- format_error(ErrorDescriptor) -> Chars + Format an error descriptor - - ErrorDescriptor = errordesc() - Chars = [char() | Chars] - -

Returns a string which describes the error ErrorDescriptor +

Returns a string which describes the error ErrorDescriptor returned when there is an error in a regular expression.

diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 3610bb0184..071ee437cb 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -4,7 +4,7 @@
- 20002009 + 20002011 Ericsson AB. All Rights Reserved. @@ -43,202 +43,141 @@ different if and only if they do not compare equal (==).

-
- DATA TYPES - -set() - as returned by new/0 -
+ + + set() +

As returned by new/0.

+
+
- new() -> Set + Return an empty set - - Set = set() -

Returns a new empty set.

- is_set(Set) -> bool() + Test for an Set - - Set = term() - -

Returns true if Set is a set of +

Returns true if Set is a set of elements, otherwise false.

- size(Set) -> int() + Return the number of elements in a set - - Set = term() - -

Returns the number of elements in Set.

+

Returns the number of elements in Set.

- to_list(Set) -> List + Convert an Setinto a list - - Set = set() - List = [term()] - -

Returns the elements of Set as a list.

+

Returns the elements of Set as a list.

- from_list(List) -> Set + Convert a list into an Set - - List = [term()] - Set = set() - -

Returns an set of the elements in List.

+

Returns an set of the elements in List.

- is_element(Element, Set) -> bool() + Test for membership of an Set - - Element = term() - Set = set() - -

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

+

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

- add_element(Element, Set1) -> Set2 + Add an element to an Set - - Element = term() - Set1 = Set2 = set() - -

Returns a new set formed from Set1 with - Element inserted.

+

Returns a new set formed from Set1 with + Element inserted.

- del_element(Element, Set1) -> Set2 + Remove an element from an Set - - Element = term() - Set1 = Set2 = set() - -

Returns Set1, but with Element removed.

+

Returns Set1, but with Element removed.

- union(Set1, Set2) -> Set3 + Return the union of two Sets - - Set1 = Set2 = Set3 = set() - -

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

+

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

- union(SetList) -> Set + Return the union of a list of Sets - - SetList = [set()] - Set = set() -

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

- intersection(Set1, Set2) -> Set3 + Return the intersection of two Sets - - Set1 = Set2 = Set3 = set() - -

Returns the intersection of Set1 and - Set2.

+

Returns the intersection of Set1 and + Set2.

- intersection(SetList) -> Set + Return the intersection of a list of Sets - - SetList = [set()] - Set = set() -

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

- is_disjoint(Set1, Set2) -> bool() + Check whether two Sets are disjoint - - Set1 = Set2 = set() - -

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

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

- subtract(Set1, Set2) -> Set3 + Return the difference of two Sets - - Set1 = Set2 = Set3 = set() - -

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

+

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

- is_subset(Set1, Set2) -> bool() + Test for subset - - Set1 = Set2 = set() - -

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

+

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

- fold(Function, Acc0, Set) -> Acc1 + Fold over set elements - - Function = fun (E, AccIn) -> AccOut - Acc0 = Acc1 = AccIn = AccOut = term() - Set = set() - -

Fold Function over every element in Set +

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

- filter(Pred, Set1) -> Set2 + Filter set elements - - Pred = fun (E) -> bool() - Set1 = Set2 = set() - -

Filter elements in Set1 with boolean function - Fun.

+

Filter elements in Set1 with boolean function + Pred.

diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml index 73cc1b33bd..bc2120c37d 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -4,7 +4,7 @@
- 19962010 + 19962011 Ericsson AB. All Rights Reserved. @@ -763,26 +763,20 @@ loop(N) -> - history(N) -> integer() + Sets the number of previous commands to keep - - N = integer() -

Sets the number of previous commands to keep in the - history list to N. The previous number is returned. + history list to N. The previous number is returned. The default number is 20.

- results(N) -> integer() + Sets the number of previous results to keep - - N = integer() -

Sets the number of results from previous commands to keep in - the history list to N. The previous number is returned. + the history list to N. The previous number is returned. The default number is 20.

@@ -790,7 +784,7 @@ loop(N) -> catch_exception(Bool) -> Bool Sets the exception handling of the shell - Bool = bool() + Bool = boolean()

Sets the exception handling of the evaluator process. The @@ -804,38 +798,29 @@ loop(N) -> - prompt_func(PromptFunc) -> prompt_func() + Sets the shell prompt - - PromptFunc = prompt_func() - prompt_func() = default | {Mod, Func} - Mod = Func = atom() -

Sets the shell prompt function to PromptFunc. The previous prompt function is returned.

- start_restricted(Module) -> ok | {error, Reason} + Exits a normal shell and starts a restricted shell. - - Module = atom() - Reason = atom() -

Exits a normal shell and starts a restricted - shell. Module specifies the callback module for the + shell. Module specifies the callback module for the functions local_allowed/3 and non_local_allowed/3. The function is meant to be called from the shell.

If the callback module cannot be loaded, an error tuple is - returned. The Reason in the error tuple is the one + returned. The Reason in the error tuple is the one returned by the code loader when trying to load the code of the callback module.

- stop_restricted() -> ok + Exits a restricted shell and starts a normal shell.

Exits a restricted shell and starts a normal shell. The function diff --git a/lib/stdlib/doc/src/slave.xml b/lib/stdlib/doc/src/slave.xml index 168d83f301..15b6711731 100644 --- a/lib/stdlib/doc/src/slave.xml +++ b/lib/stdlib/doc/src/slave.xml @@ -4,7 +4,7 @@

- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -56,22 +56,16 @@ - start(Host) -> - start(Host, Name) -> - start(Host, Name, Args) -> {ok, Node} | {error, Reason} + + + Start a slave node on a host - - Host = Name = atom() - Args = string() - Node = node() - Reason = timeout | no_rsh | {already_running, Node} - -

Starts a slave node on the host Host. Host names need +

Starts a slave node on the host Host. Host names need not necessarily be specified as fully qualified names; short names can also be used. This is the same condition that applies to names of distributed Erlang nodes.

-

The name of the started node will be Name@Host. If no +

The name of the started node will be Name@Host. If no name is provided, the name will be the same as the node which executes the call (with the exception of the host name part of the node name).

@@ -79,7 +73,7 @@ terminal I/O which is produced at the slave is automatically relayed to the master. Also, the file process will be relayed to the master.

-

The Args argument is used to set erl command +

The Args argument is used to set erl command line arguments. If provided, it is passed to the new node and can be used for a variety of purposes. See erl(1)

@@ -103,9 +97,9 @@ E = " -env DISPLAY " ++ net_adm:localhost() ++ ":0 ", Arg = "-mnesia_dir " ++ M ++ " -pa " ++ Dir ++ E, slave:start(H, Name, Arg).
-

If successful, the function returns {ok, Node}, - where Node is the name of the new node. Otherwise it - returns {error, Reason}, where Reason can be +

If successful, the function returns {ok, Node}, + where Node is the name of the new node. Otherwise it + returns {error, Reason}, where Reason can be one of:

timeout @@ -123,24 +117,18 @@ slave:start(H, Name, Arg).

There is no rsh program on the computer.

- {already_running, Node} + {already_running, Node} -

A node with the name Name@Host already exists.

+

A node with the name Name@Host already exists.

- start_link(Host) -> - start_link(Host, Name) -> - start_link(Host, Name, Args) -> {ok, Node} | {error, Reason} + + + Start and link to a slave node on a host - - Host = Name = atom() - Args = string() - Node = node() - Reason = timeout | no_rsh | {already_running, Node} -

Starts a slave node in the same way as start/1,2,3, except that the slave node is linked to the currently @@ -151,11 +139,8 @@ slave:start(H, Name, Arg). - stop(Node) -> ok + Stop (kill) a node - - Node = node() -

Stops (kills) a node.

@@ -177,12 +162,8 @@ slave:start(H, Name, Arg).
- pseudo(Master, ServerList) -> ok + Start a number of pseudo servers - - Master = node() - ServerList = [atom()] -

Starts a number of pseudo servers. A pseudo server is a server with a registered name which does absolutely nothing @@ -198,16 +179,13 @@ rpc:call(N, slave, pseudo, [node(), [pxw_server]]). - relay(Pid) + Run a pseudo server - - Pid = pid() -

Runs a pseudo server. This function never returns any value and the process which executes the function will receive messages. All messages received will simply be passed on to - Pid.

+ Pid.

diff --git a/lib/stdlib/doc/src/sofs.xml b/lib/stdlib/doc/src/sofs.xml index 729df1e678..2e7768a1df 100644 --- a/lib/stdlib/doc/src/sofs.xml +++ b/lib/stdlib/doc/src/sofs.xml @@ -4,7 +4,7 @@
- 20012010 + 20012011 Ericsson AB. All Rights Reserved. @@ -181,10 +181,11 @@ the canonical map is the function that maps every element of X onto its equivalence class.

-

Relations as defined above (as sets of ordered pairs) will from - now on be referred to as binary relations. We call a - set of ordered sets (x[1], ..., x[n]) - an (n-ary) relation, and say that the relation is a subset of +

Relations as defined above + (as sets of ordered pairs) will from now on be referred to as + binary relations. We call a set of ordered sets + (x[1], ..., x[n]) an + (n-ary) relation, and say that the relation is a subset of the Cartesian product X[1] × ... × X[n] where x[i] is an element of X[i], 1 <= i <= n. @@ -293,7 +294,8 @@ partition_family/2, projection/2, restriction/3, substitution/2) accept an Erlang function as a means to modify each element of a given unordered - set. Such a function, called SetFun in the following, can be + set. Such a function, called + SetFun in the following, can be specified as a functional object (fun), a tuple {external, Fun}, or an integer. If SetFun is specified as a fun, the fun is applied to each element of the @@ -337,34 +339,73 @@ fun(S) -> sofs:partition(1, S) end message when given badly formed arguments or sets the types of which are not compatible.

When comparing external sets the operator ==/2 is used.

-

Types

-
-anyset() = - an unordered, ordered or atomic set -
-binary_relation() = - a binary relation -
-bool() = true | false
-external_set() = - an external set -
-family() = - a family (of subsets) -
-function() = - a function -
-ordset() = - an ordered set -
-relation() = - an n-ary relation -
-set() = - an unordered set -
-set_of_sets() = - an unordered set of set() -
-set_fun() = integer() >= 1
-          | {external, fun(external_set()) -> external_set()}
-          | fun(anyset()) -> anyset()
-spec_fun() = {external, fun(external_set()) -> bool()}
-           | fun(anyset()) -> bool()
-type() = - a type - 
+ + + +

Any kind of set (also included are the atomic sets).

+
+ + +

A binary + relation.

+
+ + +

An external + set.

+
+ + +

A family (of subsets).

+
+
+ + +

A function.

+
+ + +

An ordered + set.

+
+ + +

An n-ary relation. +

+
+ + +

An unordered + set.

+
+ + +

An unordered + set of unordered sets.

+
+ + +

A SetFun.

+
+ + + + + +

A type.

+
+ + + tuple_of(T) +

A tuple where the elements are of type T.

+
+
- a_function(Tuples [, Type]) -> Function + + Create a function. - - Function = function() - Tuples = [tuple()] - Type = type() -

Creates a function. a_function(F, T) is equivalent to @@ -375,16 +416,12 @@ type() = - a type - - canonical_relation(SetOfSets) -> BinRel + Return the canonical map. - - BinRel = binary_relation() - SetOfSets = set_of_sets() -

Returns the binary relation containing the elements - (E, Set) such that Set belongs to SetOfSets and E - belongs to Set. If SetOfSets is + (E, Set) such that Set belongs to SetOfSets and E + belongs to Set. If SetOfSets is a partition of a set X and R is the equivalence relation in X induced by SetOfSets, then the returned relation is @@ -398,14 +435,12 @@ type() = - a type - - composite(Function1, Function2) -> Function3 + Return the composite of two functions. - - Function1 = Function2 = Function3 = function() -

Returns the composite of - the functions Function1 and Function2.

+ the functions Function1 and + Function2.

 1> F1 = sofs:a_function([{a,1},{b,2},{c,2}]),
 F2 = sofs:a_function([{1,x},{2,y},{3,z}]),
@@ -415,14 +450,9 @@ type() = - a type - 
- constant_function(Set, AnySet) -> Function + Create the function that maps each element of a set onto another set. - - AnySet = anyset() - Function = function() - Set = set() -

Creates the function that maps each element of the set Set onto AnySet.

@@ -435,14 +465,11 @@ type() = - a type -
- converse(BinRel1) -> BinRel2 + Return the converse of a binary relation. - - BinRel1 = BinRel2 = binary_relation() -

Returns the converse - of the binary relation BinRel1.

+ of the binary relation BinRel1.

 1> R1 = sofs:relation([{1,a},{2,b},{3,a}]),
 R2 = sofs:converse(R1),
@@ -451,31 +478,25 @@ type() = - a type - 
- difference(Set1, Set2) -> Set3 + Return the difference of two sets. - - Set1 = Set2 = Set3 = set() -

Returns the difference of - the sets Set1 and Set2.

+ the sets Set1 and Set2.

- digraph_to_family(Graph [, Type]) -> Family + + Create a family from a directed graph. - - Graph = digraph() - see digraph(3) - - Family = family() - Type = type() -

Creates a family from - the directed graph Graph. Each vertex a of Graph is + the directed graph Graph. Each vertex a of + Graph is represented by a pair (a, {b[1], ..., b[n]}) where the b[i]'s are the out-neighbours of a. If no type is explicitly given, [{atom, [atom]}] is used as type of - the family. It is assumed that Type is + the family. It is assumed that Type is a valid type of the external set of the family.

If G is a directed graph, it holds that the vertices and @@ -484,15 +505,11 @@ type() = - a type - - domain(BinRel) -> Set + Return the domain of a binary relation. - - BinRel = binary_relation() - Set = set() -

Returns the domain of - the binary relation BinRel.

+ the binary relation BinRel.

 1> R = sofs:relation([{1,a},{1,b},{2,b},{2,c}]),
 S = sofs:domain(R),
@@ -501,16 +518,13 @@ type() = - a type - 
- drestriction(BinRel1, Set) -> BinRel2 + Return a restriction of a binary relation. - - BinRel1 = BinRel2 = binary_relation() - Set = set() - -

Returns the difference between the binary relation BinRel1 +

Returns the difference between the binary relation + BinRel1 and the restriction - of BinRel1 to Set.

+ of BinRel1 to Set.

 1> R1 = sofs:relation([{1,a},{2,b},{3,c}]),
 S = sofs:set([2,4,6]),
@@ -522,16 +536,13 @@ type() = - a type - 
- drestriction(SetFun, Set1, Set2) -> Set3 + Return a restriction of a relation. - - SetFun = set_fun() - Set1 = Set2 = Set3 = set() - - -

Returns a subset of Set1 containing those elements that do - not yield an element in Set2 as the result of applying - SetFun.

+ +

Returns a subset of Set1 containing those elements + that do + not yield an element in Set2 as the result of applying + SetFun.

 1> SetFun = {external, fun({_A,B,C}) -> {B,C} end},
 R1 = sofs:relation([{a,aa,1},{b,bb,2},{c,cc,3}]),
@@ -544,11 +555,8 @@ type() = - a type - 
- empty_set() -> Set + Return the untyped empty set. - - Set = set() -

Returns the untyped empty set. empty_set() is equivalent to @@ -556,19 +564,14 @@ type() = - a type - - extension(BinRel1, Set, AnySet) -> BinRel2 + Extend the domain of a binary relation. - - AnySet = anyset() - BinRel1 = BinRel2 = binary_relation() - Set = set() -

Returns the extension of - BinRel1 such that - for each element E in Set that does not belong to the - domain of BinRel1, - BinRel2 contains the pair (E, AnySet).

+ BinRel1 such that + for each element E in Set that does not belong to the + domain of BinRel1, + BinRel2 contains the pair (E, AnySet).

 1> S = sofs:set([b,c]),
 A = sofs:empty_set(),
@@ -579,13 +582,9 @@ type() = - a type - 
- family(Tuples [, Type]) -> Family + + Create a family of subsets. - - Family = family() - Tuples = [tuple()] - Type = type() -

Creates a family of subsets. family(F, T) is equivalent to @@ -596,18 +595,17 @@ type() = - a type - - family_difference(Family1, Family2) -> Family3 + Return the difference of two families. - - Family1 = Family2 = Family3 = family() - -

If Family1 and Family2 +

If Family1 and Family2 are families, then - Family3 is the family + Family3 is the family such that the index set is equal to the index set of - Family1, and Family3[i] is the difference between Family1[i] - and Family2[i] if Family2 maps i, Family1[i] otherwise.

+ Family1, and Family3[i] is the + difference between Family1[i] + and Family2[i] if Family2 maps i, + Family1[i] otherwise.

 1> F1 = sofs:family([{a,[1,2]},{b,[3,4]}]),
 F2 = sofs:family([{b,[4,5]},{c,[6,7]}]),
@@ -617,17 +615,18 @@ type() = - a type - 
- family_domain(Family1) -> Family2 + Return a family of domains. - - Family1 = Family2 = family() - - -

If Family1 is a family - and Family1[i] is a binary relation for every i in the index - set of Family1, then Family2 is the family with the same - index set as Family1 such that Family2[i] is - the domain of Family1[i].

+ +

If Family1 is + a family + and Family1[i] is a binary relation for every i + in the index set of Family1, + then Family2 is the family with the same index + set as Family1 such + that Family2[i] is + the domain of + Family1[i].

 1> FR = sofs:from_term([{a,[{1,a},{2,b},{3,c}]},{b,[]},{c,[{4,d},{5,e}]}]),
 F = sofs:family_domain(FR),
@@ -636,17 +635,18 @@ type() = - a type - 
- family_field(Family1) -> Family2 + Return a family of fields. - - Family1 = Family2 = family() - - -

If Family1 is a family - and Family1[i] is a binary relation for every i in the index - set of Family1, then Family2 is the family with the same - index set as Family1 such that Family2[i] is - the field of Family1[i].

+ +

If Family1 is + a family + and Family1[i] is a binary relation for every i + in the index set of Family1, + then Family2 is the family with the same index + set as Family1 such + that Family2[i] is + the field of + Family1[i].

 1> FR = sofs:from_term([{a,[{1,a},{2,b},{3,c}]},{b,[]},{c,[{4,d},{5,e}]}]),
 F = sofs:family_field(FR),
@@ -657,21 +657,21 @@ type() = - a type - 
- family_intersection(Family1) -> Family2 + Return the intersection of a family of sets of sets. - - Family1 = Family2 = family() - - -

If Family1 is a family - and Family1[i] is a set of sets for every i in the index set - of Family1, then Family2 is the family with the same index - set as Family1 such that Family2[i] is - the intersection of - Family1[i].

-

If Family1[i] is an empty set for some i, then the process - exits with a badarg message.

+ +

If Family1 is + a family + and Family1[i] is a set of sets for every i in + the index set of Family1, + then Family2 is the family with the same index + set as Family1 such + that Family2[i] is + the intersection + of Family1[i].

+

If Family1[i] is an empty set for some i, then + the process exits with a badarg message.

 1> F1 = sofs:from_term([{a,[[1,2,3],[2,3,4]]},{b,[[x,y,z],[x,y]]}]),
 F2 = sofs:family_intersection(F1),
@@ -680,17 +680,16 @@ type() = - a type - 
- family_intersection(Family1, Family2) -> Family3 + Return the intersection of two families. - - Family1 = Family2 = Family3 = family() - - -

If Family1 and Family2 - are families, then Family3 - is the family such that the index set is the intersection of - Family1's and Family2's index sets, and Family3[i] is the - intersection of Family1[i] and Family2[i].

+ +

If Family1 and Family2 + are families, + then Family3 is the family such that the index + set is the intersection of Family1's and + Family2's index sets, + and Family3[i] is the intersection of + Family1[i] and Family2[i].

 1> F1 = sofs:family([{a,[1,2]},{b,[3,4]},{c,[5,6]}]),
 F2 = sofs:family([{b,[4,5]},{c,[7,8]},{d,[9,10]}]),
@@ -700,18 +699,16 @@ type() = - a type - 
- family_projection(SetFun, Family1) -> Family2 + Return a family of modified subsets. - - SetFun = set_fun() - Family1 = Family2 = family() - Set = set() - - -

If Family1 is a family - then Family2 is the family with the same index set as - Family1 such that Family2[i] is the result of calling SetFun - with Family1[i] as argument.

+ +

If Family1 is + a family + then Family2 is the family with the same index + set as Family1 such + that Family2[i] is the result of + calling SetFun with Family1[i] as + argument.

 1> F1 = sofs:from_term([{a,[[1,2],[2,3]]},{b,[[]]}]),
 F2 = sofs:family_projection({sofs, union}, F1),
@@ -720,17 +717,18 @@ type() = - a type - 
- family_range(Family1) -> Family2 + Return a family of ranges. - - Family1 = Family2 = family() - - -

If Family1 is a family - and Family1[i] is a binary relation for every i in the index - set of Family1, then Family2 is the family with the same - index set as Family1 such that Family2[i] is - the range of Family1[i].

+ +

If Family1 is + a family + and Family1[i] is a binary relation for every i + in the index set of Family1, + then Family2 is the family with the same index + set as Family1 such + that Family2[i] is + the range of + Family1[i].

 1> FR = sofs:from_term([{a,[{1,a},{2,b},{3,c}]},{b,[]},{c,[{4,d},{5,e}]}]),
 F = sofs:family_range(FR),
@@ -739,22 +737,21 @@ type() = - a type - 
- family_specification(Fun, Family1) -> Family2 + Select a subset of a family using a predicate. - - Fun = spec_fun() - Family1 = Family2 = family() - - -

If Family1 is a family, - then Family2 is - the restriction of - Family1 to those elements i of the - index set for which Fun applied to Family1[i] returns - true. If Fun is a tuple {external, Fun2}, - Fun2 is applied to - the external set of - Family1[i], otherwise Fun is applied to Family1[i].

+ +

If Family1 is + a family, + then Family2 is + the restriction of + Family1 to those elements i of the index set + for which Fun applied + to Family1[i] returns + true. If Fun is a + tuple {external, Fun2}, Fun2 is applied to + the external set + of Family1[i], otherwise Fun is + applied to Family1[i].

 1> F1 = sofs:family([{a,[1,2,3]},{b,[1,2]},{c,[1]}]),
 SpecFun = fun(S) -> sofs:no_elements(S) =:= 2 end,
@@ -764,24 +761,22 @@ type() = - a type - 
- family_to_digraph(Family [, GraphType]) -> Graph + + Create a directed graph from a family. - - Graph = digraph() - Family = family() - GraphType = - see digraph(3) - -

Creates a directed graph from - the family Family. For each - pair (a, {b[1], ..., b[n]}) of Family, the vertex + the family Family. + For each pair (a, {b[1], ..., b[n]}) + of Family, the vertex a as well the edges (a, b[i]) for 1 <= i <= n are added to a newly created directed graph.

-

If no graph type is given, digraph:new/1 is used for - creating the directed graph, otherwise the GraphType +

If no graph type is given + digraph:new/0 is used for + creating the directed graph, otherwise the GraphType argument is passed on as second argument to - digraph:new/2.

+ digraph:new/1.

It F is a family, it holds that F is a subset of digraph_to_family(family_to_digraph(F), type(F)). Equality holds if union_of_family(F) is a subset of @@ -791,17 +786,15 @@ type() = - a type - - family_to_relation(Family) -> BinRel + Create a binary relation from a family. - - Family = family() - BinRel = binary_relation() - - -

If Family is a family, - then BinRel is the binary relation containing all pairs - (i, x) such that i belongs to the index set of Family - and x belongs to Family[i].

+ +

If Family is + a family, + then BinRel is the binary relation containing + all pairs (i, x) such that i belongs to the index set + of Family and x belongs + to Family[i].

 1> F = sofs:family([{a,[]}, {b,[1]}, {c,[2,3]}]),
 R = sofs:family_to_relation(F),
@@ -810,17 +803,18 @@ type() = - a type - 
- family_union(Family1) -> Family2 + Return the union of a family of sets of sets. - - Family1 = Family2 = family() - - -

If Family1 is a family - and Family1[i] is a set of sets for each i in the index set - of Family1, then Family2 is the family with the same index - set as Family1 such that Family2[i] is - the union of Family1[i].

+ +

If Family1 is + a family + and Family1[i] is a set of sets for each i in + the index set of Family1, + then Family2 is the family with the same index + set as Family1 such + that Family2[i] is + the union of + Family1[i].

 1> F1 = sofs:from_term([{a,[[1,2],[2,3]]},{b,[[]]}]),
 F2 = sofs:family_union(F1),
@@ -831,18 +825,18 @@ type() = - a type - 
- family_union(Family1, Family2) -> Family3 + Return the union of two families. - - Family1 = Family2 = Family3 = family() - - -

If Family1 and Family2 - are families, then Family3 - is the family such that the index set is the union of Family1's - and Family2's index sets, and Family3[i] is the union of - Family1[i] and Family2[i] if both maps i, Family1[i] or - Family2[i] otherwise.

+ +

If Family1 and Family2 + are families, + then Family3 is the family such that the index + set is the union of Family1's + and Family2's index sets, + and Family3[i] is the union + of Family1[i] and Family2[i] if + both maps i, Family1[i] + or Family2[i] otherwise.

 1> F1 = sofs:family([{a,[1,2]},{b,[3,4]},{c,[5,6]}]),
 F2 = sofs:family([{b,[4,5]},{c,[7,8]},{d,[9,10]}]),
@@ -852,15 +846,11 @@ type() = - a type - 
- field(BinRel) -> Set + Return the field of a binary relation. - - BinRel = binary_relation() - Set = set() -

Returns the field of the - binary relation BinRel.

+ binary relation BinRel.

 1> R = sofs:relation([{1,a},{1,b},{2,b},{2,c}]),
 S = sofs:field(R),
@@ -871,31 +861,24 @@ type() = - a type - 
- from_external(ExternalSet, Type) -> AnySet + Create a set. - - ExternalSet = external_set() - AnySet = anyset() - Type = type() -

Creates a set from the external - set ExternalSet - and the type Type. It is - assumed that Type is a valid - type of ExternalSet.

+ set ExternalSet + and the type Type. + It is assumed that Type is + a valid + type of ExternalSet.

- from_sets(ListOfSets) -> Set + Create a set out of a list of sets. - - Set = set() - ListOfSets = [anyset()] -

Returns the unordered - set containing the sets of the list ListOfSets.

+ set containing the sets of the list + ListOfSets.

 1> S1 = sofs:relation([{a,1},{b,2}]),
 S2 = sofs:relation([{x,3},{y,4}]),
@@ -905,38 +888,33 @@ type() = - a type - 
- from_sets(TupleOfSets) -> Ordset + Create an ordered set out of a tuple of sets. - - Ordset = ordset() - TupleOfSets = tuple-of(anyset()) -

Returns the ordered set containing the sets of the non-empty tuple - TupleOfSets.

+ TupleOfSets.

- from_term(Term [, Type]) -> AnySet + + Create a set. - - AnySet = anyset() - Term = term() - Type = type() -

Creates an element of Sets by - traversing the term Term, sorting lists, removing duplicates and + traversing the term Term, sorting lists, + removing duplicates and deriving or verifying a valid type for the so obtained external set. An - explicitly given type Type + explicitly given type + Type can be used to limit the depth of the traversal; an atomic type stops the traversal, as demonstrated by this example where "foo" and {"foo"} are left unmodified:

-1> S = sofs:from_term([{{"foo"},[1,1]},{"foo",[2,2]}], [{atom,[atom]}]),
+1> S = sofs:from_term([{{"foo"},[1,1]},{"foo",[2,2]}],
+[{atom,[atom]}]),
 sofs:to_external(S).
 [{{"foo"},[1]},{"foo",[2]}]

from_term can be used for creating atomic or ordered @@ -963,15 +941,12 @@ type() = - a type - - image(BinRel, Set1) -> Set2 + Return the image of a set under a binary relation. - - BinRel = binary_relation() - Set1 = Set2 = set() -

Returns the image of the - set Set1 under the binary relation BinRel.

+ set Set1 under the binary + relation BinRel.

 1> R = sofs:relation([{1,a},{2,b},{2,c},{3,d}]),
 S1 = sofs:set([1,2]),
@@ -981,42 +956,32 @@ type() = - a type - 
- intersection(SetOfSets) -> Set + Return the intersection of a set of sets. - - Set = set() - SetOfSets = set_of_sets() -

Returns the intersection of - the set of sets SetOfSets.

+ the set of sets SetOfSets.

Intersecting an empty set of sets exits the process with a badarg message.

- intersection(Set1, Set2) -> Set3 + Return the intersection of two sets. - - Set1 = Set2 = Set3 = set() -

Returns the intersection of - Set1 and Set2.

+ Set1 and Set2.

- intersection_of_family(Family) -> Set + Return the intersection of a family. - - Family = family() - Set = set() -

Returns the intersection of - the family Family.

+ the family Family. +

Intersecting an empty family exits the process with a badarg message.

@@ -1027,14 +992,11 @@ type() = - a type - 
- inverse(Function1) -> Function2 + Return the inverse of a function. - - Function1 = Function2 = function() -

Returns the inverse - of the function Function1.

+ of the function Function1.

 1> R1 = sofs:relation([{1,a},{2,b},{3,c}]),
 R2 = sofs:inverse(R1),
@@ -1043,16 +1005,13 @@ type() = - a type - 
- inverse_image(BinRel, Set1) -> Set2 + Return the inverse image of a set under a binary relation. - - BinRel = binary_relation() - Set1 = Set2 = set() - -

Returns the inverse - image of Set1 under the binary relation BinRel.

+

Returns the inverse + image of Set1 under the binary + relation BinRel.

 1> R = sofs:relation([{1,a},{2,b},{2,c},{3,d}]),
 S1 = sofs:set([c,d,e]),
@@ -1062,52 +1021,38 @@ type() = - a type - 
- is_a_function(BinRel) -> Bool + Test for a function. - - Bool = bool() - BinRel = binary_relation() - -

Returns true if the binary relation BinRel is a - function or the +

Returns true if the binary relation BinRel + is a function or the untyped empty set, false otherwise.

- is_disjoint(Set1, Set2) -> Bool + Test for disjoint sets. - - Bool = bool() - Set1 = Set2 = set() - -

Returns true if Set1 and Set2 +

Returns true if Set1 + and Set2 are disjoint, false otherwise.

- is_empty_set(AnySet) -> Bool + Test for an empty set. - - AnySet = anyset() - Bool = bool() - -

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

+

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

- is_equal(AnySet1, AnySet2) -> Bool + Test two sets for equality. - - AnySet1 = AnySet2 = anyset() - Bool = bool() - -

Returns true if the AnySet1 and AnySet2 +

Returns true if the AnySet1 + and AnySet2 are equal, false otherwise. This example shows that ==/2 is used when comparing sets for equality:

@@ -1119,67 +1064,49 @@ true
- is_set(AnySet) -> Bool + Test for an unordered set. - - AnySet = anyset() - Bool = bool() - -

Returns true if AnySet is +

Returns true if AnySet is an unordered set, and - false if AnySet is an ordered set or an atomic set.

+ false if AnySet is an ordered set or an + atomic set.

- is_sofs_set(Term) -> Bool + Test for an unordered set. - - Bool = bool() - Term = term() - -

Returns true if Term is +

Returns true if Term is an unordered set, an ordered set or an atomic set, false otherwise.

- is_subset(Set1, Set2) -> Bool + Test two sets for subset. - - Bool = bool() - Set1 = Set2 = set() - -

Returns true if Set1 is - a subset of Set2, false - otherwise.

+

Returns true if Set1 is + a subset + of Set2, false otherwise.

- is_type(Term) -> Bool + Test for a type. - - Bool = bool() - Term = term() - -

Returns true if the term Term is +

Returns true if the term Term is a type.

- join(Relation1, I, Relation2, J) -> Relation3 + Return the join of two relations. - - Relation1 = Relation2 = Relation3 = relation() - I = J = integer() > 0 -

Returns the natural - join of the relations Relation1 and Relation2 on - coordinates I and J.

+ join of the relations Relation1 + and Relation2 on coordinates I and + J.

 1> R1 = sofs:relation([{a,x,1},{b,y,2}]),
 R2 = sofs:relation([{1,f,g},{1,h,i},{2,3,4}]),
@@ -1189,20 +1116,17 @@ true
- multiple_relative_product(TupleOfBinRels, BinRel1) -> BinRel2 + Return the multiple relative product of a tuple of binary relations and a relation. - - TupleOfBinRels = tuple-of(BinRel) - BinRel = BinRel1 = BinRel2 = binary_relation() - - -

If TupleOfBinRels is a non-empty tuple - {R[1], ..., R[n]} of binary relations and BinRel1 - is a binary relation, then BinRel2 is + +

If TupleOfBinRels is a non-empty tuple + {R[1], ..., R[n]} of binary relations + and BinRel1 is a binary relation, + then BinRel2 is the multiple relative product of the ordered set - (R[i], ..., R[n]) and BinRel1.

+ (R[i], ..., R[n]) and BinRel1.

 1> Ri = sofs:relation([{a,1},{b,2},{c,3}]),
 R = sofs:relation([{a,b},{b,c},{c,a}]),
@@ -1212,29 +1136,21 @@ true
- no_elements(ASet) -> NoElements + Return the number of elements of a set. - - ASet = set() | ordset() - NoElements = integer() >= 0 -

Returns the number of elements of the ordered or unordered - set ASet.

+ set ASet.

- partition(SetOfSets) -> Partition + Return the coarsest partition given a set of sets. - - SetOfSets = set_of_sets() - Partition = set() -

Returns the partition of - the union of the set of sets SetOfSets such that two + the union of the set of sets SetOfSets such that two elements are considered equal if they belong to the same - elements of SetOfSets.

+ elements of SetOfSets.

 1> Sets1 = sofs:from_term([[a,b,c],[d,e,f],[g,h,i]]),
 Sets2 = sofs:from_term([[b,c,d],[e,f,g],[h,i,j]]),
@@ -1244,17 +1160,12 @@ true
- partition(SetFun, Set) -> Partition + Return a partition of a set. - - SetFun = set_fun() - Partition = set() - Set = set() -

Returns the partition of - Set such that two elements are considered equal if the - results of applying SetFun are equal.

+ Set such that two elements are considered equal + if the results of applying SetFun are equal.

 1> Ss = sofs:from_term([[a],[b],[c,d],[e,f]]),
 SetFun = fun(S) -> sofs:from_term(sofs:no_elements(S)) end,
@@ -1264,19 +1175,16 @@ true
- partition(SetFun, Set1, Set2) -> {Set3, Set4} + Return a partition of a set. - - SetFun = set_fun() - Set1 = Set2 = Set3 = Set4 = set() -

Returns a pair of sets that, regarded as constituting a set, forms a partition of - Set1. If the - result of applying SetFun to an element of Set1 yields an - element in Set2, the element belongs to Set3, otherwise the - element belongs to Set4.

+ Set1. If the + result of applying SetFun to an element + of Set1 yields an element in Set2, + the element belongs to Set3, otherwise the + element belongs to Set4.

 1> R1 = sofs:relation([{1,a},{2,b},{3,c}]),
 S = sofs:set([2,4,6]),
@@ -1289,21 +1197,17 @@ true
- partition_family(SetFun, Set) -> Family + Return a family indexing a partition. - - Family = family() - SetFun = set_fun() - Set = set() -

Returns the family - Family where the indexed set is - a partition of Set - such that two elements are considered equal if the results - of applying SetFun are the same value i. This i is the index - that Family maps onto - the equivalence + Family where the indexed set is + a partition + of Set such that two elements are considered + equal if the results of applying SetFun are the + same value i. This i is the index that Family + maps onto + the equivalence class.

 1> S = sofs:relation([{a,a,a,a},{a,a,b,b},{a,b,b,b}]),
@@ -1314,18 +1218,15 @@ true
- product(TupleOfSets) -> Relation + Return the Cartesian product of a tuple of sets. - - Relation = relation() - TupleOfSets = tuple-of(set()) -

Returns the Cartesian product of the non-empty tuple of sets - TupleOfSets. If (x[1], ..., x[n]) is an element of - the n-ary relation Relation, then x[i] is drawn from element - i of TupleOfSets.

+ TupleOfSets. If (x[1], ..., x[n]) is + an element of the n-ary relation Relation, then + x[i] is drawn from element i + of TupleOfSets.

 1> S1 = sofs:set([a,b]),
 S2 = sofs:set([1,2]),
@@ -1336,15 +1237,12 @@ true
- product(Set1, Set2) -> BinRel + Return the Cartesian product of two sets. - - BinRel = binary_relation() - Set1 = Set2 = set() -

Returns the Cartesian - product of Set1 and Set2.

+ product of Set1 + and Set2.

 1> S1 = sofs:set([1,2]),
 S2 = sofs:set([a,b]),
@@ -1356,19 +1254,16 @@ true
- projection(SetFun, Set1) -> Set2 + Return a set of substituted elements. - - SetFun = set_fun() - Set1 = Set2 = set() -

Returns the set created by substituting each element of - Set1 by the result of applying SetFun to the element.

-

If SetFun is a number i >= 1 and Set1 is a - relation, then the returned set is - the projection of Set1 - onto coordinate i.

+ Set1 by the result of + applying SetFun to the element.

+

If SetFun is a number i >= 1 and + Set1 is a relation, then the returned set is + the projection of + Set1 onto coordinate i.

 1> S1 = sofs:from_term([{1,a},{2,b},{3,a}]),
 S2 = sofs:projection(2, S1),
@@ -1377,15 +1272,11 @@ true
- range(BinRel) -> Set + Return the range of a binary relation. - - BinRel = binary_relation() - Set = set() -

Returns the range of the - binary relation BinRel.

+ binary relation BinRel.

 1> R = sofs:relation([{1,a},{1,b},{2,b},{2,c}]),
 S = sofs:range(R),
@@ -1394,41 +1285,33 @@ true
- relation(Tuples [, Type]) -> Relation + + Create a relation. - - N = integer() - Type = N | type() - Relation = relation() - Tuples = [tuple()] -

Creates a relation. relation(R, T) is equivalent to from_term(R, T), if T is a type and the result is a - relation. If Type is an integer N, then + relation. If Type is an integer N, then [{atom, ..., atom}]), where the size of the tuple is N, is used as type of the relation. If no type is - explicitly given, the size of the first tuple of Tuples is + explicitly given, the size of the first tuple of + Tuples is used if there is such a tuple. relation([]) is equivalent to relation([], 2).

- relation_to_family(BinRel) -> Family + Create a family from a binary relation. - - Family = family() - BinRel = binary_relation() -

Returns the family - Family such that the index set is equal to + Family such that the index set is equal to the domain of the binary - relation BinRel, and Family[i] is + relation BinRel, and Family[i] is the image of the set of i - under BinRel.

+ under BinRel.

 1> R = sofs:relation([{b,1},{c,2},{c,3}]),
 F = sofs:relation_to_family(R),
@@ -1437,63 +1320,57 @@ true
- relative_product(TupleOfBinRels [, BinRel1]) -> BinRel2 - Return the relative product of a tuple of binary relations + + + Return the relative product of a list of binary relations and a binary relation. - - TupleOfBinRels = tuple-of(BinRel) - BinRel = BinRel1 = BinRel2 = binary_relation() - - -

If TupleOfBinRels is a non-empty tuple - {R[1], ..., R[n]} of binary relations and BinRel1 - is a binary relation, then BinRel2 is - the relative - product of the ordered set (R[i], ..., R[n]) - and BinRel1.

-

If BinRel1 is omitted, the relation of equality between the - elements of - the Cartesian - product of the ranges of R[i], + +

If ListOfBinRels is a non-empty list + [R[1], ..., R[n]] of binary relations and + BinRel1 + is a binary relation, then BinRel2 is the relative product + of the ordered set (R[i], ..., R[n]) and + BinRel1.

+

If BinRel1 is omitted, the relation of equality + between the elements of + the Cartesian + product of the ranges of R[i], range R[1] × ... × range R[n], is used instead (intuitively, nothing is "lost").

 1> TR = sofs:relation([{1,a},{1,aa},{2,b}]),
 R1 = sofs:relation([{1,u},{2,v},{3,c}]),
-R2 = sofs:relative_product({TR, R1}),
+R2 = sofs:relative_product([TR, R1]),
 sofs:to_external(R2).
 [{1,{a,u}},{1,{aa,u}},{2,{b,v}}]
-

Note that relative_product({R1}, R2) is +

Note that relative_product([R1], R2) is different from relative_product(R1, R2); the - tuple of one element is not identified with the element + list of one element is not identified with the element itself.

- relative_product(BinRel1, BinRel2) -> BinRel3 + Return the relative product of two binary relations. - - BinRel1 = BinRel2 = BinRel3 = binary_relation() -

Returns the relative - product of the binary relations BinRel1 and BinRel2.

+ product of the binary relations BinRel1 + and BinRel2.

- relative_product1(BinRel1, BinRel2) -> BinRel3 + Return the relative_product of two binary relations. - - BinRel1 = BinRel2 = BinRel3 = binary_relation() -

Returns the relative product of the converse of the - binary relation BinRel1 and the binary relation BinRel2.

+ binary relation BinRel1 and the binary + relation BinRel2.

 1> R1 = sofs:relation([{1,a},{1,aa},{2,b}]),
 R2 = sofs:relation([{1,u},{2,v},{3,c}]),
@@ -1505,15 +1382,12 @@ true
- restriction(BinRel1, Set) -> BinRel2 + Return a restriction of a binary relation. - - BinRel1 = BinRel2 = binary_relation() - Set = set() -

Returns the restriction of - the binary relation BinRel1 to Set.

+ the binary relation BinRel1 + to Set.

 1> R1 = sofs:relation([{1,a},{2,b},{3,c}]),
 S = sofs:set([1,2,4]),
@@ -1523,15 +1397,12 @@ true
- restriction(SetFun, Set1, Set2) -> Set3 + Return a restriction of a set. - - SetFun = set_fun() - Set1 = Set2 = Set3 = set() - -

Returns a subset of Set1 containing those elements that - yield an element in Set2 as the result of applying SetFun.

+

Returns a subset of Set1 containing those + elements that yield an element in Set2 as the + result of applying SetFun.

 1> S1 = sofs:relation([{1,a},{2,b},{3,c}]),
 S2 = sofs:set([b,c,d]),
@@ -1541,13 +1412,9 @@ true
- set(Terms [, Type]) -> Set + + Create a set of atoms or any type of sets. - - Set = set() - Terms = [term()] - Type = type() -

Creates an unordered set. set(L, T) is equivalent to @@ -1557,18 +1424,16 @@ true - specification(Fun, Set1) -> Set2 + Select a subset using a predicate. - - Fun = spec_fun() - Set1 = Set2 = set() - -

Returns the set containing every element of Set1 for which - Fun returns true. If Fun is a tuple +

Returns the set containing every element + of Set1 for which Fun + returns true. If Fun is a tuple {external, Fun2}, Fun2 is applied to the external set of - each element, otherwise Fun is applied to each element.

+ each element, otherwise Fun is applied to each + element.

 1> R1 = sofs:relation([{a,1},{b,2}]),
 R2 = sofs:relation([{x,1},{x,2},{y,3}]),
@@ -1579,15 +1444,13 @@ true
- strict_relation(BinRel1) -> BinRel2 + Return the strict relation corresponding to a given relation. - - BinRel1 = BinRel2 = binary_relation() -

Returns the strict - relation corresponding to the binary relation BinRel1.

+ relation corresponding to the binary + relation BinRel1.

 1> R1 = sofs:relation([{1,1},{1,2},{2,1},{2,2}]),
 R2 = sofs:strict_relation(R1),
@@ -1596,16 +1459,13 @@ true
- substitution(SetFun, Set1) -> Set2 + Return a function with a given set as domain. - - SetFun = set_fun() - Set1 = Set2 = set() - - -

Returns a function, the domain of which is Set1. The value - of an element of the domain is the result of applying SetFun - to the element.

+ +

Returns a function, the domain of which + is Set1. The value of an element of the domain + is the result of applying SetFun to the + element.

 1> L = [{a,1},{b,2}].
 [{a,1},{b,2}]
@@ -1647,14 +1507,12 @@ images2(SetOfSets, BinRel) ->
       
     
     
-      symdiff(Set1, Set2) -> Set3
+      
       Return the symmetric difference of two sets.
-      
-        Set1 = Set2 = Set3 = set()
-      
       
         

Returns the symmetric - difference (or the Boolean sum) of Set1 and Set2.

+ difference (or the Boolean sum) + of Set1 and Set2.

 1> S1 = sofs:set([1,2,3]),
 S2 = sofs:set([2,3,4]),
@@ -1664,88 +1522,67 @@ images2(SetOfSets, BinRel) ->
       
     
     
-      symmetric_partition(Set1, Set2) -> {Set3, Set4, Set5}
+      
       Return a partition of two sets.
-      
-        Set1 = Set2 = Set3 = Set4 = Set5 = set()
-      
       
-        

Returns a triple of sets: Set3 contains the elements - of Set1 that do not belong to Set2; Set4 contains the - elements of Set1 that belong to Set2; Set5 contains the - elements of Set2 that do not belong to Set1.

+

Returns a triple of sets: Set3 contains the + elements of Set1 that do not belong + to Set2; Set4 contains the + elements of Set1 that belong + to Set2; Set5 contains the + elements of Set2 that do not belong + to Set1.

- to_external(AnySet) -> ExternalSet + Return the elements of a set. - - ExternalSet = external_set() - AnySet = anyset() -

Returns the external set of an atomic, ordered or unordered set.

- to_sets(ASet) -> Sets + Return a list or a tuple of the elements of set. - - ASet = set() | ordset() - Sets = tuple_of(AnySet) | [AnySet] - -

Returns the elements of the ordered set ASet as a tuple of - sets, and the elements of the unordered set ASet as a sorted - list of sets without duplicates.

+

Returns the elements of the ordered set ASet + as a tuple of sets, and the elements of the unordered set + ASet as a sorted list of sets without + duplicates.

- type(AnySet) -> Type + Return the type of a set. - - AnySet = anyset() - Type = type() -

Returns the type of an atomic, ordered or unordered set.

- union(SetOfSets) -> Set + Return the union of a set of sets. - - Set = set() - SetOfSets = set_of_sets() -

Returns the union of the - set of sets SetOfSets.

+ set of sets SetOfSets.

- union(Set1, Set2) -> Set3 + Return the union of two sets. - - Set1 = Set2 = Set3 = set() -

Returns the union of - Set1 and Set2.

+ Set1 and Set2.

- union_of_family(Family) -> Set + Return the union of a family. - - Family = family() - Set = set() -

Returns the union of - the family Family.

+ the family Family. +

 1> F = sofs:family([{a,[0,2,4]},{b,[0,1,2]},{c,[2,3]}]),
 S = sofs:union_of_family(F),
@@ -1754,17 +1591,15 @@ images2(SetOfSets, BinRel) ->
       
     
     
-      weak_relation(BinRel1) -> BinRel2
+      
       Return the weak relation corresponding to 
         a given relation.
-      
-        BinRel1 = BinRel2 = binary_relation()
-      
       
         

Returns a subset S of the weak relation W - corresponding to the binary relation BinRel1. Let F be the - field of BinRel1. The + corresponding to the binary relation BinRel1. + Let F be the field of + BinRel1. The subset S is defined so that x S y if x W y for some x in F and for some y in F.

diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml
new file mode 100644
index 0000000000..98338b5ec2
--- /dev/null
+++ b/lib/stdlib/doc/src/specs.xml
@@ -0,0 +1,63 @@
+
+
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+
diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml
index de1b99a2d5..48867ffe72 100644
--- a/lib/stdlib/doc/src/string.xml
+++ b/lib/stdlib/doc/src/string.xml
@@ -4,7 +4,7 @@
 
   
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -38,65 +38,46 @@ - len(String) -> Length + Return the length of a string - - String = string() - Length = integer() -

Returns the number of characters in the string.

- equal(String1, String2) -> bool() + Test string equality - - String1 = String2 = string() -

Tests whether two strings are equal. Returns true if they are, otherwise false.

- concat(String1, String2) -> String3 + Concatenate two strings - - String1 = String2 = String3 = string() -

Concatenates two strings to form a new string. Returns the new string.

- chr(String, Character) -> Index - rchr(String, Character) -> Index + + Return the index of the first/last occurrence ofCharacterin String - - String = string() - Character = char() - Index = integer() -

Returns the index of the first/last occurrence of - Character in String. 0 is returned if Character does not + Character in String. 0 is returned if Character does not occur.

- str(String, SubString) -> Index - rstr(String, SubString) -> Index + + Find the index of a substring - - String = SubString = string() - Index = integer() -

Returns the position where the first/last occurrence of - SubString begins in String. 0 is returned if SubString - does not exist in String. + SubString begins in String. 0 is returned if SubString + does not exist in String. For example:

> string:str(" Hello Hello World World ", "Hello World"). @@ -104,17 +85,13 @@
- span(String, Chars) -> Length - cspan(String, Chars) -> Length + + Span characters at start of string - - String = Chars = string() - Length = integer() -

Returns the length of the maximum initial segment of - String, which consists entirely of characters from (not - from) Chars.

+ String, which consists entirely of characters from (not + from) Chars.

For example:

> string:span("\t abcdef", " \t"). @@ -124,17 +101,13 @@
- substr(String, Start) -> SubString - substr(String, Start, Length) -> Substring + + Return a substring of String - - String = SubString = string() - Start = Length = integer() - -

Returns a substring of String, starting at the - position Start, and ending at the end of the string or - at length Length.

+

Returns a substring of String, starting at the + position Start, and ending at the end of the string or + at length Length.

For example:

> substr("Hello World", 4, 5). @@ -142,15 +115,11 @@
- tokens(String, SeparatorList) -> Tokens + Split string into tokens - - String = SeparatorList = string() - Tokens = [string()] - -

Returns a list of tokens in String, separated by the - characters in SeparatorList.

+

Returns a list of tokens in String, separated by the + characters in SeparatorList.

For example:

> tokens("abc defxxghix jkl", "x "). @@ -158,15 +127,11 @@
- join(StringList, Separator) -> String + Join a list of strings with separator - - StringList = [string()] - Separator = string() - -

Returns a string with the elements of StringList - separated by the string in Seperator.

+

Returns a string with the elements of StringList + separated by the string in Separator.

For example:

> join(["one", "two", "three"], ", "). @@ -174,44 +139,30 @@
- chars(Character, Number) -> String - chars(Character, Number, Tail) -> String + + Returns a string consisting of numbers of characters - - Character = char() - Number = integer() - String = string() - -

Returns a string consisting of Number of characters - Character. Optionally, the string can end with the - string Tail.

+

Returns a string consisting of Number of characters + Character. Optionally, the string can end with the + string Tail.

- copies(String, Number) -> Copies + Copy a string - - String = Copies = string() - Number = integer() - -

Returns a string containing String repeated - Number times.

+

Returns a string containing String repeated + Number times.

- words(String) -> Count - words(String, Character) -> Count + + Count blank separated words - - String = string() - Character = char() - Count = integer() - -

Returns the number of words in String, separated by - blanks or Character.

+

Returns the number of words in String, separated by + blanks or Character.

For example:

> words(" Hello old boy!", $o). @@ -219,17 +170,12 @@
- sub_word(String, Number) -> Word - sub_word(String, Number, Character) -> Word + + Extract subword - - String = Word = string() - Character = char() - Number = integer() - -

Returns the word in position Number of String. - Words are separated by blanks or Characters.

+

Returns the word in position Number of String. + Words are separated by blanks or Characters.

For example:

> string:sub_word(" Hello old boy !",3,$o). @@ -237,19 +183,14 @@
- strip(String) -> Stripped - strip(String, Direction) -> Stripped - strip(String, Direction, Character) -> Stripped + + + Strip leading or trailing characters - - String = Stripped = string() - Direction = left | right | both - Character = char() -

Returns a string, where leading and/or trailing blanks or a - number of Character have been removed. - Direction can be left, right, or + number of Character have been removed. + Direction can be left, right, or both and indicates from which direction blanks are to be removed. The function strip/1 is equivalent to strip(String, both).

@@ -260,19 +201,14 @@
- left(String, Number) -> Left - left(String, Number, Character) -> Left + + Adjust left end of string - - String = Left = string() - Character = char - Number = integer() - -

Returns the String with the length adjusted in - accordance with Number. The left margin is - fixed. If the length(String) < Number, - String is padded with blanks or Characters.

+

Returns the String with the length adjusted in + accordance with Number. The left margin is + fixed. If the length(String) < Number, + String is padded with blanks or Characters.

For example:

> string:left("Hello",10,$.). @@ -280,19 +216,14 @@
- right(String, Number) -> Right - right(String, Number, Character) -> Right + + Adjust right end of string - - String = Right = string() - Character = char - Number = integer() - -

Returns the String with the length adjusted in - accordance with Number. The right margin is - fixed. If the length of (String) < Number, - String is padded with blanks or Characters.

+

Returns the String with the length adjusted in + accordance with Number. The right margin is + fixed. If the length of (String) < Number, + String is padded with blanks or Characters.

For example:

> string:right("Hello", 10, $.). @@ -300,32 +231,23 @@
- centre(String, Number) -> Centered - centre(String, Number, Character) -> Centered + + Center a string - - String = Centered = string() - Character = char - Number = integer() - -

Returns a string, where String is centred in the +

Returns a string, where String is centred in the string and surrounded by blanks or characters. The resulting - string will have the length Number.

+ string will have the length Number.

- sub_string(String, Start) -> SubString - sub_string(String, Start, Stop) -> SubString + + Extract a substring - - String = SubString = string() - Start = Stop = integer() - -

Returns a substring of String, starting at the - position Start to the end of the string, or to and - including the Stop position.

+

Returns a substring of String, starting at the + position Start to the end of the string, or to and + including the Stop position.

For example:

sub_string("Hello World", 4, 8). @@ -383,15 +305,15 @@ sub_string("Hello World", 4, 8).
- to_lower(String) -> Result - to_lower(Char) -> CharResult - to_upper(String) -> Result - to_upper(Char) -> CharResult + + + + Convert case of string (ISO/IEC 8859-1) - - String = Result = string() - Char = CharResult = integer() - + + + +

The given string or character is case-converted. Note that the supported character set is ISO/IEC 8859-1 (a.k.a. Latin 1), diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index d6203bdaa0..009aa60faa 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -199,51 +199,81 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} + + + + + + +

Not a pid().

+ + + + + + +

A (the argument list) has the value + undefined if Restart is temporary.

+
+
+ + + + + + + + + + + + + + + + + + + - start_link(Module, Args) -> Result - start_link(SupName, Module, Args) -> Result + + Create a supervisor process. - - SupName = {local,Name} | {global,Name} -  Name = atom() - Module = atom() - Args = term() - Result = {ok,Pid} | ignore | {error,Error} -  Pid = pid() -  Error = {already_started,Pid}} | shutdown | term() - + + +

Creates a supervisor process as part of a supervision tree. The function will, among other things, ensure that the supervisor is linked to the calling process (its supervisor).

-

The created supervisor process calls Module:init/1 to +

The created supervisor process calls Module:init/1 to find out about restart strategy, maximum restart frequency and child processes. To ensure a synchronized start-up procedure, start_link/2,3 does not return until - Module:init/1 has returned and all child processes + Module:init/1 has returned and all child processes have been started.

-

If SupName={local,Name} the supervisor is registered +

If SupName={local,Name} the supervisor is registered locally as Name using register/2. If - SupName={global,Name} the supervisor is registered + SupName={global,Name} the supervisor is registered globally as Name using global:register_name/2. If no name is provided, the supervisor is not registered.

-

Module is the name of the callback module.

-

Args is an arbitrary term which is passed as - the argument to Module:init/1.

+

Module is the name of the callback module.

+

Args is an arbitrary term which is passed as + the argument to Module:init/1.

If the supervisor and its child processes are successfully created (i.e. if all child process start functions return {ok,Child}, {ok,Child,Info}, or ignore) the function returns {ok,Pid}, where Pid is the pid of the supervisor. If there already exists a process - with the specified SupName the function returns + with the specified SupName the function returns {error,{already_started,Pid}}, where Pid is the pid of that process.

-

If Module:init/1 returns ignore, this function +

If Module:init/1 returns ignore, this function returns ignore as well and the supervisor terminates with reason normal. - If Module:init/1 fails or returns an incorrect value, + If Module:init/1 fails or returns an incorrect value, this function returns {error,Term} where Term is a term with information about the error, and the supervisor terminates with reason Term.

@@ -255,21 +285,15 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
- start_child(SupRef, ChildSpec) -> Result + Dynamically add a child process to a supervisor. - - SupRef = Name | {Name,Node} | {global,Name} | pid() -  Name = Node = atom() - ChildSpec = child_spec() | [term()] - Result = {ok,Child} | {ok,Child,Info} | {error,Error} -  Child = pid() | undefined -  Info = term() -  Error = already_present | {already_started,Child} | term() - + + +

Dynamically adds a child specification to the supervisor - SupRef which starts the corresponding child process.

-

SupRef can be:

+ SupRef which starts the corresponding child process.

+

SupRef can be:

the pid, Name, if the supervisor is locally registered, @@ -278,26 +302,26 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} {global,Name}, if the supervisor is globally registered. -

ChildSpec should be a valid child specification +

ChildSpec should be a valid child specification (unless the supervisor is a simple_one_for_one supervisor, see below). The child process will be started by using the start function as defined in the child specification.

If the case of a simple_one_for_one supervisor, the child specification defined in Module:init/1 will - be used and ChildSpec should instead be an arbitrary - list of terms List. The child process will then be - started by appending List to the existing start + be used and ChildSpec should instead be an arbitrary + list of terms List. The child process will then be + started by appending List to the existing start function arguments, i.e. by calling - apply(M, F, A++List) where {M,F,A} is the start + apply(M, F, A++List) where {M,F,A} is the start function defined in the child specification.

If there already exists a child specification with - the specified Id, ChildSpec is discarded and + the specified Id, ChildSpec is discarded and the function returns {error,already_present} or - {error,{already_started,Child}}, depending on if + {error,{already_started,Child}}, depending on if the corresponding child process is running or not.

-

If the child process start function returns {ok,Child} - or {ok,Child,Info}, the child specification and pid is +

If the child process start function returns {ok,Child} + or {ok,Child,Info}, the child specification and pid is added to the supervisor and the function returns the same value.

If the child process start function returns ignore, @@ -312,27 +336,20 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} - terminate_child(SupRef, Id) -> Result + Terminate a child process belonging to a supervisor. - - SupRef = Name | {Name,Node} | {global,Name} | pid() -  Name = Node = atom() - Id = pid() | term() - Result = ok | {error,Error} -  Error = not_found | simple_one_for_one - -

Tells the supervisor SupRef to terminate the given +

Tells the supervisor SupRef to terminate the given child.

If the supervisor is not simple_one_for_one, - Id must be the child specification identifier. The + Id must be the child specification identifier. The process, if there is one, is terminated but the child specification is kept by the supervisor. The child process may later be restarted by the supervisor. The child process can also be restarted explicitly by calling restart_child/2. Use delete_child/2 to remove the child specification.

-

If the supervisor is simple_one_for_one, Id +

If the supervisor is simple_one_for_one, Id must be the child process' pid(). I the specified process is alive, but is not a child of the given supervisor, the function will return @@ -340,119 +357,93 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} identifier is given instead instead of a pid(), the function will return {error,simple_one_for_one}.

If successful, the function returns ok. If there is - no child specification with the specified Id, the + no child specification with the specified Id, the function returns {error,not_found}.

See start_child/2 for a description of - SupRef.

+ SupRef.

- delete_child(SupRef, Id) -> Result + Delete a child specification from a supervisor. - - SupRef = Name | {Name,Node} | {global,Name} | pid() -  Name = Node = atom() - Id = term() - Result = ok | {error,Error} -  Error = running | not_found | simple_one_for_one - -

Tells the supervisor SupRef to delete the child - specification identified by Id. The corresponding child +

Tells the supervisor SupRef to delete the child + specification identified by Id. The corresponding child process must not be running, use terminate_child/2 to terminate it.

-

See start_child/2 for a description of SupRef.

+

See start_child/2 for a description of + SupRef.

If successful, the function returns ok. If the child - specification identified by Id exists but + specification identified by Id exists but the corresponding child process is running, the function returns {error,running}. If the child specification - identified by Id does not exist, the function returns + identified by Id does not exist, the function returns {error,not_found}.

- restart_child(SupRef, Id) -> Result + Restart a terminated child process belonging to a supervisor. - - SupRef = Name | {Name,Node} | {global,Name} | pid() -  Name = Node = atom() - Id = term() - Result = {ok,Child} | {ok,Child,Info} | {error,Error} -  Child = pid() | undefined -  Error = running | not_found | simple_one_for_one | term() - -

Tells the supervisor SupRef to restart a child process +

Tells the supervisor SupRef to restart a child process corresponding to the child specification identified by - Id. The child specification must exist and + Id. The child specification must exist and the corresponding child process must not be running.

-

See start_child/2 for a description of SupRef.

-

If the child specification identified by Id does not +

See start_child/2 for a description of + SupRef.

+

If the child specification identified by Id does not exist, the function returns {error,not_found}. If the child specification exists but the corresponding process is already running, the function returns {error,running}.

-

If the child process start function returns {ok,Child} - or {ok,Child,Info}, the pid is added to the supervisor +

If the child process start function returns {ok,Child} + or {ok,Child,Info}, the pid is added to the supervisor and the function returns the same value.

If the child process start function returns ignore, the pid remains set to undefined and the function returns {ok,undefined}.

If the child process start function returns an error tuple or an erroneous value, or if it fails, the function returns - {error,Error} where Error is a term containing + {error,Error} where Error is a term containing information about the error.

- which_children(SupRef) -> [{Id,Child,Type,Modules}] + Return information about all children specifications and child processes belonging to a supervisor. - - SupRef = Name | {Name,Node} | {global,Name} | pid() -  Name = Node = atom() - Id = term() | undefined - Child = pid() | undefined - Type = worker | supervisor - Modules = [Module] | dynamic -  Module = atom() -

Returns a newly created list with information about all child specifications and child processes belonging to - the supervisor SupRef.

+ the supervisor SupRef.

Note that calling this function when supervising a large number of children under low memory conditions can cause an out of memory exception.

-

See start_child/2 for a description of SupRef.

+

See start_child/2 for a description of + SupRef.

The information given for each child specification/process is:

-

Id - as defined in the child specification or +

Id - as defined in the child specification or undefined in the case of a simple_one_for_one supervisor.

-

Child - the pid of the corresponding child +

Child - the pid of the corresponding child process, or undefined if there is no such process.

-

Type - as defined in the child specification.

+

Type - as defined in the child specification.

-

Modules - as defined in the child specification.

+

Modules - as defined in the child specification.

- count_children(SupRef) -> PropListOfCounts + Return counts for the number of childspecs, active children, supervisors and workers. - - SupRef = Name | {Name,Node} | {global,Name} | pid() -  Name = Node = atom() - PropListOfCounts = [{specs, ChildSpecCount}, {active, ActiveProcessCount}, {supervisors, ChildSupervisorCount}, {workers, ChildWorkerCount}] -

Returns a property list (see proplists) containing the counts for each of the following elements of the supervisor's @@ -479,17 +470,12 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} - check_childspecs([ChildSpec]) -> Result + Check if children specifications are syntactically correct. - - ChildSpec = child_spec() - Result = ok | {error,Error} -  Error = term() -

This function takes a list of child specification as argument and returns ok if all of them are syntactically - correct, or {error,Error} otherwise.

+ correct, or {error,Error} otherwise.

@@ -506,9 +492,9 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} Args = term() Result = {ok,{{RestartStrategy,MaxR,MaxT},[ChildSpec]}} | ignore -  RestartStrategy = one_for_all | one_for_one | rest_for_one | simple_one_for_one -  MaxR = MaxT = int()>=0 -  ChildSpec = child_spec() +  RestartStrategy = strategy() +  MaxR = MaxT = integer()>=0 +  ChildSpec = child_spec()

Whenever a supervisor is started using diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml index cbd0d9230b..c1a5e7947f 100644 --- a/lib/stdlib/doc/src/supervisor_bridge.xml +++ b/lib/stdlib/doc/src/supervisor_bridge.xml @@ -50,46 +50,37 @@ - start_link(Module, Args) -> Result - start_link(SupBridgeName, Module, Args) -> Result + + Create a supervisor bridge process. - - SupBridgeName = {local,Name} | {global,Name} -  Name = atom() - Module = atom() - Args = term() - Result = {ok,Pid} | ignore | {error,Error} -  Pid = pid() -  Error = {already_started,Pid} | term() -

Creates a supervisor_bridge process, linked to the calling - process, which calls Module:init/1 to start the subsystem. + process, which calls Module:init/1 to start the subsystem. To ensure a synchronized start-up procedure, this function does - not return until Module:init/1 has returned.

-

If SupBridgeName={local,Name} the supervisor_bridge is - registered locally as Name using register/2. - If SupBridgeName={global,Name} the supervisor_bridge is - registered globally as Name using + not return until Module:init/1 has returned.

+

If SupBridgeName={local,Name} the supervisor_bridge is + registered locally as Name using register/2. + If SupBridgeName={global,Name} the supervisor_bridge is + registered globally as Name using global:register_name/2. If no name is provided, the supervisor_bridge is not registered. If there already exists a process with the specified - SupBridgeName the function returns - {error,{already_started,Pid}}, where Pid is the pid + SupBridgeName the function returns + {error,{already_started,Pid}}, where Pid is the pid of that process.

-

Module is the name of the callback module.

-

Args is an arbitrary term which is passed as the argument - to Module:init/1.

+

Module is the name of the callback module.

+

Args is an arbitrary term which is passed as the argument + to Module:init/1.

If the supervisor_bridge and the subsystem are successfully - started the function returns {ok,Pid}, where Pid is + started the function returns {ok,Pid}, where Pid is is the pid of the supervisor_bridge.

-

If Module:init/1 returns ignore, this function +

If Module:init/1 returns ignore, this function returns ignore as well and the supervisor_bridge terminates with reason normal. - If Module:init/1 fails or returns an error tuple or an - incorrect value, this function returns {error,Term} where - Term is a term with information about the error, and - the supervisor_bridge terminates with reason Term.

+ If Module:init/1 fails or returns an error tuple or an + incorrect value, this function returns {error,Errorr} where + Error is a term with information about the error, and + the supervisor_bridge terminates with reason Error.

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index efa8922a9d..073faf2df2 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -39,24 +39,12 @@

Functions used for implementation of processes should also understand system messages such as debugging messages and code change. These functions must be used to implement the use of system messages for a process; either directly, or through standard behaviours, such as gen_server.

-

The following types are used in the functions defined below:

- - -

Name = pid() | atom() | {global, atom()}

-
- -

Timeout = int() >= 0 | infinity

-
- -

system_event() = {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()

-
-

The default timeout is 5000 ms, unless otherwise specified. The timeout defines the time period to wait for the process to respond to a request. If the process does not respond, the function evaluates exit({timeout, {M, F, A}}).

-

The functions make reference to a debug structure. +

The functions make reference to a debug structure. The debug structure is a list of dbg_opt(). dbg_opt() is an internal data type used by the handle_system_msg/6 function. No debugging is performed if it is an empty list. @@ -113,20 +101,31 @@ own system events. It is always up to the process itself to format these events.

+ + + + + + + + + +

See above.

+
+ + + +
- log(Name,Flag) - log(Name,Flag,Timeout) -> ok | {ok, [system_event()]} + + Log system events in memory - - Flag = true | {true, N} | false | get | print - N = integer() > 0 -

Turns the logging of system events On or Off. If On, a - maximum of N events are kept in the - debug structure (the default is 10). If Flag is get, a list of all - logged events is returned. If Flag is print, the + maximum of N events are kept in the + debug structure (the default is 10). If Flag is get, a list of all + logged events is returned. If Flag is print, the logged events are printed to standard_io. The events are formatted with a function that is defined by the process that generated the event (with a call to @@ -134,13 +133,9 @@ - log_to_file(Name,Flag) - log_to_file(Name,Flag,Timeout) -> ok | {error, open_file} + + Log system events to the specified file - - Flag = FileName | false - FileName = string() -

Enables or disables the logging of all system events in textual format to the file. The events are formatted with a function that is @@ -149,27 +144,18 @@ - statistics(Name,Flag) - statistics(Name,Flag,Timeout) -> ok | {ok, Statistics} + + Enable or disable the collections of statistics - - Flag = true | false | get - Statistics = [{start_time, {Date1, Time1}}, {current_time, {Date, Time2}}, {reductions, integer()}, {messages_in, integer()}, {messages_out, integer()}] - Date1 = Date2 = {Year, Month, Day} - Time1 = Time2 = {Hour, Min, Sec} - -

Enables or disables the collection of statistics. If Flag is +

Enables or disables the collection of statistics. If Flag is get, the statistical collection is returned.

- trace(Name,Flag) - trace(Name,Flag,Timeout) -> void() + + Print all system events on standard_io - - Flag = boolean() -

Prints all system events on standard_io. The events are formatted with a function that is defined by the process that @@ -178,8 +164,8 @@ - no_debug(Name) - no_debug(Name,Timeout) -> void() + + Turn off debugging

Turns off all debugging for the process. This includes @@ -188,8 +174,8 @@ - suspend(Name) - suspend(Name,Timeout) -> void() + + Suspend the process

Suspends the process. When the process is suspended, it @@ -198,49 +184,37 @@ - resume(Name) - resume(Name,Timeout) -> void() + + Resume a suspended process

Resumes a suspended process.

- change_code(Name, Module, OldVsn, Extra) - change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason} + + Send the code change system message to the process - - OldVsn = undefined | term() - Module = atom() - Extra = term() -

Tells the process to change code. The process must be - suspended to handle this message. The Extra argument is + suspended to handle this message. The Extra argument is reserved for each process to use as its own. The function - Mod:system_code_change/4 is called. OldVsn is - the old version of the Module.

+ Module:system_code_change/4 is called. OldVsn is + the old version of the Module.

- get_status(Name) - get_status(Name,Timeout) -> {status, Pid, {module, Mod}, [PDict, SysState, Parent, Dbg, Misc]} + + Get the status of the process - - PDict = [{Key, Value}] - SysState = running | suspended - Parent = pid() - Dbg = [dbg_opt()] - Misc = term() -

Gets the status of the process.

-

The value of Misc varies for different types of +

The value of Misc varies for different types of processes. For example, a gen_server process returns the callback module's state, and a gen_fsm process returns information such as its current state name. Callback modules for gen_server and gen_fsm can also - customise the value of Misc by exporting + customise the value of Misc by exporting a format_status/2 function that contributes module-specific information; see gen_server:format_status/2 @@ -249,17 +223,9 @@ - install(Name,{Func,FuncState}) - install(Name,{Func,FuncState},Timeout) + + Install a debug function in the process - - Func = dbg_fun() - dbg_fun() = fun(FuncState, Event, ProcState) -> done | NewFuncState - FuncState = term() - Event = system_event() - ProcState = term() - NewFuncState = term() -

This function makes it possible to install other debug functions than the ones defined above. An example of such a @@ -267,22 +233,19 @@ special event and performs some action when the event is generated. This could, for example, be turning on low level tracing.

-

Func is called whenever a system event is +

Func is called whenever a system event is generated. This function should return done, or a new func state. In the first case, the function is removed. It is removed if the function fails.

- remove(Name,Func) - remove(Name,Func,Timeout) -> void() + + Remove a debug function from the process - - Func = dbg_fun() -

Removes a previously installed debug function from the - process. Func must be the same as previously + process. Func must be the same as previously installed.

@@ -296,86 +259,65 @@ - debug_options(Options) -> [dbg_opt()] + Convert a list of options to a debug structure - - Options = [Opt] - Opt = trace | log | statistics | {log_to_file, FileName} | {install, {Func, FuncState}} - Func = dbg_fun() - FuncState = term() -

This function can be used by a process that initiates a debug structure from a list of options. The values of the - Opt argument are the same as the corresponding + Opt argument are the same as the corresponding functions.

- get_debug(Item,Debug,Default) -> term() + Get the data associated with a debug option - - Item = log | statistics - Debug = [dbg_opt()] - Default = term() - -

This function gets the data associated with a debug option. Default is returned if the - Item is not found. Can be +

This function gets the data associated with a debug option. Default is returned if the + Item is not found. Can be used by the process to retrieve debug data for printing before it terminates.

- handle_debug([dbg_opt()],FormFunc,Extra,Event) -> [dbg_opt()] + Generate a system event - - FormFunc = dbg_fun() - Extra = term() - Event = system_event() - -

This function is called by a process when it generates a system event. FormFunc is a formatting function which is called as FormFunc(Device, Event, Extra) in order to print the events, which is necessary if tracing is activated. Extra is any - extra information which the process needs in the format function, for example the name of the process.

+

This function is called by a process when it generates a + system event. FormFunc is a formatting + function which is called as FormFunc(Device, + Event, Extra) in order to print + the events, which is necessary if tracing is activated. + Extra is any extra information which the + process needs in the format function, for example the name + of the process.

- handle_system_msg(Msg,From,Parent,Module,Debug,Misc) + Take care of system messages - - Msg = term() - From = pid() - Parent = pid() - Module = atom() - Debug = [dbg_opt()] - Misc = term() -

This function is used by a process module that wishes to take care of system - messages. The process receives a {system, From, Msg} - message and passes the Msg and From to this + messages. The process receives a {system, From, Msg} + message and passes the Msg and From to this function.

This function never returns. It calls the function - Module:system_continue(Parent, NDebug, Misc) where the + Module:system_continue(Parent, NDebug, Misc) where the process continues the execution, or - Module:system_terminate(Reason, Parent, Debug, Misc) if - the process should terminate. The Module must export + Module:system_terminate(Reason, Parent, Debug, Misc) if + the process should terminate. The Module must export system_continue/3, system_terminate/4, and system_code_change/4 (see below).

-

The Misc argument can be used to save internal data +

The Misc argument can be used to save internal data in a process, for example its state. It is sent to - Module:system_continue/3 or - Module:system_terminate/4

+ Module:system_continue/3 or + Module:system_terminate/4

- print_log(Debug) -> void() + Print the logged events in the debug structure - - Debug = [dbg_opt()] -

Prints the logged system events in the debug structure using FormFunc as defined when the event was @@ -383,11 +325,11 @@ - Mod:system_continue(Parent, Debug, Misc) + Mod:system_continue(Parent, Debug, Misc) -> none() Called when the process should continue its execution Parent = pid() - Debug = [dbg_opt()] + Debug = [dbg_opt()] Misc = term() @@ -397,12 +339,12 @@ - Mod:system_terminate(Reason, Parent, Debug, Misc) + Mod:system_terminate(Reason, Parent, Debug, Misc) -> none() Called when the process should terminate Reason = term() Parent = pid() - Debug = [dbg_opt()] + Debug = [dbg_opt()] Misc = term() diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index cae655f801..b741ab7db1 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -49,9 +49,19 @@ as requested.

+ + + +

Time in milliseconds.

+
+ + +

A timer reference.

+
+
- start() -> ok + Start a global timer server (named timer_server).

Starts the timer server. Normally, the server does not need @@ -62,214 +72,181 @@ - apply_after(Time, Module, Function, Arguments) -> {ok, Tref} | {error, Reason} + Apply Module:Function(Arguments)after a specified Time. - - Time = integer() in Milliseconds - Module = Function = atom() - Arguments = [term()] - -

Evaluates apply(M, F, A) after Time amount of time - has elapsed. Returns {ok, TRef}, or {error, Reason}.

+

Evaluates apply(Module, Function, Arguments) after Time amount of time + has elapsed. Returns {ok, TRef}, or {error, Reason}.

- send_after(Time, Pid, Message) -> {ok, TRef} | {error,Reason} - send_after(Time, Message) -> {ok, TRef} | {error,Reason} + + Send Messageto Pidafter a specified Time. - - Time = integer() in Milliseconds - Pid = pid() | atom() - Message = term() - Result = {ok, TRef} | {error, Reason} -

send_after/3 -

Evaluates Pid ! Message after Time amount - of time has elapsed. (Pid can also be an atom of a - registered name.) Returns {ok, TRef}, or - {error, Reason}.

+

Evaluates Pid ! Message after Time amount + of time has elapsed. (Pid can also be an atom of a + registered name.) Returns {ok, TRef}, or + {error, Reason}.

send_after/2 -

Same as send_after(Time, self(), Message).

+

Same as send_after(Time, self(), Message).

- exit_after(Time, Pid, Reason1) -> {ok, TRef} | {error,Reason2} - exit_after(Time, Reason1) -> {ok, TRef} | {error,Reason2} - kill_after(Time, Pid)-> {ok, TRef} | {error,Reason2} - kill_after(Time) -> {ok, TRef} | {error,Reason2} + + + + Send an exit signal with Reasonafter a specified Time. - - Time = integer() in milliseconds - Pid = pid() | atom() - Reason1 = Reason2 = term() -

exit_after/3 -

Send an exit signal with reason Reason1 to Pid - Pid. Returns {ok, TRef}, or - {error, Reason2}.

+

Send an exit signal with reason Reason1 to Pid + Pid. Returns {ok, TRef}, or + {error, Reason2}.

exit_after/2 -

Same as exit_after(Time, self(), Reason1).

+

Same as exit_after(Time, self(), Reason1).

kill_after/2 -

Same as exit_after(Time, Pid, kill).

+

Same as exit_after(Time, Pid, kill).

kill_after/1 -

Same as exit_after(Time, self(), kill).

+

Same as exit_after(Time, self(), kill).

- apply_interval(Time, Module, Function, Arguments) -> {ok, TRef} | {error, Reason} + Evaluate Module:Function(Arguments)repeatedly at intervals of Time. - - Time = integer() in milliseconds - Module = Function = atom() - Arguments = [term()] - -

Evaluates apply(Module, Function, Arguments) repeatedly at - intervals of Time. Returns {ok, TRef}, or - {error, Reason}.

+

Evaluates apply(Module, Function, Arguments) repeatedly at + intervals of Time. Returns {ok, TRef}, or + {error, Reason}.

- send_interval(Time, Pid, Message) -> {ok, TRef} | {error, Reason} - send_interval(Time, Message) -> {ok, TRef} | {error, Reason} + + Send Messagerepeatedly at intervals of Time. - - Time = integer() in milliseconds - Pid = pid() | atom() - Message = term() - Reason = term() -

send_interval/3 -

Evaluates Pid ! Message repeatedly after Time - amount of time has elapsed. (Pid can also be an atom of - a registered name.) Returns {ok, TRef} or - {error, Reason}.

+

Evaluates Pid ! Message repeatedly after Time + amount of time has elapsed. (Pid can also be an atom of + a registered name.) Returns {ok, TRef} or + {error, Reason}.

send_interval/2 -

Same as send_interval(Time, self(), Message).

+

Same as send_interval(Time, self(), Message).

- cancel(TRef) -> {ok, cancel} | {error, Reason} + Cancel a previously requested timeout identified by TRef. -

Cancels a previously requested timeout. TRef is a unique +

Cancels a previously requested timeout. TRef is a unique timer reference returned by the timer function in question. Returns - {ok, cancel}, or {error, Reason} when TRef + {ok, cancel}, or {error, Reason} when TRef is not a timer reference.

- sleep(Time) -> ok + Suspend the calling process for Timeamount of milliseconds. - - Time = integer() in milliseconds or the atom infinity - -

Suspends the process calling this function for Time amount +

Suspends the process calling this function for Time amount of milliseconds and then returns ok, or suspend the process - forever if Time is the atom infinity. Naturally, this + forever if Time is the atom infinity. Naturally, this function does not return immediately.

- tc(Module, Function, Arguments) -> {Time, Value} - tc(Fun, Arguments) -> {Time, Value} + + + Measure the real time it takes to evaluate apply(Module, Function, Arguments) or apply(Fun, Arguments) - - Module = Function = atom() - Fun = fun() - Arguments = [term()] - Time = integer() in microseconds - Value = term() - + In microseconds

tc/3 -

Evaluates apply(Module, Function, Arguments) and measures - the elapsed real time as reported by now/0. - Returns {Time, Value}, where - Time is the elapsed real time in microseconds, - and Value is what is returned from the apply.

+

Evaluates apply(Module, Function, Arguments) and measures + the elapsed real time as reported by os:timestamp/0. + Returns {Time, Value}, where + Time is the elapsed real time in microseconds, + and Value is what is returned from the apply.

tc/2 -

Evaluates apply(Fun, Arguments). Otherwise works +

Evaluates apply(Fun, Arguments). Otherwise works like tc/3.

+ tc/1 + +

Evaluates Fun(). Otherwise works like tc/2.

+
+
- now_diff(T2, T1) -> Tdiff + Calculate time difference between now/0timestamps - - T1 = T2 = {MegaSecs, Secs, MicroSecs} - Tdiff = MegaSecs = Secs = MicroSecs = integer() - + In microseconds -

Calculates the time difference Tdiff = T2 - T1 in - microseconds, where T1 and T2 probably +

Calculates the time difference Tdiff = T2 - T1 in + microseconds, where T1 and T2 probably are timestamp tuples returned from erlang:now/0.

- seconds(Seconds) -> Milliseconds + Convert Secondsto Milliseconds. -

Returns the number of milliseconds in Seconds.

+

Returns the number of milliseconds in Seconds.

- minutes(Minutes) -> Milliseconds + Converts Minutesto Milliseconds. -

Return the number of milliseconds in Minutes.

+

Return the number of milliseconds in Minutes.

- hours(Hours) -> Milliseconds + Convert Hoursto Milliseconds. -

Returns the number of milliseconds in Hours.

+

Returns the number of milliseconds in Hours.

- hms(Hours, Minutes, Seconds) -> Milliseconds + Convert Hours+Minutes+Secondsto Milliseconds. -

Returns the number of milliseconds in Hours + Minutes + Seconds.

+

Returns the number of milliseconds in Hours + Minutes + Seconds.

diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index cb1cfa8ed0..d02763f75c 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -38,50 +38,83 @@

It is recommended to only use external encodings for communication with external entities where this is required. When working inside the Erlang/OTP environment, it is recommended to keep binaries in UTF-8 when representing Unicode characters. Latin1 encoding is supported both for backward compatibility and for communication with external entities not supporting Unicode character sets.

-
- DATA TYPES - - -unicode_binary() = binary() with characters encoded in UTF-8 coding standard -unicode_char() = integer() representing valid unicode codepoint - -chardata() = charlist() | unicode_binary() - -charlist() = [unicode_char() | unicode_binary() | charlist()] - a unicode_binary is allowed as the tail of the list - - -external_unicode_binary() = binary() - with characters coded in a user specified Unicode encoding other - than UTF-8 (UTF-16 or UTF-32) - -external_chardata() = external_charlist() | external_unicode_binary() - -external_charlist() = [unicode_char() | external_unicode_binary() | external_charlist()] - an external_unicode_binary is allowed as the tail of the list - - -latin1_binary() = binary() with characters coded in iso-latin-1 -latin1_char() = integer() representing valid latin1 character (0-255) - -latin1_chardata() = latin1_charlist() | latin1_binary() + + + + + + + + + + +

A binary() with characters encoded in the UTF-8 coding standard.

+
+
+ + + +

An integer() representing a valid unicode codepoint.

+
+
+ + + + + + +

A unicode_binary is allowed as the tail of the list.

+
+
+ + + +

A binary() with characters coded in a user specified Unicode + encoding other than UTF-8 (UTF-16 or UTF-32).

+
+
+ + + + + + +

An external_unicode_binary() is allowed as the tail + of the list.

+
+
+ + +

A binary() with characters coded in iso-latin-1.

+
+
+ + +

An integer() representing valid latin1 + character (0-255).

+
+
+ + + + + +

A latin1_binary() is allowed as the tail of + the list.

+
+
+
-latin1_charlist() = [latin1_char() | latin1_binary() | latin1_charlist()] - a latin1_binary is allowed as the tail of the list
-
- bom_to_encoding(Bin) -> {Encoding,Length} + Identify UTF byte order marks in a binary. - - Bin = binary() of byte_size 4 or more - Encoding = latin1 | utf8 | {utf16,little} | {utf16,big} | {utf32,little} | {utf32,big} - Length = int() - + + A binary() of byte_size 4 or more.

Check for a UTF byte order mark (BOM) in the beginning of a - binary. If the supplied binary Bin begins with a valid + binary. If the supplied binary Bin begins with a valid byte order mark for either UTF-8, UTF-16 or UTF-32, the function returns the encoding identified along with the length of the BOM in bytes.

@@ -90,23 +123,24 @@ latin1_charlist() = [latin1_char() | latin1_binary() | latin1_charlist()]
- characters_to_list(Data) -> list() | {error, list(), RestData} | {incomplete, list(), binary()} + Convert a collection of characters to list of Unicode characters - - Data = latin1_chardata() | chardata() | external_chardata() - RestData = latin1_chardata() | chardata() | external_chardata() - -

Same as characters_to_list(Data,unicode).

+

Same as characters_to_list(Data,unicode).

- characters_to_list(Data, InEncoding) -> list() | {error, list(), RestData} | {incomplete, list(), binary()} + characters_to_list(Data, InEncoding) -> Result Convert a collection of characters to list of Unicode characters - Data = latin1_chardata() | chardata() | external_chardata() - RestData = latin1_chardata() | chardata() | external_chardata() - InEncoding = latin1 | unicode | utf8 | utf16 | utf32 | {utf16,little} | {utf16,big} | {utf32,little} | {utf32,big} + Data = latin1_chardata() + | chardata() + | external_chardata() + Result = list() | {error, list(), RestData} | {incomplete, list(), binary()} + RestData = latin1_chardata() + | chardata() + | external_chardata() + InEncoding = encoding() @@ -234,44 +268,42 @@ latin1_charlist() = [latin1_char() | latin1_binary() | latin1_charlist()] - characters_to_binary(Data) -> binary() | {error, binary(), RestData} | {incomplete, binary(), binary()} - Convert a collection of characters to an UTF-8 binary - Data = latin1_chardata() | chardata() | external_chardata() - RestData = latin1_chardata() | chardata() | external_chardata() - + + Convert a collection of characters to an UTF-8 binary

Same as characters_to_binary(Data, unicode, unicode).

- characters_to_binary(Data,InEncoding) -> binary() | {error, binary(), RestData} | {incomplete, binary(), binary()} - Convert a collection of characters to an UTF-8 binary - Data = latin1_chardata() | chardata() | external_chardata() - RestData = latin1_chardata() | chardata() | external_chardata() - InEncoding = latin1 | unicode | utf8 | utf16 | utf32 | {utf16,little} | {utf16,big} | {utf32,little} | {utf32,big} + characters_to_binary(Data,InEncoding) -> Result + Convert a collection of characters to an UTF-8 binary + + + Data = latin1_chardata() + | chardata() + | external_chardata() + Result = binary() | {error, binary(), RestData} | {incomplete, binary(), binary()} + RestData = latin1_chardata() + | chardata() + | external_chardata() + InEncoding = encoding()

Same as characters_to_binary(Data, InEncoding, unicode).

- characters_to_binary(Data, InEncoding, OutEncoding) -> binary() | {error, binary(), RestData} | {incomplete, binary(), binary()} + Convert a collection of characters to an UTF-8 binary - - Data = latin1_chardata() | chardata() | external_chardata() - RestData = latin1_chardata() | chardata() | external_chardata() - InEncoding = latin1 | unicode | utf8 | utf16 | utf32 | {utf16,little} | {utf16,big} | {utf32,little} | {utf32,big} - OutEncoding = latin1 | unicode | utf8 | utf16 | utf32| {utf16,little} | {utf16,big} | {utf32,little} | {utf32,big} -

This function behaves as characters_to_list/2, but produces an binary instead of a unicode list. The - InEncoding defines how input is to be interpreted if + InEncoding defines how input is to be interpreted if binaries are present in the Data, while - OutEncoding defines in what format output is to be + OutEncoding defines in what format output is to be generated.

The option unicode is an alias for utf8, as this is the @@ -291,17 +323,13 @@ latin1_charlist() = [latin1_char() | latin1_binary() | latin1_charlist()] - encoding_to_bom(InEncoding) -> Bin + Create a binary UTF byte order mark from encoding. - - Bin = binary() of byte_size 4 or less - InEncoding = latin1 | unicode | utf8 | utf16 | utf32 | {utf16,little} | {utf16,big} | {utf32,little} | {utf32,big} - Length = int() - + A binary() of byte_size 4 or more.

Create an UTF byte order mark (BOM) as a binary from the - supplied InEncoding. The BOM is, if supported at all, + supplied InEncoding. The BOM is, if supported at all, expected to be placed first in UTF encoded files or messages.

diff --git a/lib/stdlib/doc/src/win32reg.xml b/lib/stdlib/doc/src/win32reg.xml index 28960cd098..99fd7fdeb6 100644 --- a/lib/stdlib/doc/src/win32reg.xml +++ b/lib/stdlib/doc/src/win32reg.xml @@ -4,7 +4,7 @@
- 20002009 + 20002011 Ericsson AB. All Rights Reserved. @@ -85,14 +85,22 @@ hkdd HKEY_DYN_DATA

For additional information on the Windows registry consult the Win32 Programmer's Reference.

+ + + +

As returned by open/1.

+
+ + + + + + +
- change_key(RegHandle, Key) -> ReturnValue + Move to a key in the registry - - RegHandle = term() - Key = string() -

Changes the current key to another key. Works like cd. The key can be specified as a relative path or as an @@ -100,12 +108,8 @@ hkdd HKEY_DYN_DATA

- change_key_create(RegHandle, Key) -> ReturnValue + Move to a key, create it if it is not there - - RegHandle = term() - Key = string() -

Creates a key, or just changes to it, if it is already there. Works like a combination of mkdir and cd. Calls the Win32 API function @@ -114,23 +118,16 @@ hkdd HKEY_DYN_DATA

- close(RegHandle)-> ReturnValue + Close the registry. - - RegHandle = term() - -

Closes the registry. After that, the RegHandle cannot +

Closes the registry. After that, the RegHandle cannot be used.

- current_key(RegHandle) -> ReturnValue + Return the path to the current key. - - RegHandle = term() - ReturnValue = {ok, string()} -

Returns the path to the current key. This is the equivalent of pwd.

Note that the current key is stored in the driver, and might be @@ -138,12 +135,8 @@ hkdd HKEY_DYN_DATA

- delete_key(RegHandle) -> ReturnValue + Delete the current key - - RegHandle = term() - ReturnValue = ok | {error, ErrorId} -

Deletes the current key, if it is valid. Calls the Win32 API function RegDeleteKey(). Note that this call does not change the current key, @@ -152,12 +145,8 @@ hkdd HKEY_DYN_DATA - delete_value(RegHandle, Name) -> ReturnValue + Delete the named value on the current key. - - RegHandle = term() - ReturnValue = ok | {error, ErrorId} -

Deletes a named value on the current key. The atom default is used for the the default value.

@@ -165,12 +154,8 @@ hkdd HKEY_DYN_DATA
- expand(String) -> ExpandedString + Expand a string with environment variables - - String = string() - ExpandedString = string() -

Expands a string containing environment variables between percent characters. Anything between two % is taken for a environment @@ -180,23 +165,15 @@ hkdd HKEY_DYN_DATA - format_error(ErrorId) -> ErrorString + Convert an POSIX errorcode to a string - - ErrorId = atom() - ErrorString = string() -

Convert an POSIX errorcode to a string (by calling erl_posix_msg:message).

- open(OpenModeList)-> ReturnValue + Open the registry for reading or writing - - OpenModeList = [OpenMode] - OpenMode = read | write -

Opens the registry for reading or writing. The current key will be the root (HKEY_CLASSES_ROOT). The read flag in the mode list can be omitted.

@@ -204,12 +181,8 @@ hkdd HKEY_DYN_DATA
- set_value(RegHandle, Name, Value) -> ReturnValue + Set value at the current registry key with specified name. - - Name = string() | default - Value = string() | integer() | binary() -

Sets the named (or default) value to value. Calls the Win32 API function RegSetValueEx(). The value can be of three types, and @@ -221,13 +194,8 @@ hkdd HKEY_DYN_DATA - sub_keys(RegHandle) -> ReturnValue + Get subkeys to the current key. - - ReturnValue = {ok, SubKeys} | {error, ErrorId} - SubKeys = [SubKey] - SubKey = string() -

Returns a list of subkeys to the current key. Calls the Win32 API function EnumRegKeysEx().

@@ -235,13 +203,8 @@ hkdd HKEY_DYN_DATA
- value(RegHandle, Name) -> ReturnValue + Get the named value on the current key. - - Name = string() | default - ReturnValue = {ok, Value} - Value = string() | integer() | binary() -

Retrieves the named value (or default) on the current key. Registry values of type REG_SZ, are returned as strings. Type REG_DWORD @@ -249,15 +212,8 @@ hkdd HKEY_DYN_DATA - values(RegHandle) -> ReturnValue + Get all values on the current key. - - ReturnValue = {ok, ValuePairs} | {ok, ErrorId} - ValuePairs = [ValuePair] - ValuePair = {Name, Value} - Name = string | default - Value = string() | integer() | binary() -

Retrieves a list of all values on the current key. The values have types corresponding to the registry types, see value. diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml index 529a70a23d..b03fc7f4e2 100644 --- a/lib/stdlib/doc/src/zip.xml +++ b/lib/stdlib/doc/src/zip.xml @@ -4,7 +4,7 @@

- 20062010 + 20062011 Ericsson AB. All Rights Reserved. @@ -85,67 +85,55 @@ recreated.

-
- DATA TYPES - -zip_file() -

The record zip_file contains the following fields.

- - name = string() - -

the name of the file

-
- info = file_info() - -

file info as in - file:read_file_info/1

-
- comment = string() - -

the comment for the file in the zip archive

-
- offset = integer() - -

the offset of the file in the zip archive (used internally)

-
- comp_size = integer() - -

the compressed size of the file (the uncompressed size is found - in info)

-
-
- zip_comment -

The record zip_comment just contains the archive comment for - a zip archive

- - comment = string() - -

the comment for the zip archive

-
-
-
+ + + + +

The record zip_comment just contains the archive comment for + a zip archive

+
+
+ + + +

The record zip_file contains the following fields.

+ + name + +

the name of the file

+
+ info + +

file info as in + file:read_file_info/1

+
+ comment + +

the comment for the file in the zip archive

+
+ offset + +

the offset of the file in the zip archive (used internally)

+
+ comp_size + +

the compressed size of the file (the uncompressed size is found + in info)

+
+
+
+
+
- zip(Name, FileList) -> RetValue - zip(Name, FileList, Options) -> RetValue - create(Name, FileList) -> RetValue - create(Name, FileList, Options) -> RetValue + + + + Create a zip archive with options - - Name = filename() - FileList = [FileSpec] - FileSpec = filename() | {filename(), binary()} | {filename(), binary(), #file_info{}} - Options = [Option] - Option = memory | cooked | verbose | {comment, Comment} | {cwd, CWD} | {compress, What} | {uncompress, What} - What = all | [Extension] | {add, [Extension]} | {del, [Extension]} - Extension = string() - Comment = CWD = string() - RetValue = {ok, Name} | {ok, {Name, binary()}} | {error, Reason} - Reason = term() -

The zip function creates a - zip archive containing the files specified in FileList.

+ zip archive containing the files specified in FileList.

As synonyms, the functions create/2 and create/3 are provided, to make it resemble the erl_tar module.

The file-list is a list of files, with paths relative to the @@ -161,9 +149,9 @@ zip_file() .Z, .zip, .zoo, .arc, .lzh, .arj.

It is possible to override the default behavior and - explicitly control what types of files should be - compressed by using the {compress, What} and - {uncompress, What} options. It is possible to have + explicitly control what types of files that should be + compressed by using the {compress, What} and + {uncompress, What} options. It is possible to have several compress and uncompress options. In order to trigger compression of a file, its extension must match with the @@ -191,22 +179,22 @@ zip_file() memory

The output will not be to a file, but instead as a tuple - {FileName, binary()}. The binary will be a full zip + {FileName, binary()}. The binary will be a full zip archive with header, and can be extracted with for instance unzip/2.

- {comment, Comment} + {comment, Comment}

Add a comment to the zip-archive.

- {cwd, CWD} + {cwd, CWD}

Use the given directory as current directory, it will be prepended to file names when adding them, although it will not be in the zip-archive. (Acting like a file:set_cwd/1, but without changing the global cwd property.)

- {compress, What} + {compress, What}

Controls what types of files will be compressed. It is by default set to all. The @@ -215,18 +203,18 @@ zip_file() all

means that all files will be compressed (as long as they pass the uncompress condition).

- [Extension] + [Extension]

means that only files with exactly these extensions will be compressed.

- {add,[Extension]} + {add,[Extension]}

adds these extensions to the list of compress extensions.

- {del,[Extension]} + {del,[Extension]}

deletes these extensions from the list of compress extensions.

- {uncompress, What} + {uncompress, What}

Controls what types of files will be uncompressed. It is by default set to [".Z",".zip",".zoo",".arc",".lzh",".arj"]. @@ -234,13 +222,13 @@ zip_file() all

means that no files will be compressed.

- [Extension] + [Extension]

means that files with these extensions will be uncompressed.

- {add,[Extension]} + {add,[Extension]}

adds these extensions to the list of uncompress extensions.

- {del,[Extension]} + {del,[Extension]}

deletes these extensions from the list of uncompress extensions.

@@ -249,23 +237,11 @@ zip_file() - unzip(Archive) -> RetValue - unzip(Archive, Options) -> RetValue - extract(Archive) -> RetValue - extract(Archive, Options) -> RetValue + + + + Extract files from a zip archive - - Archive = filename() | binary() - Options = [Option] - Option = {file_list, FileList} | keep_old_files | verbose | memory | {file_filter, FileFilter} | {cwd, CWD} - FileList = [filename()] - FileBinList = [{filename(),binary()}] - FileFilter = fun(ZipFile) -> true | false - CWD = string() - ZipFile = zip_file() - RetValue = {ok,FileList} | {ok,FileBinList} | {error, Reason} | {error, {Name, Reason}} - Reason = term() -

The unzip/1 function extracts @@ -273,17 +249,17 @@ zip_file() unzip/2 function provides options to extract some files, and more.

-

If the Archive argument is given as a binary, +

If the Archive argument is given as a binary, the contents of the binary is assumed to be a zip archive, otherwise it should be a filename.

The following options are available:

- {file_list, FileList} + {file_list, FileList}

By default, all files will be extracted from the zip - archive. With the {file_list,FileList} option, + archive. With the {file_list, FileList} option, the unzip/2 function will only extract the files - whose names are included in FileList. The full + whose names are included in FileList. The full paths, including the names of all sub directories within the zip archive, must be specified.

@@ -329,29 +305,29 @@ zip_file()
- foldl(Fun, Acc0, Archive) -> {ok, Acc1} | {error, Reason} + Fold a function over all files in a zip archive - - Fun = fun(FileInArchive, GetInfo, GetBin, AccIn) -> AccOut - FileInArchive = filename() - GetInfo = fun() -> #file_info{} - GetBin = fun() -> binary() - Acc0 = Acc1 = AccIn = AccOut = term() - Archive = filename() | {filename(), binary()} -

The foldl/3 function - calls Fun(FileInArchive, GetInfo, GetBin, AccIn) on - successive files in the Archive, starting with AccIn - == Acc0. FileInArchive is the name that the file - has in the archive. GetInfo is a fun that returns info - about the the file. GetBin returns the contents of the - file. Both GetInfo and GetBin must be called - within the Fun. Their behavior is undefined if they are - called outside the context of the Fun. The Fun + calls Fun(FileInArchive, GetInfo + , GetBin, AccIn) on + successive files in the Archive, starting with + AccIn + == Acc0. FileInArchive is + the name that the file + has in the archive. GetInfo is a fun that + returns info + about the the file. GetBin returns the contents + of the + file. Both GetInfo and GetBin + must be called + within the Fun. Their behavior is undefined if + they are + called outside the context of the Fun. + The Fun must return a new accumulator which is passed to the next call. foldl/3 returns the final value of the - accumulator. Acc0 is returned if the archive is + accumulator. Acc0 is returned if the archive is empty. It is not necessary to iterate over all files in the archive. The iteration may be ended prematurely in a controlled manner by throwing an exception.

@@ -387,26 +363,16 @@ zip_file()
- list_dir(Archive) -> RetValue - list_dir(Archive, Options) - table(Archive) -> RetValue - table(Archive, Options) + + + + Retrieve the name of all files in a zip archive - - Archive = filename() | binary() - RetValue = {ok, [Comment, Files]} | {error, Reason} - Comment = zip_comment() - Files = [zip_file()] - Options = [Option] - Option = cooked - Reason = term() - -

The -list_dir/1 function retrieves - the names of all files in the zip archive Archive. The - -list_dir/2 function provides options.

+

The list_dir/1 + function retrieves the names of all files in the zip archive + Archive. The + list_dir/2 function provides options.

As synonyms, the functions table/2 and table/3 are provided, to make it resemble the erl_tar module.

The result value is the tuple {ok, List}, where List @@ -425,43 +391,27 @@ zip_file() - t(Archive) + Print the name of each file in a zip archive - - Archive = filename() | binary() | ZipHandle - ZipHandle = pid() - -

The -t/1 function prints the names - of all files in the zip archive Archive to the Erlang shell. +

The t/1 function prints the names + of all files in the zip archive Archive to the Erlang shell. (Similar to "tar t".)

- tt(Archive) + Print name and information for each file in a zip archive - - Archive = filename() | binary() - -

The -tt/1 function prints names and - information about all files in the zip archive Archive to +

The tt/1 function prints names and + information about all files in the zip archive Archive to the Erlang shell. (Similar to "tar tv".)

- zip_open(Archive) -> {ok, ZipHandle} | {error, Reason} - zip_open(Archive, Options) -> {ok, ZipHandle} | {error, Reason} + + Open an archive and return a handle to it - - Archive = filename() | binary() - Options = [Option] - Options = cooked | memory | {cwd, CWD} - CWD = string() - ZipHandle = pid() -

The zip_open function opens a @@ -472,29 +422,19 @@ zip_file() - zip_list_dir(ZipHandle) -> Result | {error, Reason} + Return a table of files in open zip archive - - Result = [ZipComment, ZipFile...] - ZipComment = #zip_comment{} - ZipFile = #zip_file{} - ZipHandle = pid() - -

The -zip_list_dir/1 function - returns the file list of an open zip archive.

+

The + zip_list_dir/1 function + returns the file list of an open zip archive. The first returned + element is the zip archive comment.

- zip_get(ZipHandle) -> {ok, [Result]} | {error, Reason} - zip_get(FileName, ZipHandle) -> {ok, Result} | {error, Reason} + + Extract files from an open archive - - FileName = filename() - ZipHandle = pid() - Result = filename() | {filename(), binary()} -

The zip_get function extracts @@ -505,11 +445,8 @@ zip_file() - zip_close(ZipHandle) -> ok | {error, einval} + Close an open archive - - ZipHandle = pid() -

The zip_close/1 function closes -- cgit v1.2.3