diff options
Diffstat (limited to 'lib/stdlib/doc/src')
| -rw-r--r-- | lib/stdlib/doc/src/Makefile | 20 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/binary.xml | 226 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/digraph_utils.xml | 4 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/epp.xml | 2 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/ets.xml | 537 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/filelib.xml | 9 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gb_trees.xml | 18 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gen_event.xml | 63 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gen_fsm.xml | 55 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gen_server.xml | 41 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/lists.xml | 72 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/math.xml | 57 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/ms_transform.xml | 4 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/notes.xml | 245 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/re.xml | 94 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/sofs.xml | 10 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/string.xml | 26 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/supervisor.xml | 46 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/supervisor_bridge.xml | 7 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/unicode.xml | 50 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/unicode_usage.xml | 10 |
21 files changed, 795 insertions, 801 deletions
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index 6c92756ae7..50f6427eaa 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2011. All Rights Reserved. +# Copyright Ericsson AB 1997-2012. 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 @@ -173,15 +173,15 @@ $(SPECDIR)/specs_erl_id_trans.xml: include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs - $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf - $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf - $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf" + $(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf" + $(INSTALL_DIR) "$(RELSYSDIR)/doc/html" $(INSTALL_DATA) $(HTMLDIR)/* \ - $(RELSYSDIR)/doc/html - $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) - $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 - $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 - $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 - $(INSTALL_DATA) $(MAN6_FILES) $(RELEASE_PATH)/man/man6 + "$(RELSYSDIR)/doc/html" + $(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)" + $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3" + $(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3" + $(INSTALL_DIR) "$(RELEASE_PATH)/man/man6" + $(INSTALL_DATA) $(MAN6_FILES) "$(RELEASE_PATH)/man/man6" release_spec: diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml index 88ce77e0d0..06cfad0b0b 100644 --- a/lib/stdlib/doc/src/binary.xml +++ b/lib/stdlib/doc/src/binary.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2009</year> - <year>2011</year> + <year>2012</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -77,41 +77,30 @@ </datatypes> <funcs> <func> - <name>at(Subject, Pos) -> byte()</name> + <name name="at" arity="2"/> <fsummary>Returns the byte at a specific position in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pos = integer() >= 0</v> - </type> <desc> - <p>Returns the byte at position <c>Pos</c> (zero-based) in the binary - <c>Subject</c> as an integer. If <c>Pos</c> >= <c>byte_size(Subject)</c>, + <p>Returns the byte at position <c><anno>Pos</anno></c> (zero-based) in the binary + <c><anno>Subject</anno></c> as an integer. If <c><anno>Pos</anno></c> >= <c>byte_size(<anno>Subject</anno>)</c>, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>bin_to_list(Subject) -> [byte()]</name> + <name name="bin_to_list" arity="1"/> <fsummary>Convert a binary to a list of integers</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>The same as <c>bin_to_list(Subject,{0,byte_size(Subject)})</c>.</p> + <p>The same as <c>bin_to_list(<anno>Subject</anno>,{0,byte_size(<anno>Subject</anno>)})</c>.</p> </desc> </func> <func> - <name>bin_to_list(Subject, PosLen) -> [byte()]</name> + <name name="bin_to_list" arity="2"/> <fsummary>Convert a binary to a list of integers</fsummary> - <type> - <v>Subject = binary()</v> - <v>PosLen = part()</v> - </type> <desc> - <p>Converts <c>Subject</c> to a list of <c>byte()</c>s, each representing + <p>Converts <c><anno>Subject</anno></c> to a list of <c>byte()</c>s, each representing the value of one byte. The <c>part()</c> denotes which part of the <c>binary()</c> to convert. Example:</p> @@ -120,27 +109,19 @@ "rla" %% or [114,108,97] in list notation. </code> - <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> + <p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>bin_to_list(Subject, Pos, Len) -> [byte()]</name> + <name name="bin_to_list" arity="3"/> <fsummary>Convert a binary to a list of integers</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pos = integer() >= 0</v> - <v>Len = integer() >= 0</v> - </type> <desc> - <p>The same as<c> bin_to_list(Subject,{Pos,Len})</c>.</p> + <p>The same as<c> bin_to_list(<anno>Subject</anno>,{<anno>Pos</anno>,<anno>Len</anno>})</c>.</p> </desc> </func> <func> - <name>compile_pattern(Pattern) -> cp()</name> + <name name="compile_pattern" arity="1"/> <fsummary>Pre-compiles a binary search pattern</fsummary> - <type> - <v>Pattern = binary() | [ binary() ]</v> - </type> <desc> <p>Builds an internal structure representing a compilation of a @@ -155,7 +136,7 @@ <p>When a list of binaries is given, it denotes a set of alternative binaries to search for. I.e if <c>[<<"functional">>,<<"programming">>]</c> - is given as <c>Pattern</c>, this + is given as <c><anno>Pattern</anno></c>, this means "either <c><<"functional">></c> or <c><<"programming">></c>". The pattern is a set of alternatives; when only a single binary is given, the set has @@ -163,32 +144,25 @@ <p>The list of binaries used for search alternatives shall be flat and proper.</p> - <p>If <c>Pattern</c> is not a binary or a flat proper list of binaries with length > 0, + <p>If <c><anno>Pattern</anno></c> is not a binary or a flat proper list of binaries with length > 0, a <c>badarg</c> exception will be raised.</p> </desc> </func> <func> - <name>copy(Subject) -> binary()</name> + <name name="copy" arity="1"/> <fsummary>Creates a duplicate of a binary</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>The same as <c>copy(Subject, 1)</c>.</p> + <p>The same as <c>copy(<anno>Subject</anno>, 1)</c>.</p> </desc> </func> <func> - <name>copy(Subject,N) -> binary()</name> + <name name="copy" arity="2"/> <fsummary>Duplicates a binary N times and creates a new</fsummary> - <type> - <v>Subject = binary()</v> - <v>N = integer() >= 0</v> - </type> <desc> - <p>Creates a binary with the content of <c>Subject</c> duplicated <c>N</c> times.</p> + <p>Creates a binary with the content of <c><anno>Subject</anno></c> duplicated <c><anno>N</anno></c> times.</p> - <p>This function will always create a new binary, even if <c>N = + <p>This function will always create a new binary, even if <c><anno>N</anno> = 1</c>. By using <c>copy/1</c> on a binary referencing a larger binary, one might free up the larger binary for garbage collection.</p> @@ -201,32 +175,23 @@ large binaries are no longer used in any process, deliberate copying might be a good idea.</p> </note> - <p>If <c>N</c> < <c>0</c>, a <c>badarg</c> exception is raised.</p> + <p>If <c><anno>N</anno></c> < <c>0</c>, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>decode_unsigned(Subject) -> Unsigned</name> + <name name="decode_unsigned" arity="1"/> <fsummary>Decode a whole binary into an integer of arbitrary size</fsummary> - <type> - <v>Subject = binary()</v> - <v>Unsigned = integer() >= 0</v> - </type> <desc> - <p>The same as <c>decode_unsigned(Subject,big)</c>.</p> + <p>The same as <c>decode_unsigned(<anno>Subject</anno>, big)</c>.</p> </desc> </func> <func> - <name>decode_unsigned(Subject, Endianess) -> Unsigned</name> + <name name="decode_unsigned" arity="2"/> <fsummary>Decode a whole binary into an integer of arbitrary size</fsummary> - <type> - <v>Subject = binary()</v> - <v>Endianess = big | little</v> - <v>Unsigned = integer() >= 0</v> - </type> <desc> <p>Converts the binary digit representation, in big or little - endian, of a positive integer in <c>Subject</c> to an Erlang <c>integer()</c>.</p> + endian, of a positive integer in <c><anno>Subject</anno></c> to an Erlang <c>integer()</c>.</p> <p>Example:</p> @@ -237,22 +202,15 @@ </desc> </func> <func> - <name>encode_unsigned(Unsigned) -> binary()</name> + <name name="encode_unsigned" arity="1"/> <fsummary>Encodes an unsigned integer into the minimal binary</fsummary> - <type> - <v>Unsigned = integer() >= 0</v> - </type> <desc> - <p>The same as <c>encode_unsigned(Unsigned,big)</c>.</p> + <p>The same as <c>encode_unsigned(<anno>Unsigned</anno>, big)</c>.</p> </desc> </func> <func> - <name>encode_unsigned(Unsigned,Endianess) -> binary()</name> + <name name="encode_unsigned" arity="2"/> <fsummary>Encodes an unsigned integer into the minimal binary</fsummary> - <type> - <v>Unsigned = integer() >= 0</v> - <v>Endianess = big | little</v> - </type> <desc> <p>Converts a positive integer to the smallest possible @@ -268,51 +226,39 @@ </desc> </func> <func> - <name>first(Subject) -> byte()</name> + <name name="first" arity="1"/> <fsummary>Returns the first byte of a binary</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>Returns the first byte of the binary <c>Subject</c> as an integer. If the - size of <c>Subject</c> is zero, a <c>badarg</c> exception is raised.</p> + <p>Returns the first byte of the binary <c><anno>Subject</anno></c> as an integer. If the + size of <c><anno>Subject</anno></c> is zero, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>last(Subject) -> byte()</name> + <name name="last" arity="1"/> <fsummary>Returns the last byte of a binary</fsummary> - <type> - <v>Subject = binary()</v> - </type> <desc> - <p>Returns the last byte of the binary <c>Subject</c> as an integer. If the - size of <c>Subject</c> is zero, a <c>badarg</c> exception is raised.</p> + <p>Returns the last byte of the binary <c><anno>Subject</anno></c> as an integer. If the + size of <c><anno>Subject</anno></c> is zero, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>list_to_bin(ByteList) -> binary()</name> + <name name="list_to_bin" arity="1"/> <fsummary>Convert a list of integers and binaries to a binary</fsummary> - <type> - <v>ByteList = iodata() (see module erlang)</v> - </type> <desc> <p>Works exactly as <c>erlang:list_to_binary/1</c>, added for completeness.</p> </desc> </func> <func> - <name>longest_common_prefix(Binaries) -> integer() >= 0</name> + <name name="longest_common_prefix" arity="1"/> <fsummary>Returns length of longest common prefix for a set of binaries</fsummary> - <type> - <v>Binaries = [ binary() ]</v> - </type> <desc> <p>Returns the length of the longest common prefix of the - binaries in the list <c>Binaries</c>. Example:</p> + binaries in the list <c><anno>Binaries</anno></c>. Example:</p> <code> 1> binary:longest_common_prefix([<<"erlang">>,<<"ergonomy">>]). @@ -321,19 +267,16 @@ 0 </code> - <p>If <c>Binaries</c> is not a flat list of binaries, a <c>badarg</c> exception is raised.</p> + <p>If <c><anno>Binaries</anno></c> is not a flat list of binaries, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>longest_common_suffix(Binaries) -> integer() >= 0</name> + <name name="longest_common_suffix" arity="1"/> <fsummary>Returns length of longest common suffix for a set of binaries</fsummary> - <type> - <v>Binaries = [ binary() ]</v> - </type> <desc> <p>Returns the length of the longest common suffix of the - binaries in the list <c>Binaries</c>. Example:</p> + binaries in the list <c><anno>Binaries</anno></c>. Example:</p> <code> 1> binary:longest_common_suffix([<<"erlang">>,<<"fang">>]). @@ -347,35 +290,24 @@ </desc> </func> <func> - <name>match(Subject, Pattern) -> Found | <c>nomatch</c></name> + <name name="match" arity="2"/> <fsummary>Searches for the first match of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = part()</v> - </type> <desc> - <p>The same as <c>match(Subject, Pattern, [])</c>.</p> + <p>The same as <c>match(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.</p> </desc> </func> <func> - <name>match(Subject,Pattern,Options) -> Found | <c>nomatch</c></name> + <name name="match" arity="3"/> + <type name="part"/> <fsummary>Searches for the first match of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = part()</v> - <v>Options = [ Option ]</v> - <v>Option = {scope, part()}</v> - </type> <desc> - <p>Searches for the first occurrence of <c>Pattern</c> in <c>Subject</c> and + <p>Searches for the first occurrence of <c><anno>Pattern</anno></c> in <c><anno>Subject</anno></c> and returns the position and length.</p> - <p>The function will return <c>{Pos,Length}</c> for the binary - in <c>Pattern</c> starting at the lowest position in - <c>Subject</c>, Example:</p> + <p>The function will return <c>{Pos, Length}</c> for the binary + in <c><anno>Pattern</anno></c> starting at the lowest position in + <c><anno>Subject</anno></c>, Example:</p> <code> 1> binary:match(<<"abcde">>, [<<"bcde">>,<<"cd">>],[]). @@ -391,16 +323,16 @@ <p>Summary of the options:</p> <taglist> - <tag>{scope, {Start, Length}}</tag> + <tag>{scope, {<anno>Start</anno>, <anno>Length</anno>}}</tag> <item><p>Only the given part is searched. Return values still have - offsets from the beginning of <c>Subject</c>. A negative <c>Length</c> is - allowed as described in the <c>TYPES</c> section of this manual.</p></item> + offsets from the beginning of <c><anno>Subject</anno></c>. A negative <c>Length</c> is + allowed as described in the <c>DATA TYPES</c> section of this manual.</p></item> </taglist> <p>If none of the strings in - <c>Pattern</c> is found, the atom <c>nomatch</c> is returned.</p> + <c><anno>Pattern</anno></c> is found, the atom <c>nomatch</c> is returned.</p> - <p>For a description of <c>Pattern</c>, see + <p>For a description of <c><anno>Pattern</anno></c>, see <seealso marker="#compile_pattern-1">compile_pattern/1</seealso>.</p> <p>If <c>{scope, {Start,Length}}</c> is given in the options @@ -412,32 +344,21 @@ </desc> </func> <func> - <name>matches(Subject, Pattern) -> Found</name> + <name name="matches" arity="2"/> <fsummary>Searches for all matches of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = [ part() ] | []</v> - </type> <desc> - <p>The same as <c>matches(Subject, Pattern, [])</c>.</p> + <p>The same as <c>matches(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.</p> </desc> </func> <func> - <name>matches(Subject,Pattern,Options) -> Found</name> + <name name="matches" arity="3"/> + <type name="part"/> <fsummary>Searches for all matches of a pattern in a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pattern = binary() | [ binary() ] | cp()</v> - <v>Found = [ part() ] | []</v> - <v>Options = [ Option ]</v> - <v>Option = {scope, part()}</v> - </type> <desc> - <p>Works like match, but the <c>Subject</c> is searched until + <p>Works like <c>match/2</c>, but the <c><anno>Subject</anno></c> is searched until exhausted and a list of all non-overlapping parts matching - <c>Pattern</c> is returned (in order). </p> + <c><anno>Pattern</anno></c> is returned (in order). </p> <p>The first and longest match is preferred to a shorter, which is illustrated by the following example:</p> @@ -458,26 +379,22 @@ <p>If none of the strings in pattern is found, an empty list is returned.</p> - <p>For a description of <c>Pattern</c>, see <seealso marker="#compile_pattern-1">compile_pattern/1</seealso> and for a + <p>For a description of <c><anno>Pattern</anno></c>, see <seealso marker="#compile_pattern-1">compile_pattern/1</seealso> and for a description of available options, see <seealso marker="#match-3">match/3</seealso>.</p> - <p>If <c>{scope, {Start,Length}}</c> is given in the options such that - <c>Start</c> is larger than the size of <c>Subject</c>, <c>Start + Length</c> is - less than zero or <c>Start + Length</c> is larger than the size of - <c>Subject</c>, a <c>badarg</c> exception is raised.</p> + <p>If <c>{scope, {<anno>Start</anno>,<anno>Length</anno>}}</c> is given in the options such that + <c><anno>Start</anno></c> is larger than the size of <c><anno>Subject</anno></c>, <c><anno>Start</anno> + <anno>Length</anno></c> is + less than zero or <c><anno>Start</anno> + <anno>Length</anno></c> is larger than the size of + <c><anno>Subject</anno></c>, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>part(Subject, PosLen) -> binary()</name> + <name name="part" arity="2"/> <fsummary>Extracts a part of a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>PosLen = part()</v> - </type> <desc> - <p>Extracts the part of the binary <c>Subject</c> described by <c>PosLen</c>.</p> + <p>Extracts the part of the binary <c><anno>Subject</anno></c> described by <c><anno>PosLen</anno></c>.</p> <p>Negative length can be used to extract bytes at the end of a binary:</p> @@ -494,25 +411,20 @@ <c>binary_part/3</c>. Those BIFs are allowed in guard tests.</p> </note> - <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception + <p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p> </desc> </func> <func> - <name>part(Subject, Pos, Len) -> binary()</name> + <name name="part" arity="3"/> <fsummary>Extracts a part of a binary</fsummary> - <type> - <v>Subject = binary()</v> - <v>Pos = integer() >= 0</v> - <v>Len = integer() >= 0</v> - </type> <desc> - <p>The same as <c>part(Subject, {Pos, Len})</c>.</p> + <p>The same as <c>part(<anno>Subject</anno>, {<anno>Pos</anno>, <anno>Len</anno>})</c>.</p> </desc> </func> <func> - <name>referenced_byte_size(binary()) -> integer() >= 0</name> + <name name="referenced_byte_size" arity="1"/> <fsummary>Determines the size of the actual binary pointed out by a sub-binary</fsummary> <desc> diff --git a/lib/stdlib/doc/src/digraph_utils.xml b/lib/stdlib/doc/src/digraph_utils.xml index e44632bfd2..ef6e1cb46f 100644 --- a/lib/stdlib/doc/src/digraph_utils.xml +++ b/lib/stdlib/doc/src/digraph_utils.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2011</year> + <year>2000</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -156,7 +156,7 @@ <p>Creates a digraph where the vertices are the <seealso marker="#strong_components">strongly connected components</seealso> of <c><anno>Digraph</anno></c> as returned by - <c>strong_components/1</c>. If X and Y are strongly + <c>strong_components/1</c>. If X and Y are two different strongly connected components, and there exist vertices x and y in X and Y respectively such that there is an edge <seealso marker="#emanate">emanating</seealso> from x diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml index 488499581f..386ed89fe1 100644 --- a/lib/stdlib/doc/src/epp.xml +++ b/lib/stdlib/doc/src/epp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index efd9514db6..abaf64fb91 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -128,11 +128,17 @@ <datatypes> <datatype> + <name name="access"/> + </datatype> + <datatype> <name><marker id="type-continuation">continuation()</marker></name> <desc> <p>Opaque continuation used by <seealso marker="#select/1"> - <c>select/1</c></seealso> and <seealso marker="#select/3"> - <c>select/3</c></seealso>.</p> + <c>select/1,3</c></seealso>, <seealso marker="#select_reverse/1"> + <c>select_reverse/1,3</c></seealso>, <seealso + marker="#match/1"> + <c>match/1,3</c></seealso>, and <seealso marker="#match_object/1"> + <c>match_object/1,3</c></seealso>.</p> </desc> </datatype> <datatype> @@ -140,6 +146,10 @@ <desc><p>A match specification, see above.</p></desc> </datatype> <datatype> + <name name="comp_match_spec"/> + <desc><p>A compiled match specification.</p></desc> + </datatype> + <datatype> <name name="match_pattern"/> </datatype> <datatype> @@ -149,14 +159,14 @@ <name name="tid"/> <desc><p>A table identifier, as returned by new/2.</p></desc> </datatype> + <datatype> + <name name="type"/> + </datatype> </datatypes> <funcs> <func> - <name>all() -> [Tab]</name> + <name name="all" arity="0"/> <fsummary>Return a list of all ETS tables.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> <p>Returns a list of all tables at the node. Named tables are given by their names, unnamed tables are given by their @@ -164,48 +174,34 @@ </desc> </func> <func> - <name>delete(Tab) -> true</name> + <name name="delete" arity="1"/> <fsummary>Delete an entire ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> - <p>Deletes the entire table <c>Tab</c>.</p> + <p>Deletes the entire table <c><anno>Tab</anno></c>.</p> </desc> </func> <func> - <name>delete(Tab, Key) -> true</name> + <name name="delete" arity="2"/> <fsummary>Delete all objects with a given key from an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> - <p>Deletes all objects with the key <c>Key</c> from the table - <c>Tab</c>.</p> + <p>Deletes all objects with the key <c><anno>Key</anno></c> from the table + <c><anno>Tab</anno></c>.</p> </desc> </func> <func> - <name>delete_all_objects(Tab) -> true</name> + <name name="delete_all_objects" arity="1"/> <fsummary>Delete all objects in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> - <p>Delete all objects in the ETS table <c>Tab</c>. + <p>Delete all objects in the ETS table <c><anno>Tab</anno></c>. The operation is guaranteed to be <seealso marker="#concurrency">atomic and isolated</seealso>.</p> </desc> </func> <func> - <name>delete_object(Tab,Object) -> true</name> + <name name="delete_object" arity="2"/> <fsummary>Deletes a specific from an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Object = tuple()</v> - </type> <desc> - <p>Delete the exact object <c>Object</c> from the ETS table, + <p>Delete the exact object <c><anno>Object</anno></c> from the ETS table, leaving objects with the same key but other differences (useful for type <c>bag</c>). In a <c>duplicate_bag</c>, all instances of the object will be deleted.</p> @@ -257,14 +253,10 @@ </desc> </func> <func> - <name>first(Tab) -> Key | '$end_of_table'</name> + <name name="first" arity="1"/> <fsummary>Return the first key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> - <p>Returns the first key <c>Key</c> in the table <c>Tab</c>. + <p>Returns the first key <c><anno>Key</anno></c> in the table <c><anno>Tab</anno></c>. If the table is of the <c>ordered_set</c> type, the first key in Erlang term order will be returned. If the table is of any other type, the first key according to the table's internal @@ -336,7 +328,7 @@ the source file.</p> <p>The fun is very restricted, it can take only a single parameter (the object to match): a sole variable or a - tuple. It needs to use the <c>is_</c>XXX guard tests. + tuple. It needs to use the <c>is_</c> guard tests. Language constructs that have no representation in a match_spec (like <c>if</c>, <c>case</c>, <c>receive</c> etc) are not allowed.</p> @@ -386,19 +378,14 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>give_away(Tab, Pid, GiftData) -> true</name> + <name name="give_away" arity="3"/> <fsummary>Change owner of a table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pid = pid()</v> - <v>GiftData = term()</v> - </type> <desc> - <p>Make process <c>Pid</c> the new owner of table <c>Tab</c>. + <p>Make process <c><anno>Pid</anno></c> the new owner of table <c><anno>Tab</anno></c>. If successful, the message - <c>{'ETS-TRANSFER',Tab,FromPid,GiftData}</c> will be sent + <c>{'ETS-TRANSFER',<anno>Tab</anno>,FromPid,<anno>GiftData</anno>}</c> will be sent to the new owner.</p> - <p>The process <c>Pid</c> must be alive, local and not already the + <p>The process <c><anno>Pid</anno></c> must be alive, local and not already the owner of the table. The calling process must be the table owner.</p> <p>Note that <c>give_away</c> does not at all affect the <seealso marker="#heir">heir</seealso> option of the table. A table @@ -421,81 +408,72 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>info(Tab) -> [{Item, Value}] | undefined</name> + <name name="info" arity="1"/> <fsummary>Return information about an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Item = atom(), see below</v> - <v>Value = term(), see below</v> - </type> <desc> - <p>Returns information about the table <c>Tab</c> as a list of - <c>{Item, Value}</c> tuples. If <c>Tab</c> has the correct type + <p>Returns information about the table <c><anno>Tab</anno></c> as a list of + tuples. If <c><anno>Tab</anno></c> has the correct type for a table identifier, but does not refer to an existing ETS - table, <c>undefined</c> is returned. If <c>Tab</c> is not of the + table, <c>undefined</c> is returned. If <c><anno>Tab</anno></c> is not of the correct type, this function fails with reason <c>badarg</c>.</p> <list type="bulleted"> - <item><c>Item=memory, Value=integer()</c> <br></br> + <item><c>{compressed, boolean()}</c> <br></br> - The number of words allocated to the table.</item> - <item><c>Item=owner, Value=pid()</c> <br></br> - - The pid of the owner of the table.</item> - <item><c>Item=heir, Value=pid()|none</c> <br></br> + Indicates if the table is compressed or not.</item> + <item><c>{heir, pid() | none}</c> <br></br> The pid of the heir of the table, or <c>none</c> if no heir is set.</item> - <item><c>Item=name, Value=atom()</c> <br></br> + <item><c>{keypos, integer() >= 1}</c> <br></br> - The name of the table.</item> - <item><c>Item=size, Value=integer()</c> <br></br> + The key position.</item> + <item><c>{memory, integer() >= 0</c> <br></br> - The number of objects inserted in the table.</item> - <item><c>Item=node, Value=atom()</c> <br></br> + The number of words allocated to the table.</item> + <item><c>{name, atom()}</c> <br></br> - The node where the table is stored. This field is no longer - meaningful as tables cannot be accessed from other nodes.</item> - <item><c>Item=named_table, Value=true|false</c> <br></br> + The name of the table.</item> + <item><c>{named_table, boolean()}</c> <br></br> Indicates if the table is named or not.</item> - <item><c>Item=type, Value=set|ordered_set|bag|duplicate_bag</c> <br></br> + <item><c>{node, node()}</c> <br></br> - The table type.</item> - <item><c>Item=keypos, Value=integer()</c> <br></br> + The node where the table is stored. This field is no longer + meaningful as tables cannot be accessed from other nodes.</item> + <item><c>{owner, pid()}</c> <br></br> - The key position.</item> - <item><c>Item=protection, Value=public|protected|private</c> <br></br> + The pid of the owner of the table.</item> + <item><c>{protection, <seealso marker="#type-access">access()</seealso>}</c> <br></br> The table access rights.</item> - <item><c>Item=compressed, Value=true|false</c> <br></br> + <item><c>{size, integer() >= 0</c> <br></br> - Indicates if the table is compressed or not.</item> + The number of objects inserted in the table.</item> + <item><c>{type, <seealso marker="#type-type">type()</seealso>}</c> <br></br> + + The table type.</item> </list> </desc> </func> <func> - <name>info(Tab, Item) -> Value | undefined</name> + <name name="info" arity="2"/> <fsummary>Return the information associated with given item for an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Item, Value - see below</v> - </type> <desc> <p>Returns the information associated with <c>Item</c> for - the table <c>Tab</c>, or returns <c>undefined</c> if <c>Tab</c> + the table <c><anno>Tab</anno></c>, or returns <c>undefined</c> if <c>Tab</c> does not refer an existing ETS table. - If <c>Tab</c> is not of the correct type, or if <c>Item</c> is not + If <c><anno>Tab</anno></c> is not of the correct type, or if <c><anno>Item</anno></c> is not one of the allowed values, this function fails with reason <c>badarg</c>.</p> <warning><p>In R11B and earlier, this function would not fail but return <c>undefined</c> for invalid values for <c>Item</c>.</p> </warning> - <p>In addition to the <c>{Item,Value}</c> + <p>In addition to the <c>{<anno>Item</anno>,<anno>Value</anno>}</c> pairs defined for <c>info/1</c>, the following items are allowed:</p> <list type="bulleted"> - <item><c>Item=fixed, Value=true|false</c> <br></br> + <item><c>Item=fixed, Value=boolean()</c> <br></br> Indicates if the table is fixed by any process or not.</item> <item> @@ -547,15 +525,11 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>insert(Tab, ObjectOrObjects) -> true</name> + <name name="insert" arity="2"/> <fsummary>Insert an object into an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>ObjectOrObjects = tuple() | [tuple()]</v> - </type> <desc> <p>Inserts the object or all of the objects in the list - <c>ObjectOrObjects</c> into the table <c>Tab</c>. + <c><anno>ObjectOrObjects</anno></c> into the table <c><anno>Tab</anno></c>. If the table is a <c>set</c> and the key of the inserted objects <em>matches</em> the key of any object in the table, the old object will be replaced. If the table is an @@ -572,19 +546,15 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>insert_new(Tab, ObjectOrObjects) -> boolean()</name> + <name name="insert_new" arity="2"/> <fsummary>Insert an object into an ETS table if the key is not already present.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>ObjectOrObjects = tuple() | [tuple()]</v> - </type> <desc> <p>This function works exactly like <c>insert/2</c>, with the exception that instead of overwriting objects with the same key (in the case of <c>set</c> or <c>ordered_set</c>) or adding more objects with keys already existing in the table (in the case of <c>bag</c> and <c>duplicate_bag</c>), it - simply returns <c>false</c>. If <c>ObjectOrObjects</c> is a + simply returns <c>false</c>. If <c><anno>ObjectOrObjects</anno></c> is a list, the function checks <em>every</em> key prior to inserting anything. Nothing will be inserted if not <em>all</em> keys present in the list are absent from the @@ -593,11 +563,8 @@ Error: fun containing local Erlang function calls </desc> </func> <func> - <name>is_compiled_ms(Term) -> boolean()</name> + <name name="is_compiled_ms" arity="1"/> <fsummary>Checks if an Erlang term is the result of ets:match_spec_compile</fsummary> - <type> - <v>Term = term()</v> - </type> <desc> <p>This function is used to check if a term is a valid compiled <seealso marker="#match_spec">match_spec</seealso>. @@ -626,14 +593,10 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>last(Tab) -> Key | '$end_of_table'</name> + <name name="last" arity="1"/> <fsummary>Return the last key in an ETS table of type<c>ordered_set</c>.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> - <p>Returns the last key <c>Key</c> according to Erlang term + <p>Returns the last key <c><anno>Key</anno></c> according to Erlang term order in the table <c>Tab</c> of the <c>ordered_set</c> type. If the table is of any other type, the function is synonymous to <c>first/2</c>. If the table is empty, @@ -642,16 +605,11 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>lookup(Tab, Key) -> [Object]</name> + <name name="lookup" arity="2"/> <fsummary>Return all objects with a given key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - <v>Object = tuple()</v> - </type> <desc> - <p>Returns a list of all objects with the key <c>Key</c> in - the table <c>Tab</c>.</p> + <p>Returns a list of all objects with the key <c><anno>Key</anno></c> in + the table <c><anno>Tab</anno></c>.</p> <p>In the case of <c>set, bag and duplicate_bag</c>, an object is returned only if the given key <em>matches</em> the key of the object in the table. If the table is an @@ -671,7 +629,7 @@ ets:is_compiled_ms(Broken).</code> <c>duplicate_bag</c>, the function returns a list of arbitrary length.</p> <p>Note that the time order of object insertions is preserved; - The first object inserted with the given key will be first + the first object inserted with the given key will be first in the resulting list, and so on.</p> <p>Insert and look-up times in tables of type <c>set</c>, <c>bag</c> and <c>duplicate_bag</c> are constant, regardless @@ -681,22 +639,16 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>lookup_element(Tab, Key, Pos) -> Elem</name> + <name name="lookup_element" arity="3"/> <fsummary>Return the <c>Pos</c>:th element of all objects with a given key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - <v>Pos = integer()</v> - <v>Elem = term() | [term()]</v> - </type> <desc> - <p>If the table <c>Tab</c> is of type <c>set</c> or - <c>ordered_set</c>, the function returns the <c>Pos</c>:th - element of the object with the key <c>Key</c>.</p> + <p>If the table <c><anno>Tab</anno></c> is of type <c>set</c> or + <c>ordered_set</c>, the function returns the <c><anno>Pos</anno></c>:th + element of the object with the key <c><anno>Key</anno></c>.</p> <p>If the table is of type <c>bag</c> or <c>duplicate_bag</c>, - the functions returns a list with the <c>Pos</c>:th element of - every object with the key <c>Key</c>.</p> - <p>If no object with the key <c>Key</c> exists, the function + the functions returns a list with the <c><anno>Pos</anno></c>:th element of + every object with the key <c><anno>Key</anno></c>.</p> + <p>If no object with the key <c><anno>Key</anno></c> exists, the function will exit with reason <c>badarg</c>.</p> <p>The difference between <c>set</c>, <c>bag</c> and <c>duplicate_bag</c> on one hand, and <c>ordered_set</c> on @@ -708,16 +660,11 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match(Tab, Pattern) -> [Match]</name> + <name name="match" arity="2"/> <fsummary>Match the objects in an ETS table against a pattern.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = tuple()</v> - <v>Match = [term()]</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> against the - pattern <c>Pattern</c>.</p> + <p>Matches the objects in the table <c><anno>Tab</anno></c> against the + pattern <c><anno>Pattern</anno></c>.</p> <p>A pattern is a term that may contain:</p> <list type="bulleted"> <item>bound parts (Erlang terms),</item> @@ -744,18 +691,12 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match(Tab, Pattern, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match" arity="3"/> <fsummary>Match the objects in an ETS table against a pattern and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = tuple()</v> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>ets:match/2</c> but only returns a limited - (<c>Limit</c>) number of matching objects. The - <c>Continuation</c> term can then be used in subsequent calls + (<c><anno>Limit</anno></c>) number of matching objects. The + <c><anno>Continuation</anno></c> term can then be used in subsequent calls to <c>ets:match/1</c> to get the next chunk of matching objects. This is a space efficient way to work on objects in a table which is still faster than traversing the table object @@ -764,16 +705,12 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match" arity="1"/> <fsummary>Continues matching objects in an ETS table.</fsummary> - <type> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with <c>ets:match/3</c>. The next chunk of the size given in the initial <c>ets:match/3</c> - call is returned together with a new <c>Continuation</c> + call is returned together with a new <c><anno>Continuation</anno></c> that can be used in subsequent calls to this function.</p> <p><c>'$end_of_table'</c> is returned when there are no more objects in the table.</p> @@ -789,15 +726,11 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_object(Tab, Pattern) -> [Object]</name> + <name name="match_object" arity="2"/> <fsummary>Match the objects in an ETS table against a pattern.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = Object = tuple()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> against the - pattern <c>Pattern</c>. See <c>match/2</c> for a description + <p>Matches the objects in the table <c><anno>Tab</anno></c> against the + pattern <c><anno>Pattern</anno></c>. See <c>match/2</c> for a description of patterns. The function returns a list of all objects which match the pattern.</p> <p>If the key is specified in the pattern, the match is very @@ -809,18 +742,12 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_object(Tab, Pattern, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match_object" arity="3"/> <fsummary>Match the objects in an ETS table against a pattern and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Pattern = tuple()</v> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>ets:match_object/2</c> but only returns a - limited (<c>Limit</c>) number of matching objects. The - <c>Continuation</c> term can then be used in subsequent calls + limited (<c><anno>Limit</anno></c>) number of matching objects. The + <c><anno>Continuation</anno></c> term can then be used in subsequent calls to <c>ets:match_object/1</c> to get the next chunk of matching objects. This is a space efficient way to work on objects in a table which is still faster than traversing the table object @@ -829,29 +756,21 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_object(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="match_object" arity="1"/> <fsummary>Continues matching objects in an ETS table.</fsummary> - <type> - <v>Match = [term()]</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with <c>ets:match_object/3</c>. The next chunk of the size given in the initial <c>ets:match_object/3</c> call is returned together with a - new <c>Continuation</c> that can be used in subsequent calls + new <c><anno>Continuation</anno></c> that can be used in subsequent calls to this function.</p> <p><c>'$end_of_table'</c> is returned when there are no more objects in the table.</p> </desc> </func> <func> - <name>match_spec_compile(MatchSpec) -> CompiledMatchSpec</name> + <name name="match_spec_compile" arity="1"/> <fsummary>Compiles a match specification into its internal representation</fsummary> - <type> - <v>MatchSpec = match_spec()</v> - <v>CompiledMatchSpec = comp_match_spec()</v> - </type> <desc> <p>This function transforms a <seealso marker="#match_spec">match_spec</seealso> into an @@ -863,7 +782,7 @@ ets:is_compiled_ms(Broken).</code> valid compiled match_spec, nor can it be stored on disk). The validity of a compiled match_spec can be checked using <c>ets:is_compiled_ms/1</c>.</p> - <p>If the term <c>MatchSpec</c> can not be compiled (does not + <p>If the term <c><anno>MatchSpec</anno></c> can not be compiled (does not represent a valid match_spec), a <c>badarg</c> fault is thrown.</p> <note> @@ -873,25 +792,21 @@ ets:is_compiled_ms(Broken).</code> </desc> </func> <func> - <name>match_spec_run(List,CompiledMatchSpec) -> list()</name> + <name name="match_spec_run" arity="2"/> <fsummary>Performs matching, using a compiled match_spec, on a list of tuples</fsummary> - <type> - <v>List = [ tuple() ]</v> - <v>CompiledMatchSpec = comp_match_spec()</v> - </type> <desc> <p>This function executes the matching specified in a compiled <seealso marker="#match_spec">match_spec</seealso> on - a list of tuples. The <c>CompiledMatchSpec</c> term should be + a list of tuples. The <c><anno>CompiledMatchSpec</anno></c> term should be the result of a call to <c>ets:match_spec_compile/1</c> and is hence the internal representation of the match_spec one wants to use.</p> - <p>The matching will be executed on each element in <c>List</c> + <p>The matching will be executed on each element in <c><anno>List</anno></c> and the function returns a list containing all results. If an - element in <c>List</c> does not match, nothing is returned + element in <c><anno>List</anno></c> does not match, nothing is returned for that element. The length of the result list is therefore equal or less than the the length of the parameter - <c>List</c>. The two calls in the following example will give + <c><anno>List</anno></c>. The two calls in the following example will give the same result (but certainly not the same execution time...):</p> <code type="none"> @@ -910,37 +825,23 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>member(Tab, Key) -> true | false</name> + <name name="member" arity="2"/> <fsummary>Tests for occurrence of a key in an ETS table</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - </type> <desc> <p>Works like <c>lookup/2</c>, but does not return the objects. The function returns <c>true</c> if one or more elements in - the table has the key <c>Key</c>, <c>false</c> otherwise.</p> + the table has the key <c><anno>Key</anno></c>, <c>false</c> otherwise.</p> </desc> </func> <func> - <name>new(Name, Options) -> tid() | atom()</name> + <name name="new" arity="2"/> <fsummary>Create a new ETS table.</fsummary> - <type> - <v>Name = atom()</v> - <v>Options = [Option]</v> - <v> Option = Type | Access | named_table | {keypos,Pos} | {heir,pid(),HeirData} | {heir,none} | Tweaks</v> - <v> Type = set | ordered_set | bag | duplicate_bag</v> - <v> Access = public | protected | private</v> - <v> Tweaks = {write_concurrency,boolean()} | {read_concurrency,boolean()} | compressed</v> - <v> Pos = integer()</v> - <v> HeirData = term()</v> - </type> <desc> <p>Creates a new table and returns a table identifier which can be used in subsequent operations. The table identifier can be sent to other processes so that a table can be shared between different processes within a node.</p> - <p>The parameter <c>Options</c> is a list of atoms which + <p>The parameter <c><anno>Options</anno></c> is a list of atoms which specifies table type, access rights, key position and if the table is named or not. If one or more options are left out, the default values are used. This means that not specifying @@ -997,27 +898,27 @@ ets:select(Table,MatchSpec),</code> </item> <item> <p><c>named_table</c> - If this option is present, the name <c>Name</c> is + If this option is present, the name <c><anno>Name</anno></c> is associated with the table identifier. The name can then be used instead of the table identifier in subsequent operations.</p> </item> <item> - <p><c>{keypos,Pos}</c> + <p><c>{keypos,<anno>Pos</anno>}</c> Specfies which element in the stored tuples should be used as key. By default, it is the first element, i.e. - <c>Pos=1</c>. However, this is not always appropriate. In + <c><anno>Pos</anno>=1</c>. However, this is not always appropriate. In particular, we do not want the first element to be the key if we want to store Erlang records in a table.</p> <p>Note that any tuple stored in the table must have at - least <c>Pos</c> number of elements.</p> + least <c><anno>Pos</anno></c> number of elements.</p> </item> <item> <marker id="heir"></marker> - <p><c>{heir,Pid,HeirData} | {heir,none}</c><br></br> + <p><c>{heir,<anno>Pid</anno>,<anno>HeirData</anno>} | {heir,none}</c><br></br> Set a process as heir. The heir will inherit the table if the owner terminates. The message - <c>{'ETS-TRANSFER',tid(),FromPid,HeirData}</c> will be sent to + <c>{'ETS-TRANSFER',tid(),FromPid,<anno>HeirData</anno>}</c> will be sent to the heir when that happens. The heir must be a local process. Default heir is <c>none</c>, which will destroy the table when the owner terminates.</p> @@ -1082,15 +983,11 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>next(Tab, Key1) -> Key2 | '$end_of_table'</name> + <name name="next" arity="2"/> <fsummary>Return the next key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key1 = Key2 = term()</v> - </type> <desc> - <p>Returns the next key <c>Key2</c>, following the key - <c>Key1</c> in the table <c>Tab</c>. If the table is of the + <p>Returns the next key <c><anno>Key2</anno></c>, following the key + <c><anno>Key1</anno></c> in the table <c><anno>Tab</anno></c>. If the table is of the <c>ordered_set</c> type, the next key in Erlang term order is returned. If the table is of any other type, the next key according to the table's internal order is returned. If there @@ -1105,16 +1002,12 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>prev(Tab, Key1) -> Key2 | '$end_of_table'</name> + <name name="prev" arity="2"/> <fsummary>Return the previous key in an ETS table of type<c>ordered_set</c>.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key1 = Key2 = term()</v> - </type> <desc> - <p>Returns the previous key <c>Key2</c>, preceding the key - <c>Key1</c> according the Erlang term order in the table - <c>Tab</c> of the <c>ordered_set</c> type. If the table is of + <p>Returns the previous key <c><anno>Key2</anno></c>, preceding the key + <c><anno>Key1</anno></c> according the Erlang term order in the table + <c><anno>Tab</anno></c> of the <c>ordered_set</c> type. If the table is of any other type, the function is synonymous to <c>next/2</c>. If there is no previous key, <c>'$end_of_table'</c> is returned.</p> @@ -1122,14 +1015,11 @@ ets:select(Table,MatchSpec),</code> </desc> </func> <func> - <name>rename(Tab, Name) -> Name</name> + <name name="rename" arity="2"/> <fsummary>Rename a named ETS table.</fsummary> - <type> - <v>Tab = Name = atom()</v> - </type> <desc> - <p>Renames the named table <c>Tab</c> to the new name - <c>Name</c>. Afterwards, the old name can not be used to + <p>Renames the named table <c><anno>Tab</anno></c> to the new name + <c><anno>Name</anno></c>. Afterwards, the old name can not be used to access the table. Renaming an unnamed table has no effect.</p> </desc> </func> @@ -1186,18 +1076,15 @@ ets:select(ets:repair_continuation(Broken,MS)).</code> </desc> </func> <func> - <name>safe_fixtable(Tab, true|false) -> true</name> + <name name="safe_fixtable" arity="2"/> <fsummary>Fix an ETS table for safe traversal.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - </type> <desc> <p>Fixes a table of the <c>set</c>, <c>bag</c> or <c>duplicate_bag</c> table type for safe traversal.</p> <p>A process fixes a table by calling - <c>safe_fixtable(Tab,true)</c>. The table remains fixed until + <c>safe_fixtable(<anno>Tab</anno>, true)</c>. The table remains fixed until the process releases it by calling - <c>safe_fixtable(Tab,false)</c>, or until the process + <c>safe_fixtable(<anno>Tab</anno>, false)</c>, or until the process terminates.</p> <p>If several processes fix a table, the table will remain fixed until all processes have released it (or terminated). @@ -1242,15 +1129,10 @@ clean_all_with_value(Tab,X,Key) -> </desc> </func> <func> - <name>select(Tab, MatchSpec) -> [Match]</name> + <name name="select" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> using a + <p>Matches the objects in the table <c><anno>Tab</anno></c> using a <seealso marker="#match_spec">match_spec</seealso>. This is a more general call than the <c>ets:match/2</c> and <c>ets:match_object/2</c> calls. In its simplest forms the @@ -1337,18 +1219,12 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select(Tab, MatchSpec, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select" arity="3"/> <fsummary>Match the objects in an ETS table against a match_spec and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>ets:select/2</c> but only returns a limited - (<c>Limit</c>) number of matching objects. The - <c>Continuation</c> term can then be used in subsequent calls + (<c><anno>Limit</anno></c>) number of matching objects. The + <c><anno>Continuation</anno></c> term can then be used in subsequent calls to <c>ets:select/1</c> to get the next chunk of matching objects. This is a space efficient way to work on objects in a table which is still faster than traversing the table object @@ -1357,33 +1233,23 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select" arity="1"/> <fsummary>Continue matching objects in an ETS table.</fsummary> - <type> - <v>Match = term()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with <c>ets:select/3</c>. The next chunk of the size given in the initial <c>ets:select/3</c> - call is returned together with a new <c>Continuation</c> + call is returned together with a new <c><anno>Continuation</anno></c> that can be used in subsequent calls to this function.</p> <p><c>'$end_of_table'</c> is returned when there are no more objects in the table.</p> </desc> </func> <func> - <name>select_count(Tab, MatchSpec) -> NumMatched</name> + <name name="select_count" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec and returns the number of objects for which the match_spec returned 'true'</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Object = tuple()</v> - <v>MatchSpec = match_spec()</v> - <v>NumMatched = integer()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> using a + <p>Matches the objects in the table <c><anno>Tab</anno></c> using a <seealso marker="#match_spec">match_spec</seealso>. If the match_spec returns <c>true</c> for an object, that object considered a match and is counted. For any other result from @@ -1396,16 +1262,10 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select_delete(Tab, MatchSpec) -> NumDeleted</name> + <name name="select_delete" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec and deletes objects where the match_spec returns 'true'</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Object = tuple()</v> - <v>MatchSpec = match_spec()</v> - <v>NumDeleted = integer()</v> - </type> <desc> - <p>Matches the objects in the table <c>Tab</c> using a + <p>Matches the objects in the table <c><anno>Tab</anno></c> using a <seealso marker="#match_spec">match_spec</seealso>. If the match_spec returns <c>true</c> for an object, that object is removed from the table. For any other result from the @@ -1422,13 +1282,8 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select_reverse(Tab, MatchSpec) -> [Match]</name> + <name name="select_reverse" arity="2"/> <fsummary>Match the objects in an ETS table against a match_spec.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - </type> <desc> <p>Works like <c>select/2</c>, but returns the list in reverse @@ -1438,14 +1293,8 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>select_reverse(Tab, MatchSpec, Limit) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select_reverse" arity="3"/> <fsummary>Match the objects in an ETS table against a match_spec and returns part of the answers.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Match = term()</v> - <v>MatchSpec = match_spec()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Works like <c>select/3</c>, but for the <c>ordered_set</c> @@ -1456,18 +1305,14 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> <p>Note that this is <em>not</em> equivalent to reversing the result list of a <c>select/3</c> call, as the result list - is not only reversed, but also contains the last <c>Limit</c> + is not only reversed, but also contains the last <c><anno>Limit</anno></c> matching objects in the table, not the first.</p> </desc> </func> <func> - <name>select_reverse(Continuation) -> {[Match],Continuation} | '$end_of_table'</name> + <name name="select_reverse" arity="1"/> <fsummary>Continue matching objects in an ETS table.</fsummary> - <type> - <v>Match = term()</v> - <v>Continuation = term()</v> - </type> <desc> <p>Continues a match started with @@ -1477,7 +1322,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> returned list will also contain objects with keys in reverse order.</p> - <p>For all other table types, the behaviour is exatly that of <c>select/1</c>.</p> + <p>For all other table types, the behaviour is exactly that of <c>select/1</c>.</p> <p>Example:</p> <code> 1> T = ets:new(x,[ordered_set]). @@ -1501,14 +1346,8 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>setopts(Tab, Opts) -> true</name> + <name name="setopts" arity="2"/> <fsummary>Set table options.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Opts = Opt | [Opt]</v> - <v>Opt = {heir,pid(),HeirData} | {heir,none}</v> - <v>HeirData = term()</v> - </type> <desc> <p>Set table options. The only option that currently is allowed to be set after the table has been created is @@ -1517,28 +1356,23 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </desc> </func> <func> - <name>slot(Tab, I) -> [Object] | '$end_of_table'</name> + <name name="slot" arity="2"/> <fsummary>Return all objects in a given slot of an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>I = integer()</v> - <v>Object = tuple()</v> - </type> <desc> <p>This function is mostly for debugging purposes, Normally one should use <c>first/next</c> or <c>last/prev</c> instead.</p> - <p>Returns all objects in the <c>I</c>:th slot of the table - <c>Tab</c>. A table can be traversed by repeatedly calling - the function, starting with the first slot <c>I=0</c> and + <p>Returns all objects in the <c><anno>I</anno></c>:th slot of the table + <c><anno>Tab</anno></c>. A table can be traversed by repeatedly calling + the function, starting with the first slot <c><anno>I</anno>=0</c> and ending when <c>'$end_of_table'</c> is returned. The function will fail with reason <c>badarg</c> if the - <c>I</c> argument is out of range.</p> + <c><anno>I</anno></c> argument is out of range.</p> <p>Unless a table of type <c>set</c>, <c>bag</c> or <c>duplicate_bag</c> is protected using <c>safe_fixtable/2</c>, see above, a traversal may fail if concurrent updates are made to the table. If the table is of type <c>ordered_set</c>, the function returns a list - containing the <c>I</c>:th object in Erlang term order.</p> + containing the <c><anno>I</anno></c>:th object in Erlang term order.</p> </desc> </func> <func> @@ -1754,16 +1588,16 @@ true</pre> </desc> </func> <func> - <name>update_counter(Tab, Key, UpdateOp) -> Result</name> - <name>update_counter(Tab, Key, [UpdateOp]) -> [Result]</name> - <name>update_counter(Tab, Key, Incr) -> Result</name> + <name name="update_counter" arity="3" clause_i="1"/> + <name name="update_counter" arity="3" clause_i="2"/> + <name name="update_counter" arity="3" clause_i="3"/> + <type variable="Tab"/> + <type variable="Key"/> + <type variable="UpdateOp" name_i="1"/> + <type variable="Pos" name_i="1"/> + <type variable="Threshold" name_i="1"/> + <type variable="SetValue" name_i="1"/> <fsummary>Update a counter object in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = term()</v> - <v>UpdateOp = {Pos,Incr} | {Pos,Incr,Threshold,SetValue}</v> - <v>Pos = Incr = Threshold = SetValue = Result = integer()</v> - </type> <desc> <p>This function provides an efficient way to update one or more counters, without the hassle of having to look up an object, update @@ -1771,22 +1605,22 @@ true</pre> into the table again. (The update is done atomically; i.e. no process can access the ets table in the middle of the operation.) </p> - <p>It will destructively update the object with key <c>Key</c> - in the table <c>Tab</c> by adding <c>Incr</c> to the element - at the <c>Pos</c>:th position. The new counter value is + <p>It will destructively update the object with key <c><anno>Key</anno></c> + in the table <c><anno>Tab</anno></c> by adding <c><anno>Incr</anno></c> to the element + at the <c><anno>Pos</anno></c>:th position. The new counter value is returned. If no position is specified, the element directly following the key (<c><![CDATA[<keypos>+1]]></c>) is updated.</p> - <p>If a <c>Threshold</c> is specified, the counter will be - reset to the value <c>SetValue</c> if the following + <p>If a <c><anno>Threshold</anno></c> is specified, the counter will be + reset to the value <c><anno>SetValue</anno></c> if the following conditions occur:</p> <list type="bulleted"> - <item>The <c>Incr</c> is not negative (<c>>= 0</c>) and the - result would be greater than (<c>></c>) <c>Threshold</c></item> - <item>The <c>Incr</c> is negative (<c><![CDATA[< 0]]></c>) and the + <item>The <c><anno>Incr</anno></c> is not negative (<c>>= 0</c>) and the + result would be greater than (<c>></c>) <c><anno>Threshold</anno></c></item> + <item>The <c><anno>Incr</anno></c> is negative (<c><![CDATA[< 0]]></c>) and the result would be less than (<c><![CDATA[<]]></c>) - <c>Threshold</c></item> + <c><anno>Threshold</anno></c></item> </list> - <p>A list of <c>UpdateOp</c> can be supplied to do several update + <p>A list of <c><anno>UpdateOp</anno></c> can be supplied to do several update operations within the object. The operations are carried out in the order specified in the list. If the same counter position occurs more than one time in the list, the corresponding counter will thus @@ -1797,7 +1631,7 @@ true</pre> returned. If the function should fail, no updates will be done at all. </p> - <p>The given Key is used to identify the object by either + <p>The given <c><anno>Key</anno></c> is used to identify the object by either <em>matching</em> the key of an object in a <c>set</c> table, or <em>compare equal</em> to the key of an object in an <c>ordered_set</c> table (see @@ -1812,29 +1646,28 @@ true</pre> <item>the object has the wrong arity,</item> <item>the element to update is not an integer,</item> <item>the element to update is also the key, or,</item> - <item>any of <c>Pos</c>, <c>Incr</c>, <c>Threshold</c> or - <c>SetValue</c> is not an integer</item> + <item>any of <c><anno>Pos</anno></c>, <c><anno>Incr</anno></c>, <c><anno>Threshold</anno></c> or + <c><anno>SetValue</anno></c> is not an integer</item> </list> </desc> </func> <func> - <name>update_element(Tab, Key, {Pos,Value}) -> true | false</name> - <name>update_element(Tab, Key, [{Pos,Value}]) -> true | false</name> + <name name="update_element" arity="3" clause_i="1"/> + <name name="update_element" arity="3" clause_i="2"/> + <type variable="Tab"/> + <type variable="Key"/> + <type variable="Value"/> + <type variable="Pos"/> <fsummary>Updates the <c>Pos</c>:th element of the object with a given key in an ETS table.</fsummary> - <type> - <v>Tab = tid() | atom()</v> - <v>Key = Value = term()</v> - <v>Pos = integer()</v> - </type> <desc> <p>This function provides an efficient way to update one or more elements within an object, without the hassle of having to look up, update and write back the entire object. </p> - <p>It will destructively update the object with key <c>Key</c> - in the table <c>Tab</c>. The element at the <c>Pos</c>:th position - will be given the value <c>Value</c>. </p> - <p>A list of <c>{Pos,Value}</c> can be supplied to update several + <p>It will destructively update the object with key <c><anno>Key</anno></c> + in the table <c><anno>Tab</anno></c>. The element at the <c><anno>Pos</anno></c>:th position + will be given the value <c><anno>Value</anno></c>. </p> + <p>A list of <c>{<anno>Pos</anno>,<anno>Value</anno>}</c> can be supplied to update several elements within the same object. If the same position occurs more than one in the list, the last value in the list will be written. If the list is empty or the function fails, no updates will be done at @@ -1842,9 +1675,9 @@ true</pre> can never see any intermediate results. </p> <p>The function returns <c>true</c> if an object with the key - <c>Key</c> was found, <c>false</c> otherwise. + <c><anno>Key</anno></c> was found, <c>false</c> otherwise. </p> - <p>The given Key is used to identify the object by either + <p>The given <c><anno>Key</anno></c> is used to identify the object by either <em>matching</em> the key of an object in a <c>set</c> table, or <em>compare equal</em> to the key of an object in an <c>ordered_set</c> table (see @@ -1855,7 +1688,7 @@ true</pre> <list type="bulleted"> <item>the table is not of type <c>set</c> or <c>ordered_set</c>,</item> - <item><c>Pos</c> is less than 1 or greater than the object + <item><c><anno>Pos</anno></c> is less than 1 or greater than the object arity, or,</item> <item>the element to update is also the key</item> </list> diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index f3079c7337..cec20aee8e 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -150,6 +150,11 @@ <p>Matches any number of characters up to the end of the filename, the next dot, or the next slash.</p> </item> + <tag>**</tag> + <item> + <p>Two adjacent <c>*</c>'s used as a single pattern will + match all files and zero or more directories and subdirectories.</p> + </item> <tag>[Character1,Character2,...]</tag> <item> <p>Matches any of the characters listed. Two characters @@ -192,6 +197,10 @@ <c>src</c> or <c>include</c> directories, use:</p> <code type="none"> filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}") </code> + <p>To find all <c>.erl</c> or <c>.hrl</c> files in any + subdirectory, use:</p> + <code type="none"> + filelib:wildcard("lib/**/*.{erl,hrl}") </code> </desc> </func> <func> diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 65c866efbe..9316d60b1a 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -132,15 +132,6 @@ </desc> </func> <func> - <name name="lookup" arity="2"/> - <fsummary>Look up a key in a tree</fsummary> - <desc> - <p>Looks up <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>; returns - <c>{value, <anno>Val</anno>}</c>, or <c>none</c> if <c><anno>Key</anno></c> is not - present.</p> - </desc> - </func> - <func> <name name="insert" arity="3"/> <fsummary>Insert a new key and value in a tree</fsummary> <desc> @@ -196,6 +187,15 @@ </desc> </func> <func> + <name name="lookup" arity="2"/> + <fsummary>Look up a key in a tree</fsummary> + <desc> + <p>Looks up <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>; returns + <c>{value, <anno>Val</anno>}</c>, or <c>none</c> if <c><anno>Key</anno></c> is not + present.</p> + </desc> + </func> + <func> <name name="map" arity="2"/> <fsummary>Return largest key and value</fsummary> <desc><p>Maps the function F(<anno>K</anno>, <anno>V1</anno>) -> <anno>V2</anno> to all key-value pairs diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index 79a0c8ad89..1601ea9892 100644 --- a/lib/stdlib/doc/src/gen_event.xml +++ b/lib/stdlib/doc/src/gen_event.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -120,8 +120,10 @@ gen_event:stop -----> Module:terminate/2 <name>start_link(EventMgrName) -> Result</name> <fsummary>Create a generic event manager process in a supervision tree.</fsummary> <type> - <v>EventMgrName = {local,Name} | {global,Name}</v> + <v>EventMgrName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Result = {ok,Pid} | {error,{already_started,Pid}}</v> <v> Pid = pid()</v> </type> @@ -132,10 +134,17 @@ gen_event:stop -----> Module:terminate/2 the event manager is linked to the supervisor.</p> <p>If <c>EventMgrName={local,Name}</c>, the event manager is registered locally as <c>Name</c> using <c>register/2</c>. - If <c>EventMgrName={global,Name}</c>, the event manager is - registered globally as <c>Name</c> using + If <c>EventMgrName={global,GlobalName}</c>, the event manager is + registered globally as <c>GlobalName</c> using <c>global:register_name/2</c>. If no name is provided, - the event manager is not registered.</p> + the event manager is not registered. + If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will + register with the registry represented by <c>Module</c>. + The <c>Module</c> callback should export the functions + <c>register_name/2</c>, <c>unregister_name/1</c>, + <c>whereis_name/1</c> and <c>send/2</c>, which should behave like the + corresponding functions in <c>global</c>. Thus, + <c>{via,global,GlobalName}</c> is a valid reference.</p> <p>If the event manager is successfully created the function returns <c>{ok,Pid}</c>, where <c>Pid</c> is the pid of the event manager. If there already exists a process with @@ -149,8 +158,10 @@ gen_event:stop -----> Module:terminate/2 <name>start(EventMgrName) -> Result</name> <fsummary>Create a stand-alone event manager process.</fsummary> <type> - <v>EventMgrName = {local,Name} | {global,Name}</v> + <v>EventMgrName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Result = {ok,Pid} | {error,{already_started,Pid}}</v> <v> Pid = pid()</v> </type> @@ -166,8 +177,10 @@ gen_event:stop -----> Module:terminate/2 <name>add_handler(EventMgrRef, Handler, Args) -> Result</name> <fsummary>Add an event handler to a generic event manager.</fsummary> <type> - <v>EventMgr = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgr = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Handler = Module | {Module,Id}</v> <v> Module = atom()</v> <v> Id = term()</v> @@ -185,8 +198,10 @@ gen_event:stop -----> Module:terminate/2 <item><c>Name</c>, if the event manager is locally registered,</item> <item><c>{Name,Node}</c>, if the event manager is locally registered at another node, or</item> - <item><c>{global,Name}</c>, if the event manager is globally + <item><c>{global,GlobalName}</c>, if the event manager is globally registered.</item> + <item><c>{via,Module,ViaName}</c>, if the event manager is registered + through an alternative process registry.</item> </list> <p><c>Handler</c> is the name of the callback module <c>Module</c> or a tuple <c>{Module,Id}</c>, where <c>Id</c> is any term. @@ -208,8 +223,10 @@ gen_event:stop -----> Module:terminate/2 <name>add_sup_handler(EventMgrRef, Handler, Args) -> Result</name> <fsummary>Add a supervised event handler to a generic event manager.</fsummary> <type> - <v>EventMgr = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgr = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Handler = Module | {Module,Id}</v> <v> Module = atom()</v> <v> Id = term()</v> @@ -253,8 +270,10 @@ gen_event:stop -----> Module:terminate/2 <name>sync_notify(EventMgrRef, Event) -> ok</name> <fsummary>Notify an event manager about an event.</fsummary> <type> - <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Event = term()</v> </type> <desc> @@ -278,8 +297,10 @@ gen_event:stop -----> Module:terminate/2 <name>call(EventMgrRef, Handler, Request, Timeout) -> Result</name> <fsummary>Make a synchronous call to a generic event manager.</fsummary> <type> - <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Handler = Module | {Module,Id}</v> <v> Module = atom()</v> <v> Id = term()</v> @@ -318,8 +339,10 @@ gen_event:stop -----> Module:terminate/2 <name>delete_handler(EventMgrRef, Handler, Args) -> Result</name> <fsummary>Delete an event handler from a generic event manager.</fsummary> <type> - <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Handler = Module | {Module,Id}</v> <v> Module = atom()</v> <v> Id = term()</v> @@ -346,8 +369,10 @@ gen_event:stop -----> Module:terminate/2 <name>swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name> <fsummary>Replace an event handler in a generic event manager.</fsummary> <type> - <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Handler1 = Handler2 = Module | {Module,Id}</v> <v> Module = atom()</v> <v> Id = term()</v> @@ -390,8 +415,10 @@ gen_event:stop -----> Module:terminate/2 <name>swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name> <fsummary>Replace an event handler in a generic event manager.</fsummary> <type> - <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Handler1 = Handler 2 = Module | {Module,Id}</v> <v> Module = atom()</v> <v> Id = term()</v> @@ -412,8 +439,10 @@ gen_event:stop -----> Module:terminate/2 <name>which_handlers(EventMgrRef) -> [Handler]</name> <fsummary>Return all event handlers installed in a generic event manager.</fsummary> <type> - <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> + <v> GlobalName = ViaName = term()</v> <v>Handler = Module | {Module,Id}</v> <v> Module = atom()</v> <v> Id = term()</v> @@ -429,8 +458,10 @@ gen_event:stop -----> Module:terminate/2 <name>stop(EventMgrRef) -> ok</name> <fsummary>Terminate a generic event manager.</fsummary> <type> - <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v>Name = Node = atom()</v> + <v>GlobalName = ViaName = term()</v> </type> <desc> <p>Terminates the event manager <c>EventMgrRef</c>. Before diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index 421eeb4fd3..73c1911f1e 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -84,9 +84,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <name>start_link(FsmName, Module, Args, Options) -> Result</name> <fsummary>Create a gen_fsm process in a supervision tree.</fsummary> <type> - <v>FsmName = {local,Name} | {global,GlobalName}</v> + <v>FsmName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Module = atom()</v> <v>Args = term()</v> <v>Options = [Option]</v> @@ -113,8 +114,16 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 locally as <c>Name</c> using <c>register/2</c>. If <c>FsmName={global,GlobalName}</c>, the gen_fsm is registered globally as <c>GlobalName</c> using - <c>global:register_name/2</c>. If no name is provided, - the gen_fsm is not registered.</p> + <c>global:register_name/2</c>. + If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will + register with the registry represented by <c>Module</c>. + The <c>Module</c> callback should export the functions + <c>register_name/2</c>, <c>unregister_name/1</c>, + <c>whereis_name/1</c> and <c>send/2</c>, which should behave like the + corresponding functions in <c>global</c>. Thus, + <c>{via,global,GlobalName}</c> is a valid reference.</p> + <p>If no name is provided, + the gen_fsm is not registered.</p> <p><c>Module</c> is the name of the callback module.</p> <p><c>Args</c> is an arbitrary term which is passed as the argument to <c>Module:init/1</c>.</p> @@ -154,9 +163,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <name>start(FsmName, Module, Args, Options) -> Result</name> <fsummary>Create a stand-alone gen_fsm process.</fsummary> <type> - <v>FsmName = {local,Name} | {global,GlobalName}</v> + <v>FsmName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Module = atom()</v> <v>Args = term()</v> <v>Options = [Option]</v> @@ -180,9 +190,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <name>send_event(FsmRef, Event) -> ok</name> <fsummary>Send an event asynchronously to a generic FSM.</fsummary> <type> - <v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v> + <v>FsmRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Event = term()</v> </type> <desc> @@ -196,9 +207,11 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <item>the pid,</item> <item><c>Name</c>, if the gen_fsm is locally registered,</item> <item><c>{Name,Node}</c>, if the gen_fsm is locally - registered at another node, or</item> - <item><c>{global,GlobalName}</c>, if the gen_fsm is globally - registered.</item> + registered at another node, or</item> + <item><c>{global,GlobalName}</c>, if the gen_fsm is globally + registered.</item> + <item><c>{via,Module,ViaName}</c>, if the event manager is registered + through an alternative process registry.</item> </list> <p><c>Event</c> is an arbitrary term which is passed as one of the arguments to <c>Module:StateName/2</c>.</p> @@ -208,9 +221,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <name>send_all_state_event(FsmRef, Event) -> ok</name> <fsummary>Send an event asynchronously to a generic FSM.</fsummary> <type> - <v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v> + <v>FsmRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Event = term()</v> </type> <desc> @@ -232,9 +246,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <name>sync_send_event(FsmRef, Event, Timeout) -> Reply</name> <fsummary>Send an event synchronously to a generic FSM.</fsummary> <type> - <v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v> + <v>FsmRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Event = term()</v> <v>Timeout = int()>0 | infinity</v> <v>Reply = term()</v> @@ -264,9 +279,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <name>sync_send_all_state_event(FsmRef, Event, Timeout) -> Reply</name> <fsummary>Send an event synchronously to a generic FSM.</fsummary> <type> - <v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v> + <v>FsmRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Name = Node = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Event = term()</v> <v>Timeout = int()>0 | infinity</v> <v>Reply = term()</v> @@ -388,9 +404,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 <v> | {log_to_file,FileName} | {install,{Func,FuncState}}</v> <v>StateName = atom()</v> <v>StateData = term()</v> - <v>FsmName = {local,Name} | {global,GlobalName}</v> + <v>FsmName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Timeout = int() | infinity</v> </type> <desc> diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index edeb7dff91..abb4c73c7b 100644 --- a/lib/stdlib/doc/src/gen_server.xml +++ b/lib/stdlib/doc/src/gen_server.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -83,9 +83,10 @@ gen_server:abcast -----> Module:handle_cast/2 <name>start_link(ServerName, Module, Args, Options) -> Result</name> <fsummary>Create a gen_server process in a supervision tree.</fsummary> <type> - <v>ServerName = {local,Name} | {global,GlobalName}</v> + <v>ServerName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Module = atom()</v> <v>Args = term()</v> <v>Options = [Option]</v> @@ -111,14 +112,22 @@ gen_server:abcast -----> Module:handle_cast/2 If <c>ServerName={global,GlobalName}</c> the gen_server is registered globally as <c>GlobalName</c> using <c>global:register_name/2</c>. If no name is provided, - the gen_server is not registered.</p> + the gen_server is not registered. + If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will + register with the registry represented by <c>Module</c>. + The <c>Module</c> callback should export the functions + <c>register_name/2</c>, <c>unregister_name/1</c>, + <c>whereis_name/1</c> and <c>send/2</c>, which should behave like the + corresponding functions in <c>global</c>. Thus, + <c>{via,global,GlobalName}</c> is a valid reference.</p> <p><c>Module</c> is the name of the callback module.</p> <p><c>Args</c> is an arbitrary term which is passed as the argument to <c>Module:init/1</c>.</p> <p>If the option <c>{timeout,Time}</c> is present, the gen_server is allowed to spend <c>Time</c> milliseconds initializing or it will be terminated and the start function - will return <c>{error,timeout}</c>.</p> + will return <c>{error,timeout}</c>. + </p> <p>If the option <c>{debug,Dbgs}</c> is present, the corresponding <c>sys</c> function will be called for each item in <c>Dbgs</c>. See @@ -151,9 +160,10 @@ gen_server:abcast -----> Module:handle_cast/2 <name>start(ServerName, Module, Args, Options) -> Result</name> <fsummary>Create a stand-alone gen_server process.</fsummary> <type> - <v>ServerName = {local,Name} | {global,GlobalName}</v> + <v>ServerName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Module = atom()</v> <v>Args = term()</v> <v>Options = [Option]</v> @@ -178,9 +188,10 @@ gen_server:abcast -----> Module:handle_cast/2 <name>call(ServerRef, Request, Timeout) -> Reply</name> <fsummary>Make a synchronous call to a generic server.</fsummary> <type> - <v>ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()</v> + <v>ServerRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Node = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Request = term()</v> <v>Timeout = int()>0 | infinity</v> <v>Reply = term()</v> @@ -198,6 +209,8 @@ gen_server:abcast -----> Module:handle_cast/2 registered at another node, or</item> <item><c>{global,GlobalName}</c>, if the gen_server is globally registered.</item> + <item><c>{via,Module,ViaName}</c>, if the gen_server is + registered through an alternative process registry.</item> </list> <p><c>Request</c> is an arbitrary term which is passed as one of the arguments to <c>Module:handle_call/3</c>.</p> @@ -281,9 +294,10 @@ gen_server:abcast -----> Module:handle_cast/2 <name>cast(ServerRef, Request) -> ok</name> <fsummary>Send an asynchronous request to a generic server.</fsummary> <type> - <v>ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()</v> + <v>ServerRef = Name | {Name,Node} | {global,GlobalName} + | {via,Module,ViaName} | pid()</v> <v> Node = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Request = term()</v> </type> <desc> @@ -355,9 +369,10 @@ gen_server:abcast -----> Module:handle_cast/2 <v> Dbg = trace | log | statistics</v> <v> | {log_to_file,FileName} | {install,{Func,FuncState}}</v> <v>State = term()</v> - <v>ServerName = {local,Name} | {global,GlobalName}</v> + <v>ServerName = {local,Name} | {global,GlobalName} + | {via,Module,ViaName}</v> <v> Name = atom()</v> - <v> GlobalName = term()</v> + <v> GlobalName = ViaName = term()</v> <v>Timeout = int() | infinity</v> </type> <desc> diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml index 7042c84437..b6c0fa4e05 100644 --- a/lib/stdlib/doc/src/lists.xml +++ b/lib/stdlib/doc/src/lists.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -248,18 +248,13 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>keyfind(Key, N, TupleList) -> Tuple | false</name> + <name name="keyfind" arity="3"/> + <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <fsummary>Search for an element in a list of tuples</fsummary> - <type> - <v>Key = term()</v> - <v>N = 1..tuple_size(Tuple)</v> - <v>TupleList = [Tuple]</v> - <v>Tuple = tuple()</v> - </type> - <desc> - <p>Searches the list of tuples <c>TupleList</c> for a - tuple whose <c>N</c>th element compares equal to <c>Key</c>. - Returns <c>Tuple</c> if such a tuple is found, + <desc> + <p>Searches the list of tuples <c><anno>TupleList</anno></c> for a + tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>. + Returns <c><anno>Tuple</anno></c> if such a tuple is found, otherwise <c>false</c>.</p> </desc> </func> @@ -281,17 +276,12 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>keymember(Key, N, TupleList) -> boolean()</name> + <name name="keymember" arity="3"/> + <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <fsummary>Test for membership of a list of tuples</fsummary> - <type> - <v>Key = term()</v> - <v>N = 1..tuple_size(Tuple)</v> - <v>TupleList = [Tuple]</v> - <v> Tuple = tuple()</v> - </type> - <desc> - <p>Returns <c>true</c> if there is a tuple in <c>TupleList</c> - whose <c>N</c>th element compares equal to <c>Key</c>, otherwise + <desc> + <p>Returns <c>true</c> if there is a tuple in <c><anno>TupleList</anno></c> + whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>, otherwise <c>false</c>.</p> </desc> </func> @@ -321,18 +311,13 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>keysearch(Key, N, TupleList) -> {value, Tuple} | false</name> + <name name="keysearch" arity="3"/> + <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <fsummary>Search for an element in a list of tuples</fsummary> - <type> - <v>Key = term()</v> - <v>N = 1..tuple_size(Tuple)</v> - <v>TupleList = [Tuple]</v> - <v>Tuple = tuple()</v> - </type> - <desc> - <p>Searches the list of tuples <c>TupleList</c> for a - tuple whose <c>N</c>th element compares equal to <c>Key</c>. - Returns <c>{value, Tuple}</c> if such a tuple is found, + <desc> + <p>Searches the list of tuples <c><anno>TupleList</anno></c> for a + tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>. + Returns <c>{value, <anno>Tuple</anno>}</c> if such a tuple is found, otherwise <c>false</c>.</p> <note><p>This function is retained for backward compatibility. The function <c>lists:keyfind/3</c> (introduced in R13A) @@ -425,15 +410,11 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name>member(Elem, List) -> boolean()</name> + <name name="member" arity="2"/> <fsummary>Test for membership of a list</fsummary> - <type> - <v>Elem = term()</v> - <v>List = [term()]</v> - </type> <desc> - <p>Returns <c>true</c> if <c>Elem</c> matches some element of - <c>List</c>, otherwise <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Elem</anno></c> matches some element of + <c><anno>List</anno></c>, otherwise <c>false</c>.</p> </desc> </func> <func> @@ -562,14 +543,11 @@ c</pre> </desc> </func> <func> - <name>reverse(List1, Tail) -> List2</name> + <name name="reverse" arity="2"/> <fsummary>Reverse a list appending a tail</fsummary> - <type> - <v>List1 = Tail = List2 = [term()]</v> - </type> <desc> - <p>Returns a list with the elements in <c>List1</c> - in reverse order, with the tail <c>Tail</c> appended. For + <p>Returns a list with the elements in <c><anno>List1</anno></c> + in reverse order, with the tail <c><anno>Tail</anno></c> appended. For example:</p> <pre> > <input>lists:reverse([1, 2, 3, 4], [a, b, c]).</input> @@ -663,7 +641,7 @@ splitwith(Pred, List) -> <desc> <p>Returns the sub-list of <c><anno>List1</anno></c> starting at position 1 and with (max) <c><anno>Len</anno></c> elements. It is not an error for - <c><anno>Len</anno></c> to exceed the length of the list -- in that case + <c><anno>Len</anno></c> to exceed the length of the list, in that case the whole list is returned.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index 518457d5d8..0219dcce10 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2012</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -52,54 +52,47 @@ </desc> </func> <func> - <name>sin(X)</name> - <name>cos(X)</name> - <name>tan(X)</name> - <name>asin(X)</name> - <name>acos(X)</name> - <name>atan(X)</name> - <name>atan2(Y, X)</name> - <name>sinh(X)</name> - <name>cosh(X)</name> - <name>tanh(X)</name> - <name>asinh(X)</name> - <name>acosh(X)</name> - <name>atanh(X)</name> - <name>exp(X)</name> - <name>log(X)</name> - <name>log10(X)</name> - <name>pow(X, Y)</name> - <name>sqrt(X)</name> + <name name="sin" arity="1"/> + <name name="cos" arity="1"/> + <name name="tan" arity="1"/> + <name name="asin" arity="1"/> + <name name="acos" arity="1"/> + <name name="atan" arity="1"/> + <name name="atan2" arity="2"/> + <name name="sinh" arity="1"/> + <name name="cosh" arity="1"/> + <name name="tanh" arity="1"/> + <name name="asinh" arity="1"/> + <name name="acosh" arity="1"/> + <name name="atanh" arity="1"/> + <name name="exp" arity="1"/> + <name name="log" arity="1"/> + <name name="log10" arity="1"/> + <name name="pow" arity="2"/> + <name name="sqrt" arity="1"/> + <type variable="X" name_i="7"/> + <type variable="Y" name_i="7"/> <fsummary>Diverse math functions</fsummary> - <type> - <v>X = Y = number()</v> - </type> <desc> <p>A collection of math functions which return floats. Arguments are numbers. </p> </desc> </func> <func> - <name>erf(X) -> float()</name> + <name name="erf" arity="1"/> <fsummary>Error function.</fsummary> - <type> - <v>X = number()</v> - </type> <desc> - <p>Returns the error function of <c>X</c>, where</p> + <p>Returns the error function of <c><anno>X</anno></c>, where</p> <pre> erf(X) = 2/sqrt(pi)*integral from 0 to X of exp(-t*t) dt. </pre> </desc> </func> <func> - <name>erfc(X) -> float()</name> + <name name="erfc" arity="1"/> <fsummary>Another error function</fsummary> - <type> - <v>X = number()</v> - </type> <desc> <p><c>erfc(X)</c> returns <c>1.0 - erf(X)</c>, computed by - methods that avoid cancellation for large <c>X</c>. </p> + methods that avoid cancellation for large <c><anno>X</anno></c>. </p> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/ms_transform.xml b/lib/stdlib/doc/src/ms_transform.xml index f81f8bda96..ad5f8bd5ac 100644 --- a/lib/stdlib/doc/src/ms_transform.xml +++ b/lib/stdlib/doc/src/ms_transform.xml @@ -308,7 +308,7 @@ ets:select(emp_tab, ets:fun2ms( Erlang code. Also arithmetics is allowed, as well as ordinary guard bif's. Here's a list of bif's and expressions:</p> <list type="bulleted"> - <item>The type tests: is_atom, is_constant, is_float, is_integer, + <item>The type tests: is_atom, is_float, is_integer, is_list, is_number, is_pid, is_port, is_reference, is_tuple, is_binary, is_function, is_record</item> <item>The boolean operators: not, and, or, andalso, orelse </item> @@ -318,7 +318,7 @@ ets:select(emp_tab, ets:fun2ms( <item>The guard bif's: abs, element, hd, length, node, round, size, tl, trunc, self</item> <item>The obsolete type test (only in guards): - atom, constant, float, integer, + atom, float, integer, list, number, pid, port, reference, tuple, binary, function, record</item> </list> diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index 42a26ee44a..b4d9f9a444 100644 --- a/lib/stdlib/doc/src/notes.xml +++ b/lib/stdlib/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2011</year> + <year>2004</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,6 +30,249 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<section><title>STDLIB 1.18.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed bug where if given an invalid drive letter on + windows ensure dir would go into an infinite loop.</p> + <p> + Own Id: OTP-10104</p> + </item> + <item> + <p> + Calls to gen_server:enter_loop/4 where ServerName has a + global scope and no timeout is given now works correctly.</p> + <p> + Thanks to Sam Bobroff for reporting the issue.</p> + <p> + Own Id: OTP-10130</p> + </item> + <item> + <p> + fix escript/primary archive reloading</p> + <p> + If the mtime of an escript/primary archive file changes + after being added to the code path, correctly reload the + archive and update the cache. (Thanks to Tuncer Ayaz)</p> + <p> + Own Id: OTP-10151</p> + </item> + <item> + <p> + Fix bug that in some cases could cause corrupted binaries + in ETS tables with <c>compressed</c> option.</p> + <p> + Own Id: OTP-10182</p> + </item> + <item> + <p> + Fix filename:nativename/1 on Win32</p> + <p> + Don't choke on paths given as binary argument on Win32. + Thanks to Jan Kl�tzke</p> + <p> + Own Id: OTP-10188</p> + </item> + <item> + <p> + Fix bug in <c>ets:test_ms/2</c> that could cause emulator + crash when using <c>'$_'</c> in match spec.</p> + <p> + Own Id: OTP-10190</p> + </item> + <item> + <p> + Fix bug where zip archives wrongly have a first disk + number set to 1</p> + <p> + Own Id: OTP-10223</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The message printed by the Erlang shell as an + explanation of the <c>badarith</c> error has been + corrected. (Thanks to Matthias Lang.) </p> + <p> + Own Id: OTP-10054</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 1.18.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + References to <c>is_constant/1</c> (which was removed in + the R12 release) has been removed from documentation and + code.</p> + <p> + Own Id: OTP-6454 Aux Id: seq10407 </p> + </item> + <item> + <p> + Leave control back to gen_server during supervisor's + restart loop</p> + <p> + When an attempt to restart a child failed, supervisor + would earlier keep the execution flow and try to restart + the child over and over again until it either succeeded + or the restart frequency limit was reached. If none of + these happened, supervisor would hang forever in this + loop.</p> + <p> + This commit adds a timer of 0 ms where the control is + left back to the gen_server which implements the + supervisor. This way any incoming request to the + supervisor will be handled - which could help breaking + the infinite loop - e.g. shutdown request for the + supervisor or for the problematic child.</p> + <p> + This introduces some incompatibilities in stdlib due to + new return values from supervisor: <list> + <item>restart_child/2 can now return + {error,restarting}</item> <item>delete_child/2 can now + return {error,restarting}</item> <item>which_children/1 + returns a list of {Id,Child,Type,Mods}, where Child, in + addition to the old pid() or 'undefined', now also can be + 'restarting'.</item> </list></p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-9549</p> + </item> + <item> + <p> + If a temporary child's start function returned 'ignore', + then the supervisor would keep it's child specification. + This has been corrected. Child specifications for + non-existing temporary children shall never be kept.</p> + <p> + Own Id: OTP-9782 Aux Id: seq11964 </p> + </item> + <item> + <p> Use universal time as base in error logger + <p> + Previous conversion used the deprecated + calendar:local_time_to_universal_time/1 </p></p> + <p> + Own Id: OTP-9854</p> + </item> + <item> + <p>Calling a guard test (such as is_list/1) from the + top-level in a guard, would cause a compiler crash if + there was a local definition with the same name. + Corrected to reject the program with an error + message.</p> + <p> + Own Id: OTP-9866</p> + </item> + <item> + <p> + Fix the type spec from the doc of binary:part/3 (Thanks + to Ricardo Catalinas Jim�nez)</p> + <p> + Own Id: OTP-9920</p> + </item> + <item> + <p> + Correct spelling of registered (Thanks to Richard + Carlsson)</p> + <p> + Own Id: OTP-9925</p> + </item> + <item> + <p> + Put gb_trees documentation into alphabetical order + (Thanks to Aidan Hobson Sayers)</p> + <p> + Own Id: OTP-9929</p> + </item> + <item> + <p> + Fix bug in ETS with <c>compressed</c> option and + insertion of term containing large integers (>2G) on + 64-bit machines. Seen to cause emulator crash. (Thanks to + Diego Llarrull for excellent bug report)</p> + <p> + Own Id: OTP-9932</p> + </item> + <item> + <p> + Add plugin support for alternative name lookup This patch + introduces a new way of locating a behaviour instance: + {via, Module, Name}. (Thanks to Ulf Wiger)</p> + <p> + Own Id: OTP-9945</p> + </item> + <item> + <p> The function <c>digraph_utils:condensation/1</c> used + to create a digraph containing loops contradicting the + documentation which states that the created digraph is + free of cycles. This bug has been fixed. (Thanks to + Kostis Sagonas for finding the bug.) </p> + <p> + Own Id: OTP-9953</p> + </item> + <item> + <p> When an escript ends now all printout to standard + output and standard error gets out on the terminal. This + bug has been corrected by changing the behaviour of + erlang:halt/0,1, which should fix the same problem for + other escript-like applications, i.e that data stored in + the output port driver buffers got lost when printing on + a TTY and exiting through erlang:halt/0,1. </p> + <p> The BIF:s erlang:halt/0,1 has gotten improved + semantics and there is a new BIF erlang:halt/2 to + accomplish something like the old semantics. See the + documentation. </p> + <p> Now erlang:halt/0 and erlang:halt/1 with an integer + argument will close all ports and allow all pending async + threads operations to finish before exiting the emulator. + Previously erlang:halt/0 and erlang:halt(0) would just + wait for pending async threads operations but not close + ports. And erlang:halt/1 with a non-zero integer argument + would not even wait for pending async threads operations. + </p> + <p> To roughly the old behaviour, to not wait for ports + and async threads operations when you exit the emulator, + you use erlang:halt/2 with an integer first argument and + an option list containing {flush,false} as the second + argument. Note that now is flushing not dependant of the + exit code, and you can not only flush async threads + operations which we deemed as a strange behaviour anyway. + </p> + <p>Also, erlang:halt/1,2 has gotten a new feature: If the + first argument is the atom 'abort' the emulator is + aborted producing a core dump, if the operating system so + allows. </p> + <p> + Own Id: OTP-9985</p> + </item> + <item> + <p> + Add escript win32 alternative invocation. escript can now + be started as both "escript.exe" and "escript" (Thanks to + Pierre Rouleau)</p> + <p> + Own Id: OTP-9997</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 1.18</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 6d5336796c..2211bfb925 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>2007</year> - <year>2011</year> + <year>2012</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -78,28 +78,15 @@ </datatypes> <funcs> <func> - <name>compile(Regexp) -> {ok, MP} | {error, ErrSpec}</name> + <name name="compile" arity="1"/> <fsummary>Compile a regular expression into a match program</fsummary> - <type> - <v>Regexp = iodata()</v> - </type> <desc> - <p>The same as <c>compile(Regexp,[])</c></p> + <p>The same as <c>compile(<anno>Regexp</anno>,[])</c></p> </desc> </func> <func> - <name>compile(Regexp,Options) -> {ok, MP} | {error, ErrSpec}</name> + <name name="compile" arity="2"/> <fsummary>Compile a regular expression into a match program</fsummary> - <type> - <v>Regexp = iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>Options = [ Option ]</v> - <v>Option = <seealso marker="#type-compile_option">compile_option()</seealso></v> - <v>NLSpec = <seealso marker="#type-nl_spec">nl_spec()</seealso></v> - <v>MP = <seealso marker="#type-mp">mp()</seealso></v> - <v>ErrSpec = {ErrString, Position}</v> - <v>ErrString = string()</v> - <v>Position = non_neg_integer()</v> - </type> <desc> <p>This function compiles a regular expression with the syntax described below into an internal format to be used later as a @@ -165,44 +152,23 @@ This option makes it possible to include comments inside complicated patterns. N </func> <func> - <name>run(Subject,RE) -> {match, Captured} | nomatch</name> + <name name="run" arity="2"/> <fsummary>Match a subject against regular expression and capture subpatterns</fsummary> - <type> - <v>Subject = iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>RE = <seealso marker="#type-mp">mp()</seealso> | iodata()</v> - <v>Captured = [ CaptureData ]</v> - <v>CaptureData = {integer(),integer()}</v> - </type> <desc> - <p>The same as <c>run(Subject,RE,[])</c>.</p> + <p>The same as <c>run(<anno>Subject</anno>,<anno>RE</anno>,[])</c>.</p> </desc> </func> <func> - <name>run(Subject,RE,Options) -> {match, Captured} | match | nomatch</name> + <name name="run" arity="3"/> + <type_desc variable="CompileOpt">See <seealso marker="#compile_options">compile/2</seealso> above.</type_desc> <fsummary>Match a subject against regular expression and capture subpatterns</fsummary> - <type> - <v>Subject = iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>RE = <seealso marker="#type-mp">mp()</seealso> | iodata() | <seealso marker="unicode#type-charlist">io:charlist()</seealso></v> - <v>Options = [ Option ]</v> - <v>Option = anchored | global | notbol | noteol | notempty | {offset, integer() >= 0} | {newline, NLSpec} | bsr_anycrlf | bsr_unicode | {capture, ValueSpec} | {capture, ValueSpec, Type} | CompileOpt</v> - <v>Type = index | list | binary</v> - <v>ValueSpec = all | all_but_first | first | none | ValueList</v> - <v>ValueList = [ ValueID ]</v> - <v>ValueID = integer() | string() | atom()</v> - <v>CompileOpt = <seealso marker="#type-compile_option">compile_option()</seealso></v> - <d>See <seealso marker="#compile_options">compile/2</seealso> above.</d> - <v>NLSpec = <seealso marker="#type-nl_spec">nl_spec()</seealso></v> - <v>Captured = [ CaptureData ] | [ [ CaptureData ] ... ]</v> - <v>CaptureData = {integer(),integer()} | ListConversionData | binary()</v> - <v>ListConversionData = string() | {error, string(), binary()} | {incomplete, string(), binary()}</v> - </type> <desc> <p>Executes a regexp matching, returning <c>match/{match, - Captured}</c> or <c>nomatch</c>. The regular expression can be + <anno>Captured</anno>}</c> or <c>nomatch</c>. The regular expression can be given either as <c>iodata()</c> in which case it is automatically compiled (as by <c>re:compile/2</c>) and executed, - or as a pre compiled <c>mp()</c> in which case it is executed + or as a pre-compiled <c>mp()</c> in which case it is executed against the subject directly.</p> <p>When compilation is involved, the exception <c>badarg</c> is @@ -214,23 +180,23 @@ This option makes it possible to include comments inside complicated patterns. N list can only contain the options <c>anchored</c>, <c>global</c>, <c>notbol</c>, <c>noteol</c>, <c>notempty</c>, <c>{offset, integer() >= 0}</c>, <c>{newline, - NLSpec}</c> and <c>{capture, ValueSpec}/{capture, ValueSpec, - Type}</c>. Otherwise all options valid for the + <anno>NLSpec</anno>}</c> and <c>{capture, <anno>ValueSpec</anno>}/{capture, <anno>ValueSpec</anno>, + <anno>Type</anno>}</c>. Otherwise all options valid for the <c>re:compile/2</c> function are allowed as well. Options allowed both for compilation and execution of a match, namely - <c>anchored</c> and <c>{newline, NLSpec}</c>, will affect both + <c>anchored</c> and <c>{newline, <anno>NLSpec</anno>}</c>, will affect both the compilation and execution if present together with a non pre-compiled regular expression.</p> <p>If the regular expression was previously compiled with the - option <c>unicode</c>, the <c>Subject</c> should be provided as + option <c>unicode</c>, the <c><anno>Subject</anno></c> should be provided as a valid Unicode <c>charlist()</c>, otherwise any <c>iodata()</c> will do. If compilation is involved and the option - <c>unicode</c> is given, both the <c>Subject</c> and the regular + <c>unicode</c> is given, both the <c><anno>Subject</anno></c> and the regular expression should be given as valid Unicode <c>charlists()</c>.</p> - <p>The <c>{capture, ValueSpec}/{capture, ValueSpec, Type}</c> + <p>The <c>{capture, <anno>ValueSpec</anno>}/{capture, <anno>ValueSpec</anno>, <anno>Type</anno>}</c> defines what to return from the function upon successful matching. The <c>capture</c> tuple may contain both a value specification telling which of the captured @@ -244,9 +210,9 @@ This option makes it possible to include comments inside complicated patterns. N at all is to be done (<c>{capture, none}</c>), the function will return the single atom <c>match</c> upon successful matching, otherwise the tuple - <c>{match, ValueList}</c> is returned. Disabling capturing can + <c>{match, <anno>ValueList</anno>}</c> is returned. Disabling capturing can be done either by specifying <c>none</c> or an empty list as - <c>ValueSpec</c>.</p> + <c><anno>ValueSpec</anno></c>.</p> <p>The options relevant for execution are:</p> @@ -266,7 +232,7 @@ This option makes it possible to include comments inside complicated patterns. N Perl). Each match is returned as a separate <c>list()</c> containing the specific match as well as any matching subexpressions (or as specified by the <c>capture - option</c>). The <c>Captured</c> part of the return value will + option</c>). The <c><anno>Captured</anno></c> part of the return value will hence be a <c>list()</c> of <c>list()</c>s when this option is given.</p> @@ -362,7 +328,7 @@ This option makes it possible to include comments inside complicated patterns. N subject string. The offset is zero-based, so that the default is <c>{offset,0}</c> (all of the subject string).</item> - <tag><c>{newline, NLSpec}</c></tag> + <tag><c>{newline, <anno>NLSpec</anno>}</c></tag> <item> <p>Override the default definition of a newline in the subject string, which is LF (ASCII 10) in Erlang.</p> <taglist> @@ -383,7 +349,7 @@ This option makes it possible to include comments inside complicated patterns. N <tag><c>bsr_unicode</c></tag> <item>Specifies specifically that \R is to match all the Unicode newline characters (including crlf etc, the default).(overrides compilation option)</item> - <tag><c>{capture, ValueSpec}</c>/<c>{capture, ValueSpec, Type}</c></tag> + <tag><c>{capture, <anno>ValueSpec</anno>}</c>/<c>{capture, <anno>ValueSpec</anno>, <anno>Type</anno>}</c></tag> <item> <p>Specifies which captured substrings are returned and in what @@ -392,7 +358,7 @@ This option makes it possible to include comments inside complicated patterns. N substring as well as all capturing subpatterns (all of the pattern is automatically captured). The default return type is (zero-based) indexes of the captured parts of the string, given as - <c>{Offset,Length}</c> pairs (the <c>index</c> <c>Type</c> of + <c>{Offset,Length}</c> pairs (the <c>index</c> <c><anno>Type</anno></c> of capturing).</p> <p>As an example of the default behavior, the following call:</p> @@ -422,8 +388,8 @@ This option makes it possible to include comments inside complicated patterns. N <p>The capture tuple is built up as follows:</p> <taglist> - <tag><c>ValueSpec</c></tag> - <item><p>Specifies which captured (sub)patterns are to be returned. The ValueSpec can either be an atom describing a predefined set of return values, or a list containing either the indexes or the names of specific subpatterns to return.</p> + <tag><c><anno>ValueSpec</anno></c></tag> + <item><p>Specifies which captured (sub)patterns are to be returned. The <c><anno>ValueSpec</anno></c> can either be an atom describing a predefined set of return values, or a list containing either the indexes or the names of specific subpatterns to return.</p> <p>The predefined sets of subpatterns are:</p> <taglist> <tag><c>all</c></tag> @@ -437,7 +403,7 @@ This option makes it possible to include comments inside complicated patterns. N </taglist> <p>The value list is a list of indexes for the subpatterns to return, where index 0 is for all of the pattern, and 1 is for the first explicit capturing subpattern in the regular expression, and so forth. When using named captured subpatterns (see below) in the regular expression, one can use <c>atom()</c>s or <c>string()</c>s to specify the subpatterns to be returned. For example, consider the regular expression:</p> <code> ".*(abcd).*"</code> - <p>matched against the string ""ABCabcdABC", capturing only the "abcd" part (the first explicit subpattern):</p> + <p>matched against the string "ABCabcdABC", capturing only the "abcd" part (the first explicit subpattern):</p> <code> re:run("ABCabcdABC",".*(abcd).*",[{capture,[1]}]).</code> <p>The call will yield the following result:</p> <code> {match,[{3,4}]}</code> @@ -460,8 +426,8 @@ This option makes it possible to include comments inside complicated patterns. N or list respectively.</p> </item> - <tag><c>Type</c></tag> - <item><p>Optionally specifies how captured substrings are to be returned. If omitted, the default of <c>index</c> is used. The <c>Type</c> can be one of the following:</p> + <tag><c><anno>Type</anno></c></tag> + <item><p>Optionally specifies how captured substrings are to be returned. If omitted, the default of <c>index</c> is used. The <c><anno>Type</anno></c> can be one of the following:</p> <taglist> <tag><c>index</c></tag> <item>Return captured substrings as pairs of byte indexes into the subject string and length of the matching string in the subject (as if the subject string was flattened with <c>iolist_to_binary/1</c> or <c>unicode:characters_to_binary/2</c> prior to matching). Note that the <c>unicode</c> option results in <em>byte-oriented</em> indexes in a (possibly virtual) <em>UTF-8 encoded</em> binary. A byte index tuple <c>{0,2}</c> might therefore represent one or two characters when <c>unicode</c> is in effect. This might seem counter-intuitive, but has been deemed the most effective and useful way to way to do it. To return lists instead might result in simpler code if that is desired. This return type is the default.</item> @@ -478,7 +444,7 @@ This option makes it possible to include comments inside complicated patterns. N <code> "ABCabcdABC"</code> <p>the subpattern at index 2 won't match, as "abdd" is not present in the string, but the complete pattern matches (due to the alternative <c>a(..d)</c>. The subpattern at index 2 is therefore unassigned and the default return value will be:</p> <code> {match,[{0,10},{3,4},{-1,0},{4,3}]}</code> - <p>Setting the capture <c>Type</c> to <c>binary</c> would give the following:</p> + <p>Setting the capture <c><anno>Type</anno></c> to <c>binary</c> would give the following:</p> <code> {match,[<<"ABCabcdABC">>,<<"abcd">>,<<>>,<<"bcd">>]}</code> <p>where the empty binary (<c><<>></c>) represents the unassigned subpattern. In the <c>binary</c> case, some information about the matching is therefore lost, the <c><<>></c> might just as well be an empty string captured.</p> <p>If differentiation between empty matches and non existing subpatterns is necessary, use the <c>type</c> <c>index</c> @@ -524,8 +490,8 @@ This option makes it possible to include comments inside complicated patterns. N <p>The replacement string can contain the special character <c>&</c>, which inserts the whole matching expression in the - result, and the special sequence <c>\</c>N (where N is an - integer > 0), resulting in the subexpression number N will be + result, and the special sequence <c>\</c>N (where N is an integer > 0), + <c>\g</c>N or <c>\g{</c>N<c>}</c> resulting in the subexpression number N will be inserted in the result. If no subexpression with that number is generated by the regular expression, nothing is inserted.</p> <p>To insert an <c>&</c> or <c>\</c> in the result, precede it diff --git a/lib/stdlib/doc/src/sofs.xml b/lib/stdlib/doc/src/sofs.xml index 2e7768a1df..37c41501ae 100644 --- a/lib/stdlib/doc/src/sofs.xml +++ b/lib/stdlib/doc/src/sofs.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2011</year> + <year>2001</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -317,7 +317,7 @@ but is to be preferred since it makes it possible to handle this case even more efficiently. Examples of SetFuns:</p> <pre> -{sofs, union} +fun sofs:union/1 fun(S) -> sofs:partition(1, S) end {external, fun(A) -> A end} {external, fun({A,_,C}) -> {C,A} end} @@ -711,7 +711,7 @@ fun(S) -> sofs:partition(1, S) end argument.</p> <pre> 1> <input>F1 = sofs:from_term([{a,[[1,2],[2,3]]},{b,[[]]}]),</input> -<input>F2 = sofs:family_projection({sofs, union}, F1),</input> +<input>F2 = sofs:family_projection(fun sofs:union/1, F1),</input> <input>sofs:to_external(F2).</input> [{a,[1,2,3]},{b,[]}]</pre> </desc> @@ -821,7 +821,7 @@ fun(S) -> sofs:partition(1, S) end <input>sofs:to_external(F2).</input> [{a,[1,2,3]},{b,[]}]</pre> <p><c>family_union(F)</c> is equivalent to - <c>family_projection({sofs,union}, F)</c>.</p> + <c>family_projection(fun sofs:union/1, F)</c>.</p> </desc> </func> <func> @@ -1438,7 +1438,7 @@ true</pre> 1> <input>R1 = sofs:relation([{a,1},{b,2}]),</input> <input>R2 = sofs:relation([{x,1},{x,2},{y,3}]),</input> <input>S1 = sofs:from_sets([R1,R2]),</input> -<input>S2 = sofs:specification({sofs,is_a_function}, S1),</input> +<input>S2 = sofs:specification(fun sofs:is_a_function/1, S1),</input> <input>sofs:to_external(S2).</input> [[{a,1},{b,2}]]</pre> </desc> diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index 48867ffe72..549c871aed 100644 --- a/lib/stdlib/doc/src/string.xml +++ b/lib/stdlib/doc/src/string.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -255,18 +255,12 @@ sub_string("Hello World", 4, 8). </desc> </func> <func> - <name>to_float(String) -> {Float,Rest} | {error,Reason} </name> + <name name="to_float" arity="1"/> <fsummary>Returns a float whose text representation is the integers (ASCII values) in String.</fsummary> - <type> - <v>String = string()</v> - <v>Float = float()</v> - <v>Rest = string()</v> - <v>Reason = no_float | not_a_list</v> - </type> <desc> - <p>Argument <c>String</c> is expected to start with a valid text + <p>Argument <c><anno>String</anno></c> is expected to start with a valid text represented float (the digits being ASCII values). Remaining characters - in the string after the float are returned in <c>Rest</c>.</p> + in the string after the float are returned in <c><anno>Rest</anno></c>.</p> <p>Example:</p> <code type="none"> > {F1,Fs} = string:to_float("1.0-1.0e-1"), @@ -280,18 +274,12 @@ sub_string("Hello World", 4, 8). </desc> </func> <func> - <name>to_integer(String) -> {Int,Rest} | {error,Reason} </name> + <name name="to_integer" arity="1"/> <fsummary>Returns an integer whose text representation is the integers (ASCII values) in String.</fsummary> - <type> - <v>String = string()</v> - <v>Int = integer()</v> - <v>Rest = string()</v> - <v>Reason = no_integer | not_a_list</v> - </type> <desc> - <p>Argument <c>String</c> is expected to start with a valid text + <p>Argument <c><anno>String</anno></c> is expected to start with a valid text represented integer (the digits being ASCII values). Remaining characters - in the string after the integer are returned in <c>Rest</c>.</p> + in the string after the integer are returned in <c><anno>Rest</anno></c>.</p> <p>Example:</p> <code type="none"> > {I1,Is} = string:to_integer("33+22"), diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index 33a7f5bb6a..f9a5e245b4 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -55,7 +55,8 @@ monitoring its child processes. The basic idea of a supervisor is that it should keep its child processes alive by restarting them when necessary.</p> - <p>The children of a supervisor is defined as a list of <em>child specifications</em>. When the supervisor is started, the child + <p>The children of a supervisor is defined as a list of + <em>child specifications</em>. When the supervisor is started, the child processes are started in order from left to right according to this list. When the supervisor terminates, it first terminates its child processes in reversed start order, from right to left.</p> @@ -100,7 +101,8 @@ </item> </list> <p>To prevent a supervisor from getting into an infinite loop of - child process terminations and restarts, a <em>maximum restart frequency</em> is defined using two integer values <c>MaxR</c> + child process terminations and restarts, a <em>maximum restart frequency</em> + is defined using two integer values <c>MaxR</c> and <c>MaxT</c>. If more than <c>MaxR</c> restarts occur within <c>MaxT</c> seconds, the supervisor terminates all child processes and then itself. @@ -114,7 +116,7 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} M = F = atom() A = [term()] Restart = permanent | transient | temporary - Shutdown = brutal_kill | int()>=0 | infinity + Shutdown = brutal_kill | int()>0 | infinity Type = worker | supervisor Modules = [Module] | dynamic Module = atom()</pre> @@ -197,7 +199,8 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} the callback module, if the child process is a supervisor, gen_server or gen_fsm. If the child process is an event manager (gen_event) with a dynamic set of callback modules, - <c>Modules</c> should be <c>dynamic</c>. See <em>OTP Design Principles</em> for more information about release handling.</p> + <c>Modules</c> should be <c>dynamic</c>. See <em>OTP Design Principles</em> + for more information about release handling.</p> </item> <item> <p>Internally, the supervisor also keeps track of the pid @@ -264,8 +267,14 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} <p>If <c><anno>SupName</anno>={local,Name}</c> the supervisor is registered locally as <c>Name</c> using <c>register/2</c>. If <c><anno>SupName</anno>={global,Name}</c> the supervisor is registered - globally as <c>Name</c> using <c>global:register_name/2</c>. - If no name is provided, the supervisor is not registered.</p> + globally as <c>Name</c> using <c>global:register_name/2</c>. If + <c><anno>SupName</anno>={via,Module,Name}</c> the supervisor + is registered as <c>Name</c> using the registry represented by + <c>Module</c>. The <c>Module</c> callback should export the functions + <c>register_name/2</c>, <c>unregister_name/1</c> and <c>send/2</c>, + which should behave like the corresponding functions in <c>global</c>. + Thus, <c>{via,global,Name}</c> is a valid reference.</p> + <p>If no name is provided, the supervisor is not registered.</p> <p><c><anno>Module</anno></c> is the name of the callback module.</p> <p><c><anno>Args</anno></c> is an arbitrary term which is passed as the argument to <c><anno>Module</anno>:init/1</c>.</p> @@ -308,6 +317,8 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} registered at another node, or</item> <item><c>{global,Name}</c>, if the supervisor is globally registered.</item> + <item><c>{via,Module,Name}</c>, if the supervisor is registered + through an alternative process registry.</item> </list> <p><c><anno>ChildSpec</anno></c> should be a valid child specification (unless the supervisor is a <c>simple_one_for_one</c> @@ -391,10 +402,11 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} <c>SupRef</c>.</p> <p>If successful, the function returns <c>ok</c>. If the child specification identified by <c><anno>Id</anno></c> exists but - the corresponding child process is running, the function - returns <c>{error,running}</c>. If the child specification - identified by <c><anno>Id</anno></c> does not exist, the function returns - <c>{error,not_found}</c>.</p> + the corresponding child process is running or about to be restarted, + the function returns <c>{error,running}</c> or + <c>{error,restarting}</c> respectively. If the child specification + identified by <c><anno>Id</anno></c> does not exist, the function + returns <c>{error,not_found}</c>.</p> </desc> </func> <func> @@ -434,7 +446,8 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} </func> <func> <name name="which_children" arity="1"/> - <fsummary>Return information about all children specifications and child processes belonging to a supervisor.</fsummary> + <fsummary>Return information about all children specifications and + child processes belonging to a supervisor.</fsummary> <desc> <p>Returns a newly created list with information about all child specifications and child processes belonging to @@ -454,7 +467,8 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} </item> <item> <p><c><anno>Child</anno></c> - the pid of the corresponding child - process, or <c>undefined</c> if there is no such process.</p> + process, the atom <c>restarting</c> if the process is about to be + restarted or <c>undefined</c> if there is no such process.</p> </item> <item> <p><c><anno>Type</anno></c> - as defined in the child specification.</p> @@ -467,7 +481,8 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} </func> <func> <name name="count_children" arity="1"/> - <fsummary>Return counts for the number of childspecs, active children, supervisors and workers.</fsummary> + <fsummary>Return counts for the number of childspecs, active children, + supervisors and workers.</fsummary> <desc> <p>Returns a property list (see <c>proplists</c>) containing the counts for each of the following elements of the supervisor's @@ -517,7 +532,8 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} <v>Args = term()</v> <v>Result = {ok,{{RestartStrategy,MaxR,MaxT},[ChildSpec]}} | ignore</v> <v> RestartStrategy = <seealso marker="#type-strategy">strategy()</seealso></v> - <v> MaxR = MaxT = integer()>=0</v> + <v> MaxR = integer()>=0</v> + <v> MaxT = integer()>0</v> <v> ChildSpec = <seealso marker="#type-child_spec">child_spec()</seealso></v> </type> <desc> diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml index c1a5e7947f..f6712d6c1d 100644 --- a/lib/stdlib/doc/src/supervisor_bridge.xml +++ b/lib/stdlib/doc/src/supervisor_bridge.xml @@ -63,6 +63,13 @@ If <c><anno>SupBridgeName</anno>={global,<anno>Name</anno>}</c> the supervisor_bridge is registered globally as <c><anno>Name</anno></c> using <c>global:register_name/2</c>. + If <c><anno>SupBridgeName</anno>={via,<anno>Module</anno>,<anno>Name</anno>}</c> the supervisor_bridge is + registered as <c><anno>Name</anno></c> using a registry represented + by <anno>Module</anno>. The <c>Module</c> callback should export + the functions <c>register_name/2</c>, <c>unregister_name/1</c> + and <c>send/2</c>, which should behave like the + corresponding functions in <c>global</c>. Thus, + <c>{via,global,GlobalName}</c> is a valid reference. If no name is provided, the supervisor_bridge is not registered. If there already exists a process with the specified <c><anno>SupBridgeName</anno></c> the function returns diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index 1001ebbae4..1f6cbaccd7 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2012</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -130,34 +130,24 @@ </desc> </func> <func> - <name>characters_to_list(Data, InEncoding) -> Result</name> + <name name="characters_to_list" arity="2"/> <fsummary>Convert a collection of characters to list of Unicode characters</fsummary> - <type> - <v>Data = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>Result = list() | {error, list(), RestData} | {incomplete, list(), binary()}</v> - <v>RestData = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>InEncoding = <seealso marker="#type-encoding">encoding()</seealso></v> - </type> <desc> <p>This function converts a possibly deep list of integers and binaries into a list of integers representing unicode characters. The binaries in the input may have characters encoded as latin1 (0 - 255, one character per byte), in which - case the <c>InEncoding</c> parameter should be given as + case the <c><anno>InEncoding</anno></c> parameter should be given as <c>latin1</c>, or have characters encoded as one of the - UTF-encodings, which is given as the <c>InEncoding</c> - parameter. Only when the <c>InEncoding</c> is one of the UTF + UTF-encodings, which is given as the <c><anno>InEncoding</anno></c> + parameter. Only when the <c><anno>InEncoding</anno></c> is one of the UTF encodings, integers in the list are allowed to be grater than 255.</p> - <p>If <c>InEncoding</c> is <c>latin1</c>, the <c>Data</c> parameter + <p>If <c><anno>InEncoding</anno></c> is <c>latin1</c>, the <c><anno>Data</anno></c> parameter corresponds to the <c>iodata()</c> type, but for <c>unicode</c>, - the <c>Data</c> parameter can contain integers greater than 255 + the <c><anno>Data</anno></c> parameter can contain integers greater than 255 (unicode characters beyond the iso-latin-1 range), which would make it invalid as <c>iodata()</c>.</p> @@ -188,16 +178,16 @@ depth as the original data. The error occurs when traversing the list and whatever's left to decode is simply returned as is.</p> - <p>However, if the input <c>Data</c> is a pure binary, the third + <p>However, if the input <c><anno>Data</anno></c> is a pure binary, the third part of the error tuple is guaranteed to be a binary as well.</p> <p>Errors occur for the following reasons:</p> <list type="bulleted"> - <item>Integers out of range - If <c>InEncoding</c> is + <item>Integers out of range - If <c><anno>InEncoding</anno></c> is <c>latin1</c>, an error occurs whenever an integer greater - than 255 is found in the lists. If <c>InEncoding</c> is + than 255 is found in the lists. If <c><anno>InEncoding</anno></c> is of a Unicode type, an error occurs whenever an integer <list type="bulleted"> <item>greater than <c>16#10FFFF</c> @@ -208,7 +198,7 @@ is found. </item> - <item>UTF encoding incorrect - If <c>InEncoding</c> is + <item>UTF encoding incorrect - If <c><anno>InEncoding</anno></c> is one of the UTF types, the bytes in any binaries have to be valid in that encoding. Errors can occur for various reasons, including "pure" decoding errors @@ -220,7 +210,7 @@ number should have been encoded in fewer bytes. The case of a truncated UTF is handled specially, see the paragraph about incomplete binaries below. If - <c>InEncoding</c> is <c>latin1</c>, binaries are always valid + <c><anno>InEncoding</anno></c> is <c>latin1</c>, binaries are always valid as long as they contain whole bytes, as each byte falls into the valid iso-latin-1 range.</item> @@ -238,7 +228,7 @@ the first part of a (so far) valid UTF character.</p> <p>If one UTF characters is split over two consecutive - binaries in the <c>Data</c>, the conversion succeeds. This means + binaries in the <c><anno>Data</anno></c>, the conversion succeeds. This means that a character can be decoded from a range of binaries as long as the whole range is given as input without errors occurring. Example:</p> @@ -274,21 +264,11 @@ </desc> </func> <func> - <name>characters_to_binary(Data,InEncoding) -> Result</name> + <name name="characters_to_binary" arity="2"/> <fsummary>Convert a collection of characters to an UTF-8 binary</fsummary> - <type> - <v>Data = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>Result = binary() | {error, binary(), RestData} | {incomplete, binary(), binary()}</v> - <v>RestData = <seealso marker="#type-latin1_chardata">latin1_chardata()</seealso> - | <seealso marker="#type-chardata">chardata()</seealso> - | <seealso marker="#type-external_chardata">external_chardata()</seealso></v> - <v>InEncoding = <seealso marker="#type-encoding">encoding()</seealso></v> - </type> <desc> - <p>Same as characters_to_binary(Data, InEncoding, unicode).</p> + <p>Same as characters_to_binary(<anno>Data</anno>, <anno>InEncoding</anno>, unicode).</p> </desc> </func> <func> diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index a7e010a05f..bbcd49a934 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1999</year> - <year>2011</year> + <year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -53,7 +53,7 @@ <item>Basically the same as UTF-32, but without some Unicode semantics, defined by IEEE and has little use as a separate encoding standard. For all normal (and possibly abnormal) usages, UTF-32 and UCS-4 are interchangeable.</item> </taglist> <p>Certain ranges of characters are left unused and certain ranges are even deemed invalid. The most notable invalid range is 16#D800 - 16#DFFF, as the UTF-16 encoding does not allow for encoding of these numbers. It can be speculated that the UTF-16 encoding standard was, from the beginning, expected to be able to hold all Unicode characters in one 16-bit entity, but then had to be extended, leaving a hole in the Unicode range to cope with backward compatibility.</p> -<p>Additionally, the codepoint 16#FEFF is used for byte order marks (BOM's) and use of that character is not encouraged in other contexts than that. It actually is valid though, as the character "ZWNBS" (Zero Width Non Breaking Space). BOM's are used to identify encodings and byte order for programs where such parameters are not known in advance. Byte order marks are more seldom used than one could expect, put their use is becoming more widely spread as they provide the means for programs to make educated guesses about the Unicode format of a certain file.</p> +<p>Additionally, the codepoint 16#FEFF is used for byte order marks (BOM's) and use of that character is not encouraged in other contexts than that. It actually is valid though, as the character "ZWNBS" (Zero Width Non Breaking Space). BOM's are used to identify encodings and byte order for programs where such parameters are not known in advance. Byte order marks are more seldom used than one could expect, but their use is becoming more widely spread as they provide the means for programs to make educated guesses about the Unicode format of a certain file.</p> </section> <section> <title>Standard Unicode representation in Erlang</title> @@ -210,6 +210,12 @@ Eshell V5.7 (abort with ^G) </section> </section> <section> +<title>Unicode in environment variables and parameters</title> +<p>Environment variables and their interpretation is handled much in the same way as file names. If Unicode file names are enabled, environment variables as well as parameters to the Erlang VM are expected to be in Unicode.</p> +<p>If Unicode file names are enabled, the calls to <seealso marker="kernel:os#getenv/0"><c>os:getenv/0</c></seealso>, <seealso marker="kernel:os#getenv/1"><c>os:getenv/1</c></seealso> and <seealso marker="kernel:os#putenv/2"><c>os:putenv/2</c></seealso> will handle Unicode strings. On Unix-like platforms, the built-in functions will translate environment variables in UTF-8 to/from Unicode strings, possibly with codepoints > 255. On Windows the Unicode versions of the environment system API will be used, also allowing for codepoints > 255.</p> +<p>On Unix-like operating systems, parameters are expected to be UTF-8 without translation if Unicode file names are enabled.</p> +</section> +<section> <title>Unicode-aware modules</title> <p>Most of the modules in Erlang/OTP are of course Unicode-unaware in the sense that they have no notion of Unicode and really shouldn't have. Typically they handle non-textual or byte-oriented data (like <c>gen_tcp</c> etc).</p> <p>Modules that actually handle textual data (like <c>io_lib</c>, <c>string</c> etc) are sometimes subject to conversion or extension to be able to handle Unicode characters.</p> |