diff options
Diffstat (limited to 'lib/stdlib/doc/src')
72 files changed, 6273 insertions, 3169 deletions
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index 26602764a6..4541b4a463 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2016. All Rights Reserved. +# Copyright Ericsson AB 1997-2018. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -71,7 +71,6 @@ XML_REF3_FILES = \ gen_statem.xml \ io.xml \ io_lib.xml \ - lib.xml \ lists.xml \ log_mf_h.xml \ maps.xml \ @@ -98,13 +97,15 @@ XML_REF3_FILES = \ sys.xml \ timer.xml \ unicode.xml \ + uri_string.xml \ win32reg.xml \ zip.xml XML_REF6_FILES = stdlib_app.xml -XML_PART_FILES = part.xml part_notes.xml part_notes_history.xml -XML_CHAPTER_FILES = io_protocol.xml unicode_usage.xml notes.xml notes_history.xml assert_hrl.xml +XML_PART_FILES = part.xml +XML_CHAPTER_FILES = introduction.xml io_protocol.xml unicode_usage.xml \ + notes.xml assert_hrl.xml BOOK_FILES = book.xml @@ -131,9 +132,9 @@ SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml) TOP_SPECS_FILE = specs.xml # ---------------------------------------------------- -# FLAGS +# FLAGS # ---------------------------------------------------- -XML_FLAGS += +XML_FLAGS += SPECS_FLAGS = -I../../include -I../../../kernel/include @@ -150,23 +151,24 @@ html: $(HTML_REF_MAN_FILE) man: $(MAN3_FILES) $(MAN6_FILES) -debug opt: +debug opt: clean clean_docs: rm -rf $(HTMLDIR)/* + rm -rf $(XMLDIR) rm -f $(MAN3DIR)/* rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f $(SPECDIR)/* - rm -f errs core *~ + rm -f errs core *~ $(SPECDIR)/specs_erl_id_trans.xml: - escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ + $(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \ -o$(dir $@) -module erl_id_trans # ---------------------------------------------------- # Release Target -# ---------------------------------------------------- +# ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml index db0ab42372..aa1577a067 100644 --- a/lib/stdlib/doc/src/array.xml +++ b/lib/stdlib/doc/src/array.xml @@ -32,7 +32,7 @@ <rev>A</rev> <file>array.xml</file> </header> - <module>array</module> + <module since="">array</module> <modulesummary>Functional, extendible arrays.</modulesummary> <description> <p>Functional, extendible arrays. Arrays can have fixed size, or can grow @@ -137,7 +137,7 @@ A3 = array:fix(A2).</pre> <funcs> <func> - <name name="default" arity="1"/> + <name name="default" arity="1" since=""/> <fsummary>Get the value used for uninitialized entries.</fsummary> <desc><marker id="default-1"/> <p>Gets the value used for uninitialized entries.</p> @@ -146,7 +146,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="fix" arity="1"/> + <name name="fix" arity="1" since=""/> <fsummary>Fix the array size.</fsummary> <desc><marker id="fix-1"/> <p>Fixes the array size. This prevents it from growing automatically @@ -157,7 +157,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="foldl" arity="3"/> + <name name="foldl" arity="3" since=""/> <fsummary>Fold the array elements using the specified function and initial accumulator value.</fsummary> <desc><marker id="foldl-3"/> @@ -172,7 +172,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="foldr" arity="3"/> + <name name="foldr" arity="3" since=""/> <fsummary>Fold the array elements right-to-left using the specified function and initial accumulator value.</fsummary> <desc><marker id="foldr-3"/> @@ -186,7 +186,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since=""/> <fsummary>Equivalent to <c>from_list(List, undefined)</c>.</fsummary> <desc><marker id="from_list-1"/> <p>Equivalent to @@ -195,7 +195,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="from_list" arity="2"/> + <name name="from_list" arity="2" since=""/> <fsummary>Convert a list to an extendible array.</fsummary> <desc><marker id="from_list-2"/> <p>Converts a list to an extendible array. <c><anno>Default</anno></c> @@ -208,7 +208,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="from_orddict" arity="1"/> + <name name="from_orddict" arity="1" since=""/> <fsummary>Equivalent to <c>from_orddict(Orddict, undefined)</c>. </fsummary> <desc><marker id="from_orddict-1"/> @@ -218,7 +218,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="from_orddict" arity="2"/> + <name name="from_orddict" arity="2" since=""/> <fsummary>Convert an ordered list of pairs <c>{Index, Value}</c> to a corresponding extendible array.</fsummary> <desc><marker id="from_orddict-2"/> @@ -234,7 +234,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="get" arity="2"/> + <name name="get" arity="2" since=""/> <fsummary>Get the value of entry <c>I</c>.</fsummary> <desc><marker id="get-2"/> <p>Gets the value of entry <c><anno>I</anno></c>. If @@ -249,7 +249,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="is_array" arity="1"/> + <name name="is_array" arity="1" since=""/> <fsummary>Returns <c>true</c> if <c>X</c> is an array, otherwise <c>false</c>.</fsummary> <desc><marker id="is_array-1"/> @@ -261,7 +261,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="is_fix" arity="1"/> + <name name="is_fix" arity="1" since=""/> <fsummary>Check if the array has fixed size.</fsummary> <desc><marker id="is_fix-1"/> <p>Checks if the array has fixed size. Returns <c>true</c> if the array @@ -271,7 +271,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="map" arity="2"/> + <name name="map" arity="2" since=""/> <fsummary>Map the specified function onto each array element.</fsummary> <desc><marker id="map-2"/> <p>Maps the specified function onto each array element. The elements are @@ -285,7 +285,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Create a new, extendible array with initial size zero. </fsummary> <desc><marker id="new-0"/> @@ -296,7 +296,7 @@ A3 = array:fix(A2).</pre> </func> <func> - <name name="new" arity="1"/> + <name name="new" arity="1" since=""/> <fsummary>Create a new array according to the specified options. </fsummary> <desc><marker id="new-1"/> @@ -346,7 +346,7 @@ array:new([{size,10},{fixed,false},{default,-1}])</pre> </func> <func> - <name name="new" arity="2"/> + <name name="new" arity="2" since=""/> <fsummary>Create a new array according to the specified size and options. </fsummary> <desc><marker id="new-2"/> @@ -370,7 +370,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="relax" arity="1"/> + <name name="relax" arity="1" since=""/> <fsummary>Make the array resizable.</fsummary> <desc><marker id="relax-1"/> <p>Makes the array resizable. (Reverses the effects of @@ -380,7 +380,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="reset" arity="2"/> + <name name="reset" arity="2" since=""/> <fsummary>Reset entry <c>I</c> to the default value for the array. </fsummary> <desc><marker id="reset-2"/> @@ -399,7 +399,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="resize" arity="1"/> + <name name="resize" arity="1" since=""/> <fsummary>Change the array size to that reported by <c>sparse_size/1</c>. </fsummary> <desc><marker id="resize-1"/> @@ -413,7 +413,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="resize" arity="2"/> + <name name="resize" arity="2" since=""/> <fsummary>Change the array size.</fsummary> <desc><marker id="resize-2"/> <p>Change the array size. If <c><anno>Size</anno></c> is not a @@ -424,7 +424,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="set" arity="3"/> + <name name="set" arity="3" since=""/> <fsummary>Set entry <c>I</c> of the array to <c>Value</c>.</fsummary> <desc><marker id="set-3"/> <p>Sets entry <c><anno>I</anno></c> of the array to @@ -441,7 +441,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Get the number of entries in the array.</fsummary> <desc><marker id="size-1"/> <p>Gets the number of entries in the array. Entries are numbered from @@ -454,7 +454,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="sparse_foldl" arity="3"/> + <name name="sparse_foldl" arity="3" since=""/> <fsummary>Fold the array elements using the specified function and initial accumulator value, skipping default-valued entries.</fsummary> <desc><marker id="sparse_foldl-3"/> @@ -469,7 +469,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="sparse_foldr" arity="3"/> + <name name="sparse_foldr" arity="3" since=""/> <fsummary>Fold the array elements right-to-left using the specified function and initial accumulator value, skipping default-valued entries.</fsummary> @@ -485,7 +485,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="sparse_map" arity="2"/> + <name name="sparse_map" arity="2" since=""/> <fsummary>Map the specified function onto each array element, skipping default-valued entries.</fsummary> <desc><marker id="sparse_map-2"/> @@ -498,7 +498,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="sparse_size" arity="1"/> + <name name="sparse_size" arity="1" since=""/> <fsummary>Get the number of entries in the array up until the last non-default-valued entry.</fsummary> <desc><marker id="sparse_size-1"/> @@ -512,7 +512,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="sparse_to_list" arity="1"/> + <name name="sparse_to_list" arity="1" since=""/> <fsummary>Convert the array to a list, skipping default-valued entries. </fsummary> <desc><marker id="sparse_to_list-1"/> @@ -522,7 +522,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="sparse_to_orddict" arity="1"/> + <name name="sparse_to_orddict" arity="1" since=""/> <fsummary>Convert the array to an ordered list of pairs <c>{Index, Value}</c>, skipping default-valued entries.</fsummary> <desc><marker id="sparse_to_orddict-1"/> @@ -534,7 +534,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert the array to a list.</fsummary> <desc><marker id="to_list-1"/> <p>Converts the array to a list.</p> @@ -545,7 +545,7 @@ array:new(100, {default,0})</pre> </func> <func> - <name name="to_orddict" arity="1"/> + <name name="to_orddict" arity="1" since=""/> <fsummary>Convert the array to an ordered list of pairs <c>{Index, Value}</c>.</fsummary> <desc><marker id="to_orddict-1"/> diff --git a/lib/stdlib/doc/src/assert_hrl.xml b/lib/stdlib/doc/src/assert_hrl.xml index cb91b1f126..fb27954235 100644 --- a/lib/stdlib/doc/src/assert_hrl.xml +++ b/lib/stdlib/doc/src/assert_hrl.xml @@ -4,7 +4,7 @@ <fileref> <header> <copyright> - <year>2012</year><year>2016</year> + <year>2012</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <file>assert.hrl.xml</file> + <file>assert.hrl</file> <filesummary>Assert macros.</filesummary> <description> <p>The include file <c>assert.hrl</c> provides macros for inserting @@ -46,28 +46,36 @@ is the macro name, for example, <c>assertEqual</c>. <c>Info</c> is a list of tagged values, such as <c>[{module, M}, {line, L}, ...]</c>, which gives more information about the location and cause of the exception. All - entries in the <c>Info</c> list are optional; do not rely programatically + entries in the <c>Info</c> list are optional; do not rely programmatically on any of them being present.</p> + <p>Each assert macro has a corresponding version with an extra argument, + for adding comments to assertions. These can for example be printed as + part of error reports, to clarify the meaning of the check that + failed. For example, <c>?assertEqual(0, fib(0), "Fibonacci is defined + for zero")</c>. The comment text can be any character data (string, + UTF8-binary, or deep list of such data), and will be included in the + error term as <c>{comment, Text}</c>.</p> + <p>If the macro <c>NOASSERT</c> is defined when <c>assert.hrl</c> is read by the compiler, the macros are defined as equivalent to the atom - <c>ok</c>. The test is not performed and there is no cost at runtime.</p> + <c>ok</c>. The test will not be performed and there is no cost at runtime.</p> <p>For example, using <c>erlc</c> to compile your modules, the following - disable all assertions:</p> + disables all assertions:</p> <code type="none"> erlc -DNOASSERT=true *.erl</code> - <p>The value of <c>NOASSERT</c> does not matter, only the fact that it is - defined.</p> + <p>(The value of <c>NOASSERT</c> does not matter, only the fact that it is + defined.)</p> <p>A few other macros also have effect on the enabling or disabling of assertions:</p> <list type="bulleted"> - <item><p>If <c>NODEBUG</c> is defined, it implies <c>NOASSERT</c>, unless - <c>DEBUG</c> is also defined, which is assumed to take precedence.</p> + <item><p>If <c>NODEBUG</c> is defined, it implies <c>NOASSERT</c> (unless + <c>DEBUG</c> is also defined, which overrides <c>NODEBUG</c>).</p> </item> <item><p>If <c>ASSERT</c> is defined, it overrides <c>NOASSERT</c>, that is, the assertions remain enabled.</p></item> @@ -84,16 +92,22 @@ erlc -DNOASSERT=true *.erl</code> <title>Macros</title> <taglist> <tag><c>assert(BoolExpr)</c></tag> + <item></item> + <tag><c>assert(BoolExpr, Comment)</c></tag> <item> <p>Tests that <c>BoolExpr</c> completes normally returning <c>true</c>.</p> </item> <tag><c>assertNot(BoolExpr)</c></tag> + <item></item> + <tag><c>assertNot(BoolExpr, Comment)</c></tag> <item> <p>Tests that <c>BoolExpr</c> completes normally returning <c>false</c>.</p> </item> <tag><c>assertMatch(GuardedPattern, Expr)</c></tag> + <item></item> + <tag><c>assertMatch(GuardedPattern, Expr, Comment)</c></tag> <item> <p>Tests that <c>Expr</c> completes normally yielding a value that matches <c>GuardedPattern</c>, for example:</p> @@ -104,6 +118,8 @@ erlc -DNOASSERT=true *.erl</code> ?assertMatch({bork, X} when X > 0, f())</code> </item> <tag><c>assertNotMatch(GuardedPattern, Expr)</c></tag> + <item></item> + <tag><c>assertNotMatch(GuardedPattern, Expr, Comment)</c></tag> <item> <p>Tests that <c>Expr</c> completes normally yielding a value that does not match <c>GuardedPattern</c>.</p> @@ -111,16 +127,22 @@ erlc -DNOASSERT=true *.erl</code> <c>when</c> part.</p> </item> <tag><c>assertEqual(ExpectedValue, Expr)</c></tag> + <item></item> + <tag><c>assertEqual(ExpectedValue, Expr, Comment)</c></tag> <item> <p>Tests that <c>Expr</c> completes normally yielding a value that is exactly equal to <c>ExpectedValue</c>.</p> </item> <tag><c>assertNotEqual(ExpectedValue, Expr)</c></tag> + <item></item> + <tag><c>assertNotEqual(ExpectedValue, Expr, Comment)</c></tag> <item> <p>Tests that <c>Expr</c> completes normally yielding a value that is not exactly equal to <c>ExpectedValue</c>.</p> </item> <tag><c>assertException(Class, Term, Expr)</c></tag> + <item></item> + <tag><c>assertException(Class, Term, Expr, Comment)</c></tag> <item> <p>Tests that <c>Expr</c> completes abnormally with an exception of type <c>Class</c> and with the associated <c>Term</c>. The assertion fails @@ -130,6 +152,8 @@ erlc -DNOASSERT=true *.erl</code> patterns, as in <c>assertMatch</c>.</p> </item> <tag><c>assertNotException(Class, Term, Expr)</c></tag> + <item></item> + <tag><c>assertNotException(Class, Term, Expr, Comment)</c></tag> <item> <p>Tests that <c>Expr</c> does not evaluate abnormally with an exception of type <c>Class</c> and with the associated <c>Term</c>. @@ -139,14 +163,20 @@ erlc -DNOASSERT=true *.erl</code> be guarded patterns.</p> </item> <tag><c>assertError(Term, Expr)</c></tag> + <item></item> + <tag><c>assertError(Term, Expr, Comment)</c></tag> <item> <p>Equivalent to <c>assertException(error, Term, Expr)</c></p> </item> <tag><c>assertExit(Term, Expr)</c></tag> + <item></item> + <tag><c>assertExit(Term, Expr, Comment)</c></tag> <item> <p>Equivalent to <c>assertException(exit, Term, Expr)</c></p> </item> <tag><c>assertThrow(Term, Expr)</c></tag> + <item></item> + <tag><c>assertThrow(Term, Expr, Comment)</c></tag> <item> <p>Equivalent to <c>assertException(throw, Term, Expr)</c></p> </item> diff --git a/lib/stdlib/doc/src/base64.xml b/lib/stdlib/doc/src/base64.xml index cfa1ecc006..479072ba4f 100644 --- a/lib/stdlib/doc/src/base64.xml +++ b/lib/stdlib/doc/src/base64.xml @@ -29,7 +29,7 @@ <rev></rev> <file>base64.xml</file> </header> - <module>base64</module> + <module since="">base64</module> <modulesummary>Provides base64 encode and decode, see RFC 2045.</modulesummary> <description> @@ -51,10 +51,10 @@ <funcs> <func> - <name name="decode" arity="1"/> - <name name="decode_to_string" arity="1"/> - <name name="mime_decode" arity="1"/> - <name name="mime_decode_to_string" arity="1"/> + <name name="decode" arity="1" since=""/> + <name name="decode_to_string" arity="1" since=""/> + <name name="mime_decode" arity="1" since=""/> + <name name="mime_decode_to_string" arity="1" since=""/> <fsummary>Decode a base64 encoded string to data.</fsummary> <type variable="Base64" name_i="1"/> <type variable="Data" name_i="1"/> @@ -69,8 +69,8 @@ </func> <func> - <name name="encode" arity="1"/> - <name name="encode_to_string" arity="1"/> + <name name="encode" arity="1" since=""/> + <name name="encode_to_string" arity="1" since=""/> <fsummary>Encode data into base64.</fsummary> <type variable="Data"/> <type variable="Base64" name_i="1"/> diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index d5ec90b060..8bb4cf9101 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2016</year> + <year>2000</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date>1999-10-30</date> <rev>PA1</rev> </header> - <module>beam_lib</module> + <module since="">beam_lib</module> <modulesummary>An interface to the BEAM file format.</modulesummary> <description> <p>This module provides an interface to files created by @@ -42,10 +42,10 @@ and the corresponding identifiers are as follows:</p> <list type="bulleted"> - <item><c>abstract_code ("Abst")</c></item> <item><c>atoms ("Atom")</c></item> <item><c>attributes ("Attr")</c></item> <item><c>compile_info ("CInf")</c></item> + <item><c>debug_info ("Dbgi")</c></item> <item><c>exports ("ExpT")</c></item> <item><c>imports ("ImpT")</c></item> <item><c>indexed_imports ("ImpT")</c></item> @@ -60,9 +60,8 @@ <title>Debug Information/Abstract Code</title> <p>Option <c>debug_info</c> can be specified to the Compiler (see <seealso marker="compiler:compile#debug_info"><c>compile(3)</c></seealso>) - to have debug information in the form of abstract code (see section - <seealso marker="erts:absform">The Abstract Format</seealso> in the - ERTS User's Guide) stored in the <c>abstract_code</c> chunk. + to have debug information, such as <seealso marker="erts:absform">Erlang + Abstract Format</seealso>, stored in the <c>debug_info</c> chunk. Tools such as Debugger and Xref require the debug information to be included.</p> @@ -79,7 +78,7 @@ <section> <title>Reconstruct Source Code</title> - <p>The following example shows how to reconstruct source code from + <p>The following example shows how to reconstruct Erlang source code from the debug information in a BEAM file <c>Beam</c>:</p> <code type="none"> @@ -117,7 +116,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <list type="ordered"> <item> - <p>Use Compiler option <c>{debug_info,Key}</c>, see + <p>Use Compiler option <c>{debug_info_key,Key}</c>, see <seealso marker="compiler:compile#debug_info_key"><c>compile(3)</c></seealso> and function <seealso marker="#crypto_key_fun/1"><c>crypto_key_fun/1</c></seealso> @@ -181,8 +180,8 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <name name="beam"/> <desc> <p>Each of the functions described below accept either the - module name, the filename, or a binary containing the BEAM - module.</p> + filename (as a string) or a binary containing the BEAM + module.</p> </desc> </datatype> <datatype> @@ -198,18 +197,40 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <datatype> <name name="chunkid"/> <desc> - <p>"Abst" | "Attr" | "CInf" | "ExpT" | "ImpT" | "LocT" | "Atom"</p> + <p>"Attr" | "CInf" | "Dbgi" | "ExpT" | "ImpT" | "LocT" | "AtU8"</p> </desc> </datatype> <datatype> <name name="dataB"/> </datatype> <datatype> + <name name="debug_info"/> + <desc> + <p>The format stored in the <c>debug_info</c> chunk. + To retrieve particular code representation from the backend, + <c>Backend:debug_info(Format, Module, Data, Opts)</c> must be + invoked. <c>Format</c> is an atom, such as <c>erlang_v1</c> for + the Erlang Abstract Format or <c>core_v1</c> for Core Erlang. + <c>Module</c> is the module represented by the beam file and + <c>Data</c> is the value stored in the debug info chunk. + <c>Opts</c> is any list of values supported by the <c>Backend</c>. + <c>Backend:debug_info/4</c> must return <c>{ok, Code}</c> or + <c>{error, Term}</c>.</p> + + <p>Developers must always invoke the <c>debug_info/4</c> function + and never rely on the <c>Data</c> stored in the <c>debug_info</c> + chunk, as it is opaque and may change at any moment. <c>no_debug_info</c> + means that chunk <c>"Dbgi"</c> is present, but empty.</p> + </desc> + </datatype> + <datatype> <name name="abst_code"/> <desc> <p>It is not checked that the forms conform to the abstract format indicated by <c><anno>AbstVersion</anno></c>. <c>no_abstract_code</c> means that chunk <c>"Abst"</c> is present, but empty.</p> + <p>For modules compiled with OTP 20 onwards, the <c>abst_code</c> chunk + is automatically computed from the <c>debug_info</c> chunk.</p> </desc> </datatype> <datatype> @@ -246,7 +267,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <funcs> <func> - <name name="all_chunks" arity="1"/> + <name name="all_chunks" arity="1" since="OTP 18.2"/> <fsummary>Read all chunks from a BEAM file or binary</fsummary> <desc> <p>Reads chunk data for all chunks.</p> @@ -254,7 +275,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> </func> <func> - <name name="build_module" arity="1"/> + <name name="build_module" arity="1" since="OTP 18.2"/> <fsummary>Create a BEAM module from a list of chunks.</fsummary> <desc> <p>Builds a BEAM module (as a binary) from a list of chunks.</p> @@ -262,7 +283,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> </func> <func> - <name name="chunks" arity="2"/> + <name name="chunks" arity="2" since=""/> <fsummary>Read selected chunks from a BEAM file or binary.</fsummary> <desc> <p>Reads chunk data for selected chunks references. The order of @@ -272,7 +293,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> </func> <func> - <name name="chunks" arity="3"/> + <name name="chunks" arity="3" since=""/> <fsummary>Read selected chunks from a BEAM file or binary.</fsummary> <desc> <p>Reads chunk data for selected chunks references. The order of @@ -291,7 +312,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> </func> <func> - <name name="clear_crypto_key_fun" arity="0"/> + <name name="clear_crypto_key_fun" arity="0" since=""/> <fsummary>Unregister the current crypto key fun.</fsummary> <desc> <p>Unregisters the crypto key fun and terminates the process @@ -306,7 +327,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> </func> <func> - <name name="cmp" arity="2"/> + <name name="cmp" arity="2" since=""/> <fsummary>Compare two BEAM files.</fsummary> <type name="cmp_rsn"/> <desc> @@ -320,7 +341,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> </func> <func> - <name name="cmp_dirs" arity="2"/> + <name name="cmp_dirs" arity="2" since=""/> <fsummary>Compare the BEAM files in two directories.</fsummary> <desc> <p>Compares the BEAM files in @@ -338,7 +359,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> </func> <func> - <name name="crypto_key_fun" arity="1"/> + <name name="crypto_key_fun" arity="1" since=""/> <fsummary>Register a fun that provides a crypto key.</fsummary> <type name="crypto_fun"/> <type name="crypto_fun_arg"/> @@ -346,7 +367,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code> <desc> <p>Registers an unary fun that is called if <c>beam_lib</c> must read an - <c>abstract_code</c> chunk that has been encrypted. The fun + <c>debug_info</c> chunk that has been encrypted. The fun is held in a process that is started by the function.</p> <p>If a fun is already registered when attempting to register a fun, <c>{error, exists}</c> is returned.</p> @@ -377,7 +398,7 @@ CryptoKeyFun(clear) -> term()</code> </func> <func> - <name name="diff_dirs" arity="2"/> + <name name="diff_dirs" arity="2" since=""/> <fsummary>Compare the BEAM files in two directories.</fsummary> <desc> <p>Compares the BEAM files in two directories as @@ -388,7 +409,7 @@ CryptoKeyFun(clear) -> term()</code> </func> <func> - <name name="format_error" arity="1"/> + <name name="format_error" arity="1" since=""/> <fsummary>Return an English description of a BEAM read error reply. </fsummary> <desc> @@ -401,7 +422,7 @@ CryptoKeyFun(clear) -> term()</code> </func> <func> - <name name="info" arity="1"/> + <name name="info" arity="1" since=""/> <fsummary>Information about a BEAM file.</fsummary> <desc> <p>Returns a list containing some information about a BEAM file @@ -428,7 +449,7 @@ CryptoKeyFun(clear) -> term()</code> </func> <func> - <name name="md5" arity="1"/> + <name name="md5" arity="1" since=""/> <fsummary>Read the module version of the BEAM file.</fsummary> <desc> <p>Calculates an MD5 redundancy check for the code of the module @@ -437,31 +458,32 @@ CryptoKeyFun(clear) -> term()</code> </func> <func> - <name name="strip" arity="1"/> + <name name="strip" arity="1" since=""/> <fsummary>Remove chunks not needed by the loader from a BEAM file. </fsummary> <desc> <p>Removes all chunks from a BEAM file except those needed by the loader. In particular, - the debug information (chunk <c>abstract_code</c>) is removed.</p> + the debug information (chunk <c>debug_info</c> and <c>abstract_code</c>) + is removed.</p> </desc> </func> <func> - <name name="strip_files" arity="1"/> + <name name="strip_files" arity="1" since=""/> <fsummary>Removes chunks not needed by the loader from BEAM files. </fsummary> <desc> <p>Removes all chunks except those needed by the loader from BEAM files. In particular, - the debug information (chunk <c>abstract_code</c>) is removed. - The returned list contains one element for each specified filename, - in the same order as in <c>Files</c>.</p> + the debug information (chunk <c>debug_info</c> and <c>abstract_code</c>) + is removed. The returned list contains one element for each + specified filename, in the same order as in <c>Files</c>.</p> </desc> </func> <func> - <name name="strip_release" arity="1"/> + <name name="strip_release" arity="1" since=""/> <fsummary>Remove chunks not needed by the loader from all BEAM files of a release.</fsummary> <desc> @@ -475,7 +497,7 @@ CryptoKeyFun(clear) -> term()</code> </func> <func> - <name name="version" arity="1"/> + <name name="version" arity="1" since=""/> <fsummary>Read the module version of the BEAM file.</fsummary> <desc> <p>Returns the module version or versions. A version is defined by diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml index 6a86d6c7ba..f3d4edd30f 100644 --- a/lib/stdlib/doc/src/binary.xml +++ b/lib/stdlib/doc/src/binary.xml @@ -34,7 +34,7 @@ <rev>A</rev> <file>binary.xml</file> </header> - <module>binary</module> + <module since="OTP R14B">binary</module> <modulesummary>Library for handling binary data.</modulesummary> <description> @@ -79,7 +79,7 @@ <funcs> <func> - <name name="at" arity="2"/> + <name name="at" arity="2" since="OTP R14B"/> <fsummary>Return the byte at a specific position in a binary.</fsummary> <desc> <p>Returns the byte at position <c><anno>Pos</anno></c> (zero-based) in @@ -90,7 +90,7 @@ </func> <func> - <name name="bin_to_list" arity="1"/> + <name name="bin_to_list" arity="1" since="OTP R14B"/> <fsummary>Convert a binary to a list of integers.</fsummary> <desc> <p>Same as <c>bin_to_list(<anno>Subject</anno>, {0,byte_size(<anno>Subject</anno>)})</c>.</p> @@ -98,7 +98,7 @@ </func> <func> - <name name="bin_to_list" arity="2"/> + <name name="bin_to_list" arity="2" since="OTP R14B"/> <fsummary>Convert a binary to a list of integers.</fsummary> <desc> <p>Converts <c><anno>Subject</anno></c> to a list of <c>byte()</c>s, each @@ -118,7 +118,7 @@ </func> <func> - <name name="bin_to_list" arity="3"/> + <name name="bin_to_list" arity="3" since="OTP R14B"/> <fsummary>Convert a binary to a list of integers.</fsummary> <desc> <p>Same as<c> bin_to_list(<anno>Subject</anno>, {<anno>Pos</anno>, <anno>Len</anno>})</c>.</p> @@ -126,7 +126,7 @@ </func> <func> - <name name="compile_pattern" arity="1"/> + <name name="compile_pattern" arity="1" since="OTP R14B"/> <fsummary>Precompile a binary search pattern.</fsummary> <desc> <p>Builds an internal structure representing a compilation of a @@ -158,7 +158,7 @@ </func> <func> - <name name="copy" arity="1"/> + <name name="copy" arity="1" since="OTP R14B"/> <fsummary>Create a duplicate of a binary.</fsummary> <desc> <p>Same as <c>copy(<anno>Subject</anno>, 1)</c>.</p> @@ -166,7 +166,7 @@ </func> <func> - <name name="copy" arity="2"/> + <name name="copy" arity="2" since="OTP R14B"/> <fsummary>Duplicate a binary <c>N</c> times and create a new.</fsummary> <desc> <p>Creates a binary with the content of <c><anno>Subject</anno></c> @@ -193,7 +193,7 @@ </func> <func> - <name name="decode_unsigned" arity="1"/> + <name name="decode_unsigned" arity="1" since="OTP R14B"/> <fsummary>Decode a whole binary into an integer of arbitrary size. </fsummary> <desc> @@ -202,7 +202,7 @@ </func> <func> - <name name="decode_unsigned" arity="2"/> + <name name="decode_unsigned" arity="2" since="OTP R14B"/> <fsummary>Decode a whole binary into an integer of arbitrary size. </fsummary> <desc> @@ -219,7 +219,7 @@ </func> <func> - <name name="encode_unsigned" arity="1"/> + <name name="encode_unsigned" arity="1" since="OTP R14B"/> <fsummary>Encode an unsigned integer into the minimal binary.</fsummary> <desc> <p>Same as <c>encode_unsigned(<anno>Unsigned</anno>, big)</c>.</p> @@ -227,7 +227,7 @@ </func> <func> - <name name="encode_unsigned" arity="2"/> + <name name="encode_unsigned" arity="2" since="OTP R14B"/> <fsummary>Encode an unsigned integer into the minimal binary.</fsummary> <desc> <p>Converts a positive integer to the smallest possible @@ -243,7 +243,7 @@ </func> <func> - <name name="first" arity="1"/> + <name name="first" arity="1" since="OTP R14B"/> <fsummary>Return the first byte of a binary.</fsummary> <desc> <p>Returns the first byte of binary <c><anno>Subject</anno></c> as an @@ -253,7 +253,7 @@ </func> <func> - <name name="last" arity="1"/> + <name name="last" arity="1" since="OTP R14B"/> <fsummary>Return the last byte of a binary.</fsummary> <desc> <p>Returns the last byte of binary <c><anno>Subject</anno></c> as an @@ -263,7 +263,7 @@ </func> <func> - <name name="list_to_bin" arity="1"/> + <name name="list_to_bin" arity="1" since="OTP R14B"/> <fsummary>Convert a list of integers and binaries to a binary.</fsummary> <desc> <p>Works exactly as @@ -273,7 +273,7 @@ </func> <func> - <name name="longest_common_prefix" arity="1"/> + <name name="longest_common_prefix" arity="1" since="OTP R14B"/> <fsummary>Return length of longest common prefix for a set of binaries. </fsummary> <desc> @@ -294,7 +294,7 @@ </func> <func> - <name name="longest_common_suffix" arity="1"/> + <name name="longest_common_suffix" arity="1" since="OTP R14B"/> <fsummary>Return length of longest common suffix for a set of binaries. </fsummary> <desc> @@ -315,7 +315,7 @@ </func> <func> - <name name="match" arity="2"/> + <name name="match" arity="2" since="OTP R14B"/> <fsummary>Search for the first match of a pattern in a binary.</fsummary> <desc> <p>Same as <c>match(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>. @@ -324,7 +324,7 @@ </func> <func> - <name name="match" arity="3"/> + <name name="match" arity="3" since="OTP R14B"/> <fsummary>Search for the first match of a pattern in a binary.</fsummary> <type name="part"/> <desc> @@ -372,7 +372,7 @@ </func> <func> - <name name="matches" arity="2"/> + <name name="matches" arity="2" since="OTP R14B"/> <fsummary>Search for all matches of a pattern in a binary.</fsummary> <desc> <p>Same as <c>matches(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>. @@ -381,7 +381,7 @@ </func> <func> - <name name="matches" arity="3"/> + <name name="matches" arity="3" since="OTP R14B"/> <fsummary>Search for all matches of a pattern in a binary.</fsummary> <type name="part"/> <desc> @@ -425,7 +425,7 @@ </func> <func> - <name name="part" arity="2"/> + <name name="part" arity="2" since="OTP R14B"/> <fsummary>Extract a part of a binary.</fsummary> <desc> <p>Extracts the part of binary <c><anno>Subject</anno></c> described by @@ -453,7 +453,7 @@ </func> <func> - <name name="part" arity="3"/> + <name name="part" arity="3" since="OTP R14B"/> <fsummary>Extract a part of a binary.</fsummary> <desc> <p>Same as <c>part(<anno>Subject</anno>, {<anno>Pos</anno>, @@ -462,7 +462,7 @@ </func> <func> - <name name="referenced_byte_size" arity="1"/> + <name name="referenced_byte_size" arity="1" since="OTP R14B"/> <fsummary>Determine the size of the binary pointed out by a subbinary. </fsummary> <desc> @@ -525,7 +525,7 @@ store(Binary, GBSet) -> </func> <func> - <name name="replace" arity="3"/> + <name name="replace" arity="3" since="OTP R14B"/> <fsummary>Replace bytes in a binary according to a pattern.</fsummary> <desc> <p>Same as <c>replace(<anno>Subject</anno>, <anno>Pattern</anno>, <anno>Replacement</anno>,[])</c>.</p> @@ -533,7 +533,7 @@ store(Binary, GBSet) -> </func> <func> - <name name="replace" arity="4"/> + <name name="replace" arity="4" since="OTP R14B"/> <fsummary>Replace bytes in a binary according to a pattern.</fsummary> <type_desc variable="OnePos">An integer() =< byte_size(<anno>Replacement</anno>) </type_desc> @@ -575,7 +575,7 @@ store(Binary, GBSet) -> </func> <func> - <name name="split" arity="2"/> + <name name="split" arity="2" since="OTP R14B"/> <fsummary>Split a binary according to a pattern.</fsummary> <desc> <p>Same as <c>split(<anno>Subject</anno>, <anno>Pattern</anno>, @@ -584,7 +584,7 @@ store(Binary, GBSet) -> </func> <func> - <name name="split" arity="3"/> + <name name="split" arity="3" since="OTP R14B"/> <fsummary>Split a binary according to a pattern.</fsummary> <desc> <p>Splits <c><anno>Subject</anno></c> into a list of binaries based on diff --git a/lib/stdlib/doc/src/c.xml b/lib/stdlib/doc/src/c.xml index 92ab59c6b0..29edc373c7 100644 --- a/lib/stdlib/doc/src/c.xml +++ b/lib/stdlib/doc/src/c.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date>1996-10-30</date> <rev>B</rev> </header> - <module>c</module> + <module since="">c</module> <modulesummary>Command interface module.</modulesummary> <description> <p>This module enables users to enter the short form of @@ -41,7 +41,7 @@ <funcs> <func> - <name name="bt" arity="1"/> + <name name="bt" arity="1" since=""/> <fsummary>Stack backtrace for a process.</fsummary> <desc> <p>Stack backtrace for a process. Equivalent to @@ -50,15 +50,29 @@ </func> <func> - <name name="c" arity="1"/> - <name name="c" arity="2"/> - <fsummary>Compile and load code in a file.</fsummary> + <name name="c" arity="1" since=""/> + <name name="c" arity="2" since=""/> + <name name="c" arity="3" since="OTP 20.0"/> + <fsummary>Compile and load a file or module.</fsummary> <desc> - <p>Compiles and then purges and loads the code for a file. - <c><anno>Options</anno></c> defaults to <c>[]</c>. Compilation is - equivalent to:</p> - <code type="none"> -compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_warnings])</code> + <p>Compiles and then purges and loads the code for a module. + <c><anno>Module</anno></c> can be either a module name or a source + file path, with or without <c>.erl</c> extension. + <c><anno>Options</anno></c> defaults to <c>[]</c>.</p> + <p>If <c><anno>Module</anno></c> is an atom and is not the path of a + source file, then the code path is searched to locate the object + file for the module and extract its original compiler options and + source path. If the source file is not found in the original + location, <seealso + marker="filelib#find_source/1"><c>filelib:find_source/1</c></seealso> + is used to search for it relative to the directory of the object + file.</p> + <p>The source file is compiled with the the original + options appended to the given <c><anno>Options</anno></c>, the + output replacing the old object file if and only if compilation + succeeds. A function <c><anno>Filter</anno></c> can be specified + for removing elements from from the original compiler options + before the new options are added.</p> <p>Notice that purging the code means that any processes lingering in old code for the module are killed without warning. For more information, see <c>code/3</c>.</p> @@ -66,7 +80,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="cd" arity="1"/> + <name name="cd" arity="1" since=""/> <fsummary>Change working directory.</fsummary> <desc> <p>Changes working directory to <c><anno>Dir</anno></c>, which can be a @@ -80,7 +94,16 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="flush" arity="0"/> + <name name="erlangrc" arity="1" since="OTP 21.0"/> + <fsummary>Load an erlang resource file.</fsummary> + <desc> + <p>Search <c>PathList</c> and load <c>.erlang</c> resource file if + found.</p> + </desc> + </func> + + <func> + <name name="flush" arity="0" since=""/> <fsummary>Flush any messages sent to the shell.</fsummary> <desc> <p>Flushes any messages sent to the shell.</p> @@ -88,7 +111,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="help" arity="0"/> + <name name="help" arity="0" since=""/> <fsummary>Help information.</fsummary> <desc> <p>Displays help information: all valid shell internal commands, @@ -97,8 +120,8 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="i" arity="0"/> - <name name="ni" arity="0"/> + <name name="i" arity="0" since=""/> + <name name="ni" arity="0" since=""/> <fsummary>System information.</fsummary> <desc> <p><c>i/0</c> displays system information, listing @@ -108,7 +131,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="i" arity="3"/> + <name name="i" arity="3" since=""/> <fsummary>Information about pid <X.Y.Z>.</fsummary> <desc> <p>Displays information about a process, Equivalent to @@ -118,7 +141,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="l" arity="1"/> + <name name="l" arity="1" since=""/> <fsummary>Load or reload a module.</fsummary> <desc> <p>Purges and loads, or reloads, a module by calling @@ -131,7 +154,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name>lc(Files) -> ok</name> + <name since="">lc(Files) -> ok</name> <fsummary>Compile a list of files.</fsummary> <type> <v>Files = [File]</v> @@ -148,7 +171,16 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="ls" arity="0"/> + <name name="lm" arity="0" since="OTP 20.0"/> + <fsummary>Loads all modified modules.</fsummary> + <desc> + <p>Reloads all currently loaded modules that have changed on disk (see <c>mm()</c>). + Returns the list of results from calling <c>l(M)</c> for each such <c>M</c>.</p> + </desc> + </func> + + <func> + <name name="ls" arity="0" since=""/> <fsummary>List files in the current directory.</fsummary> <desc> <p>Lists files in the current directory.</p> @@ -156,7 +188,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="ls" arity="1"/> + <name name="ls" arity="1" since=""/> <fsummary>List files in a directory or a single file.</fsummary> <desc> <p>Lists files in directory <c><anno>Dir</anno></c> or, if <c>Dir</c> @@ -165,7 +197,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="m" arity="0"/> + <name name="m" arity="0" since=""/> <fsummary>Which modules are loaded.</fsummary> <desc> <p>Displays information about the loaded modules, including @@ -174,7 +206,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="m" arity="1"/> + <name name="m" arity="1" since=""/> <fsummary>Information about a module.</fsummary> <desc> <p>Displays information about <c><anno>Module</anno></c>.</p> @@ -182,7 +214,16 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="memory" arity="0"/> + <name name="mm" arity="0" since="OTP 20.0"/> + <fsummary>Lists all modified modules.</fsummary> + <desc> + <p>Lists all modified modules. Shorthand for + <seealso marker="kernel:code#modified_modules/0"><c>code:modified_modules/0</c></seealso>.</p> + </desc> + </func> + + <func> + <name name="memory" arity="0" since=""/> <fsummary>Memory allocation information.</fsummary> <desc> <p>Memory allocation information. Equivalent to @@ -191,8 +232,8 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="memory" arity="1" clause_i="1"/> - <name name="memory" arity="1" clause_i="2"/> + <name name="memory" arity="1" clause_i="1" since=""/> + <name name="memory" arity="1" clause_i="2" since=""/> <fsummary>Memory allocation information.</fsummary> <desc> <p>Memory allocation information. Equivalent to @@ -201,8 +242,8 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="nc" arity="1"/> - <name name="nc" arity="2"/> + <name name="nc" arity="1" since=""/> + <name name="nc" arity="2" since=""/> <fsummary>Compile and load code in a file on all nodes.</fsummary> <desc> <p>Compiles and then loads the code for a file on all nodes. @@ -214,7 +255,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="nl" arity="1"/> + <name name="nl" arity="1" since=""/> <fsummary>Load module on all nodes.</fsummary> <desc> <p>Loads <c><anno>Module</anno></c> on all nodes.</p> @@ -222,7 +263,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="pid" arity="3"/> + <name name="pid" arity="3" since=""/> <fsummary>Convert <c>X,Y,Z</c> to a pid.</fsummary> <desc> <p>Converts <c><anno>X</anno></c>, <c><anno>Y</anno></c>, @@ -232,7 +273,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="pwd" arity="0"/> + <name name="pwd" arity="0" since=""/> <fsummary>Print working directory.</fsummary> <desc> <p>Prints the name of the working directory.</p> @@ -240,7 +281,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="q" arity="0"/> + <name name="q" arity="0" since=""/> <fsummary>Quit - shorthand for <c>init:stop()</c>.</fsummary> <desc> <p>This function is shorthand for <c>init:stop()</c>, that is, @@ -249,8 +290,8 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="regs" arity="0"/> - <name name="nregs" arity="0"/> + <name name="regs" arity="0" since=""/> + <name name="nregs" arity="0" since=""/> <fsummary>Information about registered processes.</fsummary> <desc> <p><c>regs/0</c> displays information about all registered @@ -260,7 +301,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name name="uptime" arity="0"/> + <name name="uptime" arity="0" since="OTP 18.0"/> <fsummary>Print node uptime.</fsummary> <desc> <p>Prints the node uptime (as specified by @@ -269,7 +310,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name>xm(ModSpec) -> void()</name> + <name since="">xm(ModSpec) -> void()</name> <fsummary>Cross-reference check a module.</fsummary> <type> <v>ModSpec = Module | Filename</v> @@ -284,7 +325,7 @@ compile:file(<anno>File</anno>, <anno>Options</anno> ++ [report_errors, report_w </func> <func> - <name>y(File) -> YeccRet</name> + <name since="">y(File) -> YeccRet</name> <fsummary>Generate an LALR-1 parser.</fsummary> <type> <v>File = name()</v> @@ -303,7 +344,7 @@ yecc:file(File)</code> </func> <func> - <name>y(File, Options) -> YeccRet</name> + <name since="">y(File, Options) -> YeccRet</name> <fsummary>Generate an LALR-1 parser.</fsummary> <type> <v>File = name()</v> diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml index 65b3edcdf6..518a085c89 100644 --- a/lib/stdlib/doc/src/calendar.xml +++ b/lib/stdlib/doc/src/calendar.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date>1996-11-05</date> <rev>B</rev> </header> - <module>calendar</module> + <module since="">calendar</module> <modulesummary>Local and universal time, day of the week, date and time conversions.</modulesummary> <description> @@ -128,8 +128,8 @@ <funcs> <func> - <name name="date_to_gregorian_days" arity="1"/> - <name name="date_to_gregorian_days" arity="3"/> + <name name="date_to_gregorian_days" arity="1" since=""/> + <name name="date_to_gregorian_days" arity="3" since=""/> <fsummary>Compute the number of days from year 0 up to the specified date.</fsummary> <type variable="Date" name_i="1"/> @@ -143,7 +143,7 @@ </func> <func> - <name name="datetime_to_gregorian_seconds" arity="1"/> + <name name="datetime_to_gregorian_seconds" arity="1" since=""/> <fsummary>Compute the number of seconds from year 0 up to the specified date and time.</fsummary> <desc> @@ -153,8 +153,8 @@ </func> <func> - <name name="day_of_the_week" arity="1"/> - <name name="day_of_the_week" arity="3"/> + <name name="day_of_the_week" arity="1" since=""/> + <name name="day_of_the_week" arity="3" since=""/> <fsummary>Compute the day of the week.</fsummary> <type variable="Date" name_i="1"/> <type variable="Year"/> @@ -169,7 +169,7 @@ </func> <func> - <name name="gregorian_days_to_date" arity="1"/> + <name name="gregorian_days_to_date" arity="1" since=""/> <fsummary>Compute the date from the number of gregorian days.</fsummary> <desc> <p>Computes the date from the specified number of gregorian days.</p> @@ -177,7 +177,7 @@ </func> <func> - <name name="gregorian_seconds_to_datetime" arity="1"/> + <name name="gregorian_seconds_to_datetime" arity="1" since=""/> <fsummary>Compute the date and time from the number of gregorian seconds. </fsummary> <desc> @@ -187,7 +187,7 @@ </func> <func> - <name name="is_leap_year" arity="1"/> + <name name="is_leap_year" arity="1" since=""/> <fsummary>Check if the year is a leap year.</fsummary> <desc> <p>Checks if the specified year is a leap year.</p> @@ -195,7 +195,7 @@ </func> <func> - <name name="iso_week_number" arity="0"/> + <name name="iso_week_number" arity="0" since="OTP R14B02"/> <fsummary>Compute the ISO week number for the actual date.</fsummary> <desc> <p>Returns tuple <c>{Year, WeekNum}</c> representing @@ -206,7 +206,7 @@ </func> <func> - <name name="iso_week_number" arity="1"/> + <name name="iso_week_number" arity="1" since="OTP R14B02"/> <fsummary>Compute the ISO week number for the specified date.</fsummary> <desc> <p>Returns tuple <c>{Year, WeekNum}</c> representing @@ -215,7 +215,7 @@ </func> <func> - <name name="last_day_of_the_month" arity="2"/> + <name name="last_day_of_the_month" arity="2" since=""/> <fsummary>Compute the number of days in a month.</fsummary> <desc> <p>Computes the number of days in a month.</p> @@ -223,7 +223,7 @@ </func> <func> - <name name="local_time" arity="0"/> + <name name="local_time" arity="0" since=""/> <fsummary>Compute local time.</fsummary> <desc> <p>Returns the local time reported by @@ -232,7 +232,7 @@ </func> <func> - <name name="local_time_to_universal_time" arity="1"/> + <name name="local_time_to_universal_time" arity="1" since=""/> <fsummary>Convert from local time to universal time (deprecated). </fsummary> <desc> @@ -253,7 +253,7 @@ </func> <func> - <name name="local_time_to_universal_time_dst" arity="1"/> + <name name="local_time_to_universal_time_dst" arity="1" since=""/> <fsummary>Convert from local time to universal time(s).</fsummary> <desc> <p>Converts from local time to Universal Coordinated Time (UTC). @@ -285,7 +285,7 @@ </func> <func> - <name name="now_to_datetime" arity="1"/> + <name name="now_to_datetime" arity="1" since=""/> <fsummary>Convert now to date and time.</fsummary> <desc> <p>Returns Universal Coordinated Time (UTC) @@ -296,7 +296,7 @@ </func> <func> - <name name="now_to_local_time" arity="1"/> + <name name="now_to_local_time" arity="1" since=""/> <fsummary>Convert now to local date and time.</fsummary> <desc> <p>Returns local date and time converted from the return value from @@ -306,7 +306,7 @@ </func> <func> - <name name="now_to_universal_time" arity="1"/> + <name name="now_to_universal_time" arity="1" since=""/> <fsummary>Convert now to date and time.</fsummary> <desc> <p>Returns Universal Coordinated Time (UTC) @@ -317,7 +317,33 @@ </func> <func> - <name name="seconds_to_daystime" arity="1"/> + <name name="rfc3339_to_system_time" arity="1" since="OTP 21.0"/> + <name name="rfc3339_to_system_time" arity="2" since="OTP 21.0"/> + <fsummary>Convert from RFC 3339 timestamp to system time.</fsummary> + <type name="rfc3339_string"/> + <type name="rfc3339_time_unit"/> + <desc> + <p>Converts an RFC 3339 timestamp into system time. The data format + of RFC 3339 timestamps is described by + <url href="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</url>.</p> + <p>Valid option:</p> + <taglist> + <tag><c>{unit, Unit}</c></tag> + <item><p>The time unit of the return value. + The default is <c>second</c>.</p> + </item> + </taglist> + <pre> +1> <input>calendar:rfc3339_to_system_time("2018-02-01T16:17:58+01:00").</input> +1517498278 +2> <input>calendar:rfc3339_to_system_time("2018-02-01 15:18:02.088Z", + [{unit, nanosecond}]).</input> +1517498282088000000</pre> + </desc> + </func> + + <func> + <name name="seconds_to_daystime" arity="1" since=""/> <fsummary>Compute days and time from seconds.</fsummary> <desc> <p>Converts a specified number of seconds into days, hours, minutes, @@ -328,7 +354,7 @@ </func> <func> - <name name="seconds_to_time" arity="1"/> + <name name="seconds_to_time" arity="1" since=""/> <fsummary>Compute time from seconds.</fsummary> <type name="secs_per_day"/> <desc> @@ -339,7 +365,76 @@ </func> <func> - <name name="time_difference" arity="2"/> + <name name="system_time_to_local_time" arity="2" since="OTP 21.0"/> + <fsummary>Convert system time to local date and time.</fsummary> + <desc> + <p>Converts a specified system time into local date and time.</p> + </desc> + </func> + + <func> + <name name="system_time_to_rfc3339" arity="1" since="OTP 21.0"/> + <name name="system_time_to_rfc3339" arity="2" since="OTP 21.0"/> + <fsummary>Convert from system to RFC 3339 timestamp.</fsummary> + <type name="offset"/> + <type name="rfc3339_string"/> + <type name="rfc3339_time_unit"/> + <desc> + <p>Converts a system time into an RFC 3339 timestamp. The data format + of RFC 3339 timestamps is described by + <url href="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</url>. + The data format of offsets is also described by RFC 3339.</p> + <p>Valid options:</p> + <taglist> + <tag><c>{offset, Offset}</c></tag> + <item><p>The offset, either a string or an integer, to be + included in the formatted string. + An empty string, which is the default, is interpreted + as local time. A non-empty string is included as is. + The time unit of the integer is the same as the one + of <c><anno>Time</anno></c>.</p> + </item> + <tag><c>{time_designator, Character}</c></tag> + <item><p>The character used as time designator, that is, + the date and time separator. The default is <c>$T</c>.</p> + </item> + <tag><c>{unit, Unit}</c></tag> + <item><p>The time unit of <c><anno>Time</anno></c>. The + default is <c>second</c>. If some other unit is given + (<c>millisecond</c>, <c>microsecond</c>, or + <c>nanosecond</c>), the formatted string includes a + fraction of a second. The number of fractional second + digits is three, six, or nine depending on what time unit + is chosen. Notice that trailing zeros are not removed from + the fraction. + </p> + </item> + </taglist> + <pre> +1> <input>calendar:system_time_to_rfc3339(erlang:system_time(second)).</input> +"2018-04-23T14:56:28+02:00" +2> <input>calendar:system_time_to_rfc3339(erlang:system_time(second), + [{offset, "-02:00"}]).</input> +"2018-04-23T10:56:52-02:00" +3> <input>calendar:system_time_to_rfc3339(erlang:system_time(second), + [{offset, -7200}]).</input> +"2018-04-23T10:57:05-02:00" +4> <input>calendar:system_time_to_rfc3339(erlang:system_time(millisecond), + [{unit, millisecond}, {time_designator, $\s}, {offset, "Z"}]).</input> +"2018-04-23 12:57:20.482Z"</pre> + </desc> + </func> + + <func> + <name name="system_time_to_universal_time" arity="2" since="OTP 21.0"/> + <fsummary>Convert system time to universal date and time.</fsummary> + <desc> + <p>Converts a specified system time into universal date and time.</p> + </desc> + </func> + + <func> + <name name="time_difference" arity="2" since=""/> <fsummary>Compute the difference between two times (deprecated). </fsummary> <desc> @@ -354,7 +449,7 @@ </func> <func> - <name name="time_to_seconds" arity="1"/> + <name name="time_to_seconds" arity="1" since=""/> <fsummary>Compute the number of seconds since midnight up to the specified time.</fsummary> <type name="secs_per_day"/> @@ -365,7 +460,7 @@ </func> <func> - <name name="universal_time" arity="0"/> + <name name="universal_time" arity="0" since=""/> <fsummary>Compute universal time.</fsummary> <desc> <p>Returns the Universal Coordinated Time (UTC) @@ -375,7 +470,7 @@ </func> <func> - <name name="universal_time_to_local_time" arity="1"/> + <name name="universal_time_to_local_time" arity="1" since=""/> <fsummary>Convert from universal time to local time.</fsummary> <desc> <p>Converts from Universal Coordinated Time (UTC) to local time. @@ -385,8 +480,8 @@ </func> <func> - <name name="valid_date" arity="1"/> - <name name="valid_date" arity="3"/> + <name name="valid_date" arity="1" since=""/> + <name name="valid_date" arity="3" since=""/> <fsummary>Check if a date is valid</fsummary> <type variable="Date" name_i="1"/> <type variable="Year"/> diff --git a/lib/stdlib/doc/src/dets.xml b/lib/stdlib/doc/src/dets.xml index 2e4261d72e..8e4e002000 100644 --- a/lib/stdlib/doc/src/dets.xml +++ b/lib/stdlib/doc/src/dets.xml @@ -32,7 +32,7 @@ <rev>B</rev> <file>dets.xml</file> </header> - <module>dets</module> + <module since="">dets</module> <modulesummary>A disk-based term storage.</modulesummary> <description> <p>This module provides a term storage on file. The @@ -100,18 +100,12 @@ provided by Dets, neither is the limited support for concurrent updates that makes a sequence of <c>first</c> and <c>next</c> calls safe to use on fixed ETS tables. Both these - features will be provided by Dets in a future release of + features may be provided by Dets in a future release of Erlang/OTP. Until then, the Mnesia application (or some user-implemented method for locking) must be used to implement safe concurrency. Currently, no Erlang/OTP library has support for ordered disk-based term storage.</p> - <p>Two versions of the format used for storing objects on file are - supported by Dets. The first version, 8, is the format always used - for tables created by Erlang/OTP R7 and earlier. The second version, 9, - is the default version of tables created by Erlang/OTP R8 (and later - releases). Erlang/OTP R8 can create version 8 tables, and convert version - 8 tables to version 9, and conversely, upon request.</p> <p>All Dets functions return <c>{error, Reason}</c> if an error occurs (<seealso marker="#first/1"><c>first/1</c></seealso> and <seealso marker="#next/2"><c>next/2</c></seealso> are exceptions, they @@ -190,14 +184,11 @@ <datatype> <name name="type"/> </datatype> - <datatype> - <name name="version"/> - </datatype> </datatypes> <funcs> <func> - <name name="all" arity="0"/> + <name name="all" arity="0" since=""/> <fsummary>Return a list of the names of all open Dets tables on this node.</fsummary> <desc> @@ -206,7 +197,7 @@ </func> <func> - <name name="bchunk" arity="2"/> + <name name="bchunk" arity="2" since=""/> <fsummary>Return a chunk of objects stored in a Dets table. </fsummary> <desc> @@ -236,7 +227,7 @@ </func> <func> - <name name="close" arity="1"/> + <name name="close" arity="1" since=""/> <fsummary>Close a Dets table.</fsummary> <desc> <p>Closes a table. Only processes that have opened a table are @@ -248,7 +239,7 @@ </func> <func> - <name name="delete" arity="2"/> + <name name="delete" arity="2" since=""/> <fsummary>Delete all objects with a specified key from a Dets table.</fsummary> <desc> @@ -258,7 +249,7 @@ </func> <func> - <name name="delete_all_objects" arity="1"/> + <name name="delete_all_objects" arity="1" since=""/> <fsummary>Delete all objects from a Dets table.</fsummary> <desc> <p>Deletes all objects from a table in almost constant time. @@ -268,7 +259,7 @@ </func> <func> - <name name="delete_object" arity="2"/> + <name name="delete_object" arity="2" since=""/> <fsummary>Delete a specified object from a Dets table.</fsummary> <desc> <p>Deletes all instances of a specified object from a table. If a @@ -279,7 +270,7 @@ </func> <func> - <name name="first" arity="1"/> + <name name="first" arity="1" since=""/> <fsummary>Return the first key stored in a Dets table.</fsummary> <desc> <p>Returns the first key stored in table <c><anno>Name</anno></c> @@ -304,8 +295,8 @@ </func> <func> - <name name="foldl" arity="3"/> - <name name="foldr" arity="3"/> + <name name="foldl" arity="3" since=""/> + <name name="foldr" arity="3" since=""/> <fsummary>Fold a function over a Dets table.</fsummary> <desc> <p>Calls <c><anno>Function</anno></c> on successive elements of @@ -318,7 +309,7 @@ </func> <func> - <name name="from_ets" arity="2"/> + <name name="from_ets" arity="2" since=""/> <fsummary>Replace the objects of a Dets table with the objects of an ETS table.</fsummary> <desc> @@ -331,7 +322,7 @@ </func> <func> - <name name="info" arity="1"/> + <name name="info" arity="1" since=""/> <fsummary>Return information about a Dets table.</fsummary> <desc> <p>Returns information about table <c><anno>Name</anno></c> @@ -363,7 +354,7 @@ </func> <func> - <name name="info" arity="2"/> + <name name="info" arity="2" since=""/> <fsummary>Return the information associated with a specified item for a Dets table.</fsummary> <desc> @@ -385,8 +376,7 @@ <p><c>{bchunk_format, binary()}</c> - An opaque binary describing the format of the objects returned by <c>bchunk/2</c>. The binary can be used as argument to - <c>is_compatible_chunk_format/2</c>. Only available for - version 9 tables.</p> + <c>is_compatible_chunk_format/2</c>.</p> </item> <item> <p><c>{hash, Hash}</c> - Describes which BIF is @@ -394,10 +384,6 @@ Dets table. Possible values of <c>Hash</c>:</p> <list> <item> - <p><c>hash</c> - Implies that the <c>erlang:hash/2</c> BIF - is used.</p> - </item> - <item> <p><c>phash</c> - Implies that the <c>erlang:phash/2</c> BIF is used.</p> </item> @@ -413,8 +399,7 @@ </item> <item> <p><c>{no_keys, integer >= 0()}</c> - The number of different - keys stored in the table. Only available for version 9 - tables.</p> + keys stored in the table.</p> </item> <item> <p><c>{no_objects, integer >= 0()}</c> - The number of objects @@ -424,8 +409,7 @@ <p><c>{no_slots, {Min, Used, Max}}</c> - The number of slots of the table. <c>Min</c> is the minimum number of slots, <c>Used</c> is the number of currently used slots, - and <c>Max</c> is the maximum number of slots. Only - available for version 9 tables.</p> + and <c>Max</c> is the maximum number of slots.</p> </item> <item> <p><c>{owner, pid()}</c> - The pid of the process that @@ -466,17 +450,13 @@ time warp safe</seealso>. Time warp safe code must use <c>safe_fixed_monotonic_time</c> instead.</p> </item> - <item> - <p><c>{version, integer()}</c> - The version of the format of - the table.</p> - </item> </list> </desc> </func> <func> - <name name="init_table" arity="2"/> - <name name="init_table" arity="3"/> + <name name="init_table" arity="2" since=""/> + <name name="init_table" arity="3" since=""/> <fsummary>Replace all objects of a Dets table.</fsummary> <desc> <p>Replaces the existing objects of table <c><anno>Name</anno></c> @@ -536,7 +516,7 @@ </func> <func> - <name name="insert" arity="2"/> + <name name="insert" arity="2" since=""/> <fsummary>Insert one or more objects into a Dets table.</fsummary> <desc> <p>Inserts one or more objects into the table <c><anno>Name</anno></c>. @@ -547,7 +527,7 @@ </func> <func> - <name name="insert_new" arity="2"/> + <name name="insert_new" arity="2" since=""/> <fsummary>Insert one or more objects into a Dets table.</fsummary> <desc> <p>Inserts one or more objects into table <c><anno>Name</anno></c>. @@ -559,7 +539,7 @@ </func> <func> - <name name="is_compatible_bchunk_format" arity="2"/> + <name name="is_compatible_bchunk_format" arity="2" since=""/> <fsummary>Test compatibility of chunk data of a table.</fsummary> <desc> <p>Returns <c>true</c> if it would be possible to initialize @@ -574,7 +554,7 @@ </func> <func> - <name name="is_dets_file" arity="1"/> + <name name="is_dets_file" arity="1" since=""/> <fsummary>Test for a Dets table.</fsummary> <desc> <p>Returns <c>true</c> if file <c><anno>Filename</anno></c> @@ -583,7 +563,7 @@ </func> <func> - <name name="lookup" arity="2"/> + <name name="lookup" arity="2" since=""/> <fsummary>Return all objects with a specified key stored in a Dets table.</fsummary> <desc> @@ -610,7 +590,7 @@ ok </func> <func> - <name name="match" arity="1"/> + <name name="match" arity="1" since=""/> <fsummary>Match a chunk of objects stored in a Dets table and return a list of variable bindings.</fsummary> <desc> @@ -626,7 +606,7 @@ ok </func> <func> - <name name="match" arity="2"/> + <name name="match" arity="2" since=""/> <fsummary>Match the objects stored in a Dets table and return a list of variable bindings.</fsummary> <desc> @@ -642,7 +622,7 @@ ok </func> <func> - <name name="match" arity="3"/> + <name name="match" arity="3" since=""/> <fsummary>Match the first chunk of objects stored in a Dets table and return a list of variable bindings.</fsummary> <desc> @@ -662,8 +642,8 @@ ok objects at a time, until at least one object matches or the end of the table is reached. The default, indicated by giving <c><anno>N</anno></c> the value <c>default</c>, is to let - the number of objects vary depending on the sizes of the objects. If - <c><anno>Name</anno></c> is a version 9 table, all objects with the + the number of objects vary depending on the sizes of the objects. + All objects with the same key are always matched at the same time, which implies that more than <anno>N</anno> objects can sometimes be matched.</p> <p>The table is always to be protected using @@ -674,7 +654,7 @@ ok </func> <func> - <name name="match_delete" arity="2"/> + <name name="match_delete" arity="2" since=""/> <fsummary>Delete all objects that match a given pattern from a Dets table.</fsummary> <desc> @@ -687,7 +667,7 @@ ok </func> <func> - <name name="match_object" arity="1"/> + <name name="match_object" arity="1" since=""/> <fsummary>Match a chunk of objects stored in a Dets table and return a list of objects.</fsummary> <desc> @@ -703,7 +683,7 @@ ok </func> <func> - <name name="match_object" arity="2"/> + <name name="match_object" arity="2" since=""/> <fsummary>Match the objects stored in a Dets table and return a list of objects.</fsummary> <desc> @@ -722,7 +702,7 @@ ok </func> <func> - <name name="match_object" arity="3"/> + <name name="match_object" arity="3" since=""/> <fsummary>Match the first chunk of objects stored in a Dets table and return a list of objects.</fsummary> <desc> @@ -743,9 +723,9 @@ ok end of the table is reached. The default, indicated by giving <c><anno>N</anno></c> the value <c>default</c>, is to let the number - of objects vary depending on the sizes of the objects. If - <c><anno>Name</anno></c> is a version 9 table, all matching objects - with the same key are always returned in the same reply, which implies + of objects vary depending on the sizes of the objects. All + matching objects with the same key are always returned + in the same reply, which implies that more than <anno>N</anno> objects can sometimes be returned.</p> <p>The table is always to be protected using <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> @@ -755,7 +735,7 @@ ok </func> <func> - <name name="member" arity="2"/> + <name name="member" arity="2" since=""/> <fsummary>Test for occurrence of a key in a Dets table.</fsummary> <desc> <p>Works like <seealso marker="#lookup/2"><c>lookup/2</c></seealso>, @@ -766,7 +746,7 @@ ok </func> <func> - <name name="next" arity="2"/> + <name name="next" arity="2" since=""/> <fsummary>Return the next key in a Dets table.</fsummary> <desc> <p>Returns either the key following <c><anno>Key1</anno></c> in table @@ -780,7 +760,7 @@ ok </func> <func> - <name name="open_file" arity="1"/> + <name name="open_file" arity="1" since=""/> <fsummary>Open an existing Dets table.</fsummary> <desc> <p>Opens an existing table. If the table is not properly closed, @@ -790,7 +770,7 @@ ok </func> <func> - <name name="open_file" arity="2"/> + <name name="open_file" arity="2" since=""/> <fsummary>Open a Dets table.</fsummary> <desc> <p>Opens a table. An empty Dets table is created if no file @@ -842,8 +822,7 @@ ok maximal value. Notice that a higher value can increase the table fragmentation, and a smaller value can decrease the fragmentation, at - the expense of execution time. Only available for version - 9 tables.</p> + the expense of execution time.</p> </item> <item> <p><c>{min_no_slots, </c><seealso marker="#type-no_slots"> @@ -880,12 +859,7 @@ ok FileName}}</c> is returned if the table must be repaired.</p> <p>Value <c>force</c> means that a reparation is made even if the table is properly closed. - This is how to convert tables created by older versions of - STDLIB. An example is tables hashed with the deprecated - <c>erlang:hash/2</c> BIF. Tables created with Dets from - STDLIB version 1.8.2 or later use function - <c>erlang:phash/2</c> or function <c>erlang:phash2/1</c>, - which is preferred.</p> + This is a seldom needed option.</p> <p>Option <c>repair</c> is ignored if the table is already open.</p> </item> <item> @@ -893,21 +867,12 @@ ok <c>type()</c></seealso><c>}</c> - The table type. Defaults to <c>set</c>.</p> </item> - <item> - <p><c>{version, </c><seealso marker="#type-version"> - <c>version()</c></seealso><c>}</c> - The version of the format - used for the table. Defaults to <c>9</c>. Tables on the format - used before Erlang/OTP R8 can be created by specifying value - <c>8</c>. A version 8 table can be converted to a version 9 - table by specifying options <c>{version,9}</c> - and <c>{repair,force}</c>.</p> - </item> </list> </desc> </func> <func> - <name name="pid2name" arity="1"/> + <name name="pid2name" arity="1" since=""/> <fsummary>Return the name of the Dets table handled by a pid.</fsummary> <desc> <p>Returns the table name given the pid of a process @@ -918,7 +883,7 @@ ok </func> <func> - <name name="repair_continuation" arity="2"/> + <name name="repair_continuation" arity="2" since=""/> <fsummary>Repair a continuation from <c>select/1</c> or <c>select/3</c>. </fsummary> <desc> @@ -952,7 +917,7 @@ ok </func> <func> - <name name="safe_fixtable" arity="2"/> + <name name="safe_fixtable" arity="2" since=""/> <fsummary>Fix a Dets table for safe traversal.</fsummary> <desc> <p>If <c><anno>Fix</anno></c> is <c>true</c>, table @@ -980,7 +945,7 @@ ok </func> <func> - <name name="select" arity="1"/> + <name name="select" arity="1" since=""/> <fsummary>Apply a match specification to some objects stored in a Dets table.</fsummary> <desc> @@ -997,7 +962,7 @@ ok </func> <func> - <name name="select" arity="2"/> + <name name="select" arity="2" since=""/> <fsummary>Apply a match specification to all objects stored in a Dets table.</fsummary> <desc> @@ -1019,7 +984,7 @@ ok </func> <func> - <name name="select" arity="3"/> + <name name="select" arity="3" since=""/> <fsummary>Apply a match specification to the first chunk of objects stored in a Dets table.</fsummary> <desc> @@ -1041,8 +1006,8 @@ ok a time, until at least one object matches or the end of the table is reached. The default, indicated by giving <c><anno>N</anno></c> the value <c>default</c>, is to let the number - of objects vary depending on the sizes of the objects. If - <c><anno>Name</anno></c> is a version 9 table, all objects with the + of objects vary depending on the sizes of the objects. All + objects with the same key are always handled at the same time, which implies that the match specification can be applied to more than <anno>N</anno> objects.</p> @@ -1054,7 +1019,7 @@ ok </func> <func> - <name name="select_delete" arity="2"/> + <name name="select_delete" arity="2" since=""/> <fsummary>Delete all objects that match a given pattern from a Dets table.</fsummary> <desc> @@ -1071,7 +1036,7 @@ ok </func> <func> - <name name="slot" arity="2"/> + <name name="slot" arity="2" since=""/> <fsummary>Return the list of objects associated with a slot of a Dets table.</fsummary> <desc> @@ -1084,7 +1049,7 @@ ok </func> <func> - <name name="sync" arity="1"/> + <name name="sync" arity="1" since=""/> <fsummary>Ensure that all updates made to a Dets table are written to disk.</fsummary> <desc> @@ -1099,8 +1064,8 @@ ok </func> <func> - <name name="table" arity="1"/> - <name name="table" arity="2"/> + <name name="table" arity="1" since=""/> + <name name="table" arity="2" since=""/> <fsummary>Return a QLC query handle.</fsummary> <desc> <p>Returns a Query List @@ -1175,7 +1140,7 @@ true</pre> </func> <func> - <name name="to_ets" arity="2"/> + <name name="to_ets" arity="2" since=""/> <fsummary>Insert all objects of a Dets table into an ETS table.</fsummary> <desc> @@ -1188,7 +1153,7 @@ true</pre> </func> <func> - <name name="traverse" arity="2"/> + <name name="traverse" arity="2" since=""/> <fsummary>Apply a function to all or some objects stored in a Dets table.</fsummary> <desc> @@ -1227,7 +1192,7 @@ fun(X) -> {continue, X} end.</pre> </func> <func> - <name name="update_counter" arity="3"/> + <name name="update_counter" arity="3" since=""/> <fsummary>Update a counter object stored in a Dets table. </fsummary> <desc> diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index c926ff1b5b..95a98cef12 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -28,7 +28,7 @@ <date>1997-01-15</date> <rev>B</rev> </header> - <module>dict</module> + <module since="">dict</module> <modulesummary>Key-value dictionary.</modulesummary> <description> <p>This module provides a <c>Key</c>-<c>Value</c> dictionary. @@ -55,7 +55,7 @@ <funcs> <func> - <name name="append" arity="3"/> + <name name="append" arity="3" since=""/> <fsummary>Append a value to keys in a dictionary.</fsummary> <desc> <p>Appends a new <c><anno>Value</anno></c> to the current list @@ -65,7 +65,7 @@ </func> <func> - <name name="append_list" arity="3"/> + <name name="append_list" arity="3" since=""/> <fsummary>Append new values to keys in a dictionary.</fsummary> <desc> <p>Appends a list of values <c><anno>ValList</anno></c> to @@ -77,7 +77,7 @@ </func> <func> - <name name="erase" arity="2"/> + <name name="erase" arity="2" since=""/> <fsummary>Erase a key from a dictionary.</fsummary> <desc> <p>Erases all items with a given key from a dictionary.</p> @@ -85,7 +85,7 @@ </func> <func> - <name name="fetch" arity="2"/> + <name name="fetch" arity="2" since=""/> <fsummary>Look up values in a dictionary.</fsummary> <desc> <p>Returns the value associated with <c><anno>Key</anno></c> @@ -98,7 +98,7 @@ </func> <func> - <name name="fetch_keys" arity="1"/> + <name name="fetch_keys" arity="1" since=""/> <fsummary>Return all keys in a dictionary.</fsummary> <desc> <p>Returns a list of all keys in dictionary <c>Dict</c>.</p> @@ -106,7 +106,17 @@ </func> <func> - <name name="filter" arity="2"/> + <name name="take" arity="2" since="OTP 20.0"/> + <fsummary>Return value and new dictionary without element with this value.</fsummary> + <desc> + <p>This function returns value from dictionary and a + new dictionary without this value. + Returns <c>error</c> if the key is not present in the dictionary.</p> + </desc> + </func> + + <func> + <name name="filter" arity="2" since=""/> <fsummary>Select elements that satisfy a predicate.</fsummary> <desc> <p><c><anno>Dict2</anno></c> is a dictionary of all keys and values in @@ -117,7 +127,7 @@ </func> <func> - <name name="find" arity="2"/> + <name name="find" arity="2" since=""/> <fsummary>Search for a key in a dictionary.</fsummary> <desc> <p>Searches for a key in dictionary <c>Dict</c>. Returns @@ -129,7 +139,7 @@ </func> <func> - <name name="fold" arity="3"/> + <name name="fold" arity="3" since=""/> <fsummary>Fold a function over a dictionary.</fsummary> <desc> <p>Calls <c><anno>Fun</anno></c> on successive keys and values of @@ -143,7 +153,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since=""/> <fsummary>Convert a list of pairs to a dictionary.</fsummary> <desc> <p>Converts the <c><anno>Key</anno></c>-<c><anno>Value</anno></c> list @@ -152,7 +162,7 @@ </func> <func> - <name name="is_empty" arity="1"/> + <name name="is_empty" arity="1" since="OTP 17.0"/> <fsummary>Return <c>true</c> if the dictionary is empty.</fsummary> <desc> <p>Returns <c>true</c> if dictionary <c><anno>Dict</anno></c> has no @@ -161,7 +171,7 @@ </func> <func> - <name name="is_key" arity="2"/> + <name name="is_key" arity="2" since=""/> <fsummary>Test if a key is in a dictionary.</fsummary> <desc> <p>Tests if <c><anno>Key</anno></c> is contained in @@ -170,7 +180,7 @@ </func> <func> - <name name="map" arity="2"/> + <name name="map" arity="2" since=""/> <fsummary>Map a function over a dictionary.</fsummary> <desc> <p>Calls <c><anno>Fun</anno></c> on successive keys and values @@ -180,7 +190,7 @@ </func> <func> - <name name="merge" arity="3"/> + <name name="merge" arity="3" since=""/> <fsummary>Merge two dictionaries.</fsummary> <desc> <p>Merges two dictionaries, <c><anno>Dict1</anno></c> and @@ -199,7 +209,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Create a dictionary.</fsummary> <desc> <p>Creates a new dictionary.</p> @@ -207,7 +217,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Return the number of elements in a dictionary.</fsummary> <desc> <p>Returns the number of elements in dictionary @@ -216,7 +226,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="store" arity="3"/> + <name name="store" arity="3" since=""/> <fsummary>Store a value in a dictionary.</fsummary> <desc> <p>Stores a <c><anno>Key</anno></c>-<c><anno>Value</anno></c> pair in @@ -227,7 +237,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert a dictionary to a list of pairs.</fsummary> <desc> <p>Converts dictionary <c>Dict</c> to a list representation.</p> @@ -235,7 +245,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="update" arity="3"/> + <name name="update" arity="3" since=""/> <fsummary>Update a value in a dictionary.</fsummary> <desc> <p>Updates a value in a dictionary by calling <c><anno>Fun</anno></c> on @@ -245,7 +255,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="update" arity="4"/> + <name name="update" arity="4" since=""/> <fsummary>Update a value in a dictionary.</fsummary> <desc> <p>Updates a value in a dictionary by calling <c><anno>Fun</anno></c> on @@ -259,7 +269,7 @@ append(Key, Val, D) -> </func> <func> - <name name="update_counter" arity="3"/> + <name name="update_counter" arity="3" since=""/> <fsummary>Increment a value in a dictionary.</fsummary> <desc> <p>Adds <c><anno>Increment</anno></c> to the value associated with diff --git a/lib/stdlib/doc/src/digraph.xml b/lib/stdlib/doc/src/digraph.xml index 5332d7aba5..cf2c0844c9 100644 --- a/lib/stdlib/doc/src/digraph.xml +++ b/lib/stdlib/doc/src/digraph.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>C</rev> <file>digraph.xml</file> </header> - <module>digraph</module> + <module since="">digraph</module> <modulesummary>Directed graphs.</modulesummary> <description> <p>This module provides a version of labeled @@ -144,9 +144,9 @@ <funcs> <func> - <name name="add_edge" arity="3"/> - <name name="add_edge" arity="4"/> - <name name="add_edge" arity="5"/> + <name name="add_edge" arity="3" since=""/> + <name name="add_edge" arity="4" since=""/> + <name name="add_edge" arity="5" since=""/> <fsummary>Add an edge to a digraph.</fsummary> <type name="add_edge_err_rsn"/> <desc> @@ -170,6 +170,10 @@ <p>If the edge would create a cycle in an <seealso marker="#acyclic_digraph">acyclic digraph</seealso>, <c>{error, {bad_edge, <anno>Path</anno>}}</c> is returned. + If <c><anno>G</anno></c> already has an edge with value + <c><anno>E</anno></c> connecting a different pair of vertices, + <c>{error, {bad_edge, [<anno>V1</anno>, <anno>V2</anno>]}}</c> + is returned. If either of <c><anno>V1</anno></c> or <c><anno>V2</anno></c> is not a vertex of digraph <c><anno>G</anno></c>, <c>{error, {bad_vertex, </c><anno>V</anno><c>}}</c> is @@ -179,9 +183,9 @@ </func> <func> - <name name="add_vertex" arity="1"/> - <name name="add_vertex" arity="2"/> - <name name="add_vertex" arity="3"/> + <name name="add_vertex" arity="1" since=""/> + <name name="add_vertex" arity="2" since=""/> + <name name="add_vertex" arity="3" since=""/> <fsummary>Add or modify a vertex of a digraph.</fsummary> <desc> <p><c>add_vertex/3</c> creates (or modifies) vertex @@ -200,7 +204,7 @@ </func> <func> - <name name="del_edge" arity="2"/> + <name name="del_edge" arity="2" since=""/> <fsummary>Delete an edge from a digraph.</fsummary> <desc> <p>Deletes edge <c><anno>E</anno></c> from digraph @@ -209,7 +213,7 @@ </func> <func> - <name name="del_edges" arity="2"/> + <name name="del_edges" arity="2" since=""/> <fsummary>Delete edges from a digraph.</fsummary> <desc> <p>Deletes the edges in list <c><anno>Edges</anno></c> from digraph @@ -218,7 +222,7 @@ </func> <func> - <name name="del_path" arity="3"/> + <name name="del_path" arity="3" since=""/> <fsummary>Delete paths from a digraph.</fsummary> <desc> <p>Deletes edges from digraph <c><anno>G</anno></c> until there are no @@ -248,7 +252,7 @@ </func> <func> - <name name="del_vertex" arity="2"/> + <name name="del_vertex" arity="2" since=""/> <fsummary>Delete a vertex from a digraph.</fsummary> <desc> <p>Deletes vertex <c><anno>V</anno></c> from digraph @@ -261,7 +265,7 @@ </func> <func> - <name name="del_vertices" arity="2"/> + <name name="del_vertices" arity="2" since=""/> <fsummary>Delete vertices from a digraph.</fsummary> <desc> <p>Deletes the vertices in list <c><anno>Vertices</anno></c> from @@ -270,7 +274,7 @@ </func> <func> - <name name="delete" arity="1"/> + <name name="delete" arity="1" since=""/> <fsummary>Delete a digraph.</fsummary> <desc> <p>Deletes digraph <c><anno>G</anno></c>. This call is important @@ -281,7 +285,7 @@ </func> <func> - <name name="edge" arity="2"/> + <name name="edge" arity="2" since=""/> <fsummary>Return the vertices and the label of an edge of a digraph. </fsummary> <desc> @@ -299,7 +303,7 @@ </func> <func> - <name name="edges" arity="1"/> + <name name="edges" arity="1" since=""/> <fsummary>Return all edges of a digraph.</fsummary> <desc> <p>Returns a list of all edges of digraph <c><anno>G</anno></c>, in @@ -308,7 +312,7 @@ </func> <func> - <name name="edges" arity="2"/> + <name name="edges" arity="2" since=""/> <fsummary>Return the edges emanating from or incident on a vertex of a digraph.</fsummary> <desc> @@ -320,7 +324,7 @@ </func> <func> - <name name="get_cycle" arity="2"/> + <name name="get_cycle" arity="2" since=""/> <fsummary>Find one cycle in a digraph.</fsummary> <desc> <p>If a <seealso marker="#simple_cycle">simple cycle</seealso> of @@ -337,7 +341,7 @@ </func> <func> - <name name="get_path" arity="3"/> + <name name="get_path" arity="3" since=""/> <fsummary>Find one path in a digraph.</fsummary> <desc> <p>Tries to find @@ -353,7 +357,7 @@ </func> <func> - <name name="get_short_cycle" arity="2"/> + <name name="get_short_cycle" arity="2" since=""/> <fsummary>Find one short cycle in a digraph.</fsummary> <desc> <p>Tries to find an as short as possible @@ -371,7 +375,7 @@ </func> <func> - <name name="get_short_path" arity="3"/> + <name name="get_short_path" arity="3" since=""/> <fsummary>Find one short path in a digraph.</fsummary> <desc> <p>Tries to find an as short as possible @@ -388,7 +392,7 @@ </func> <func> - <name name="in_degree" arity="2"/> + <name name="in_degree" arity="2" since=""/> <fsummary>Return the in-degree of a vertex of a digraph.</fsummary> <desc> <p>Returns the <seealso marker="#in_degree">in-degree</seealso> of @@ -397,7 +401,7 @@ </func> <func> - <name name="in_edges" arity="2"/> + <name name="in_edges" arity="2" since=""/> <fsummary>Return all edges incident on a vertex of a digraph.</fsummary> <desc> <p>Returns a list of all @@ -408,7 +412,7 @@ </func> <func> - <name name="in_neighbours" arity="2"/> + <name name="in_neighbours" arity="2" since=""/> <fsummary>Return all in-neighbors of a vertex of a digraph.</fsummary> <desc> <p>Returns a list of @@ -419,7 +423,7 @@ </func> <func> - <name name="info" arity="1"/> + <name name="info" arity="1" since=""/> <fsummary>Return information about a digraph.</fsummary> <type name="d_cyclicity"/> <type name="d_protection"/> @@ -449,7 +453,7 @@ </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Return a protected empty digraph, where cycles are allowed. </fsummary> <desc> @@ -458,7 +462,7 @@ </func> <func> - <name name="new" arity="1"/> + <name name="new" arity="1" since=""/> <fsummary>Create a new empty digraph.</fsummary> <type variable="Type"/> <type name="d_type"/> @@ -488,7 +492,7 @@ </func> <func> - <name name="no_edges" arity="1"/> + <name name="no_edges" arity="1" since=""/> <fsummary>Return the number of edges of a digraph.</fsummary> <desc> <p>Returns the number of edges of digraph <c><anno>G</anno></c>.</p> @@ -496,7 +500,7 @@ </func> <func> - <name name="no_vertices" arity="1"/> + <name name="no_vertices" arity="1" since=""/> <fsummary>Return the number of vertices of a digraph.</fsummary> <desc> <p>Returns the number of vertices of digraph <c><anno>G</anno></c>.</p> @@ -504,7 +508,7 @@ </func> <func> - <name name="out_degree" arity="2"/> + <name name="out_degree" arity="2" since=""/> <fsummary>Return the out-degree of a vertex of a digraph.</fsummary> <desc> <p>Returns the <seealso marker="#out_degree">out-degree</seealso> of @@ -513,7 +517,7 @@ </func> <func> - <name name="out_edges" arity="2"/> + <name name="out_edges" arity="2" since=""/> <fsummary>Return all edges emanating from a vertex of a digraph. </fsummary> <desc> @@ -525,7 +529,7 @@ </func> <func> - <name name="out_neighbours" arity="2"/> + <name name="out_neighbours" arity="2" since=""/> <fsummary>Return all out-neighbors of a vertex of a digraph.</fsummary> <desc> <p>Returns a list of @@ -536,7 +540,7 @@ </func> <func> - <name name="vertex" arity="2"/> + <name name="vertex" arity="2" since=""/> <fsummary>Return the label of a vertex of a digraph.</fsummary> <desc> <p>Returns <c>{<anno>V</anno>, <anno>Label</anno>}</c>, @@ -549,7 +553,7 @@ </func> <func> - <name name="vertices" arity="1"/> + <name name="vertices" arity="1" since=""/> <fsummary>Return all vertices of a digraph.</fsummary> <desc> <p>Returns a list of all vertices of digraph <c><anno>G</anno></c>, in diff --git a/lib/stdlib/doc/src/digraph_utils.xml b/lib/stdlib/doc/src/digraph_utils.xml index cb316e5b93..13b0aaad9e 100644 --- a/lib/stdlib/doc/src/digraph_utils.xml +++ b/lib/stdlib/doc/src/digraph_utils.xml @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>digraph_utils.xml</file> </header> - <module>digraph_utils</module> + <module since="">digraph_utils</module> <modulesummary>Algorithms for directed graphs.</modulesummary> <description> <p>This module provides algorithms based on depth-first traversal of @@ -154,7 +154,7 @@ <funcs> <func> - <name name="arborescence_root" arity="1"/> + <name name="arborescence_root" arity="1" since=""/> <fsummary>Check if a digraph is an arborescence.</fsummary> <desc> <p>Returns <c>{yes, <anno>Root</anno>}</c> if <c><anno>Root</anno></c> @@ -164,7 +164,7 @@ </func> <func> - <name name="components" arity="1"/> + <name name="components" arity="1" since=""/> <fsummary>Return the components of a digraph.</fsummary> <desc> <p>Returns a list @@ -177,7 +177,7 @@ </func> <func> - <name name="condensation" arity="1"/> + <name name="condensation" arity="1" since=""/> <fsummary>Return a condensed graph of a digraph.</fsummary> <desc> <p>Creates a digraph where the vertices are @@ -202,7 +202,7 @@ </func> <func> - <name name="cyclic_strong_components" arity="1"/> + <name name="cyclic_strong_components" arity="1" since=""/> <fsummary>Return the cyclic strong components of a digraph.</fsummary> <desc> <p>Returns a list of <seealso marker="#strong_components">strongly @@ -218,7 +218,7 @@ </func> <func> - <name name="is_acyclic" arity="1"/> + <name name="is_acyclic" arity="1" since=""/> <fsummary>Check if a digraph is acyclic.</fsummary> <desc> <p>Returns <c>true</c> if and only if digraph @@ -228,7 +228,7 @@ </func> <func> - <name name="is_arborescence" arity="1"/> + <name name="is_arborescence" arity="1" since=""/> <fsummary>Check if a digraph is an arborescence.</fsummary> <desc> <p>Returns <c>true</c> if and only if digraph @@ -238,7 +238,7 @@ </func> <func> - <name name="is_tree" arity="1"/> + <name name="is_tree" arity="1" since=""/> <fsummary>Check if a digraph is a tree.</fsummary> <desc> <p>Returns <c>true</c> if and only if digraph @@ -248,7 +248,7 @@ </func> <func> - <name name="loop_vertices" arity="1"/> + <name name="loop_vertices" arity="1" since=""/> <fsummary>Return the vertices of a digraph included in some loop. </fsummary> <desc> @@ -258,7 +258,7 @@ </func> <func> - <name name="postorder" arity="1"/> + <name name="postorder" arity="1" since=""/> <fsummary>Return the vertices of a digraph in postorder.</fsummary> <desc> <p>Returns all vertices of digraph <c><anno>Digraph</anno></c>. @@ -273,7 +273,7 @@ </func> <func> - <name name="preorder" arity="1"/> + <name name="preorder" arity="1" since=""/> <fsummary>Return the vertices of a digraph in preorder.</fsummary> <desc> <p>Returns all vertices of digraph <c><anno>Digraph</anno></c>. @@ -285,7 +285,7 @@ </func> <func> - <name name="reachable" arity="2"/> + <name name="reachable" arity="2" since=""/> <fsummary>Return the vertices reachable from some vertices of a digraph. </fsummary> <desc> @@ -300,7 +300,7 @@ </func> <func> - <name name="reachable_neighbours" arity="2"/> + <name name="reachable_neighbours" arity="2" since=""/> <fsummary>Return the neighbors reachable from some vertices of a digraph.</fsummary> <desc> @@ -316,7 +316,7 @@ </func> <func> - <name name="reaching" arity="2"/> + <name name="reaching" arity="2" since=""/> <fsummary>Return the vertices that reach some vertices of a digraph. </fsummary> <desc> @@ -330,7 +330,7 @@ </func> <func> - <name name="reaching_neighbours" arity="2"/> + <name name="reaching_neighbours" arity="2" since=""/> <fsummary>Return the neighbors that reach some vertices of a digraph. </fsummary> <desc> @@ -345,7 +345,7 @@ </func> <func> - <name name="strong_components" arity="1"/> + <name name="strong_components" arity="1" since=""/> <fsummary>Return the strong components of a digraph.</fsummary> <desc> <p>Returns a list of <seealso marker="#strong_components">strongly @@ -359,8 +359,8 @@ </func> <func> - <name name="subgraph" arity="2"/> - <name name="subgraph" arity="3"/> + <name name="subgraph" arity="2" since=""/> + <name name="subgraph" arity="3" since=""/> <fsummary>Return a subgraph of a digraph.</fsummary> <desc> <p>Creates a maximal <seealso marker="#subgraph">subgraph</seealso> @@ -387,7 +387,7 @@ </func> <func> - <name name="topsort" arity="1"/> + <name name="topsort" arity="1" since=""/> <fsummary>Return a topological sorting of the vertices of a digraph. </fsummary> <desc> diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml index 1dc0161398..110c1cea2c 100644 --- a/lib/stdlib/doc/src/epp.xml +++ b/lib/stdlib/doc/src/epp.xml @@ -32,7 +32,7 @@ <rev>B</rev> <file>epp.xml</file> </header> - <module>epp</module> + <module since="">epp</module> <modulesummary>An Erlang code preprocessor.</modulesummary> <description> <p>The Erlang code preprocessor includes functions that are used by the @@ -76,7 +76,7 @@ <funcs> <func> - <name name="close" arity="1"/> + <name name="close" arity="1" since=""/> <fsummary>Close the preprocessing of the file associated with <c>Epp</c>. </fsummary> <desc> @@ -85,7 +85,7 @@ </func> <func> - <name name="default_encoding" arity="0"/> + <name name="default_encoding" arity="0" since="OTP R16B"/> <fsummary>Return the default encoding of Erlang source files.</fsummary> <desc> <p>Returns the default encoding of Erlang source files.</p> @@ -93,7 +93,7 @@ </func> <func> - <name name="encoding_to_string" arity="1"/> + <name name="encoding_to_string" arity="1" since="OTP R16B"/> <fsummary>Return a string representation of an encoding.</fsummary> <desc> <p>Returns a string representation of an encoding. The string @@ -107,7 +107,7 @@ </func> <func> - <name name="format_error" arity="1"/> + <name name="format_error" arity="1" since="OTP R14B03"/> <fsummary>Format an error descriptor.</fsummary> <desc> <p>Takes an <c><anno>ErrorDescriptor</anno></c> and returns @@ -120,10 +120,14 @@ </func> <func> - <name name="open" arity="1"/> + <name name="open" arity="1" since="OTP 17.0"/> <fsummary>Open a file for preprocessing.</fsummary> <desc> <p>Opens a file for preprocessing.</p> + <p>If you want to change the file name of the implicit -file() + attributes inserted during preprocessing, you can do with + <c>{source_name, <anno>SourceName</anno>}</c>. If unset it will + default to the name of the opened file.</p> <p>If <c>extra</c> is specified in <c><anno>Options</anno></c>, the return value is <c>{ok, <anno>Epp</anno>, <anno>Extra</anno>}</c> instead @@ -132,7 +136,7 @@ </func> <func> - <name name="open" arity="2"/> + <name name="open" arity="2" since=""/> <fsummary>Open a file for preprocessing.</fsummary> <desc> <p>Equivalent to @@ -141,7 +145,7 @@ </func> <func> - <name name="open" arity="3"/> + <name name="open" arity="3" since=""/> <fsummary>Open a file for preprocessing.</fsummary> <desc> <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath}, @@ -150,7 +154,7 @@ </func> <func> - <name name="parse_erl_form" arity="1"/> + <name name="parse_erl_form" arity="1" since=""/> <fsummary>Return the next Erlang form from the opened Erlang source file. </fsummary> <type name="warning_info"/> @@ -163,12 +167,16 @@ </func> <func> - <name name="parse_file" arity="2"/> + <name name="parse_file" arity="2" since="OTP 17.0"/> <fsummary>Preprocess and parse an Erlang source file.</fsummary> <desc> <p>Preprocesses and parses an Erlang source file. Notice that tuple <c>{eof, <anno>Line</anno>}</c> returned at the end of the file is included as a "form".</p> + <p>If you want to change the file name of the implicit -file() + attributes inserted during preprocessing, you can do with + <c>{source_name, <anno>SourceName</anno>}</c>. If unset it will + default to the name of the opened file.</p> <p>If <c>extra</c> is specified in <c><anno>Options</anno></c>, the return value is <c>{ok, [<anno>Form</anno>], <anno>Extra</anno>}</c> instead @@ -177,7 +185,7 @@ </func> <func> - <name name="parse_file" arity="3"/> + <name name="parse_file" arity="3" since=""/> <fsummary>Preprocess and parse an Erlang source file.</fsummary> <desc> <p>Equivalent to <c>epp:parse_file(FileName, [{includes, IncludePath}, @@ -186,8 +194,8 @@ </func> <func> - <name name="read_encoding" arity="1"/> - <name name="read_encoding" arity="2"/> + <name name="read_encoding" arity="1" since="OTP R16B"/> + <name name="read_encoding" arity="2" since="OTP R16B"/> <fsummary>Read the encoding from a file.</fsummary> <desc> <p>Read the <seealso marker="#encoding">encoding</seealso> from @@ -201,8 +209,8 @@ </func> <func> - <name name="read_encoding_from_binary" arity="1"/> - <name name="read_encoding_from_binary" arity="2"/> + <name name="read_encoding_from_binary" arity="1" since="OTP R16B"/> + <name name="read_encoding_from_binary" arity="2" since="OTP R16B"/> <fsummary>Read the encoding from a binary.</fsummary> <desc> <p>Read the <seealso marker="#encoding">encoding</seealso> from @@ -216,7 +224,7 @@ </func> <func> - <name name="set_encoding" arity="1"/> + <name name="set_encoding" arity="1" since="OTP R16B"/> <fsummary>Read and set the encoding of an I/O device.</fsummary> <desc> <p>Reads the <seealso marker="#encoding">encoding</seealso> from @@ -231,7 +239,7 @@ </func> <func> - <name name="set_encoding" arity="2"/> + <name name="set_encoding" arity="2" since="OTP 17.0"/> <fsummary>Read and set the encoding of an I/O device.</fsummary> <desc> <p>Reads the <seealso marker="#encoding">encoding</seealso> from diff --git a/lib/stdlib/doc/src/erl_anno.xml b/lib/stdlib/doc/src/erl_anno.xml index f316f63d98..dff93619ab 100644 --- a/lib/stdlib/doc/src/erl_anno.xml +++ b/lib/stdlib/doc/src/erl_anno.xml @@ -34,7 +34,7 @@ <rev>A</rev> <file>erl_anno.xml</file> </header> - <module>erl_anno</module> + <module since="OTP 18.0">erl_anno</module> <modulesummary>Abstract datatype for the annotations of the Erlang Compiler. </modulesummary> @@ -135,7 +135,7 @@ <funcs> <func> - <name name="column" arity="1"/> + <name name="column" arity="1" since="OTP 18.0"/> <fsummary>Return the column.</fsummary> <type name="column"></type> <desc> @@ -144,7 +144,7 @@ </func> <func> - <name name="end_location" arity="1"/> + <name name="end_location" arity="1" since="OTP 18.0"/> <fsummary>Return the end location of the text.</fsummary> <type name="location"></type> <desc> @@ -155,7 +155,7 @@ </func> <func> - <name name="file" arity="1"/> + <name name="file" arity="1" since="OTP 18.0"/> <fsummary>Return the filename.</fsummary> <type name="filename"></type> <desc> @@ -165,7 +165,7 @@ </func> <func> - <name name="from_term" arity="1"/> + <name name="from_term" arity="1" since="OTP 18.0"/> <fsummary>Return annotations given a term.</fsummary> <desc> <p>Returns annotations with representation <anno>Term</anno>.</p> @@ -174,7 +174,7 @@ </func> <func> - <name name="generated" arity="1"/> + <name name="generated" arity="1" since="OTP 18.0"/> <fsummary>Return the generated Boolean.</fsummary> <type name="generated"></type> <desc> @@ -185,7 +185,7 @@ </func> <func> - <name name="is_anno" arity="1"/> + <name name="is_anno" arity="1" since="OTP 18.0"/> <fsummary>Test for a collection of annotations.</fsummary> <desc> <p>Returns <c>true</c> if <anno>Term</anno> is a collection of @@ -194,7 +194,7 @@ </func> <func> - <name name="line" arity="1"/> + <name name="line" arity="1" since="OTP 18.0"/> <fsummary>Return the line.</fsummary> <type name="line"></type> <desc> @@ -203,7 +203,7 @@ </func> <func> - <name name="location" arity="1"/> + <name name="location" arity="1" since="OTP 18.0"/> <fsummary>Return the location.</fsummary> <type name="location"></type> <desc> @@ -212,7 +212,7 @@ </func> <func> - <name name="new" arity="1"/> + <name name="new" arity="1" since="OTP 18.0"/> <fsummary>Create a new collection of annotations.</fsummary> <type name="location"></type> <desc> @@ -221,7 +221,7 @@ </func> <func> - <name name="set_file" arity="2"/> + <name name="set_file" arity="2" since="OTP 18.0"/> <fsummary>Modify the filename.</fsummary> <type name="filename"></type> <desc> @@ -230,7 +230,7 @@ </func> <func> - <name name="set_generated" arity="2"/> + <name name="set_generated" arity="2" since="OTP 18.0"/> <fsummary>Modify the generated marker.</fsummary> <type name="generated"></type> <desc> @@ -240,7 +240,7 @@ </func> <func> - <name name="set_line" arity="2"/> + <name name="set_line" arity="2" since="OTP 18.0"/> <fsummary>Modify the line.</fsummary> <type name="line"></type> <desc> @@ -249,7 +249,7 @@ </func> <func> - <name name="set_location" arity="2"/> + <name name="set_location" arity="2" since="OTP 18.0"/> <fsummary>Modify the location.</fsummary> <type name="location"></type> <desc> @@ -258,7 +258,7 @@ </func> <func> - <name name="set_record" arity="2"/> + <name name="set_record" arity="2" since="OTP 18.0"/> <fsummary>Modify the record marker.</fsummary> <type name="record"></type> <desc> @@ -267,7 +267,7 @@ </func> <func> - <name name="set_text" arity="2"/> + <name name="set_text" arity="2" since="OTP 18.0"/> <fsummary>Modify the text.</fsummary> <type name="text"></type> <desc> @@ -276,7 +276,7 @@ </func> <func> - <name name="text" arity="1"/> + <name name="text" arity="1" since="OTP 18.0"/> <fsummary>Return the text.</fsummary> <type name="text"></type> <desc> @@ -286,7 +286,7 @@ </func> <func> - <name name="to_term" arity="1"/> + <name name="to_term" arity="1" since="OTP 18.0"/> <fsummary>Return the term representing a collection of annotations. </fsummary> <desc> diff --git a/lib/stdlib/doc/src/erl_eval.xml b/lib/stdlib/doc/src/erl_eval.xml index 1c0f7f062f..813cbecd89 100644 --- a/lib/stdlib/doc/src/erl_eval.xml +++ b/lib/stdlib/doc/src/erl_eval.xml @@ -32,7 +32,7 @@ <rev>B</rev> <file>erl_eval.xml</file> </header> - <module>erl_eval</module> + <module since="">erl_eval</module> <modulesummary>The Erlang meta interpreter.</modulesummary> <description> <p>This module provides an interpreter for Erlang expressions. The @@ -96,7 +96,7 @@ <funcs> <func> - <name name="add_binding" arity="3"/> + <name name="add_binding" arity="3" since=""/> <fsummary>Add a binding.</fsummary> <desc> <p>Adds binding <c><anno>Name</anno>=<anno>Value</anno></c> @@ -106,7 +106,7 @@ </func> <func> - <name name="binding" arity="2"/> + <name name="binding" arity="2" since=""/> <fsummary>Return bindings.</fsummary> <desc> <p>Returns the binding of <c><anno>Name</anno></c> @@ -115,7 +115,7 @@ </func> <func> - <name name="bindings" arity="1"/> + <name name="bindings" arity="1" since=""/> <fsummary>Return bindings.</fsummary> <desc> <p>Returns the list of bindings contained in the binding @@ -124,7 +124,7 @@ </func> <func> - <name name="del_binding" arity="2"/> + <name name="del_binding" arity="2" since=""/> <fsummary>Delete a binding.</fsummary> <desc> <p>Removes the binding of <c><anno>Name</anno></c> @@ -134,10 +134,10 @@ </func> <func> - <name name="expr" arity="2"/> - <name name="expr" arity="3"/> - <name name="expr" arity="4"/> - <name name="expr" arity="5"/> + <name name="expr" arity="2" since=""/> + <name name="expr" arity="3" since=""/> + <name name="expr" arity="4" since=""/> + <name name="expr" arity="5" since=""/> <fsummary>Evaluate expression.</fsummary> <desc> <p>Evaluates <c><anno>Expression</anno></c> with the set of bindings @@ -157,9 +157,9 @@ </func> <func> - <name name="expr_list" arity="2"/> - <name name="expr_list" arity="3"/> - <name name="expr_list" arity="4"/> + <name name="expr_list" arity="2" since=""/> + <name name="expr_list" arity="3" since=""/> + <name name="expr_list" arity="4" since=""/> <fsummary>Evaluate a list of expressions.</fsummary> <desc> <p>Evaluates a list of expressions in parallel, using the same @@ -174,9 +174,9 @@ </func> <func> - <name name="exprs" arity="2"/> - <name name="exprs" arity="3"/> - <name name="exprs" arity="4"/> + <name name="exprs" arity="2" since=""/> + <name name="exprs" arity="3" since=""/> + <name name="exprs" arity="4" since=""/> <fsummary>Evaluate expressions.</fsummary> <desc> <p>Evaluates <c><anno>Expressions</anno></c> with the set of bindings @@ -197,7 +197,7 @@ </func> <func> - <name name="new_bindings" arity="0"/> + <name name="new_bindings" arity="0" since=""/> <fsummary>Return a bindings structure.</fsummary> <desc> <p>Returns an empty binding structure.</p> diff --git a/lib/stdlib/doc/src/erl_expand_records.xml b/lib/stdlib/doc/src/erl_expand_records.xml index 7e4aa2db37..20e5f1960b 100644 --- a/lib/stdlib/doc/src/erl_expand_records.xml +++ b/lib/stdlib/doc/src/erl_expand_records.xml @@ -34,7 +34,7 @@ <rev>PA1</rev> <file>erl_expand_records.xml</file> </header> - <module>erl_expand_records</module> + <module since="">erl_expand_records</module> <modulesummary>Expands records in a module.</modulesummary> <description> <p>This module expands records in a module.</p> @@ -42,11 +42,13 @@ <funcs> <func> - <name name="module" arity="2"/> + <name name="module" arity="2" since=""/> <fsummary>Expand all records in a module.</fsummary> <desc> - <p>Expands all records in a module. The returned module has no - references to records, attributes, or code.</p> + <p>Expands all records in a module to use explicit tuple + operations and adds explicit module names to calls to BIFs and + imported functions. The returned module has no references to + records, attributes, or code.</p> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/erl_id_trans.xml b/lib/stdlib/doc/src/erl_id_trans.xml index 16952a9582..ec66842ac0 100644 --- a/lib/stdlib/doc/src/erl_id_trans.xml +++ b/lib/stdlib/doc/src/erl_id_trans.xml @@ -34,7 +34,7 @@ <rev>B</rev> <file>erl_id_trans.xml</file> </header> - <module>erl_id_trans</module> + <module since="">erl_id_trans</module> <modulesummary>An identity parse transform.</modulesummary> <description> <p>This module performs an identity parse transformation of Erlang code. @@ -46,7 +46,7 @@ <funcs> <func> - <name>parse_transform(Forms, Options) -> Forms</name> + <name since="">parse_transform(Forms, Options) -> Forms</name> <fsummary>Transform Erlang forms.</fsummary> <type> <v>Forms = [<seealso marker="erl_parse#type-abstract_form">erl_parse:abstract_form()</seealso> diff --git a/lib/stdlib/doc/src/erl_internal.xml b/lib/stdlib/doc/src/erl_internal.xml index cf49df0972..77551ffed7 100644 --- a/lib/stdlib/doc/src/erl_internal.xml +++ b/lib/stdlib/doc/src/erl_internal.xml @@ -34,7 +34,7 @@ <rev>B</rev> <file>erl_internal.xml</file> </header> - <module>erl_internal</module> + <module since="">erl_internal</module> <modulesummary>Internal Erlang definitions.</modulesummary> <description> <p>This module defines Erlang BIFs, guard tests, and operators. @@ -44,7 +44,17 @@ <funcs> <func> - <name name="arith_op" arity="2"/> + <name name="add_predefined_functions" arity="1" since="OTP 20.0"/> + <fsummary>Add code for pre-defined functions.</fsummary> + <desc> + <p>Adds to <c><anno>Forms</anno></c> the code for the standard + pre-defined functions (such as <c>module_info/0</c>) that are + to be included in every module.</p> + </desc> + </func> + + <func> + <name name="arith_op" arity="2" since=""/> <fsummary>Test for an arithmetic operator.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>OpName</anno>/<anno>Arity</anno></c> @@ -53,7 +63,7 @@ </func> <func> - <name name="bif" arity="2"/> + <name name="bif" arity="2" since=""/> <fsummary>Test for an Erlang BIF.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Name</anno>/<anno>Arity</anno></c> @@ -63,7 +73,7 @@ </func> <func> - <name name="bool_op" arity="2"/> + <name name="bool_op" arity="2" since=""/> <fsummary>Test for a Boolean operator.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>OpName</anno>/<anno>Arity</anno></c> @@ -72,7 +82,7 @@ </func> <func> - <name name="comp_op" arity="2"/> + <name name="comp_op" arity="2" since=""/> <fsummary>Test for a comparison operator.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>OpName</anno>/<anno>Arity</anno></c> @@ -81,7 +91,7 @@ </func> <func> - <name name="guard_bif" arity="2"/> + <name name="guard_bif" arity="2" since=""/> <fsummary>Test for an Erlang BIF allowed in guards.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Name</anno>/<anno>Arity</anno></c> is @@ -90,7 +100,7 @@ </func> <func> - <name name="list_op" arity="2"/> + <name name="list_op" arity="2" since=""/> <fsummary>Test for a list operator.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>OpName</anno>/<anno>Arity</anno></c> @@ -99,7 +109,7 @@ </func> <func> - <name name="op_type" arity="2"/> + <name name="op_type" arity="2" since=""/> <fsummary>Return operator type.</fsummary> <desc> <p>Returns the <c><anno>Type</anno></c> of operator that @@ -110,7 +120,7 @@ </func> <func> - <name name="send_op" arity="2"/> + <name name="send_op" arity="2" since=""/> <fsummary>Test for a send operator.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>OpName</anno>/<anno>Arity</anno></c> @@ -119,7 +129,7 @@ </func> <func> - <name name="type_test" arity="2"/> + <name name="type_test" arity="2" since=""/> <fsummary>Test for a valid type test.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Name</anno>/<anno>Arity</anno></c> is diff --git a/lib/stdlib/doc/src/erl_lint.xml b/lib/stdlib/doc/src/erl_lint.xml index 77cb7a9916..12eaafc3a8 100644 --- a/lib/stdlib/doc/src/erl_lint.xml +++ b/lib/stdlib/doc/src/erl_lint.xml @@ -32,7 +32,7 @@ <rev>B</rev> <file>erl_lint.xml</file> </header> - <module>erl_lint</module> + <module since="">erl_lint</module> <modulesummary>The Erlang code linter.</modulesummary> <description> <p>This module is used to check Erlang code for illegal syntax and @@ -78,7 +78,7 @@ <funcs> <func> - <name name="format_error" arity="1"/> + <name name="format_error" arity="1" since=""/> <fsummary>Format an error descriptor.</fsummary> <desc> <p>Takes an <c><anno>ErrorDescriptor</anno></c> and returns a string @@ -90,7 +90,7 @@ </func> <func> - <name name="is_guard_test" arity="1"/> + <name name="is_guard_test" arity="1" since=""/> <fsummary>Test for a guard test.</fsummary> <desc> <p>Tests if <c><anno>Expr</anno></c> is a legal guard test. @@ -102,9 +102,9 @@ </func> <func> - <name name="module" arity="1"/> - <name name="module" arity="2"/> - <name name="module" arity="3"/> + <name name="module" arity="1" since=""/> + <name name="module" arity="2" since=""/> + <name name="module" arity="3" since=""/> <fsummary>Check a module for errors.</fsummary> <desc> <p>Checks all the forms in a module for errors. It returns:</p> diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml index 647f36883c..8142e5c0aa 100644 --- a/lib/stdlib/doc/src/erl_parse.xml +++ b/lib/stdlib/doc/src/erl_parse.xml @@ -32,7 +32,7 @@ <rev>B</rev> <file>erl_parse.xml</file> </header> - <module>erl_parse</module> + <module since="">erl_parse</module> <modulesummary>The Erlang parser.</modulesummary> <description> <p>This module is the basic Erlang parser that converts tokens into @@ -89,7 +89,7 @@ <funcs> <func> - <name name="abstract" arity="1"/> + <name name="abstract" arity="1" since=""/> <fsummary>Convert an Erlang term into an abstract form.</fsummary> <desc> <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an @@ -102,7 +102,7 @@ </func> <func> - <name name="abstract" arity="2"/> + <name name="abstract" arity="2" since="OTP R16B01"/> <fsummary>Convert an Erlang term into an abstract form.</fsummary> <type name="encoding_func"/> <desc> @@ -124,7 +124,7 @@ </func> <func> - <name name="anno_from_term" arity="1"/> + <name name="anno_from_term" arity="1" since="OTP 18.0"/> <fsummary>Return annotations as terms.</fsummary> <desc> <p>Assumes that <c><anno>Term</anno></c> is a term with the same @@ -140,7 +140,7 @@ </func> <func> - <name name="anno_to_term" arity="1"/> + <name name="anno_to_term" arity="1" since="OTP 18.0"/> <fsummary>Return the representation of annotations.</fsummary> <desc> <p>Returns a term where each collection of annotations @@ -154,7 +154,7 @@ </func> <func> - <name name="fold_anno" arity="3"/> + <name name="fold_anno" arity="3" since="OTP 18.0"/> <fsummary>Fold a function over the annotations of an <c>erl_parse</c> tree. </fsummary> <desc> @@ -171,7 +171,7 @@ </func> <func> - <name>format_error(ErrorDescriptor) -> Chars</name> + <name since="">format_error(ErrorDescriptor) -> Chars</name> <fsummary>Format an error descriptor.</fsummary> <type> <v>ErrorDescriptor = <seealso @@ -188,7 +188,7 @@ </func> <func> - <name name="map_anno" arity="2"/> + <name name="map_anno" arity="2" since="OTP 18.0"/> <fsummary>Map a function over the annotations of an <c>erl_parse</c> tree. </fsummary> <desc> @@ -201,7 +201,7 @@ </func> <func> - <name name="mapfold_anno" arity="3"/> + <name name="mapfold_anno" arity="3" since="OTP 18.0"/> <fsummary>Map and fold a function over the annotations of an <c>erl_parse</c> tree.</fsummary> <desc> @@ -220,7 +220,7 @@ </func> <func> - <name name="new_anno" arity="1"/> + <name name="new_anno" arity="1" since="OTP 18.0"/> <fsummary>Create new annotations.</fsummary> <desc> <p>Assumes that <c><anno>Term</anno></c> is a term with the same @@ -236,7 +236,7 @@ </func> <func> - <name name="normalise" arity="1"/> + <name name="normalise" arity="1" since=""/> <fsummary>Convert abstract form to an Erlang term.</fsummary> <desc> <p>Converts the abstract form <c><anno>AbsTerm</anno></c> of a @@ -247,7 +247,7 @@ </func> <func> - <name name="parse_exprs" arity="1"/> + <name name="parse_exprs" arity="1" since=""/> <fsummary>Parse Erlang expressions.</fsummary> <desc> <p>Parses <c><anno>Tokens</anno></c> as if it was a list of expressions. @@ -267,7 +267,7 @@ </func> <func> - <name name="parse_form" arity="1"/> + <name name="parse_form" arity="1" since=""/> <fsummary>Parse an Erlang form.</fsummary> <desc> <p>Parses <c><anno>Tokens</anno></c> as if it was a form. Returns one @@ -287,7 +287,7 @@ </func> <func> - <name name="parse_term" arity="1"/> + <name name="parse_term" arity="1" since=""/> <fsummary>Parse an Erlang term.</fsummary> <desc> <p>Parses <c><anno>Tokens</anno></c> as if it was a term. Returns @@ -307,8 +307,8 @@ </func> <func> - <name name="tokens" arity="1"/> - <name name="tokens" arity="2"/> + <name name="tokens" arity="1" since=""/> + <name name="tokens" arity="2" since=""/> <fsummary>Generate a list of tokens for an expression.</fsummary> <desc> <p>Generates a list of tokens representing the abstract diff --git a/lib/stdlib/doc/src/erl_pp.xml b/lib/stdlib/doc/src/erl_pp.xml index 77a7f1e8d1..f1c3aa5a41 100644 --- a/lib/stdlib/doc/src/erl_pp.xml +++ b/lib/stdlib/doc/src/erl_pp.xml @@ -34,7 +34,7 @@ <rev>B</rev> <file>erl_pp.xml</file> </header> - <module>erl_pp</module> + <module since="">erl_pp</module> <modulesummary>The Erlang pretty printer.</modulesummary> <description> <p>The functions in this module are used to generate @@ -73,8 +73,8 @@ <funcs> <func> - <name name="attribute" arity="1"/> - <name name="attribute" arity="2"/> + <name name="attribute" arity="1" since=""/> + <name name="attribute" arity="2" since=""/> <fsummary>Pretty print an attribute.</fsummary> <desc> <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, @@ -83,10 +83,10 @@ </func> <func> - <name name="expr" arity="1"/> - <name name="expr" arity="2"/> - <name name="expr" arity="3"/> - <name name="expr" arity="4"/> + <name name="expr" arity="1" since=""/> + <name name="expr" arity="2" since=""/> + <name name="expr" arity="3" since=""/> + <name name="expr" arity="4" since=""/> <fsummary>Pretty print one <c>Expression</c>.</fsummary> <desc> <p>Prints one expression. It is useful for implementing hooks (see @@ -96,9 +96,9 @@ </func> <func> - <name name="exprs" arity="1"/> - <name name="exprs" arity="2"/> - <name name="exprs" arity="3"/> + <name name="exprs" arity="1" since=""/> + <name name="exprs" arity="2" since=""/> + <name name="exprs" arity="3" since=""/> <fsummary>Pretty print <c>Expressions</c>.</fsummary> <desc> <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, @@ -108,8 +108,8 @@ </func> <func> - <name name="form" arity="1"/> - <name name="form" arity="2"/> + <name name="form" arity="1" since=""/> + <name name="form" arity="2" since=""/> <fsummary>Pretty print a form.</fsummary> <desc> <p>Pretty prints a @@ -120,8 +120,8 @@ </func> <func> - <name name="function" arity="1"/> - <name name="function" arity="2"/> + <name name="function" arity="1" since=""/> + <name name="function" arity="2" since=""/> <fsummary>Pretty print a function.</fsummary> <desc> <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, @@ -130,8 +130,8 @@ </func> <func> - <name name="guard" arity="1"/> - <name name="guard" arity="2"/> + <name name="guard" arity="1" since=""/> + <name name="guard" arity="2" since=""/> <fsummary>Pretty print a guard.</fsummary> <desc> <p>Same as <seealso marker="#form/1"><c>form/1,2</c></seealso>, diff --git a/lib/stdlib/doc/src/erl_scan.xml b/lib/stdlib/doc/src/erl_scan.xml index 137ccd3416..38111f73bc 100644 --- a/lib/stdlib/doc/src/erl_scan.xml +++ b/lib/stdlib/doc/src/erl_scan.xml @@ -32,7 +32,7 @@ <rev>B</rev> <file>erl_scan.xml</file> </header> - <module>erl_scan</module> + <module since="">erl_scan</module> <modulesummary>The Erlang token scanner.</modulesummary> <description> <p>This module contains functions for tokenizing (scanning) characters into @@ -74,7 +74,7 @@ <funcs> <func> - <name name="category" arity="1"/> + <name name="category" arity="1" since="OTP 18.0"/> <fsummary>Return the category.</fsummary> <desc> <p>Returns the category of <c><anno>Token</anno></c>.</p> @@ -82,7 +82,7 @@ </func> <func> - <name name="column" arity="1"/> + <name name="column" arity="1" since="OTP 18.0"/> <fsummary>Return the column.</fsummary> <desc> <p>Returns the column of <c><anno>Token</anno></c>'s @@ -91,7 +91,7 @@ </func> <func> - <name name="end_location" arity="1"/> + <name name="end_location" arity="1" since="OTP 18.0"/> <fsummary>Return the end location of the text.</fsummary> <desc> <p>Returns the end location of the text of @@ -101,7 +101,7 @@ </func> <func> - <name name="format_error" arity="1"/> + <name name="format_error" arity="1" since=""/> <fsummary>Format an error descriptor.</fsummary> <desc> <p>Uses an <c><anno>ErrorDescriptor</anno></c> and returns a string @@ -113,7 +113,7 @@ </func> <func> - <name name="line" arity="1"/> + <name name="line" arity="1" since="OTP 18.0"/> <fsummary>Return the line.</fsummary> <desc> <p>Returns the line of <c><anno>Token</anno></c>'s collection @@ -122,7 +122,7 @@ </func> <func> - <name name="location" arity="1"/> + <name name="location" arity="1" since="OTP 18.0"/> <fsummary>Return the location.</fsummary> <desc> <p>Returns the location of <c><anno>Token</anno></c>'s @@ -131,7 +131,7 @@ </func> <func> - <name name="reserved_word" arity="1"/> + <name name="reserved_word" arity="1" since=""/> <fsummary>Test for a reserved word.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Atom</anno></c> is an @@ -140,9 +140,9 @@ </func> <func> - <name name="string" arity="1"/> - <name name="string" arity="2"/> - <name name="string" arity="3"/> + <name name="string" arity="1" since=""/> + <name name="string" arity="2" since=""/> + <name name="string" arity="3" since=""/> <fsummary>Scan a string and return the Erlang tokens.</fsummary> <desc> <p>Takes the list of characters <c><anno>String</anno></c> and tries to @@ -229,7 +229,7 @@ </func> <func> - <name name="symbol" arity="1"/> + <name name="symbol" arity="1" since="OTP 18.0"/> <fsummary>Return the symbol.</fsummary> <desc> <p>Returns the symbol of <c><anno>Token</anno></c>.</p> @@ -237,7 +237,7 @@ </func> <func> - <name name="text" arity="1"/> + <name name="text" arity="1" since="OTP 18.0"/> <fsummary>Return the text.</fsummary> <desc> <p>Returns the text of <c><anno>Token</anno></c>'s collection @@ -247,8 +247,8 @@ </func> <func> - <name name="tokens" arity="3"/> - <name name="tokens" arity="4"/> + <name name="tokens" arity="3" since=""/> + <name name="tokens" arity="4" since=""/> <fsummary>Re-entrant scanner.</fsummary> <type name="char_spec"/> <type name="return_cont"/> diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index 24e7b64b9e..ea8173748a 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,17 +32,18 @@ <rev>A</rev> <file>erl_tar.xml</file> </header> - <module>erl_tar</module> + <module since="">erl_tar</module> <modulesummary>Unix 'tar' utility for reading and writing tar archives. </modulesummary> <description> <p>This module archives and extract files to and from - a tar file. This module supports the <c>ustar</c> format - (IEEE Std 1003.1 and ISO/IEC 9945-1). All modern <c>tar</c> - programs (including GNU tar) can read this format. To ensure that - that GNU tar produces a tar file that <c>erl_tar</c> can read, - specify option <c>--format=ustar</c> to GNU tar.</p> - + a tar file. This module supports reading most common tar formats, + namely v7, STAR, USTAR, and PAX, as well as some of GNU tar's extensions + to the USTAR format (sparse files most notably). It produces tar archives + in USTAR format, unless the files being archived require PAX format due to + restrictions in USTAR (such as unicode metadata, filename length, and more). + As such, <c>erl_tar</c> supports tar archives produced by most all modern + tar utilities, and produces tarballs which should be similarly portable.</p> <p>By convention, the name of a tar file is to end in "<c>.tar</c>". To abide to the convention, add "<c>.tar</c>" to the name.</p> @@ -83,12 +84,14 @@ <p>If <seealso marker="kernel:file#native_name_encoding/0"> <c>file:native_name_encoding/0</c></seealso> returns <c>latin1</c>, no translation of path names is done.</p> + + <p>Unicode metadata stored in PAX headers is preserved</p> </section> <section> <title>Other Storage Media</title> - <p>The <seealso marker="inets:ftp"><c>ftp</c></seealso> - module (Inets) normally accesses the tar file on disk using + <p>The <seealso marker="ftp:ftp"><c>ftp</c></seealso> + module normally accesses the tar file on disk using the <seealso marker="kernel:file"><c>file</c></seealso> module. When other needs arise, you can define your own low-level Erlang functions to perform the writing and reading on the storage media; @@ -104,34 +107,38 @@ <title>Limitations</title> <list type="bulleted"> <item> - <p>For maximum compatibility, it is safe to archive files with names - up to 100 characters in length. Such tar files can generally be - extracted by any <c>tar</c> program.</p> + <p>If you must remain compatible with the USTAR tar format, you must ensure file paths being + stored are less than 255 bytes in total, with a maximum filename component + length of 100 bytes. USTAR uses a header field (prefix) in addition to the name field, and + splits file paths longer than 100 bytes into two parts. This split is done on a directory boundary, + and is done in such a way to make the best use of the space available in those two fields, but in practice + this will often mean that you have less than 255 bytes for a path. <c>erl_tar</c> will + automatically upgrade the format to PAX to handle longer filenames, so this is only an issue if you + need to extract the archive with an older implementation of <c>erl_tar</c> or <c>tar</c> which does + not support PAX. In this case, the PAX headers will be extracted as regular files, and you will need to + apply them manually.</p> </item> <item> - <p>For filenames exceeding 100 characters in length, the resulting tar - file can only be correctly extracted by a POSIX-compatible <c>tar</c> - program (such as Solaris <c>tar</c> or a modern GNU <c>tar</c>).</p> - </item> - <item> - <p>Files with longer names than 256 bytes cannot be stored.</p> - </item> - <item> - <p>The file name a symbolic link points is always limited - to 100 characters.</p> + <p>Like the above, if you must remain USTAR compatible, you must also ensure than paths for + symbolic/hard links are no more than 100 bytes, otherwise PAX headers will be used.</p> </item> </list> </section> <funcs> <func> - <name>add(TarDescriptor, Filename, Options) -> RetValue</name> + <name since="">add(TarDescriptor, Filename, Options) -> RetValue</name> <fsummary>Add a file to an open tar file.</fsummary> <type> <v>TarDescriptor = term()</v> - <v>Filename = filename()</v> + <v>FilenameOrBin = filename()|binary()</v> + <v>NameInArchive = filename()</v> + <v>Filename = filename()|{NameInArchive,FilenameOrBin}</v> <v>Options = [Option]</v> <v>Option = dereference|verbose|{chunks,ChunkSize}</v> + <v>|{atime,non_neg_integer()}|{mtime,non_neg_integer()}</v> + <v>|{ctime,non_neg_integer()}|{uid,non_neg_integer()}</v> + <v>|{gid,non_neg_integer()}</v> <v>ChunkSize = positive_integer()</v> <v>RetValue = ok|{error,{Filename,Reason}}</v> <v>Reason = term()</v> @@ -139,6 +146,9 @@ <desc> <p>Adds a file to a tar file that has been opened for writing by <seealso marker="#open/2"><c>open/1</c></seealso>.</p> + <p><c>NameInArchive</c> is the name under which the file becomes + stored in the tar file. The file gets this name when it is + extracted from the tar file.</p> <p>Options:</p> <taglist> <tag><c>dereference</c></tag> @@ -160,12 +170,48 @@ <seealso marker="ssh:ssh_sftp#open_tar/3"> <c>ssh_sftp:open_tar/3</c></seealso>.</p> </item> + <tag><c>{atime,non_neg_integer()}</c></tag> + <item> + <p>Sets the last time, as + <seealso marker="erts:time_correction#POSIX_Time"> + POSIX time</seealso>, when the file was read. See also + <seealso marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seealso>.</p> + </item> + <tag><c>{mtime,non_neg_integer()}</c></tag> + <item> + <p>Sets the last time, as + <seealso marker="erts:time_correction#POSIX_Time"> + POSIX time</seealso>, when the file was written. See also + <seealso marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seealso>.</p> + </item> + <tag><c>{ctime,non_neg_integer()}</c></tag> + <item> + <p>Sets the time, as + <seealso marker="erts:time_correction#POSIX_Time"> + POSIX time</seealso>, when the file was created. See also + <seealso marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seealso>.</p> + </item> + <tag><c>{uid,non_neg_integer()}</c></tag> + <item> + <p>Sets the file owner. + <seealso marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seealso>.</p> + </item> + <tag><c>{gid,non_neg_integer()}</c></tag> + <item> + <p>Sets the group that the file owner belongs to. + <seealso marker="kernel:file#read_file_info/1"> + <c>file:read_file_info/1</c></seealso>.</p> + </item> </taglist> </desc> </func> <func> - <name>add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> + <name since="">add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue </name> <fsummary>Add a file to an open tar file.</fsummary> <type> @@ -183,14 +229,11 @@ <seealso marker="#open/2"><c>open/2</c></seealso>. This function accepts the same options as <seealso marker="#add/3"><c>add/3</c></seealso>.</p> - <p><c>NameInArchive</c> is the name under which the file becomes - stored in the tar file. The file gets this name when it is - extracted from the tar file.</p> </desc> </func> <func> - <name>close(TarDescriptor)</name> + <name since="">close(TarDescriptor)</name> <fsummary>Close an open tar file.</fsummary> <type> <v>TarDescriptor = term()</v> @@ -202,12 +245,12 @@ </func> <func> - <name>create(Name, FileList) ->RetValue </name> + <name since="">create(Name, FileList) ->RetValue </name> <fsummary>Create a tar archive.</fsummary> <type> <v>Name = filename()</v> - <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, - Filename}]</v> + <v>FileList = [Filename|{NameInArchive, FilenameOrBin}]</v> + <v>FilenameOrBin = filename()|binary()</v> <v>Filename = filename()</v> <v>NameInArchive = filename()</v> <v>RetValue = ok|{error,{Name,Reason}}</v> @@ -221,12 +264,12 @@ </func> <func> - <name>create(Name, FileList, OptionList)</name> + <name since="">create(Name, FileList, OptionList)</name> <fsummary>Create a tar archive with options.</fsummary> <type> <v>Name = filename()</v> - <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, - Filename}]</v> + <v>FileList = [Filename|{NameInArchive, FilenameOrBin}]</v> + <v>FilenameOrBin = filename()|binary()</v> <v>Filename = filename()</v> <v>NameInArchive = filename()</v> <v>OptionList = [Option]</v> @@ -272,10 +315,11 @@ </func> <func> - <name>extract(Name) -> RetValue</name> + <name since="">extract(Name) -> RetValue</name> <fsummary>Extract all files from a tar file.</fsummary> <type> - <v>Name = filename()</v> + <v>Name = filename() | {binary,binary()} | {file,Fd}</v> + <v>Fd = file_descriptor()</v> <v>RetValue = ok|{error,{Name,Reason}}</v> <v>Reason = term()</v> </type> @@ -287,15 +331,18 @@ <c>Fd</c> is assumed to be a file descriptor returned from function <c>file:open/2</c>.</p> <p>Otherwise, <c>Name</c> is to be a filename.</p> + <note><p>Leading slashes in tar member names will be removed before + writing the file. That is, absolute paths will be turned into + relative paths. There will be an info message written to the error + logger when paths are changed in this way.</p></note> </desc> </func> <func> - <name>extract(Name, OptionList)</name> + <name since="">extract(Name, OptionList)</name> <fsummary>Extract files from a tar file.</fsummary> <type> - <v>Name = filename() | {binary,Binary} | {file,Fd}</v> - <v>Binary = binary()</v> + <v>Name = filename() | {binary,binary()} | {file,Fd}</v> <v>Fd = file_descriptor()</v> <v>OptionList = [Option]</v> <v>Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose|memory</v> @@ -364,19 +411,19 @@ </func> <func> - <name>format_error(Reason) -> string()</name> + <name since="">format_error(Reason) -> string()</name> <fsummary>Convert error term to a readable string.</fsummary> <type> <v>Reason = term()</v> </type> <desc> - <p>Cconverts an error reason term to a human-readable error message + <p>Converts an error reason term to a human-readable error message string.</p> </desc> </func> <func> - <name>init(UserPrivate, AccessMode, Fun) -> + <name since="OTP 17.4">init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Reason}</name> <fsummary>Create a <c>TarDescriptor</c> used in subsequent tar operations when defining own low-level storage access functions.</fsummary> @@ -471,7 +518,7 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name>open(Name, OpenModeList) -> RetValue</name> + <name since="">open(Name, OpenModeList) -> RetValue</name> <fsummary>Open a tar file for writing.</fsummary> <type> <v>Name = filename()</v> @@ -518,10 +565,10 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name>table(Name) -> RetValue</name> + <name since="">table(Name) -> RetValue</name> <fsummary>Retrieve the name of all files in a tar file.</fsummary> <type> - <v>Name = filename()</v> + <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> <v>RetValue = {ok,[string()]}|{error,{Name,Reason}}</v> <v>Reason = term()</v> </type> @@ -531,11 +578,11 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name>table(Name, Options)</name> + <name since="">table(Name, Options)</name> <fsummary>Retrieve name and information of all files in a tar file. </fsummary> <type> - <v>Name = filename()</v> + <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> </type> <desc> <p>Retrieves the names of all files in the tar file <c>Name</c>.</p> @@ -543,10 +590,10 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name>t(Name)</name> + <name since="">t(Name)</name> <fsummary>Print the name of each file in a tar file.</fsummary> <type> - <v>Name = filename()</v> + <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> </type> <desc> <p>Prints the names of all files in the tar file <c>Name</c> to the @@ -555,11 +602,11 @@ erl_tar:close(TarDesc)</code> </func> <func> - <name>tt(Name)</name> + <name since="">tt(Name)</name> <fsummary>Print name and information for each file in a tar file. </fsummary> <type> - <v>Name = filename()</v> + <v>Name = filename()|{binary,binary()}|{file,file_descriptor()}</v> </type> <desc> <p>Prints names and information about all files in the tar file diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 5f5d2b7f36..b9ceaa1d69 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>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>ets</module> + <module since="">ets</module> <modulesummary>Built-in term storage.</modulesummary> <description> <p>This module is an interface to the Erlang built-in term storage @@ -49,13 +49,24 @@ associated with each key. A <c>bag</c> or <c>duplicate_bag</c> table can have many objects associated with each key.</p> - <p>The number of tables stored at one Erlang node is limited. - The current default limit is about 1400 tables. The upper - limit can be increased by setting environment variable - <c>ERL_MAX_ETS_TABLES</c> before starting the Erlang runtime - system (that is, with option <c>-env</c> to - <c>erl</c>/<c>werl</c>). The actual limit can be slightly higher - than the one specified, but never lower.</p> + <marker id="max_ets_tables"></marker> + <note> + <p> + The number of tables stored at one Erlang node <em>used</em> to + be limited. This is no longer the case (except by memory usage). + The previous default limit was about 1400 tables and + could be increased by setting the environment variable + <c>ERL_MAX_ETS_TABLES</c> or the command line option + <seealso marker="erts:erl#+e"><c>+e</c></seealso> before starting the + Erlang runtime system. This hard limit has been removed, but it is currently + useful to set the <c>ERL_MAX_ETS_TABLES</c> anyway. It should be + set to an approximate of the maximum amount of tables used. This since + an internal table for named tables is sized using this value. If + large amounts of named tables are used and <c>ERL_MAX_ETS_TABLES</c> + hasn't been increased, the performance of named table lookup will + degrade. + </p> + </note> <p>Notice that there is no automatic garbage collection for tables. Even if there are no references to a table from any process, it @@ -127,23 +138,71 @@ operation. In database terms the isolation level can be seen as "serializable", as if all isolated operations are carried out serially, one after the other in a strict order.</p> + </section> - <p>No other support is available within this module that would guarantee - consistency between objects. However, function - <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> - can be used to guarantee that a sequence of - <seealso marker="#first/1"><c>first/1</c></seealso> and - <seealso marker="#next/2"><c>next/2</c></seealso> calls traverse the - table without errors and that each existing object in the table is - visited exactly once, even if another (or the same) process - simultaneously deletes or inserts objects into the table. - Nothing else is guaranteed; in particular objects that are inserted - or deleted during such a traversal can be visited once or not at all. - Functions that internally traverse over a table, like - <seealso marker="#select/1"><c>select</c></seealso> and - <seealso marker="#match/1"><c>match</c></seealso>, - give the same guarantee as - <seealso marker="#safe_fixtable/2"><c>safe_fixtable</c></seealso>.</p> + <section><marker id="traversal"></marker> + <title>Table traversal</title> + <p>There are different ways to traverse through the objects of a table.</p> + <list type="bulleted"> + <item><p><em>Single-step</em> traversal one key at at time, using + <seealso marker="#first/1"><c>first/1</c></seealso>, + <seealso marker="#next/2"><c>next/2</c></seealso>, + <seealso marker="#last/1"><c>last/1</c></seealso> and + <seealso marker="#prev/2"><c>prev/2</c></seealso>.</p> + </item> + <item><p>Search with simple <em>match patterns</em>, using + <seealso marker="#match/1"><c>match/1/2/3</c></seealso>, + <seealso marker="#match_delete/2"><c>match_delete/2</c></seealso> and + <seealso marker="#match_object/1"><c>match_object/1/2/3</c></seealso>.</p> + </item> + <item><p>Search with more powerful <em>match specifications</em>, using + <seealso marker="#select/1"><c>select/1/2/3</c></seealso>, + <seealso marker="#select_count/2"><c>select_count/2</c></seealso>, + <seealso marker="#select_delete/2"><c>select_delete/2</c></seealso>, + <seealso marker="#select_replace/2"><c>select_replace/2</c></seealso> and + <seealso marker="#select_reverse/1"><c>select_reverse/1/2/3</c></seealso>.</p> + </item> + <item><p><em>Table conversions</em>, using + <seealso marker="#tab2file/2"><c>tab2file/2/3</c></seealso> and + <seealso marker="#tab2list/1"><c>tab2list/1</c></seealso>.</p> + </item> + </list> + <p>None of these ways of table traversal will guarantee a consistent table snapshot + if the table is also updated during the traversal. Moreover, traversals not + done in a <em>safe</em> way, on tables where keys are inserted or deleted + during the traversal, may yield the following undesired effects:</p> + <list type="bulleted"> + <item><p>Any key may be missed.</p></item> + <item><p>Any key may be found more than once.</p></item> + <item><p>The traversal may fail with <c>badarg</c> exception if keys are deleted.</p> + </item> + </list> + <p>A table traversal is <em>safe</em> if either</p> + <list type="bulleted"> + <item><p>the table is of type <c>ordered_set</c>.</p> + </item> + <item><p>the entire table traversal is done within one ETS function + call.</p> + </item> + <item><p>function <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + is used to keep the table fixated during the entire traversal.</p> + </item> + </list> + <p>Traversals using <c>match</c> and <c>select</c> functions may not need to + scan the entire table depending on how the key is specified. A match + pattern with a <em>fully bound key</em> (without any match variables) will + optimize the operation to a single key lookup without any table traversal + at all. For <c>ordered_set</c> a <em>partially bound key</em> will limit the + traversal to only scan a subset of the table based on term order. A + partially bound key is either a list or a tuple with a prefix that is fully + bound. Example:</p> +<pre> +1> <input>T = ets:new(t,[ordered_set]), ets:insert(T, {"555-1234", "John Smith"}).</input> +true +2> <input>%% Efficient search of all with area code 555</input> +2> <input>ets:match(T,{[$5,$5,$5,$- |'$1'],'$2'}).</input> +[["1234","John Smith"]] +</pre> </section> <section> @@ -196,7 +255,7 @@ <funcs> <func> - <name name="all" arity="0"/> + <name name="all" arity="0" since=""/> <fsummary>Return a list of all ETS tables.</fsummary> <desc> <p>Returns a list of all tables at the node. Named tables are @@ -211,7 +270,7 @@ </func> <func> - <name name="delete" arity="1"/> + <name name="delete" arity="1" since=""/> <fsummary>Delete an entire ETS table.</fsummary> <desc> <p>Deletes the entire table <c><anno>Tab</anno></c>.</p> @@ -219,7 +278,7 @@ </func> <func> - <name name="delete" arity="2"/> + <name name="delete" arity="2" since=""/> <fsummary>Delete all objects with a specified key from an ETS table.</fsummary> <desc> @@ -229,7 +288,7 @@ </func> <func> - <name name="delete_all_objects" arity="1"/> + <name name="delete_all_objects" arity="1" since=""/> <fsummary>Delete all objects in an ETS table.</fsummary> <desc> <p>Delete all objects in the ETS table <c><anno>Tab</anno></c>. @@ -239,7 +298,7 @@ </func> <func> - <name name="delete_object" arity="2"/> + <name name="delete_object" arity="2" since=""/> <fsummary>Deletes a specific from an ETS table.</fsummary> <desc> <p>Delete the exact object <c><anno>Object</anno></c> from the @@ -251,7 +310,7 @@ </func> <func> - <name name="file2tab" arity="1"/> + <name name="file2tab" arity="1" since=""/> <fsummary>Read an ETS table from a file.</fsummary> <desc> <p>Reads a file produced by <seealso marker="#tab2file/2"> @@ -263,7 +322,7 @@ </func> <func> - <name name="file2tab" arity="2"/> + <name name="file2tab" arity="2" since=""/> <fsummary>Read an ETS table from a file.</fsummary> <desc> <p>Reads a file produced by <seealso marker="#tab2file/2"> @@ -295,7 +354,7 @@ </func> <func> - <name name="first" arity="1"/> + <name name="first" arity="1" since=""/> <fsummary>Return the first key in an ETS table.</fsummary> <desc> <p>Returns the first key <c><anno>Key</anno></c> in table @@ -310,13 +369,13 @@ </func> <func> - <name name="foldl" arity="3"/> + <name name="foldl" arity="3" since=""/> <fsummary>Fold a function over an ETS table.</fsummary> <desc> <p><c><anno>Acc0</anno></c> is returned if the table is empty. This function is similar to <seealso marker="lists#foldl/3"><c>lists:foldl/3</c></seealso>. - The table elements are traversed is unspecified order, except for + The table elements are traversed in an unspecified order, except for <c>ordered_set</c> tables, where they are traversed first to last.</p> <p>If <c><anno>Function</anno></c> inserts objects into the table, or another @@ -326,13 +385,13 @@ </func> <func> - <name name="foldr" arity="3"/> + <name name="foldr" arity="3" since=""/> <fsummary>Fold a function over an ETS table.</fsummary> <desc> <p><c><anno>Acc0</anno></c> is returned if the table is empty. This function is similar to <seealso marker="lists#foldr/3"><c>lists:foldr/3</c></seealso>. - The table elements are traversed is unspecified order, except for + The table elements are traversed in an unspecified order, except for <c>ordered_set</c> tables, where they are traversed last to first.</p> <p>If <c><anno>Function</anno></c> inserts objects into the table, or another @@ -342,7 +401,7 @@ </func> <func> - <name name="from_dets" arity="2"/> + <name name="from_dets" arity="2" since=""/> <fsummary>Fill an ETS table with objects from a Dets table.</fsummary> <desc> @@ -356,7 +415,7 @@ </func> <func> - <name name="fun2ms" arity="1"/> + <name name="fun2ms" arity="1" since=""/> <fsummary>Pseudo function that transforms fun syntax to a match specification.</fsummary> <desc> @@ -399,9 +458,9 @@ calls cannot be in the guard or body of the fun. Calls to built-in match specification functions is of course allowed:</p> <pre> -4> <input>ets:fun2ms(fun({M,N}) when N > X, is_atomm(M) -> M end).</input> +4> <input>ets:fun2ms(fun({M,N}) when N > X, my_fun(M) -> M end).</input> Error: fun containing local Erlang function calls -('is_atomm' called in guard) cannot be translated into match_spec +('my_fun' called in guard) cannot be translated into match_spec {error,transform_error} 5> <input>ets:fun2ms(fun({M,N}) when N > X, is_atom(M) -> M end).</input> [{{'$1','$2'},[{'>','$2',{const,3}},{is_atom,'$1'}],['$1']}]</pre> @@ -425,7 +484,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="give_away" arity="3"/> + <name name="give_away" arity="3" since=""/> <fsummary>Change owner of a table.</fsummary> <desc> <p>Make process <c><anno>Pid</anno></c> the new owner of table @@ -443,7 +502,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="i" arity="0"/> + <name name="i" arity="0" since=""/> <fsummary>Display information about all ETS tables on a terminal. </fsummary> <desc> @@ -452,7 +511,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="i" arity="1"/> + <name name="i" arity="1" since=""/> <fsummary>Browse an ETS table on a terminal.</fsummary> <desc> <p>Browses table <c><anno>Tab</anno></c> on a terminal.</p> @@ -460,7 +519,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="info" arity="1"/> + <name name="info" arity="1" since=""/> <fsummary>Return information about an <c>table</c>.</fsummary> <desc> <p>Returns information about table <c><anno>Tab</anno></c> as a list of @@ -478,6 +537,11 @@ Error: fun containing local Erlang function calls <p>The pid of the heir of the table, or <c>none</c> if no heir is set.</p> </item> + <tag><c>{id,</c><seealso marker="#type-tid"> + <c>tid()</c></seealso><c>}</c></tag> + <item> + <p>The table identifier.</p> + </item> <tag><c>{keypos, integer() >= 1}</c></tag> <item> <p>The key position.</p> @@ -531,7 +595,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="info" arity="2"/> + <name name="info" arity="2" since=""/> <fsummary>Return the information associated with the specified item for an ETS table.</fsummary> <desc> @@ -541,10 +605,6 @@ Error: fun containing local Erlang function calls <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, a <c>badarg</c> exception is raised.</p> - <warning> - <p>In Erlang/OTP 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>{<anno>Item</anno>,<anno>Value</anno>}</c> pairs defined for <seealso marker="#info/1"><c>info/1</c></seealso>, the following items are allowed:</p> @@ -607,7 +667,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="init_table" arity="2"/> + <name name="init_table" arity="2" since=""/> <fsummary>Replace all objects of an ETS table.</fsummary> <desc> <p>Replaces the existing objects of table <c><anno>Tab</anno></c> with @@ -637,7 +697,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="insert" arity="2"/> + <name name="insert" arity="2" since=""/> <fsummary>Insert an object into an ETS table.</fsummary> <desc> <p>Inserts the object or all of the objects in list @@ -669,7 +729,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="insert_new" arity="2"/> + <name name="insert_new" arity="2" since=""/> <fsummary>Insert an object into an ETS table if the key is not already present.</fsummary> <desc> @@ -688,7 +748,7 @@ Error: fun containing local Erlang function calls </func> <func> - <name name="is_compiled_ms" arity="1"/> + <name name="is_compiled_ms" arity="1" since=""/> <fsummary>Check if an Erlang term is the result of <c>match_spec_compile</c>.</fsummary> <desc> @@ -720,7 +780,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="last" arity="1"/> + <name name="last" arity="1" since=""/> <fsummary>Return the last key in an ETS table of type <c>ordered_set</c>.</fsummary> <desc> @@ -735,7 +795,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="lookup" arity="2"/> + <name name="lookup" arity="2" since=""/> <fsummary>Return all objects with a specified key in an ETS table. </fsummary> <desc> @@ -775,7 +835,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="lookup_element" arity="3"/> + <name name="lookup_element" arity="3" since=""/> <fsummary>Return the <c>Pos</c>:th element of all objects with a specified key in an ETS table.</fsummary> <desc> @@ -798,7 +858,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="match" arity="1"/> + <name name="match" arity="1" since=""/> <fsummary>Continues matching objects in an ETS table.</fsummary> <desc> <p>Continues a match started with @@ -812,7 +872,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="match" arity="2"/> + <name name="match" arity="2" since=""/> <fsummary>Match the objects in an ETS table against a pattern. </fsummary> <desc> @@ -844,7 +904,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="match" arity="3"/> + <name name="match" arity="3" since=""/> <fsummary>Match the objects in an ETS table against a pattern and return part of the answers.</fsummary> <desc> @@ -859,11 +919,14 @@ ets:is_compiled_ms(Broken).</code> <seealso marker="#first/1"><c>first/1</c></seealso> and <seealso marker="#next/2"><c>next/2</c></seealso>.</p> <p>If the table is empty, <c>'$end_of_table'</c> is returned.</p> + <p>Use <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + to guarantee <seealso marker="#traversal">safe traversal</seealso> + for subsequent calls to <seealso marker="#match/1"><c>match/1</c></seealso>.</p> </desc> </func> <func> - <name name="match_delete" arity="2"/> + <name name="match_delete" arity="2" since=""/> <fsummary>Delete all objects that match a specified pattern from an ETS table.</fsummary> <desc> @@ -874,7 +937,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="match_object" arity="1"/> + <name name="match_object" arity="1" since=""/> <fsummary>Continues matching objects in an ETS table.</fsummary> <desc> <p>Continues a match started with @@ -889,7 +952,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="match_object" arity="2"/> + <name name="match_object" arity="2" since=""/> <fsummary>Match the objects in an ETS table against a pattern. </fsummary> <desc> @@ -908,7 +971,7 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="match_object" arity="3"/> + <name name="match_object" arity="3" since=""/> <fsummary>Match the objects in an ETS table against a pattern and return part of the answers.</fsummary> <desc> @@ -924,11 +987,15 @@ ets:is_compiled_ms(Broken).</code> <seealso marker="#first/1"><c>first/1</c></seealso> and <seealso marker="#next/2"><c>next/2</c></seealso>.</p> <p>If the table is empty, <c>'$end_of_table'</c> is returned.</p> + <p>Use <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + to guarantee <seealso marker="#traversal">safe traversal</seealso> + for subsequent calls to <seealso marker="#match_object/1"> + <c>match_object/1</c></seealso>.</p> </desc> </func> <func> - <name name="match_spec_compile" arity="1"/> + <name name="match_spec_compile" arity="1" since=""/> <fsummary>Compile a match specification into its internal representation. </fsummary> <desc> @@ -956,13 +1023,13 @@ ets:is_compiled_ms(Broken).</code> </func> <func> - <name name="match_spec_run" arity="2"/> + <name name="match_spec_run" arity="2" since=""/> <fsummary>Perform matching, using a compiled match specification on a - list of tuples.</fsummary> + list of terms.</fsummary> <desc> <p>Executes the matching specified in a compiled <seealso marker="#match_spec">match specification</seealso> on a list - of tuples. Term <c><anno>CompiledMatchSpec</anno></c> is to be + of terms. Term <c><anno>CompiledMatchSpec</anno></c> is to be the result of a call to <seealso marker="#match_spec_compile/1"> <c>match_spec_compile/1</c></seealso> and is hence the internal representation of the match specification one wants to use.</p> @@ -980,7 +1047,7 @@ Table = ets:new... MatchSpec = ... % The following call... ets:match_spec_run(ets:tab2list(Table), -ets:match_spec_compile(MatchSpec)), + ets:match_spec_compile(MatchSpec)), % ...gives the same result as the more common (and more efficient) ets:select(Table, MatchSpec),</code> <note> @@ -993,7 +1060,7 @@ ets:select(Table, MatchSpec),</code> </func> <func> - <name name="member" arity="2"/> + <name name="member" arity="2" since=""/> <fsummary>Tests for occurrence of a key in an ETS table.</fsummary> <desc> <p>Works like <seealso marker="#lookup/2"><c>lookup/2</c></seealso>, @@ -1004,14 +1071,14 @@ ets:select(Table, MatchSpec),</code> </func> <func> - <name name="new" arity="2"/> + <name name="new" arity="2" since=""/> <fsummary>Create a new ETS table.</fsummary> <desc> <p>Creates a new table and returns a table identifier that 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>Parameter <c><anno>Options</anno></c> is a list of atoms that + <p>Parameter <c><anno>Options</anno></c> is a list of options that specifies table type, access rights, key position, and whether the table is named. Default values are used for omitted options. This means that not specifying any options (<c>[]</c>) is the same @@ -1069,10 +1136,13 @@ ets:select(Table, MatchSpec),</code> </item> <tag><c>named_table</c></tag> <item> - <p>If this option is present, 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> + <p>If this option is present, the table is registered under its + <c><anno>Name</anno></c> which can then be used instead of the + table identifier in subsequent operations.</p> + <p>The function will also return the <c><anno>Name</anno></c> + instead of the table identifier. To get the table identifier of a + named table, use + <seealso marker="#whereis/1"><c>whereis/1</c></seealso>.</p> </item> <tag><c>{keypos,<anno>Pos</anno>}</c></tag> <item> @@ -1165,7 +1235,7 @@ ets:select(Table, MatchSpec),</code> </func> <func> - <name name="next" arity="2"/> + <name name="next" arity="2" since=""/> <fsummary>Return the next key in an ETS table.</fsummary> <desc> <p>Returns the next key <c><anno>Key2</anno></c>, following key @@ -1177,17 +1247,18 @@ ets:select(Table, MatchSpec),</code> <p>To find the first key in the table, use <seealso marker="#first/1"><c>first/1</c></seealso>.</p> <p>Unless a table of type <c>set</c>, <c>bag</c>, or - <c>duplicate_bag</c> is protected using + <c>duplicate_bag</c> is fixated using <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso>, - a traversal can fail if - concurrent updates are made to the table. For table - type <c>ordered_set</c>, the function returns the next key in - order, even if the object does no longer exist.</p> + a call to <c>next/2</c> will fail if <c><anno>Key1</anno></c> no longer + exists in the table. For table type <c>ordered_set</c>, the function + always returns the next key after <c><anno>Key1</anno></c> in term + order, regardless whether <c><anno>Key1</anno></c> ever existed in the + table.</p> </desc> </func> <func> - <name name="prev" arity="2"/> + <name name="prev" arity="2" since=""/> <fsummary>Return the previous key in an ETS table of type <c>ordered_set</c>.</fsummary> <desc> @@ -1197,13 +1268,13 @@ ets:select(Table, MatchSpec),</code> table types, the function is synonymous to <seealso marker="#next/2"><c>next/2</c></seealso>. If no previous key exists, <c>'$end_of_table'</c> is returned.</p> - <p>To find the last key in the table, use + <p>To find the last key in an <c>ordered_set</c> table, use <seealso marker="#last/1"><c>last/1</c></seealso>.</p> </desc> </func> <func> - <name name="rename" arity="2"/> + <name name="rename" arity="2" since=""/> <fsummary>Rename a named ETS table.</fsummary> <desc> <p>Renames the named table <c><anno>Tab</anno></c> to the new name @@ -1213,7 +1284,7 @@ ets:select(Table, MatchSpec),</code> </func> <func> - <name name="repair_continuation" arity="2"/> + <name name="repair_continuation" arity="2" since=""/> <fsummary>Repair a continuation from <c>ets:select/1 or ets:select/3</c> that has passed through external representation.</fsummary> <desc> @@ -1268,11 +1339,20 @@ ets:select(ets:repair_continuation(Broken,MS)).</code> </func> <func> - <name name="safe_fixtable" arity="2"/> + <name name="safe_fixtable" arity="2" since=""/> <fsummary>Fix an ETS table for safe traversal.</fsummary> <desc> <p>Fixes a table of type <c>set</c>, <c>bag</c>, or - <c>duplicate_bag</c> for safe traversal.</p> + <c>duplicate_bag</c> for <seealso marker="#traversal"> + safe traversal</seealso> using + <seealso marker="#first/1"><c>first/1</c></seealso> & + <seealso marker="#next/2"><c>next/2</c></seealso>, + <seealso marker="#match/3"><c>match/3</c></seealso> & + <seealso marker="#match/1"><c>match/1</c></seealso>, + <seealso marker="#match_object/3"><c>match_object/3</c></seealso> & + <seealso marker="#match_object/1"><c>match_object/1</c></seealso>, or + <seealso marker="#select/3"><c>select/3</c></seealso> & + <seealso marker="#select/1"><c>select/1</c></seealso>.</p> <p>A process fixes a table by calling <c>safe_fixtable(<anno>Tab</anno>, true)</c>. The table remains fixed until the process releases it by calling @@ -1285,11 +1365,11 @@ ets:select(ets:repair_continuation(Broken,MS)).</code> <p>When a table is fixed, a sequence of <seealso marker="#first/1"><c>first/1</c></seealso> and <seealso marker="#next/2"><c>next/2</c></seealso> calls are - guaranteed to succeed, and each object in - the table is returned only once, even if objects - are removed or inserted during the traversal. The keys for new - objects inserted during the traversal <em>can</em> be returned by - <c>next/2</c> (it depends on the internal ordering of the keys).</p> + guaranteed to succeed even if keys are removed during the + traversal. The keys for objects inserted or deleted during a + traversal may or may not be returned by <c>next/2</c> depending on + the ordering of keys within the table and if the key exists at the time + <c>next/2</c> is called.</p> <p><em>Example:</em></p> <code type="none"> clean_all_with_value(Tab,X) -> @@ -1307,7 +1387,7 @@ clean_all_with_value(Tab,X,Key) -> true end, clean_all_with_value(Tab,X,ets:next(Tab,Key)).</code> - <p>Notice that no deleted objects are removed from a + <p>Notice that deleted objects are not freed from a fixed table until it has been released. If a process fixes a table but never releases it, the memory used by the deleted objects is never freed. The performance of operations on @@ -1317,14 +1397,14 @@ clean_all_with_value(Tab,X,Key) -> <c>info(Tab, safe_fixed_monotonic_time)</c></seealso>. A system with many processes fixing tables can need a monitor that sends alarms when tables have been fixed for too long.</p> - <p>Notice that for table type <c>ordered_set</c>, - <c>safe_fixtable/2</c> is not necessary, as calls to - <c>first/1</c> and <c>next/2</c> always succeed.</p> + <p>Notice that <c>safe_fixtable/2</c> is not necessary for table type + <c>ordered_set</c> and for traversals done by a single ETS function call, + like <seealso marker="#select/2"><c>select/2</c></seealso>.</p> </desc> </func> <func> - <name name="select" arity="1"/> + <name name="select" arity="1" since=""/> <fsummary>Continue matching objects in an ETS table.</fsummary> <desc> <p>Continues a match started with @@ -1338,7 +1418,7 @@ clean_all_with_value(Tab,X,Key) -> </func> <func> - <name name="select" arity="2"/> + <name name="select" arity="2" since=""/> <fsummary>Match the objects in an ETS table against a match specification.</fsummary> <desc> @@ -1433,7 +1513,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="select" arity="3"/> + <name name="select" arity="3" since=""/> <fsummary>Match the objects in an ETS table against a match specification and return part of the answers.</fsummary> <desc> @@ -1447,12 +1527,15 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> table, which is still faster than traversing the table object by object using <seealso marker="#first/1"><c>first/1</c></seealso> and <seealso marker="#next/2"><c>next/2</c></seealso>.</p> - <p>If the table is empty, <c>'$end_of_table'</c> is returned.</p> + <p>If the table is empty, <c>'$end_of_table'</c> is returned.</p> + <p>Use <seealso marker="#safe_fixtable/2"><c>safe_fixtable/2</c></seealso> + to guarantee <seealso marker="#traversal">safe traversal</seealso> + for subsequent calls to <seealso marker="#select/1"><c>select/1</c></seealso>.</p> </desc> </func> <func> - <name name="select_count" arity="2"/> + <name name="select_count" arity="2" since=""/> <fsummary>Match the objects in an ETS table against a match specification and return the number of objects for which the match specification returned <c>true</c>.</fsummary> @@ -1471,7 +1554,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="select_delete" arity="2"/> + <name name="select_delete" arity="2" since=""/> <fsummary>Match the objects in an ETS table against a match specification and delete objects where the match specification returns <c>true</c>.</fsummary> @@ -1495,7 +1578,46 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="select_reverse" arity="1"/> + <name name="select_replace" arity="2" since="OTP 20.0"/> + <fsummary>Match and replace objects atomically in an ETS table</fsummary> + <desc> + <p>Matches the objects in the table <c><anno>Tab</anno></c> using a + <seealso marker="#match_spec">match specification</seealso>. For each + matched object, the existing object is replaced with + the match specification result.</p> + <p>The match-and-replace operation for each individual object is guaranteed to be + <seealso marker="#concurrency">atomic and isolated</seealso>. The + <c>select_replace</c> table traversal as a whole, like all other select functions, + does not give such guarantees.</p> + <p>The match specifiction must be guaranteed to <em>retain the key</em> + of any matched object. If not, <c>select_replace</c> will fail with <c>badarg</c> + without updating any objects.</p> + <p>For the moment, due to performance and semantic constraints, + tables of type <c>bag</c> are not yet supported.</p> + <p>The function returns the total number of replaced objects.</p> + <p><em>Example</em></p> + <p>For all 2-tuples with a list in second position, add atom <c>'marker'</c> first in the list:</p> + <pre> +1> <input>T = ets:new(x,[]), ets:insert(T, {key, [1, 2, 3]}).</input> +true +2> <input>MS = ets:fun2ms(fun({K, L}) when is_list(L) -> {K, [marker | L]} end).</input> +[{{'$1','$2'},[{is_list,'$2'}],[{{'$1',[marker|'$2']}}]}] +3> <input>ets:select_replace(T, MS).</input> +1 +4> <input>ets:tab2list(T).</input> +[{key,[marker,1,2,3]}] + </pre> + <p>A generic single object compare-and-swap operation:</p> + <pre> +[Old] = ets:lookup(T, Key), +New = update_object(Old), +Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), + </pre> + </desc> + </func> + + <func> + <name name="select_reverse" arity="1" since="OTP R14B"/> <fsummary>Continue matching objects in an ETS table.</fsummary> <desc> <p>Continues a match started with <seealso marker="#select_reverse/3"> @@ -1528,7 +1650,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="select_reverse" arity="2"/> + <name name="select_reverse" arity="2" since="OTP R14B"/> <fsummary>Match the objects in an ETS table against a match specification.</fsummary> <desc> @@ -1540,7 +1662,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="select_reverse" arity="3"/> + <name name="select_reverse" arity="3" since="OTP R14B"/> <fsummary>Match the objects in an ETS table against a match specification and return part of the answers.</fsummary> <desc> @@ -1558,7 +1680,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="setopts" arity="2"/> + <name name="setopts" arity="2" since=""/> <fsummary>Set table options.</fsummary> <desc> <p>Sets table options. The only allowed option to be set after the @@ -1569,7 +1691,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="slot" arity="2"/> + <name name="slot" arity="2" since=""/> <fsummary>Return all objects in a specified slot of an ETS table. </fsummary> <desc> @@ -1594,7 +1716,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="tab2file" arity="2"/> + <name name="tab2file" arity="2" since=""/> <fsummary>Dump an ETS table to a file.</fsummary> <desc> <p>Dumps table <c><anno>Tab</anno></c> to file @@ -1605,7 +1727,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="tab2file" arity="3"/> + <name name="tab2file" arity="3" since=""/> <fsummary>Dump an ETS table to a file.</fsummary> <desc> <p>Dumps table <c><anno>Tab</anno></c> to file @@ -1652,7 +1774,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="tab2list" arity="1"/> + <name name="tab2list" arity="1" since=""/> <fsummary>Return a list of all objects in an ETS table.</fsummary> <desc> <p>Returns a list of all objects in table <c><anno>Tab</anno></c>.</p> @@ -1660,7 +1782,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="tabfile_info" arity="1"/> + <name name="tabfile_info" arity="1" since=""/> <fsummary>Return a list of all objects in an ETS table.</fsummary> <desc> <p>Returns information about the table dumped to file by @@ -1738,8 +1860,8 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="table" arity="1"/> - <name name="table" arity="2"/> + <name name="table" arity="1" since=""/> + <name name="table" arity="2" since=""/> <fsummary>Return a QLC query handle.</fsummary> <desc> <p>Returns a Query List @@ -1815,7 +1937,7 @@ true</pre> </func> <func> - <name name="take" arity="2"/> + <name name="take" arity="2" since="OTP 18.0"/> <fsummary>Return and remove all objects with a specified key from an ETS table.</fsummary> <desc> @@ -1830,7 +1952,7 @@ true</pre> </desc> </func> <func> - <name name="test_ms" arity="2"/> + <name name="test_ms" arity="2" since=""/> <fsummary>Test a match specification for use in <c>select/2</c>. </fsummary> <desc> @@ -1857,7 +1979,7 @@ true</pre> </func> <func> - <name name="to_dets" arity="2"/> + <name name="to_dets" arity="2" since=""/> <fsummary>Fill a Dets table with objects from an ETS table. </fsummary> <desc> @@ -1868,12 +1990,12 @@ true</pre> </func> <func> - <name name="update_counter" arity="3" clause_i="1"/> - <name name="update_counter" arity="4" clause_i="1"/> - <name name="update_counter" arity="3" clause_i="2"/> - <name name="update_counter" arity="4" clause_i="2"/> - <name name="update_counter" arity="3" clause_i="3"/> - <name name="update_counter" arity="4" clause_i="3"/> + <name name="update_counter" arity="3" clause_i="1" since=""/> + <name name="update_counter" arity="4" clause_i="1" since="OTP 18.0"/> + <name name="update_counter" arity="3" clause_i="2" since=""/> + <name name="update_counter" arity="4" clause_i="2" since="OTP 18.0"/> + <name name="update_counter" arity="3" clause_i="3" since=""/> + <name name="update_counter" arity="4" clause_i="3" since="OTP 18.0"/> <fsummary>Update a counter object in an ETS table.</fsummary> <type variable="Tab"/> <type variable="Key"/> @@ -1886,9 +2008,8 @@ true</pre> <p>This function provides an efficient way to update one or more counters, without the trouble of having to look up an object, update the object by incrementing an element, and insert the resulting - object into the table again. (The update is done atomically, - that is, no process - can access the ETS table in the middle of the operation.)</p> + object into the table again. The operation is guaranteed to be + <seealso marker="#concurrency">atomic and isolated</seealso>.</p> <p>This function destructively update the object with key <c><anno>Key</anno></c> in table <c><anno>Tab</anno></c> by adding <c><anno>Incr</anno></c> to the element at position @@ -1917,7 +2038,7 @@ true</pre> The return value is a list of the new counter values from each update operation in the same order as in the operation list. If an empty list is specified, nothing is updated and an empty list is - returned. If the function fails, no updates is done.</p> + returned. If the function fails, no updates are done.</p> <p>The specified <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 @@ -1952,8 +2073,8 @@ true</pre> </func> <func> - <name name="update_element" arity="3" clause_i="1"/> - <name name="update_element" arity="3" clause_i="2"/> + <name name="update_element" arity="3" clause_i="1" since=""/> + <name name="update_element" arity="3" clause_i="2" since=""/> <fsummary>Update the <c>Pos</c>:th element of the object with a specified key in an ETS table.</fsummary> <type variable="Tab"/> @@ -1993,6 +2114,21 @@ true</pre> </list> </desc> </func> + + <func> + <name name="whereis" arity="1" since="OTP 21.0"/> + <fsummary>Retrieves the tid() of a named table.</fsummary> + <desc> + <p>This function returns the + <seealso marker="#type-tid"><c>tid()</c></seealso> of the named table + identified by <c><anno>TableName</anno></c>, or <c>undefined</c> if + no such table exists. The <c>tid()</c> can be used in place of the + table name in all operations, which is slightly faster since the name + does not have to be resolved on each call.</p> + <p>If the table is deleted, the <c>tid()</c> will be invalid even if + another named table is created with the same name.</p> + </desc> + </func> </funcs> </erlref> diff --git a/lib/stdlib/doc/src/fascicules.xml b/lib/stdlib/doc/src/fascicules.xml deleted file mode 100644 index 0ded9007e0..0000000000 --- a/lib/stdlib/doc/src/fascicules.xml +++ /dev/null @@ -1,18 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> - -<fascicules> - <fascicule file="part" href="part_frame.html" entry="no"> - STDLIB User's Guide - </fascicule> - <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> - Reference Manual - </fascicule> - <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> - Release Notes - </fascicule> - <fascicule file="" href="../../../../doc/print.html" entry="no"> - Off-Print - </fascicule> -</fascicules> - diff --git a/lib/stdlib/doc/src/file_sorter.xml b/lib/stdlib/doc/src/file_sorter.xml index e988d58c2f..942d98fe61 100644 --- a/lib/stdlib/doc/src/file_sorter.xml +++ b/lib/stdlib/doc/src/file_sorter.xml @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>file_sorter.xml</file> </header> - <module>file_sorter</module> + <module since="">file_sorter</module> <modulesummary>File sorter.</modulesummary> <description> <p>This module contains functions for sorting terms on files, merging @@ -334,8 +334,8 @@ output(L) -> <funcs> <func> - <name name="check" arity="1"/> - <name name="check" arity="2"/> + <name name="check" arity="1" since=""/> + <name name="check" arity="2" since=""/> <fsummary>Check whether terms on files are sorted.</fsummary> <desc> <p>Checks files for sortedness. If a file is not sorted, the @@ -347,8 +347,8 @@ output(L) -> </func> <func> - <name name="keycheck" arity="2"/> - <name name="keycheck" arity="3"/> + <name name="keycheck" arity="2" since=""/> + <name name="keycheck" arity="3" since=""/> <fsummary>Check whether terms on files are sorted by key.</fsummary> <desc> <p>Checks files for sortedness. If a file is not sorted, the @@ -360,8 +360,8 @@ output(L) -> </func> <func> - <name name="keymerge" arity="3"/> - <name name="keymerge" arity="4"/> + <name name="keymerge" arity="3" since=""/> + <name name="keymerge" arity="4" since=""/> <fsummary>Merge terms on files by key.</fsummary> <desc> <p>Merges tuples on files. Each input file is assumed to be @@ -372,7 +372,7 @@ output(L) -> </func> <func> - <name name="keysort" arity="2"/> + <name name="keysort" arity="2" since=""/> <fsummary>Sort terms on files by key.</fsummary> <desc> <p>Sorts tuples on files.</p> @@ -382,8 +382,8 @@ output(L) -> </func> <func> - <name name="keysort" arity="3"/> - <name name="keysort" arity="4"/> + <name name="keysort" arity="3" since=""/> + <name name="keysort" arity="4" since=""/> <fsummary>Sort terms on files by key.</fsummary> <desc> <p>Sorts tuples on files. The sort is performed on the @@ -397,8 +397,8 @@ output(L) -> </func> <func> - <name name="merge" arity="2"/> - <name name="merge" arity="3"/> + <name name="merge" arity="2" since=""/> + <name name="merge" arity="3" since=""/> <fsummary>Merge terms on files.</fsummary> <desc> <p>Merges terms on files. Each input file is assumed to be @@ -409,7 +409,7 @@ output(L) -> </func> <func> - <name name="sort" arity="1"/> + <name name="sort" arity="1" since=""/> <fsummary>Sort terms on files.</fsummary> <desc> <p>Sorts terms on files.</p> @@ -419,8 +419,8 @@ output(L) -> </func> <func> - <name name="sort" arity="2"/> - <name name="sort" arity="3"/> + <name name="sort" arity="2" since=""/> + <name name="sort" arity="3" since=""/> <fsummary>Sort terms on files.</fsummary> <desc> <p>Sorts terms on files.</p> diff --git a/lib/stdlib/doc/src/filelib.xml b/lib/stdlib/doc/src/filelib.xml index 7c6380ce28..5df415834f 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>filelib.xml</file> </header> - <module>filelib</module> + <module since="">filelib</module> <modulesummary>File utilities, such as wildcard matching of filenames. </modulesummary> <description> @@ -45,6 +45,30 @@ <p>For more information about raw filenames, see the <seealso marker="kernel:file"><c>file</c></seealso> module.</p> + + <note> + <p> + Functionality in this module generally assumes valid input and + does not necessarily fail on input that does not use a valid + encoding, but may instead very likely produce invalid output. + </p> + <p> + File operations used to accept filenames containing + null characters (integer value zero). This caused + the name to be truncated and in some cases arguments + to primitive operations to be mixed up. Filenames + containing null characters inside the filename + are now <em>rejected</em> and will cause primitive + file operations to fail. + </p> + </note> + <warning><p> + Currently null characters at the end of the filename + will be accepted by primitive file operations. Such + filenames are however still documented as invalid. The + implementation will also change in the future and + reject such filenames. + </p></warning> </description> <datatypes> @@ -60,11 +84,17 @@ <datatype> <name name="filename_all"/> </datatype> + <datatype> + <name name="find_file_rule"/> + </datatype> + <datatype> + <name name="find_source_rule"/> + </datatype> </datatypes> <funcs> <func> - <name name="ensure_dir" arity="1"/> + <name name="ensure_dir" arity="1" since=""/> <fsummary>Ensure that all parent directories for a file or directory exist.</fsummary> <desc> @@ -78,7 +108,7 @@ </func> <func> - <name name="file_size" arity="1"/> + <name name="file_size" arity="1" since=""/> <fsummary>Return the size in bytes of a file.</fsummary> <desc> <p>Returns the size of the specified file.</p> @@ -86,7 +116,7 @@ </func> <func> - <name name="fold_files" arity="5"/> + <name name="fold_files" arity="5" since=""/> <fsummary>Fold over all files matching a regular expression.</fsummary> <desc> <p>Folds function <c><anno>Fun</anno></c> over all (regular) files @@ -112,7 +142,7 @@ </func> <func> - <name name="is_dir" arity="1"/> + <name name="is_dir" arity="1" since=""/> <fsummary>Test whether <c>Name</c> refers to a directory.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Name</anno></c> @@ -121,7 +151,7 @@ </func> <func> - <name name="is_file" arity="1"/> + <name name="is_file" arity="1" since=""/> <fsummary>Test whether <c>Name</c> refers to a file or directory. </fsummary> <desc> @@ -131,7 +161,7 @@ </func> <func> - <name name="is_regular" arity="1"/> + <name name="is_regular" arity="1" since=""/> <fsummary>Test whether <c>Name</c> refers to a (regular) file.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Name</anno></c> @@ -140,7 +170,7 @@ </func> <func> - <name name="last_modified" arity="1"/> + <name name="last_modified" arity="1" since=""/> <fsummary>Return the local date and time when a file was last modified. </fsummary> <desc> @@ -150,7 +180,7 @@ </func> <func> - <name name="wildcard" arity="1"/> + <name name="wildcard" arity="1" since=""/> <fsummary>Match filenames using Unix-style wildcards.</fsummary> <desc> <p>Returns a list of all files that match Unix-style wildcard string @@ -187,6 +217,11 @@ <p>Other characters represent themselves. Only filenames that have exactly the same character in the same position match. Matching is case-sensitive, for example, "a" does not match "A".</p> + <p>Directory separators must always be written as <c>/</c>, even on + Windows.</p> + <p>A character preceded by <c>\</c> loses its special meaning. Note + that <c>\</c> must be written as <c>\\</c> in a string literal. + For example, "\\?*" will match any filename starting with <c>?</c>.</p> <p>Notice that multiple "*" characters are allowed (as in Unix wildcards, but opposed to Windows/DOS wildcards).</p> <p><em>Examples:</em></p> @@ -217,7 +252,7 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> </func> <func> - <name name="wildcard" arity="2"/> + <name name="wildcard" arity="2" since=""/> <fsummary>Match filenames using Unix-style wildcards starting at a specified directory.</fsummary> <desc> @@ -226,7 +261,51 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> directory.</p> </desc> </func> + + <func> + <name name="find_file" arity="2" since="OTP 20.0"/> + <name name="find_file" arity="3" since="OTP 20.0"/> + <fsummary>Find a file relative to a given directory.</fsummary> + <desc> + <p>Looks for a file of the given name by applying suffix rules to + the given directory path. For example, a rule <c>{"ebin", "src"}</c> + means that if the directory path ends with <c>"ebin"</c>, the + corresponding path ending in <c>"src"</c> should be searched.</p> + <p>If <c><anno>Rules</anno></c> is left out or is an empty list, the + default system rules are used. See also the Kernel application + parameter <seealso + marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seealso>.</p> + </desc> + </func> + <func> + <name name="find_source" arity="1" since="OTP 20.0"/> + <fsummary>Find the source file for a given object file.</fsummary> + <desc> + <p>Equivalent to <c>find_source(Base, Dir)</c>, where <c>Dir</c> is + <c>filename:dirname(<anno>FilePath</anno>)</c> and <c>Base</c> is + <c>filename:basename(<anno>FilePath</anno>)</c>.</p> + </desc> + </func> + <func> + <name name="find_source" arity="2" since="OTP 20.0"/> + <name name="find_source" arity="3" since="OTP 20.0"/> + <fsummary>Find a source file relative to a given directory.</fsummary> + <desc> + <p>Applies file extension specific rules to find the source file for + a given object file relative to the object directory. For example, + for a file with the extension <c>.beam</c>, the default rule is to + look for a file with a corresponding extension <c>.erl</c> by + replacing the suffix <c>"ebin"</c> of the object directory path with + <c>"src"</c> or <c>"src/*"</c>. + The file search is done through <seealso + marker="#find_file/3"><c>find_file/3</c></seealso>. The directory of + the object file is always tried before any other directory specified + by the rules.</p> + <p>If <c><anno>Rules</anno></c> is left out or is an empty list, the + default system rules are used. See also the Kernel application + parameter <seealso + marker="kernel:kernel_app#source_search_rules"><c>source_search_rules</c></seealso>.</p> + </desc> + </func> </funcs> </erlref> - - diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index f20500709c..ae42846c6b 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2017</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date>1997-11-13</date> <rev>B</rev> </header> - <module>filename</module> + <module since="">filename</module> <modulesummary>Filename manipulation functions.</modulesummary> <description> <p>This module provides functions @@ -46,7 +46,10 @@ filename by removing redundant directory separators, use <seealso marker="#join/1"><c>join/1</c></seealso>.</p> - <p>The module supports raw filenames in the way that if a binary is + <p> + The module supports + <seealso marker="unicode_usage#notes-about-raw-filenames">raw + filenames</seealso> in the way that if a binary is present, or the filename cannot be interpreted according to the return value of <seealso marker="kernel:file#native_name_encoding/0"> <c>file:native_name_encoding/0</c></seealso>, a raw filename is also @@ -56,16 +59,35 @@ (the join operation is performed of course). For more information about raw filenames, see the <seealso marker="kernel:file"><c>file</c></seealso> module.</p> + + <note> + <p> + Functionality in this module generally assumes valid input and + does not necessarily fail on input that does not use a valid + encoding, but may instead very likely produce invalid output. + </p> + <p> + File operations used to accept filenames containing + null characters (integer value zero). This caused + the name to be truncated and in some cases arguments + to primitive operations to be mixed up. Filenames + containing null characters inside the filename + are now <em>rejected</em> and will cause primitive + file operations to fail. + </p> + </note> + <warning><p> + Currently null characters at the end of the filename + will be accepted by primitive file operations. Such + filenames are however still documented as invalid. The + implementation will also change in the future and + reject such filenames. + </p></warning> </description> - <datatypes> - <datatype> - <name name="basedir_type"/> - </datatype> - </datatypes> <funcs> <func> - <name name="absname" arity="1"/> + <name name="absname" arity="1" since=""/> <fsummary>Convert a filename to an absolute name, relative the working directory.</fsummary> <desc> @@ -97,7 +119,7 @@ </func> <func> - <name name="absname" arity="2"/> + <name name="absname" arity="2" since=""/> <fsummary>Convert a filename to an absolute name, relative a specified directory.</fsummary> <desc> @@ -108,7 +130,7 @@ </func> <func> - <name name="absname_join" arity="2"/> + <name name="absname_join" arity="2" since=""/> <fsummary>Join an absolute directory with a relative filename.</fsummary> <desc> <p>Joins an absolute directory with a relative filename. Similar to @@ -122,18 +144,37 @@ </func> <func> - <name name="basedir" arity="2"/> - <fsummary>Equivalent to <c>basedir(<anno>Type</anno>,<anno>Application</anno>,#{})</c>.</fsummary> + <name name="basedir" arity="2" clause_i="1" since="OTP 19.0"/> + <name name="basedir" arity="2" clause_i="2" since="OTP 19.0"/> + <fsummary>Equivalent to <c>basedir(<anno>PathType</anno>, + <anno>Application</anno>,#{})</c> or + <c>basedir(<anno>PathsType</anno>, <anno>Application</anno>,#{})</c>. + </fsummary> + <type variable="PathType" name_i="1"/> + <type name="basedir_path_type"/> + <type variable="PathsType" name_i="2"/> + <type name="basedir_paths_type"/> + <type variable="Application"/> <desc> <p> - Equivalent to <seealso marker="#basedir-3"> - basedir(<anno>Type</anno>, <anno>Application</anno>, #{})</seealso>. + Equivalent to <seealso marker="#basedir_3_1"> + basedir(<anno>PathType</anno>, <anno>Application</anno>, #{})</seealso> + or <seealso marker="#basedir_3_2"> +basedir(<anno>PathsType</anno>, <anno>Application</anno>, #{})</seealso>. </p> </desc> </func> <func> - <name name="basedir" arity="3"/> + <name name="basedir" arity="3" clause_i="1" anchor="basedir_3_1" since="OTP 19.0"/> + <name name="basedir" arity="3" clause_i="2" anchor="basedir_3_2" since="OTP 19.0"/> <fsummary></fsummary> + <type variable="PathType" name_i="1"/> + <type name="basedir_path_type"/> + <type variable="PathsType" name_i="2"/> + <type name="basedir_paths_type"/> + <type variable="Application"/> + <type variable="Opts"/> + <type name="basedir_opts"/> <desc><marker id="basedir-3"/> <p> Returns a suitable path, or paths, for a given type. If @@ -273,7 +314,7 @@ true </desc> </func> <func> - <name name="basename" arity="1"/> + <name name="basename" arity="1" since=""/> <fsummary>Return the last component of a filename.</fsummary> <desc> <p>Returns the last component of <c><anno>Filename</anno></c>, or @@ -291,7 +332,7 @@ true </func> <func> - <name name="basename" arity="2"/> + <name name="basename" arity="2" since=""/> <fsummary>Return the last component of a filename, stripped of the specified extension.</fsummary> <desc> @@ -316,7 +357,7 @@ true </func> <func> - <name name="dirname" arity="1"/> + <name name="dirname" arity="1" since=""/> <fsummary>Return the directory part of a path name.</fsummary> <desc> <p>Returns the directory part of <c><anno>Filename</anno></c>.</p> @@ -333,7 +374,7 @@ true </func> <func> - <name name="extension" arity="1"/> + <name name="extension" arity="1" since=""/> <fsummary>Return the file extension.</fsummary> <desc> <p>Returns the file extension of <c><anno>Filename</anno></c>, @@ -349,17 +390,19 @@ true </func> <func> - <name name="find_src" arity="1"/> - <name name="find_src" arity="2"/> + <name name="find_src" arity="1" since=""/> + <name name="find_src" arity="2" since=""/> <fsummary>Find the filename and compiler options for a module.</fsummary> <desc> <p>Finds the source filename and compiler options for a module. The result can be fed to <seealso marker="compiler:compile#file/2"> <c>compile:file/2</c></seealso> to compile the file again.</p> - <warning><p>It is not recommended to use this function. If possible, - use the <seealso marker="beam_lib"><c>beam_lib(3)</c></seealso> - module to extract the abstract code format from the Beam file and - compile that instead.</p></warning> + <warning> + <p>This function is deprecated. Use <seealso marker="filelib#find_source/1"> + <c>filelib:find_source/1</c></seealso> instead for finding source files.</p> + <p>If possible, use the <seealso marker="beam_lib"><c>beam_lib(3)</c></seealso> + module to extract the compiler options and the abstract code + format from the Beam file and compile that instead.</p></warning> <p>Argument <c><anno>Beam</anno></c>, which can be a string or an atom, specifies either the module name or the path to the source code, with or without extension <c>".erl"</c>. In either @@ -370,15 +413,18 @@ true tuples <c>{<anno>BinSuffix</anno>, <anno>SourceSuffix</anno>}</c> and is interpreted as follows: if the end of the directory name where the object is located matches <c><anno>BinSuffix</anno></c>, then the - source code directory has the same name, but with - <c><anno>BinSuffix</anno></c> replaced by - <c><anno>SourceSuffix</anno></c>. <c><anno>Rules</anno></c> defaults + name created by replacing <c><anno>BinSuffix</anno></c> with + <c><anno>SourceSuffix</anno></c> is expanded by calling + <seealso marker="filelib#wildcard/1"> + <c>filelib:wildcard/1</c></seealso>. + If a regular file is found among the matches, the function + returns that location together with <c><anno>Options</anno></c>. + Otherwise the next rule is tried, and so on.</p> + <p><c><anno>Rules</anno></c> defaults to:</p> <code type="none"> -[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}]</code> - <p>If the source file is found in the resulting directory, the function - returns that location together with <c><anno>Options</anno></c>. - Otherwise the next rule is tried, and so on.</p> +[{"", ""}, {"ebin", "src"}, {"ebin", "esrc"}, + {"ebin", "src/*"}, {"ebin", "esrc/*"}]</code> <p>The function returns <c>{<anno>SourceFile</anno>, <anno>Options</anno>}</c> if it succeeds. <c><anno>SourceFile</anno></c> is the absolute path to the source @@ -392,7 +438,7 @@ true </func> <func> - <name name="flatten" arity="1"/> + <name name="flatten" arity="1" since=""/> <fsummary>Convert a filename to a flat string.</fsummary> <desc> <p>Converts a possibly deep list filename consisting of @@ -402,7 +448,7 @@ true </func> <func> - <name name="join" arity="1"/> + <name name="join" arity="1" since=""/> <fsummary>Join a list of filename components with directory separators. </fsummary> <desc> @@ -430,7 +476,7 @@ true </func> <func> - <name name="join" arity="2"/> + <name name="join" arity="2" since=""/> <fsummary>Join two filename components with directory separators. </fsummary> <desc> @@ -441,7 +487,7 @@ true </func> <func> - <name name="nativename" arity="1"/> + <name name="nativename" arity="1" since=""/> <fsummary>Return the native form of a file path.</fsummary> <desc> <p>Converts <c><anno>Path</anno></c> to a form accepted by the command @@ -460,7 +506,7 @@ true </func> <func> - <name name="pathtype" arity="1"/> + <name name="pathtype" arity="1" since=""/> <fsummary>Return the path type.</fsummary> <desc> <p>Returns the path type, which is one of the following:</p> @@ -490,8 +536,8 @@ true </func> <func> - <name name="rootname" arity="1"/> - <name name="rootname" arity="2"/> + <name name="rootname" arity="1" since=""/> + <name name="rootname" arity="2" since=""/> <fsummary>Remove a filename extension.</fsummary> <desc> <p>Removes a filename extension. <c>rootname/2</c> works as @@ -511,7 +557,7 @@ true </func> <func> - <name name="safe_relative_path" arity="1"/> + <name name="safe_relative_path" arity="1" since="OTP 19.3"/> <fsummary>Sanitize a relative path to avoid directory traversal attacks.</fsummary> <desc> <p>Sanitizes the relative path by eliminating ".." and "." @@ -538,7 +584,7 @@ unsafe</pre> </func> <func> - <name name="split" arity="1"/> + <name name="split" arity="1" since=""/> <fsummary>Split a filename into its path components.</fsummary> <desc> <p>Returns a list whose elements are the path components of @@ -553,6 +599,7 @@ unsafe</pre> ["a:/","msdev","include"]</pre> </desc> </func> + </funcs> </erlref> diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index 7bfe477a11..a9596c6e4d 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2016</year> + <year>2001</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>gb_sets</module> + <module since="">gb_sets</module> <modulesummary>General balanced trees.</modulesummary> <description> <p>This module provides ordered sets using Prof. Arne Andersson's @@ -83,6 +83,8 @@ </item> <item><seealso marker="#is_element/2"><c>is_element/2</c></seealso> </item> + <item><seealso marker="#is_empty/1"><c>is_empty/1</c></seealso> + </item> <item><seealso marker="#is_set/1"><c>is_set/1</c></seealso> </item> <item><seealso marker="#is_subset/2"><c>is_subset/2</c></seealso> @@ -121,8 +123,8 @@ <funcs> <func> - <name name="add" arity="2"/> - <name name="add_element" arity="2"/> + <name name="add" arity="2" since=""/> + <name name="add_element" arity="2" since=""/> <fsummary>Add a (possibly existing) element to a set.</fsummary> <desc> <p>Returns a new set formed from <c><anno>Set1</anno></c> with @@ -133,7 +135,7 @@ </func> <func> - <name name="balance" arity="1"/> + <name name="balance" arity="1" since=""/> <fsummary>Rebalance tree representation of a set.</fsummary> <desc> <p>Rebalances the tree representation of <c><anno>Set1</anno></c>. @@ -147,7 +149,7 @@ </func> <func> - <name name="del_element" arity="2"/> + <name name="del_element" arity="2" since=""/> <fsummary>Remove a (possibly non-existing) element from a set.</fsummary> <desc> <p>Returns a new set formed from <c><anno>Set1</anno></c> with @@ -158,7 +160,7 @@ </func> <func> - <name name="delete" arity="2"/> + <name name="delete" arity="2" since=""/> <fsummary>Remove an element from a set.</fsummary> <desc> <p>Returns a new set formed from <c><anno>Set1</anno></c> with @@ -169,7 +171,7 @@ </func> <func> - <name name="delete_any" arity="2"/> + <name name="delete_any" arity="2" since=""/> <fsummary>Remove a (possibly non-existing) element from a set.</fsummary> <desc> <p>Returns a new set formed from <c><anno>Set1</anno></c> with @@ -180,7 +182,7 @@ </func> <func> - <name name="difference" arity="2"/> + <name name="difference" arity="2" since=""/> <fsummary>Return the difference of two sets.</fsummary> <desc> <p>Returns only the elements of <c><anno>Set1</anno></c> that are not @@ -189,7 +191,7 @@ </func> <func> - <name name="empty" arity="0"/> + <name name="empty" arity="0" since=""/> <fsummary>Return an empty set.</fsummary> <desc> <p>Returns a new empty set.</p> @@ -197,7 +199,7 @@ </func> <func> - <name name="filter" arity="2"/> + <name name="filter" arity="2" since=""/> <fsummary>Filter set elements.</fsummary> <desc> <p>Filters elements in <c><anno>Set1</anno></c> using predicate function @@ -206,7 +208,7 @@ </func> <func> - <name name="fold" arity="3"/> + <name name="fold" arity="3" since=""/> <fsummary>Fold over set elements.</fsummary> <desc> <p>Folds <c><anno>Function</anno></c> over every element in @@ -216,7 +218,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since=""/> <fsummary>Convert a list into a set.</fsummary> <desc> <p>Returns a set of the elements in <c><anno>List</anno></c>, where @@ -225,7 +227,7 @@ </func> <func> - <name name="from_ordset" arity="1"/> + <name name="from_ordset" arity="1" since=""/> <fsummary>Make a set from an ordset list.</fsummary> <desc> <p>Turns an ordered-set list <c><anno>List</anno></c> into a set. @@ -234,7 +236,7 @@ </func> <func> - <name name="insert" arity="2"/> + <name name="insert" arity="2" since=""/> <fsummary>Add a new element to a set.</fsummary> <desc> <p>Returns a new set formed from <c><anno>Set1</anno></c> with @@ -245,7 +247,7 @@ </func> <func> - <name name="intersection" arity="1"/> + <name name="intersection" arity="1" since=""/> <fsummary>Return the intersection of a list of sets.</fsummary> <desc> <p>Returns the intersection of the non-empty list of sets.</p> @@ -253,7 +255,7 @@ </func> <func> - <name name="intersection" arity="2"/> + <name name="intersection" arity="2" since=""/> <fsummary>Return the intersection of two sets.</fsummary> <desc> <p>Returns the intersection of <c><anno>Set1</anno></c> and @@ -262,7 +264,7 @@ </func> <func> - <name name="is_disjoint" arity="2"/> + <name name="is_disjoint" arity="2" since=""/> <fsummary>Check whether two sets are disjoint.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> and @@ -272,7 +274,7 @@ </func> <func> - <name name="is_element" arity="2"/> + <name name="is_element" arity="2" since=""/> <fsummary>Test for membership of a set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Element</anno></c> is an element of @@ -281,7 +283,7 @@ </func> <func> - <name name="is_empty" arity="1"/> + <name name="is_empty" arity="1" since=""/> <fsummary>Test for empty set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set</anno></c> is an empty set, @@ -290,7 +292,7 @@ </func> <func> - <name name="is_member" arity="2"/> + <name name="is_member" arity="2" since=""/> <fsummary>Test for membership of a set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Element</anno></c> is an element of @@ -299,7 +301,7 @@ </func> <func> - <name name="is_set" arity="1"/> + <name name="is_set" arity="1" since=""/> <fsummary>Test for a set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to be a set, @@ -308,7 +310,7 @@ </func> <func> - <name name="is_subset" arity="2"/> + <name name="is_subset" arity="2" since=""/> <fsummary>Test for subset.</fsummary> <desc> <p>Returns <c>true</c> when every element of <c><anno>Set1</anno></c> is @@ -317,7 +319,7 @@ </func> <func> - <name name="iterator" arity="1"/> + <name name="iterator" arity="1" since=""/> <fsummary>Return an iterator for a set.</fsummary> <desc> <p>Returns an iterator that can be used for traversing the entries of @@ -334,7 +336,7 @@ </func> <func> - <name name="iterator_from" arity="2"/> + <name name="iterator_from" arity="2" since="OTP 18.0"/> <fsummary>Return an iterator for a set starting from a specified element. </fsummary> <desc> @@ -349,7 +351,7 @@ </func> <func> - <name name="largest" arity="1"/> + <name name="largest" arity="1" since=""/> <fsummary>Return largest element.</fsummary> <desc> <p>Returns the largest element in <c><anno>Set</anno></c>. Assumes that @@ -358,7 +360,7 @@ </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Return an empty set.</fsummary> <desc> <p>Returns a new empty set.</p> @@ -366,7 +368,7 @@ </func> <func> - <name name="next" arity="1"/> + <name name="next" arity="1" since=""/> <fsummary>Traverse a set with an iterator.</fsummary> <desc> <p>Returns <c>{<anno>Element</anno>, <anno>Iter2</anno>}</c>, where @@ -379,7 +381,7 @@ </func> <func> - <name name="singleton" arity="1"/> + <name name="singleton" arity="1" since=""/> <fsummary>Return a set with one element.</fsummary> <desc> <p>Returns a set containing only element <c><anno>Element</anno></c>. @@ -388,7 +390,7 @@ </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Return the number of elements in a set.</fsummary> <desc> <p>Returns the number of elements in <c><anno>Set</anno></c>.</p> @@ -396,7 +398,7 @@ </func> <func> - <name name="smallest" arity="1"/> + <name name="smallest" arity="1" since=""/> <fsummary>Return smallest element.</fsummary> <desc> <p>Returns the smallest element in <c><anno>Set</anno></c>. Assumes that @@ -405,7 +407,7 @@ </func> <func> - <name name="subtract" arity="2"/> + <name name="subtract" arity="2" since=""/> <fsummary>Return the difference of two sets.</fsummary> <desc> <p>Returns only the elements of <c><anno>Set1</anno></c> that are not @@ -414,7 +416,7 @@ </func> <func> - <name name="take_largest" arity="1"/> + <name name="take_largest" arity="1" since=""/> <fsummary>Extract largest element.</fsummary> <desc> <p>Returns <c>{<anno>Element</anno>, <anno>Set2</anno>}</c>, where @@ -426,7 +428,7 @@ </func> <func> - <name name="take_smallest" arity="1"/> + <name name="take_smallest" arity="1" since=""/> <fsummary>Extract smallest element.</fsummary> <desc> <p>Returns <c>{<anno>Element</anno>, <anno>Set2</anno>}</c>, where @@ -438,7 +440,7 @@ </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert a set into a list.</fsummary> <desc> <p>Returns the elements of <c><anno>Set</anno></c> as a list.</p> @@ -446,7 +448,7 @@ </func> <func> - <name name="union" arity="1"/> + <name name="union" arity="1" since=""/> <fsummary>Return the union of a list of sets.</fsummary> <desc> <p>Returns the merged (union) set of the list of sets.</p> @@ -454,7 +456,7 @@ </func> <func> - <name name="union" arity="2"/> + <name name="union" arity="2" since=""/> <fsummary>Return the union of two sets.</fsummary> <desc> <p>Returns the merged (union) set of <c><anno>Set1</anno></c> and diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 790d4b8bf1..570c9c7cb6 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>gb_trees</module> + <module since="">gb_trees</module> <modulesummary>General balanced trees.</modulesummary> <description> <p>This module provides Prof. Arne Andersson's General @@ -75,7 +75,7 @@ <funcs> <func> - <name name="balance" arity="1"/> + <name name="balance" arity="1" since=""/> <fsummary>Rebalance a tree.</fsummary> <desc> <p>Rebalances <c><anno>Tree1</anno></c>. Notice that this is @@ -88,7 +88,7 @@ </func> <func> - <name name="delete" arity="2"/> + <name name="delete" arity="2" since=""/> <fsummary>Remove a node from a tree.</fsummary> <desc> <p>Removes the node with key <c><anno>Key</anno></c> from @@ -98,7 +98,7 @@ </func> <func> - <name name="delete_any" arity="2"/> + <name name="delete_any" arity="2" since=""/> <fsummary>Remove a (possibly non-existing) node from a tree.</fsummary> <desc> <p>Removes the node with key <c><anno>Key</anno></c> from @@ -109,7 +109,29 @@ </func> <func> - <name name="empty" arity="0"/> + <name name="take" arity="2" since="OTP 20.0"/> + <fsummary>Returns a value and new tree without node with key <c>Key</c>.</fsummary> + <desc> + <p>Returns a value <c><anno>Value</anno></c> from node with key <c><anno>Key</anno></c> + and new <c><anno>Tree2</anno></c> without the node with this value. + Assumes that the node with key is present in the tree, + crashes otherwise.</p> + </desc> + </func> + + <func> + <name name="take_any" arity="2" since="OTP 20.0"/> + <fsummary>Returns a value and new tree without node with key <c>Key</c>.</fsummary> + <desc> + <p>Returns a value <c><anno>Value</anno></c> from node with key <c><anno>Key</anno></c> + and new <c><anno>Tree2</anno></c> without the node with this value. + Returns <c>error</c> if the node with the key is not present in + the tree.</p> + </desc> + </func> + + <func> + <name name="empty" arity="0" since=""/> <fsummary>Return an empty tree.</fsummary> <desc> <p>Returns a new empty tree.</p> @@ -117,7 +139,7 @@ </func> <func> - <name name="enter" arity="3"/> + <name name="enter" arity="3" since=""/> <fsummary>Insert or update key with value in a tree.</fsummary> <desc> <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> @@ -129,7 +151,7 @@ </func> <func> - <name name="from_orddict" arity="1"/> + <name name="from_orddict" arity="1" since=""/> <fsummary>Make a tree from an orddict.</fsummary> <desc> <p>Turns an ordered list <c><anno>List</anno></c> of key-value tuples @@ -138,7 +160,7 @@ </func> <func> - <name name="get" arity="2"/> + <name name="get" arity="2" since=""/> <fsummary>Look up a key in a tree, if present.</fsummary> <desc> <p>Retrieves the value stored with <c><anno>Key</anno></c> in @@ -149,7 +171,7 @@ </func> <func> - <name name="insert" arity="3"/> + <name name="insert" arity="3" since=""/> <fsummary>Insert a new key and value in a tree.</fsummary> <desc> <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> @@ -160,7 +182,7 @@ </func> <func> - <name name="is_defined" arity="2"/> + <name name="is_defined" arity="2" since=""/> <fsummary>Test for membership of a tree.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Key</anno></c> is present in @@ -169,7 +191,7 @@ </func> <func> - <name name="is_empty" arity="1"/> + <name name="is_empty" arity="1" since=""/> <fsummary>Test for empty tree.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Tree</anno></c> is an empty tree, @@ -178,7 +200,7 @@ </func> <func> - <name name="iterator" arity="1"/> + <name name="iterator" arity="1" since=""/> <fsummary>Return an iterator for a tree.</fsummary> <desc> <p>Returns an iterator that can be used for traversing the @@ -196,7 +218,7 @@ </func> <func> - <name name="iterator_from" arity="2"/> + <name name="iterator_from" arity="2" since="OTP 18.0"/> <fsummary>Return an iterator for a tree starting from a specified key. </fsummary> <desc> @@ -211,7 +233,7 @@ </func> <func> - <name name="keys" arity="1"/> + <name name="keys" arity="1" since=""/> <fsummary>Return a list of the keys in a tree.</fsummary> <desc> <p>Returns the keys in <c><anno>Tree</anno></c> as an ordered list.</p> @@ -219,7 +241,7 @@ </func> <func> - <name name="largest" arity="1"/> + <name name="largest" arity="1" since=""/> <fsummary>Return largest key and value.</fsummary> <desc> <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where @@ -231,7 +253,7 @@ </func> <func> - <name name="lookup" arity="2"/> + <name name="lookup" arity="2" since=""/> <fsummary>Look up a key in a tree.</fsummary> <desc> <p>Looks up <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>. @@ -241,7 +263,7 @@ </func> <func> - <name name="map" arity="2"/> + <name name="map" arity="2" since=""/> <fsummary>Return largest key and value.</fsummary> <desc> <p>Maps function F(<anno>K</anno>, <anno>V1</anno>) -> <anno>V2</anno> @@ -253,7 +275,7 @@ </func> <func> - <name name="next" arity="1"/> + <name name="next" arity="1" since=""/> <fsummary>Traverse a tree with an iterator.</fsummary> <desc> <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, @@ -266,7 +288,7 @@ </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Return the number of nodes in a tree.</fsummary> <desc> <p>Returns the number of nodes in <c><anno>Tree</anno></c>.</p> @@ -274,7 +296,7 @@ </func> <func> - <name name="smallest" arity="1"/> + <name name="smallest" arity="1" since=""/> <fsummary>Return smallest key and value.</fsummary> <desc> <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where @@ -286,7 +308,7 @@ </func> <func> - <name name="take_largest" arity="1"/> + <name name="take_largest" arity="1" since=""/> <fsummary>Extract largest key and value.</fsummary> <desc> <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, @@ -299,7 +321,7 @@ </func> <func> - <name name="take_smallest" arity="1"/> + <name name="take_smallest" arity="1" since=""/> <fsummary>Extract smallest key and value.</fsummary> <desc> <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, @@ -312,7 +334,7 @@ </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert a tree into a list.</fsummary> <desc> <p>Converts a tree into an ordered list of key-value tuples.</p> @@ -320,7 +342,7 @@ </func> <func> - <name name="update" arity="3"/> + <name name="update" arity="3" since=""/> <fsummary>Update a key to new value in a tree.</fsummary> <desc> <p>Updates <c><anno>Key</anno></c> to value <c><anno>Value</anno></c> @@ -330,7 +352,7 @@ </func> <func> - <name name="values" arity="1"/> + <name name="values" arity="1" since=""/> <fsummary>Return a list of the values in a tree.</fsummary> <desc> <p>Returns the values in <c><anno>Tree</anno></c> as an ordered list, diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml index c24542002a..2915c4f507 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>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>gen_event</module> + <module since="">gen_event</module> <modulesummary>Generic event handling behavior.</modulesummary> <description> <p>This behavior module provides event handling functionality. It @@ -130,7 +130,7 @@ gen_event:stop -----> Module:terminate/2 <funcs> <func> - <name>add_handler(EventMgrRef, Handler, Args) -> Result</name> + <name since="">add_handler(EventMgrRef, Handler, Args) -> Result</name> <fsummary>Add an event handler to a generic event manager.</fsummary> <type> <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} @@ -178,7 +178,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>add_sup_handler(EventMgrRef, Handler, Args) -> Result</name> + <name since="">add_sup_handler(EventMgrRef, Handler, Args) -> Result</name> <fsummary>Add a supervised event handler to a generic event manager. </fsummary> <type> @@ -207,7 +207,7 @@ gen_event:stop -----> Module:terminate/2 </item> <item> <p>If the event handler is deleted later, the event manager - sends a message<c>{gen_event_EXIT,Handler,Reason}</c> to + sends a message <c>{gen_event_EXIT,Handler,Reason}</c> to the calling process. <c>Reason</c> is one of the following:</p> <list type="bulleted"> <item> @@ -241,8 +241,8 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>call(EventMgrRef, Handler, Request) -> Result</name> - <name>call(EventMgrRef, Handler, Request, Timeout) -> Result</name> + <name since="">call(EventMgrRef, Handler, Request) -> Result</name> + <name since="">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,GlobalName} @@ -285,7 +285,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>delete_handler(EventMgrRef, Handler, Args) -> Result</name> + <name since="">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,GlobalName} @@ -318,8 +318,8 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>notify(EventMgrRef, Event) -> ok</name> - <name>sync_notify(EventMgrRef, Event) -> ok</name> + <name since="">notify(EventMgrRef, Event) -> ok</name> + <name since="">sync_notify(EventMgrRef, Event) -> ok</name> <fsummary>Notify an event manager about an event.</fsummary> <type> <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} @@ -349,14 +349,19 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>start() -> Result</name> - <name>start(EventMgrName) -> Result</name> + <name since="">start() -> Result</name> + <name since="">start(EventMgrName | Options) -> Result</name> + <name since="OTP 20.0">start(EventMgrName, Options) -> Result</name> <fsummary>Create a stand-alone event manager process.</fsummary> <type> - <v>EventMgrName = {local,Name} | {global,GlobalName} - | {via,Module,ViaName}</v> + <v>EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}</v> <v> Name = atom()</v> <v> GlobalName = ViaName = term()</v> + <v>Options = [Option]</v> + <v> Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}</v> + <v> Dbgs = [Dbg]</v> + <v> Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}</v> + <v> SOpts = [term()]</v> <v>Result = {ok,Pid} | {error,{already_started,Pid}}</v> <v> Pid = pid()</v> </type> @@ -370,15 +375,20 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>start_link() -> Result</name> - <name>start_link(EventMgrName) -> Result</name> + <name since="">start_link() -> Result</name> + <name since="">start_link(EventMgrName | Options) -> Result</name> + <name since="OTP 20.0">start_link(EventMgrName, Options) -> Result</name> <fsummary>Create a generic event manager process in a supervision tree. </fsummary> <type> - <v>EventMgrName = {local,Name} | {global,GlobalName} - | {via,Module,ViaName}</v> + <v>EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}</v> <v> Name = atom()</v> <v> GlobalName = ViaName = term()</v> + <v>Options = [Option]</v> + <v> Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}</v> + <v> Dbgs = [Dbg]</v> + <v> Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}</v> + <v> SOpts = [term()]</v> <v>Result = {ok,Pid} | {error,{already_started,Pid}}</v> <v> Pid = pid()</v> </type> @@ -409,6 +419,12 @@ gen_event:stop -----> Module:terminate/2 <seealso marker="kernel:global"><c>global</c></seealso>. Thus, <c>{via,global,GlobalName}</c> is a valid reference.</p> </item> + <item> + <p>If option <c>{hibernate_after,HibernateAfterTimeout}</c> is present, the <c>gen_event</c> + process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and + if no message is received, the process goes into hibernation automatically + (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>).</p> + </item> </list> <p>If the event manager is successfully created, the function returns <c>{ok,Pid}</c>, where <c>Pid</c> is the pid of @@ -420,8 +436,8 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>stop(EventMgrRef) -> ok</name> - <name>stop(EventMgrRef, Reason, Timeout) -> ok</name> + <name since="">stop(EventMgrRef) -> ok</name> + <name since="OTP 18.0">stop(EventMgrRef, Reason, Timeout) -> ok</name> <fsummary>Terminate a generic event manager.</fsummary> <type> <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName} @@ -442,8 +458,7 @@ gen_event:stop -----> Module:terminate/2 with the expected reason. Any other reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an error report to be issued using - <seealso marker="kernel:error_logger#format/2"> - <c>error_logger:format/2</c></seealso>. + <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. The default <c>Reason</c> is <c>normal</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies how many milliseconds to wait for the event manager to @@ -459,7 +474,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name> + <name since="">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,GlobalName} @@ -506,7 +521,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name> + <name since="">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,GlobalName} @@ -531,7 +546,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>which_handlers(EventMgrRef) -> [Handler]</name> + <name since="">which_handlers(EventMgrRef) -> [Handler]</name> <fsummary>Return all event handlers installed in a generic event manager. </fsummary> <type> @@ -560,7 +575,7 @@ gen_event:stop -----> Module:terminate/2 <funcs> <func> - <name>Module:code_change(OldVsn, State, Extra) -> {ok, NewState}</name> + <name since="">Module:code_change(OldVsn, State, Extra) -> {ok, NewState}</name> <fsummary>Update the internal state during upgrade/downgrade.</fsummary> <type> <v>OldVsn = Vsn | {down, Vsn}</v> @@ -569,6 +584,13 @@ gen_event:stop -----> Module:terminate/2 <v>Extra = term()</v> </type> <desc> + <note> + <p>This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with <c>Change={advanced,Extra}</c> + specified in the <c>.appup</c> file is made when <c>code_change/3</c> + isn't implemented the event handler will crash with an <c>undef</c> error + reason.</p> + </note> <p>This function is called for an installed event handler that is to update its internal state during a release upgrade/downgrade, that is, when the instruction @@ -589,7 +611,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>Module:format_status(Opt, [PDict, State]) -> Status</name> + <name since="OTP R14B">Module:format_status(Opt, [PDict, State]) -> Status</name> <fsummary>Optional function for providing a term describing the current event handler state.</fsummary> <type> @@ -645,7 +667,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>Module:handle_call(Request, State) -> Result</name> + <name since="">Module:handle_call(Request, State) -> Result</name> <fsummary>Handle a synchronous request.</fsummary> <type> <v>Request = term()</v> @@ -676,7 +698,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>Module:handle_event(Event, State) -> Result</name> + <name since="">Module:handle_event(Event, State) -> Result</name> <fsummary>Handle an event.</fsummary> <type> <v>Event = term()</v> @@ -734,7 +756,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>Module:handle_info(Info, State) -> Result</name> + <name since="">Module:handle_info(Info, State) -> Result</name> <fsummary>Handle an incoming message.</fsummary> <type> <v>Info = term()</v> @@ -749,6 +771,12 @@ gen_event:stop -----> Module:terminate/2 <v> Id = term()</v> </type> <desc> + <note> + <p>This callback is optional, so callback modules need not + export it. The <c>gen_event</c> module provides a default + implementation of this function that logs about the unexpected + <c>Info</c> message, drops it and returns <c>{ok, State}</c>.</p> + </note> <p>This function is called for each installed event handler when an event manager receives any other message than an event or a synchronous request (or a system message).</p> @@ -760,7 +788,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate} | {error,Reason}</name> + <name since="">Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate} | {error,Reason}</name> <fsummary>Initialize an event handler.</fsummary> <type> <v>InitArgs = Args | {Args,Term}</v> @@ -797,7 +825,7 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>Module:terminate(Arg, State) -> term()</name> + <name since="">Module:terminate(Arg, State) -> term()</name> <fsummary>Clean up before deletion.</fsummary> <type> <v>Arg = Args | {stop,Reason} | stop | remove_handler</v> @@ -805,6 +833,11 @@ gen_event:stop -----> Module:terminate/2 <v> Args = Reason = Term = term()</v> </type> <desc> + <note> + <p>This callback is optional, so callback modules need not + export it. The <c>gen_event</c> module provides a default + implementation without cleanup.</p> + </note> <p>Whenever an event handler is deleted from an event manager, this function is called. It is to be the opposite of <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml index de06987d38..7187630b43 100644 --- a/lib/stdlib/doc/src/gen_fsm.xml +++ b/lib/stdlib/doc/src/gen_fsm.xml @@ -4,14 +4,14 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996-2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -29,931 +29,176 @@ <rev></rev> </header> <module>gen_fsm</module> - <modulesummary>Generic finite state machine behavior.</modulesummary> - <description> - <note> - <p> - There is a new behaviour - <seealso marker="gen_statem"><c>gen_statem</c></seealso> - that is intended to replace <c>gen_fsm</c> for new code. - <c>gen_fsm</c> will not be removed for the foreseeable future - to keep old state machine implementations running. - </p> - </note> - <p>This behavior module provides a finite state machine. - A generic finite state machine process (<c>gen_fsm</c>) implemented - using this module has a standard set of interface functions - and includes functionality for tracing and error reporting. It - also fits into an OTP supervision tree. For more information, see - <seealso marker="doc/design_principles:fsm">OTP Design Principles</seealso>. - </p> - - <p>A <c>gen_fsm</c> process assumes all specific parts to be located in a - callback module exporting a predefined set of functions. The relationship - between the behavior functions and the callback functions is as - follows:</p> - - <pre> -gen_fsm module Callback module --------------- --------------- -gen_fsm:start -gen_fsm:start_link -----> Module:init/1 - -gen_fsm:stop -----> Module:terminate/3 - -gen_fsm:send_event -----> Module:StateName/2 - -gen_fsm:send_all_state_event -----> Module:handle_event/3 - -gen_fsm:sync_send_event -----> Module:StateName/3 - -gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4 - -- -----> Module:handle_info/3 - -- -----> Module:terminate/3 + <modulesummary>Deprecated and replaced by gen_statem </modulesummary> -- -----> Module:code_change/4</pre> - - <p>If a callback function fails or returns a bad value, the <c>gen_fsm</c> - process terminates.</p> - - <p>A <c>gen_fsm</c> process handles system messages as described in - <seealso marker="sys"><c>sys(3)</c></seealso>. The <c>sys</c> module - can be used for debugging a <c>gen_fsm</c> process.</p> - - <p>Notice that a <c>gen_fsm</c> process does not trap exit signals - automatically, this must be explicitly initiated in the callback - module.</p> - - <p>Unless otherwise stated, all functions in this module fail if - the specified <c>gen_fsm</c> process does not exist or if bad arguments - are specified.</p> - - <p>The <c>gen_fsm</c> process can go into hibernation - (see <seealso marker="erts:erlang#hibernate/3"> - <c>erlang:hibernate/3</c></seealso>) if a callback function - specifies <c>'hibernate'</c> instead of a time-out value. This - can be useful if the server is expected to be idle for a long - time. However, use this feature with care, as hibernation - implies at least two garbage collections (when hibernating and - shortly after waking up) and is not something you want to do - between each call to a busy state machine.</p> + <description> + <p> Deprecated and replaced by <seealso marker="gen_statem"><c>gen_statem</c></seealso> </p> </description> - - <funcs> - <func> - <name>cancel_timer(Ref) -> RemainingTime | false</name> - <fsummary>Cancel an internal timer in a generic FSM.</fsummary> - <type> - <v>Ref = reference()</v> - <v>RemainingTime = integer()</v> - </type> - <desc> - <p>Cancels an internal timer referred by <c>Ref</c> in the - <c>gen_fsm</c> process that calls this function.</p> - <p><c>Ref</c> is a reference returned from - <seealso marker="#send_event_after/2"> - <c>send_event_after/2</c></seealso> or - <seealso marker="#start_timer/2"><c>start_timer/2</c></seealso>.</p> - <p>If the timer has already timed out, but the event not yet - been delivered, it is cancelled as if it had <em>not</em> - timed out, so there is no false timer event after - returning from this function.</p> - <p>Returns the remaining time in milliseconds until the timer would - have expired if <c>Ref</c> referred to an active timer, otherwise - <c>false</c>.</p> - </desc> - </func> - - <func> - <name>enter_loop(Module, Options, StateName, StateData)</name> - <name>enter_loop(Module, Options, StateName, StateData, FsmName)</name> - <name>enter_loop(Module, Options, StateName, StateData, Timeout)</name> - <name>enter_loop(Module, Options, StateName, StateData, FsmName, Timeout)</name> - <fsummary>Enter the <c>gen_fsm</c> receive loop.</fsummary> - <type> - <v>Module = atom()</v> - <v>Options = [Option]</v> - <v> Option = {debug,Dbgs}</v> - <v> Dbgs = [Dbg]</v> - <v> Dbg = trace | log | statistics</v> - <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> | {via,Module,ViaName}</v> - <v> Name = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Timeout = int() | infinity</v> - </type> - <desc> - <p>Makes an existing process into a <c>gen_fsm</c> process. - Does not return, - instead the calling process enters the <c>gen_fsm</c> receive - loop and becomes a <c>gen_fsm</c> process. The process <em>must</em> - have been started using one of the start functions in - <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>. The user is - responsible for any initialization of the process, including - registering a name for it.</p> - <p>This function is useful when a more complex initialization - procedure is needed than the <c>gen_fsm</c> behavior provides.</p> - <p><c>Module</c>, <c>Options</c>, and <c>FsmName</c> have - the same meanings as when calling - <seealso marker="#start_link/3"><c>start[_link]/3,4</c></seealso>. - However, if <c>FsmName</c> is specified, the process must have - been registered accordingly <em>before</em> this function is - called.</p> - <p><c>StateName</c>, <c>StateData</c>, and <c>Timeout</c> have - the same meanings as in the return value of - <seealso marker="#Moduleinit"><c>Module:init/1</c></seealso>. - The callback module <c>Module</c> does not need to - export an <c>init/1</c> function.</p> - <p>The function fails if the calling process was not started by a - <c>proc_lib</c> start function, or if it is not registered - according to <c>FsmName</c>.</p> - </desc> - </func> - - <func> - <name>reply(Caller, Reply) -> Result</name> - <fsummary>Send a reply to a caller.</fsummary> - <type> - <v>Caller - see below</v> - <v>Reply = term()</v> - <v>Result = term()</v> - </type> - <desc> - <p>This function can be used by a <c>gen_fsm</c> process to - explicitly send a reply to a client process that called - <seealso marker="#sync_send_event/2"> - <c>sync_send_event/2,3</c></seealso> or - <seealso marker="#sync_send_all_state_event/2"> - <c>sync_send_all_state_event/2,3</c></seealso> - when the reply cannot be defined in the return value of - <seealso marker="#Module:StateName/3"> - <c>Module:StateName/3</c></seealso> or - <seealso marker="#Module:handle_sync_event/4"> - <c>Module:handle_sync_event/4</c></seealso>.</p> - <p><c>Caller</c> must be the <c>From</c> argument provided to - the callback function. <c>Reply</c> is any term - given back to the client as the return value of - <c>sync_send_event/2,3</c> or - <c>sync_send_all_state_event/2,3</c>.</p> - <p>Return value <c>Result</c> is not further defined, and - is always to be ignored.</p> - </desc> - </func> - - <func> - <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}</v> - <v> | {via,Module,ViaName} | pid()</v> - <v> Name = Node = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Event = term()</v> - </type> - <desc> - <p>Sends an event asynchronously to the <c>FsmRef</c> of the - <c>gen_fsm</c> process and returns <c>ok</c> immediately. - The <c>gen_fsm</c> process calls - <seealso marker="#Module:handle_event/3"> - <c>Module:handle_event/3</c></seealso> to handle the event.</p> - <p>For a description of the arguments, see - <seealso marker="#send_event/2"><c>send_event/2</c></seealso>.</p> - <p>The difference between <c>send_event/2</c> and - <c>send_all_state_event/2</c> is which callback function is - used to handle the event. This function is useful when - sending events that are handled the same way in every state, - as only one <c>handle_event</c> clause is needed to handle - the event instead of one clause in each state name function.</p> - </desc> - </func> - - <func> - <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}</v> - <v> | {via,Module,ViaName} | pid()</v> - <v> Name = Node = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Event = term()</v> - </type> - <desc> - <p>Sends an event asynchronously to the <c>FsmRef</c> of the - <c>gen_fsm</c> process - and returns <c>ok</c> immediately. The <c>gen_fsm</c> process calls - <seealso marker="#Module:StateName/2"> - <c>Module:StateName/2</c></seealso> to handle the event, where - <c>StateName</c> is the name of the current state of - the <c>gen_fsm</c> process.</p> - <p><c>FsmRef</c> can be any of the following:</p> - <list type="bulleted"> - <item>The pid</item> - <item><c>Name</c>, if the <c>gen_fsm</c> process is locally - registered</item> - <item><c>{Name,Node}</c>, if the <c>gen_fsm</c> process is locally - registered at another node</item> - <item><c>{global,GlobalName}</c>, if the <c>gen_fsm</c> process is - globally registered</item> - <item><c>{via,Module,ViaName}</c>, if the <c>gen_fsm</c> process is - registered through an alternative process registry</item> - </list> - <p><c>Event</c> is any term that is passed as one of - the arguments to <c>Module:StateName/2</c>.</p> - </desc> - </func> - - <func> - <name>send_event_after(Time, Event) -> Ref</name> - <fsummary>Send a delayed event internally in a generic FSM.</fsummary> - <type> - <v>Time = integer()</v> - <v>Event = term()</v> - <v>Ref = reference()</v> - </type> - <desc> - <p>Sends a delayed event internally in the <c>gen_fsm</c> process - that calls this function after <c>Time</c> milliseconds. - Returns immediately a - reference that can be used to cancel the delayed send using - <seealso marker="#cancel_timer/1"><c>cancel_timer/1</c></seealso>.</p> - <p>The <c>gen_fsm</c> process calls - <seealso marker="#Module:StateName/2"> - <c>Module:StateName/2</c></seealso> to handle - the event, where <c>StateName</c> is the name of the current - state of the <c>gen_fsm</c> process at the time the delayed event is - delivered.</p> - <p><c>Event</c> is any term that is passed as one of - the arguments to <c>Module:StateName/2</c>.</p> - </desc> - </func> - - <func> - <name>start(Module, Args, Options) -> Result</name> - <name>start(FsmName, Module, Args, Options) -> Result</name> - <fsummary>Create a standalone <c>gen_fsm</c> process.</fsummary> - <type> - <v>FsmName = {local,Name} | {global,GlobalName}</v> - <v> | {via,Module,ViaName}</v> - <v> Name = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Module = atom()</v> - <v>Args = term()</v> - <v>Options = [Option]</v> - <v> Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}</v> - <v> Dbgs = [Dbg]</v> - <v> Dbg = trace | log | statistics</v> - <v> | {log_to_file,FileName} | {install,{Func,FuncState}}</v> - <v> SOpts = [term()]</v> - <v>Result = {ok,Pid} | ignore | {error,Error}</v> - <v> Pid = pid()</v> - <v> Error = {already_started,Pid} | term()</v> - </type> - <desc> - <p>Creates a standalone <c>gen_fsm</c> process, that is, a process that - is not part of a supervision tree and thus has no supervisor.</p> - <p>For a description of arguments and return values, see - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>.</p> - </desc> - </func> - - <func> - <name>start_link(Module, Args, Options) -> Result</name> - <name>start_link(FsmName, Module, Args, Options) -> Result</name> - <fsummary>Create a <c>gen_fsm</c> process in a supervision tree. - </fsummary> - <type> - <v>FsmName = {local,Name} | {global,GlobalName}</v> - <v> | {via,Module,ViaName}</v> - <v> Name = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Module = atom()</v> - <v>Args = term()</v> - <v>Options = [Option]</v> - <v> Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}</v> - <v> Dbgs = [Dbg]</v> - <v> Dbg = trace | log | statistics</v> - <v> | {log_to_file,FileName} | {install,{Func,FuncState}}</v> - <v> SOpts = [SOpt]</v> - <v> SOpt - see erlang:spawn_opt/2,3,4,5</v> - <v>Result = {ok,Pid} | ignore | {error,Error}</v> - <v> Pid = pid()</v> - <v> Error = {already_started,Pid} | term()</v> - </type> - <desc> - <p>Creates a <c>gen_fsm</c> process as part of a supervision tree. - The function is to be called, directly or indirectly, by - the supervisor. For example, it ensures that - the <c>gen_fsm</c> process is linked to the supervisor.</p> - <p>The <c>gen_fsm</c> process calls - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> to - initialize. To ensure a synchronized startup procedure, - <c>start_link/3,4</c> does not return until - <c>Module:init/1</c> has returned.</p> - <list type="bulleted"> - <item> - <p>If <c>FsmName={local,Name}</c>, the <c>gen_fsm</c> process is - registered locally as <c>Name</c> using <c>register/2</c>.</p> - </item> - <item> - <p>If <c>FsmName={global,GlobalName}</c>, the <c>gen_fsm</c> process - is registered globally as <c>GlobalName</c> using - <seealso marker="kernel:global#register_name/2"> - <c>global:register_name/2</c></seealso>.</p> - </item> - <item> - <p>If <c>FsmName={via,Module,ViaName}</c>, the <c>gen_fsm</c> - process registers with the registry represented by <c>Module</c>. - The <c>Module</c> callback is to export the functions - <c>register_name/2</c>, <c>unregister_name/1</c>, - <c>whereis_name/1</c>, and <c>send/2</c>, which are to behave - like the corresponding functions in - <seealso marker="kernel:global"><c>global</c></seealso>. - Thus, <c>{via,global,GlobalName}</c> is a valid reference.</p> - </item> - </list> - <p>If no name is provided, the <c>gen_fsm</c> process is not - registered.</p> - <p><c>Module</c> is the name of the callback module.</p> - <p><c>Args</c> is any term that is passed as - the argument to <c>Module:init/1</c>.</p> - <p>If option <c>{timeout,Time}</c> is present, the <c>gen_fsm</c> - process is allowed to spend <c>Time</c> milliseconds initializing - or it terminates and the start function returns - <c>{error,timeout}</c>.</p> - <p>If option <c>{debug,Dbgs}</c> is present, the corresponding - <c>sys</c> function is called for each item in <c>Dbgs</c>; see - <seealso marker="sys"><c>sys(3)</c></seealso>.</p> - <p>If option <c>{spawn_opt,SOpts}</c> is present, <c>SOpts</c> is - passed as option list to the <c>spawn_opt</c> BIF that is used to - spawn the <c>gen_fsm</c> process; see - <seealso marker="erts:erlang#spawn_opt/2"> - <c>spawn_opt/2</c></seealso>.</p> - <note> - <p>Using spawn option <c>monitor</c> is not - allowed, it causes the function to fail with reason - <c>badarg</c>.</p> - </note> - <p>If the <c>gen_fsm</c> process is successfully created and - initialized, the function returns <c>{ok,Pid}</c>, where <c>Pid</c> - is the pid of the <c>gen_fsm</c> process. If a process with the - specified <c>FsmName</c> exists already, the function returns - <c>{error,{already_started,Pid}}</c>, where <c>Pid</c> is - the pid of that process.</p> - <p>If <c>Module:init/1</c> fails with <c>Reason</c>, - the function returns <c>{error,Reason}</c>. If - <c>Module:init/1</c> returns <c>{stop,Reason}</c> or - <c>ignore</c>, the process is terminated and the function - returns <c>{error,Reason}</c> or <c>ignore</c>, respectively.</p> - </desc> - </func> - - <func> - <name>start_timer(Time, Msg) -> Ref</name> - <fsummary>Send a time-out event internally in a generic FSM.</fsummary> - <type> - <v>Time = integer()</v> - <v>Msg = term()</v> - <v>Ref = reference()</v> - </type> - <desc> - <p>Sends a time-out event internally in the <c>gen_fsm</c> - process that calls this function after <c>Time</c> milliseconds. - Returns immediately a - reference that can be used to cancel the timer using - <seealso marker="#cancel_timer/1"><c>cancel_timer/1</c></seealso>.</p> - <p>The <c>gen_fsm</c> process calls - <seealso marker="#Module:StateName/2"> - <c>Module:StateName/2</c></seealso> to handle - the event, where <c>StateName</c> is the name of the current - state of the <c>gen_fsm</c> process at the time the time-out - message is delivered.</p> - <p><c>Msg</c> is any term that is passed in the - time-out message, <c>{timeout, Ref, Msg}</c>, as one of - the arguments to <c>Module:StateName/2</c>.</p> - </desc> - </func> - - <func> - <name>stop(FsmRef) -> ok</name> - <name>stop(FsmRef, Reason, Timeout) -> ok</name> - <fsummary>Synchronously stop a generic FSM.</fsummary> - <type> - <v>FsmRef = Name | {Name,Node} | {global,GlobalName}</v> - <v> | {via,Module,ViaName} | pid()</v> - <v> Node = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Reason = term()</v> - <v>Timeout = int()>0 | infinity</v> - </type> - <desc> - <p>Orders a generic finite state machine to exit with the specified - <c>Reason</c> and waits for it to terminate. The <c>gen_fsm</c> - process calls <seealso marker="#Module:terminate/3"> - <c>Module:terminate/3</c></seealso> before exiting.</p> - <p>The function returns <c>ok</c> if the generic finite state machine - terminates with the expected reason. Any other reason than - <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an - error report to be issued using - <seealso marker="kernel:error_logger#format/2"> - <c>error_logger:format/2</c></seealso>. - The default <c>Reason</c> is <c>normal</c>.</p> - <p><c>Timeout</c> is an integer greater than zero that - specifies how many milliseconds to wait for the generic FSM - to terminate, or the atom <c>infinity</c> to wait - indefinitely. The default value is <c>infinity</c>. If the - generic finite state machine has not terminated within the specified - time, a <c>timeout</c> exception is raised.</p> - <p>If the process does not exist, a <c>noproc</c> exception - is raised.</p> - </desc> - </func> - - <func> - <name>sync_send_all_state_event(FsmRef, Event) -> Reply</name> - <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}</v> - <v> | {via,Module,ViaName} | pid()</v> - <v> Name = Node = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Event = term()</v> - <v>Timeout = int()>0 | infinity</v> - <v>Reply = term()</v> - </type> - <desc> - <p>Sends an event to the <c>FsmRef</c> of the <c>gen_fsm</c> - process and waits until a reply arrives or a time-out occurs. - The <c>gen_fsm</c> process calls - <seealso marker="#Module:handle_sync_event/4"> - <c>Module:handle_sync_event/4</c></seealso> to handle the event.</p> - <p>For a description of <c>FsmRef</c> and <c>Event</c>, see - <seealso marker="#send_event/2">send_event/2</seealso>. - For a description of <c>Timeout</c> and <c>Reply</c>, see - <seealso marker="#sync_send_event/3"> - <c>sync_send_event/3</c></seealso>.</p> - <p>For a discussion about the difference between - <c>sync_send_event</c> and <c>sync_send_all_state_event</c>, see - <seealso marker="#send_all_state_event/2"> - <c>send_all_state_event/2</c></seealso>.</p> - </desc> - </func> - - <func> - <name>sync_send_event(FsmRef, Event) -> Reply</name> - <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}</v> - <v> | {via,Module,ViaName} | pid()</v> - <v> Name = Node = atom()</v> - <v> GlobalName = ViaName = term()</v> - <v>Event = term()</v> - <v>Timeout = int()>0 | infinity</v> - <v>Reply = term()</v> - </type> - <desc> - <p>Sends an event to the <c>FsmRef</c> of the <c>gen_fsm</c> - process and waits until a reply arrives or a time-out occurs. - <c>The gen_fsm</c> process calls - <seealso marker="#Module:StateName/3"> - <c>Module:StateName/3</c></seealso> to handle the event, where - <c>StateName</c> is the name of the current state of - the <c>gen_fsm</c> process.</p> - <p>For a description of <c>FsmRef</c> and <c>Event</c>, see - <seealso marker="#send_event/2"><c>send_event/2</c></seealso>.</p> - <p><c>Timeout</c> is an integer greater than zero that - specifies how many milliseconds to wait for a reply, or - the atom <c>infinity</c> to wait indefinitely. Defaults - to 5000. If no reply is received within the specified time, - the function call fails.</p> - <p>Return value <c>Reply</c> is defined in the return value - of <c>Module:StateName/3</c>.</p> - <note> - <p>The ancient behavior of sometimes consuming the server - exit message if the server died during the call while - linked to the client was removed in Erlang 5.6/OTP R12B.</p> - </note> - </desc> - </func> - </funcs> - - <section> - <title>Callback Functions</title> - <p>The following functions are to be exported from a <c>gen_fsm</c> - callback module.</p> - - <p><em>state name</em> denotes a state of the state machine.</p> - - <p><em>state data</em> denotes the internal state of the Erlang process - that implements the state machine.</p> - </section> - - <funcs> - <func> - <name>Module:code_change(OldVsn, StateName, StateData, Extra) -> {ok, NextStateName, NewStateData}</name> - <fsummary>Update the internal state data during upgrade/downgrade. - </fsummary> - <type> - <v>OldVsn = Vsn | {down, Vsn}</v> - <v> Vsn = term()</v> - <v>StateName = NextStateName = atom()</v> - <v>StateData = NewStateData = term()</v> - <v>Extra = term()</v> - </type> - <desc> - <p>This function is called by a <c>gen_fsm</c> process when it is to - update its internal state data during a release upgrade/downgrade, - that is, when instruction <c>{update,Module,Change,...}</c>, - where <c>Change={advanced,Extra}</c>, is given in - the <c>appup</c> file; see section - <seealso marker="doc/design_principles:release_handling#instr"> - Release Handling Instructions</seealso> in OTP Design Principles.</p> - <p>For an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and for a downgrade, - <c>OldVsn</c> is <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the - <c>vsn</c> attribute(s) of the old version of the callback module - <c>Module</c>. If no such attribute is defined, the version is - the checksum of the Beam file.</p> - <p><c>StateName</c> is the current state name and <c>StateData</c> the - internal state data of the <c>gen_fsm</c> process.</p> - <p><c>Extra</c> is passed "as is" from the <c>{advanced,Extra}</c> - part of the update instruction.</p> - <p>The function is to return the new current state name and - updated internal data.</p> - </desc> - </func> - - <func> - <name>Module:format_status(Opt, [PDict, StateData]) -> Status</name> - <fsummary>Optional function for providing a term describing the - current <c>gen_fsm</c> process status.</fsummary> - <type> - <v>Opt = normal | terminate</v> - <v>PDict = [{Key, Value}]</v> - <v>StateData = term()</v> - <v>Status = term()</v> - </type> - <desc> - <note> - <p>This callback is optional, so callback modules need not - export it. The <c>gen_fsm</c> module provides a default - implementation of this function that returns the callback - module state data.</p> - </note> - <p>This function is called by a <c>gen_fsm</c> process in the - following situations:</p> - <list type="bulleted"> - <item>One of <seealso marker="sys#get_status/1"> - <c>sys:get_status/1,2</c></seealso> - is invoked to get the <c>gen_fsm</c> status. <c>Opt</c> is set to - the atom <c>normal</c> for this case.</item> - <item>The <c>gen_fsm</c> process terminates abnormally and logs an - error. <c>Opt</c> is set to the atom <c>terminate</c> for - this case.</item> - </list> - <p>This function is useful for changing the form and - appearance of the <c>gen_fsm</c> status for these cases. A callback - module wishing to change the <c>sys:get_status/1,2</c> - return value as well as how its status appears in - termination error logs, exports an instance - of <c>format_status/2</c> that returns a term describing the - current status of the <c>gen_fsm</c> process.</p> - <p><c>PDict</c> is the current value of the process dictionary of the - <c>gen_fsm</c> process.</p> - <p><c>StateData</c> is the internal state data of the - <c>gen_fsm</c> process.</p> - <p>The function is to return <c>Status</c>, a term that - change the details of the current state and status of - the <c>gen_fsm</c> process. There are no restrictions on the - form <c>Status</c> can take, but for - the <c>sys:get_status/1,2</c> case (when <c>Opt</c> - is <c>normal</c>), the recommended form for - the <c>Status</c> value is <c>[{data, [{"StateData", - Term}]}]</c>, where <c>Term</c> provides relevant details of - the <c>gen_fsm</c> state data. Following this recommendation is not - required, but it makes the callback module status - consistent with the rest of the <c>sys:get_status/1,2</c> - return value.</p> - <p>One use for this function is to return compact alternative - state data representations to avoid that large state terms - are printed in log files.</p> - </desc> - </func> - - <func> - <name>Module:handle_event(Event, StateName, StateData) -> Result</name> - <fsummary>Handle an asynchronous event.</fsummary> - <type> - <v>Event = term()</v> - <v>StateName = atom()</v> - <v>StateData = term()</v> - <v>Result = {next_state,NextStateName,NewStateData}</v> - <v> | {next_state,NextStateName,NewStateData,Timeout}</v> - <v> | {next_state,NextStateName,NewStateData,hibernate}</v> - <v> | {stop,Reason,NewStateData}</v> - <v> NextStateName = atom()</v> - <v> NewStateData = term()</v> - <v> Timeout = int()>0 | infinity</v> - <v> Reason = term()</v> - </type> - <desc> - <p>Whenever a <c>gen_fsm</c> process receives an event sent using - <seealso marker="#send_all_state_event/2"> - <c>send_all_state_event/2</c></seealso>, - this function is called to handle the event.</p> - <p><c>StateName</c> is the current state name of the <c>gen_fsm</c> - process.</p> - <p>For a description of the other arguments and possible return values, - see <seealso marker="#Module:StateName/2"> - <c>Module:StateName/2</c></seealso>.</p> - </desc> - </func> - - <func> - <name>Module:handle_info(Info, StateName, StateData) -> Result</name> - <fsummary>Handle an incoming message.</fsummary> - <type> - <v>Info = term()</v> - <v>StateName = atom()</v> - <v>StateData = term()</v> - <v>Result = {next_state,NextStateName,NewStateData}</v> - <v> | {next_state,NextStateName,NewStateData,Timeout}</v> - <v> | {next_state,NextStateName,NewStateData,hibernate}</v> - <v> | {stop,Reason,NewStateData}</v> - <v> NextStateName = atom()</v> - <v> NewStateData = term()</v> - <v> Timeout = int()>0 | infinity</v> - <v> Reason = normal | term()</v> - </type> - <desc> - <p>This function is called by a <c>gen_fsm</c> process when it receives - any other message than a synchronous or asynchronous event (or a - system message).</p> - <p><c>Info</c> is the received message.</p> - <p>For a description of the other arguments and possible return values, - see <seealso marker="#Module:StateName/2"> - <c>Module:StateName/2</c></seealso>.</p> - </desc> - </func> - - <func> - <name>Module:handle_sync_event(Event, From, StateName, StateData) -> Result</name> - <fsummary>Handle a synchronous event.</fsummary> - <type> - <v>Event = term()</v> - <v>From = {pid(),Tag}</v> - <v>StateName = atom()</v> - <v>StateData = term()</v> - <v>Result = {reply,Reply,NextStateName,NewStateData}</v> - <v> | {reply,Reply,NextStateName,NewStateData,Timeout}</v> - <v> | {reply,Reply,NextStateName,NewStateData,hibernate}</v> - <v> | {next_state,NextStateName,NewStateData}</v> - <v> | {next_state,NextStateName,NewStateData,Timeout}</v> - <v> | {next_state,NextStateName,NewStateData,hibernate}</v> - <v> | {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}</v> - <v> Reply = term()</v> - <v> NextStateName = atom()</v> - <v> NewStateData = term()</v> - <v> Timeout = int()>0 | infinity</v> - <v> Reason = term()</v> - </type> - <desc> - <p>Whenever a <c>gen_fsm</c> process receives an event sent using - <seealso marker="#sync_send_all_state_event/2"> - <c>sync_send_all_state_event/2,3</c></seealso>, - this function is called to handle the event.</p> - <p><c>StateName</c> is the current state name of the <c>gen_fsm</c> - process.</p> - <p>For a description of the other arguments and possible return values, - see <seealso marker="#Module:StateName/3"> - <c>Module:StateName/3</c></seealso>.</p> - </desc> - </func> - - <func> - <name>Module:init(Args) -> Result</name> - <fsummary>Initialize process and internal state name and state data. - </fsummary> - <type> - <v>Args = term()</v> - <v>Result = {ok,StateName,StateData} | {ok,StateName,StateData,Timeout}</v> - <v> | {ok,StateName,StateData,hibernate}</v> - <v> | {stop,Reason} | ignore</v> - <v> StateName = atom()</v> - <v> StateData = term()</v> - <v> Timeout = int()>0 | infinity</v> - <v> Reason = term()</v> - </type> - <desc> - <marker id="Moduleinit"></marker> - <p>Whenever a <c>gen_fsm</c> process is started using - <seealso marker="#start/3"><c>start/3,4</c></seealso> or - <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>, - this function is called by the new process to initialize.</p> - <p><c>Args</c> is the <c>Args</c> argument provided to the start - function.</p> - <p>If initialization is successful, the function is to return - <c>{ok,StateName,StateData}</c>, - <c>{ok,StateName,StateData,Timeout}</c>, or - <c>{ok,StateName,StateData,hibernate}</c>, where <c>StateName</c> - is the initial state name and <c>StateData</c> the initial - state data of the <c>gen_fsm</c> process.</p> - <p>If an integer time-out value is provided, a time-out occurs - unless an event or a message is received within <c>Timeout</c> - milliseconds. A time-out is represented by the atom - <c>timeout</c> and is to be handled by the - <seealso marker="#Module:StateName/2"> - <c>Module:StateName/2</c></seealso> callback functions. The atom - <c>infinity</c> can be used to wait indefinitely, this is - the default value.</p> - <p>If <c>hibernate</c> is specified instead of a time-out value, the - process goes into hibernation when waiting for the next message - to arrive (by calling <seealso marker="proc_lib#hibernate/3"> - <c>proc_lib:hibernate/3</c></seealso>).</p> - <p>If the initialization fails, the function returns - <c>{stop,Reason}</c>, where <c>Reason</c> is any term, - or <c>ignore</c>.</p> - </desc> - </func> - - <func> - <name>Module:StateName(Event, StateData) -> Result</name> - <fsummary>Handle an asynchronous event.</fsummary> - <type> - <v>Event = timeout | term()</v> - <v>StateData = term()</v> - <v>Result = {next_state,NextStateName,NewStateData} </v> - <v> | {next_state,NextStateName,NewStateData,Timeout}</v> - <v> | {next_state,NextStateName,NewStateData,hibernate}</v> - <v> | {stop,Reason,NewStateData}</v> - <v> NextStateName = atom()</v> - <v> NewStateData = term()</v> - <v> Timeout = int()>0 | infinity</v> - <v> Reason = term()</v> - </type> - <desc> - <p>There is to be one instance of this function for each - possible state name. Whenever a <c>gen_fsm</c> process receives - an event sent using - <seealso marker="#send_event/2"><c>send_event/2</c></seealso>, - the instance of this function with the same name as - the current state name <c>StateName</c> is called to handle - the event. It is also called if a time-out occurs.</p> - <p><c>Event</c> is either the atom <c>timeout</c>, if a time-out - has occurred, or the <c>Event</c> argument provided to - <c>send_event/2</c>.</p> - <p><c>StateData</c> is the state data of the <c>gen_fsm</c> process.</p> - <p>If the function returns - <c>{next_state,NextStateName,NewStateData}</c>, - <c>{next_state,NextStateName,NewStateData,Timeout}</c>, or - <c>{next_state,NextStateName,NewStateData,hibernate}</c>, the - <c>gen_fsm</c> process continues executing with the current state - name set to <c>NextStateName</c> and with the possibly - updated state data <c>NewStateData</c>. For a description of - <c>Timeout</c> and <c>hibernate</c>, see - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>.</p> - <p>If the function returns <c>{stop,Reason,NewStateData}</c>, - the <c>gen_fsm</c> process calls - <c>Module:terminate(Reason,StateName,NewStateData)</c> and - terminates.</p> - </desc> - </func> - - <func> - <name>Module:StateName(Event, From, StateData) -> Result</name> - <fsummary>Handle a synchronous event.</fsummary> - <type> - <v>Event = term()</v> - <v>From = {pid(),Tag}</v> - <v>StateData = term()</v> - <v>Result = {reply,Reply,NextStateName,NewStateData}</v> - <v> | {reply,Reply,NextStateName,NewStateData,Timeout}</v> - <v> | {reply,Reply,NextStateName,NewStateData,hibernate}</v> - <v> | {next_state,NextStateName,NewStateData}</v> - <v> | {next_state,NextStateName,NewStateData,Timeout}</v> - <v> | {next_state,NextStateName,NewStateData,hibernate}</v> - <v> | {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}</v> - <v> Reply = term()</v> - <v> NextStateName = atom()</v> - <v> NewStateData = term()</v> - <v> Timeout = int()>0 | infinity</v> - <v> Reason = normal | term()</v> - </type> - <desc> - <p>There is to be one instance of this function for each - possible state name. Whenever a <c>gen_fsm</c> process receives an - event sent using <seealso marker="#sync_send_event/2"> - <c>sync_send_event/2,3</c></seealso>, - the instance of this function with the same name as - the current state name <c>StateName</c> is called to handle - the event.</p> - <p><c>Event</c> is the <c>Event</c> argument provided to - <c>sync_send_event/2,3</c>.</p> - <p><c>From</c> is a tuple <c>{Pid,Tag}</c> where <c>Pid</c> is - the pid of the process that called <c>sync_send_event/2,3</c> - and <c>Tag</c> is a unique tag.</p> - <p><c>StateData</c> is the state data of the <c>gen_fsm</c> process.</p> - <list type="bulleted"> - <item> - <p>If <c>{reply,Reply,NextStateName,NewStateData}</c>, - <c>{reply,Reply,NextStateName,NewStateData,Timeout}</c>, or - <c>{reply,Reply,NextStateName,NewStateData,hibernate}</c> is - returned, <c>Reply</c> is given back to <c>From</c> as the return - value of <c>sync_send_event/2,3</c>. The <c>gen_fsm</c> process - then continues executing with the current state name set to - <c>NextStateName</c> and with the possibly updated state data - <c>NewStateData</c>. For a description of <c>Timeout</c> and - <c>hibernate</c>, see - <seealso marker="#Module:init/1"> - <c>Module:init/1</c></seealso>.</p> - </item> - <item> - <p>If <c>{next_state,NextStateName,NewStateData}</c>, - <c>{next_state,NextStateName,NewStateData,Timeout}</c>, or - <c>{next_state,NextStateName,NewStateData,hibernate}</c> is - returned, the <c>gen_fsm</c> process continues executing in - <c>NextStateName</c> with <c>NewStateData</c>. - Any reply to <c>From</c> must be specified explicitly using - <seealso marker="#reply/2"><c>reply/2</c></seealso>.</p> - </item> - <item> - <p>If the function returns - <c>{stop,Reason,Reply,NewStateData}</c>, <c>Reply</c> is - given back to <c>From</c>. If the function returns - <c>{stop,Reason,NewStateData}</c>, any reply to <c>From</c> - must be specified explicitly using <c>reply/2</c>. - The <c>gen_fsm</c> process then calls - <c>Module:terminate(Reason,StateName,NewStateData)</c> and - terminates.</p> - </item> - </list> - </desc> - </func> - - <func> - <name>Module:terminate(Reason, StateName, StateData)</name> - <fsummary>Clean up before termination.</fsummary> - <type> - <v>Reason = normal | shutdown | {shutdown,term()} | term()</v> - <v>StateName = atom()</v> - <v>StateData = term()</v> - </type> - <desc> - <p>This function is called by a <c>gen_fsm</c> process when it is about - to terminate. It is to be the opposite of - <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> - and do any necessary cleaning up. When it returns, the <c>gen_fsm</c> - process terminates with <c>Reason</c>. The return value is ignored. - </p> - <p><c>Reason</c> is a term denoting the stop reason, - <c>StateName</c> is the current state name, and - <c>StateData</c> is the state data of the <c>gen_fsm</c> process.</p> - <p><c>Reason</c> depends on why the <c>gen_fsm</c> process is - terminating. If - it is because another callback function has returned a stop - tuple <c>{stop,..}</c>, <c>Reason</c> has the value - specified in that tuple. If it is because of a failure, - <c>Reason</c> is the error reason.</p> - <p>If the <c>gen_fsm</c> process is part of a supervision tree and is - ordered by its supervisor to terminate, this function is called - with <c>Reason=shutdown</c> if the following conditions apply:</p> - <list type="bulleted"> - <item> - <p>The <c>gen_fsm</c> process has been set to trap exit signals.</p> - </item> - <item> - <p>The shutdown strategy as defined in the child specification of - the supervisor is an integer time-out value, not - <c>brutal_kill</c>.</p> - </item> - </list> - <p>Even if the <c>gen_fsm</c> process is <em>not</em> part of a - supervision tree, - this function is called if it receives an <c>'EXIT'</c> - message from its parent. <c>Reason</c> is the same as in - the <c>'EXIT'</c> message.</p> - <p>Otherwise, the <c>gen_fsm</c> process terminates immediately.</p> - <p>Notice that for any other reason than <c>normal</c>, - <c>shutdown</c>, or <c>{shutdown,Term}</c> the <c>gen_fsm</c> process - is assumed to terminate because of an error and an error report is - issued using <seealso marker="kernel:error_logger#format/2"> - <c>error_logger:format/2</c></seealso>.</p> - </desc> - </func> - </funcs> - <section> - <title>See Also</title> - <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>, - <seealso marker="gen_server"><c>gen_server(3)</c></seealso>, - <seealso marker="gen_statem"><c>gen_statem(3)</c></seealso>, - <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>, - <seealso marker="supervisor"><c>supervisor(3)</c></seealso>, - <seealso marker="sys"><c>sys(3)</c></seealso></p> + <marker id="Migration to gen_statem"/> + <title>Migration to gen_statem</title> + + <p>Here follows a simple example of turning a gen_fsm into + a <seealso marker="gen_statem"><c>gen_statem</c></seealso>. The example comes + from the previous Users Guide for <c>gen_fsm</c> </p> + + <code type="erl"> +-module(code_lock). +-define(NAME, code_lock). +%-define(BEFORE_REWRITE, true). + +-ifdef(BEFORE_REWRITE). +-behaviour(gen_fsm). +-else. +-behaviour(gen_statem). +-endif. + +-export([start_link/1, button/1, stop/0]). + +-ifdef(BEFORE_REWRITE). +-export([init/1, locked/2, open/2, handle_sync_event/4, handle_event/3, + handle_info/3, terminate/3, code_change/4]). +-else. +-export([init/1, callback_mode/0, locked/3, open/3, terminate/3, code_change/4]). +%% Add callback__mode/0 +%% Change arity of the state functions +%% Remove handle_info/3 +-endif. + +-ifdef(BEFORE_REWRITE). +start_link(Code) -> + gen_fsm:start_link({local, ?NAME}, ?MODULE, Code, []). +-else. +start_link(Code) -> + gen_statem:start_link({local,?NAME}, ?MODULE, Code, []). +-endif. + +-ifdef(BEFORE_REWRITE). +button(Digit) -> + gen_fsm:send_event(?NAME, {button, Digit}). +-else. +button(Digit) -> + gen_statem:cast(?NAME, {button,Digit}). + %% send_event is asynchronous and becomes a cast +-endif. + +-ifdef(BEFORE_REWRITE). +stop() -> + gen_fsm:sync_send_all_state_event(?NAME, stop). +-else. +stop() -> + gen_statem:call(?NAME, stop). + %% sync_send is synchronous and becomes call + %% all_state is handled by callback code in gen_statem +-endif. + +init(Code) -> + do_lock(), + Data = #{code => Code, remaining => Code}, + {ok, locked, Data}. + +-ifdef(BEFORE_REWRITE). +-else. +callback_mode() -> + state_functions. +%% state_functions mode is the mode most similar to +%% gen_fsm. There is also handle_event mode which is +%% a fairly different concept. +-endif. + +-ifdef(BEFORE_REWRITE). +locked({button, Digit}, Data0) -> + case analyze_lock(Digit, Data0) of + {open = StateName, Data} -> + {next_state, StateName, Data, 10000}; + {StateName, Data} -> + {next_state, StateName, Data} + end. +-else. +locked(cast, {button,Digit}, Data0) -> + case analyze_lock(Digit, Data0) of + {open = StateName, Data} -> + {next_state, StateName, Data, 10000}; + {StateName, Data} -> + {next_state, StateName, Data} + end; +locked({call, From}, Msg, Data) -> + handle_call(From, Msg, Data); +locked({info, Msg}, StateName, Data) -> + handle_info(Msg, StateName, Data). +%% Arity differs +%% All state events are dispatched to handle_call and handle_info help +%% functions. If you want to handle a call or cast event specifically +%% for this state you would add a special clause for it above. +-endif. + +-ifdef(BEFORE_REWRITE). +open(timeout, State) -> + do_lock(), + {next_state, locked, State}; +open({button,_}, Data) -> + {next_state, locked, Data}. +-else. +open(timeout, _, Data) -> + do_lock(), + {next_state, locked, Data}; +open(cast, {button,_}, Data) -> + {next_state, locked, Data}; +open({call, From}, Msg, Data) -> + handle_call(From, Msg, Data); +open(info, Msg, Data) -> + handle_info(Msg, open, Data). +%% Arity differs +%% All state events are dispatched to handle_call and handle_info help +%% functions. If you want to handle a call or cast event specifically +%% for this state you would add a special clause for it above. +-endif. + +-ifdef(BEFORE_REWRITE). +handle_sync_event(stop, _From, _StateName, Data) -> + {stop, normal, ok, Data}. + +handle_event(Event, StateName, Data) -> + {stop, {shutdown, {unexpected, Event, StateName}}, Data}. + +handle_info(Info, StateName, Data) -> + {stop, {shutdown, {unexpected, Info, StateName}}, StateName, Data}. +-else. +-endif. + +terminate(_Reason, State, _Data) -> + State =/= locked andalso do_lock(), + ok. +code_change(_Vsn, State, Data, _Extra) -> + {ok, State, Data}. + +%% Internal functions +-ifdef(BEFORE_REWRITE). +-else. +handle_call(From, stop, Data) -> + {stop_and_reply, normal, {reply, From, ok}, Data}. + +handle_info(Info, StateName, Data) -> + {stop, {shutdown, {unexpected, Info, StateName}}, StateName, Data}. +%% These are internal functions for handling all state events +%% and not behaviour callbacks as in gen_fsm +-endif. + +analyze_lock(Digit, #{code := Code, remaining := Remaining} = Data) -> + case Remaining of + [Digit] -> + do_unlock(), + {open, Data#{remaining := Code}}; + [Digit|Rest] -> % Incomplete + {locked, Data#{remaining := Rest}}; + _Wrong -> + {locked, Data#{remaining := Code}} + end. + +do_lock() -> + io:format("Lock~n", []). +do_unlock() -> + io:format("Unlock~n", []). + </code> </section> </erlref> diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 4a7dd60858..a4554d7657 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>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>gen_server</module> + <module since="">gen_server</module> <modulesummary>Generic server behavior.</modulesummary> <description> <p>This behavior module provides the server of a client-server @@ -60,6 +60,8 @@ gen_server:abcast -----> Module:handle_cast/2 - -----> Module:handle_info/2 +- -----> Module:handle_continue/2 + - -----> Module:terminate/2 - -----> Module:code_change/3</pre> @@ -88,12 +90,19 @@ gen_server:abcast -----> Module:handle_cast/2 implies at least two garbage collections (when hibernating and shortly after waking up) and is not something you want to do between each call to a busy server.</p> + + <p>If the <c>gen_server</c> process needs to perform an action + immediately after initialization or to break the execution of a + callback into multiple steps, it can return <c>{continue,Continue}</c> + in place of the time-out or hibernation value, which will immediately + invoke the <c>handle_continue/2</c> callback.</p> + </description> <funcs> <func> - <name>abcast(Name, Request) -> abcast</name> - <name>abcast(Nodes, Name, Request) -> abcast</name> + <name since="">abcast(Name, Request) -> abcast</name> + <name since="">abcast(Nodes, Name, Request) -> abcast</name> <fsummary>Send an asynchronous request to many generic servers.</fsummary> <type> <v>Nodes = [Node]</v> @@ -115,8 +124,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>call(ServerRef, Request) -> Reply</name> - <name>call(ServerRef, Request, Timeout) -> Reply</name> + <name since="">call(ServerRef, Request) -> Reply</name> + <name since="">call(ServerRef, Request, Timeout) -> Reply</name> <fsummary>Make a synchronous call to a generic server.</fsummary> <type> <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> @@ -162,16 +171,11 @@ gen_server:abcast -----> Module:handle_cast/2 of <c>Module:handle_call/3</c>.</p> <p>The call can fail for many reasons, including time-out and the called <c>gen_server</c> process dying before or during the call.</p> - <note> - <p>The ancient behavior of sometimes consuming the server - exit message if the server died during the call while - linked to the client was removed in Erlang 5.6/OTP R12B.</p> - </note> </desc> </func> <func> - <name>cast(ServerRef, Request) -> ok</name> + <name since="">cast(ServerRef, Request) -> ok</name> <fsummary>Send an asynchronous request to a generic server.</fsummary> <type> <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> @@ -196,15 +200,15 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>enter_loop(Module, Options, State)</name> - <name>enter_loop(Module, Options, State, ServerName)</name> - <name>enter_loop(Module, Options, State, Timeout)</name> - <name>enter_loop(Module, Options, State, ServerName, Timeout)</name> + <name since="">enter_loop(Module, Options, State)</name> + <name since="">enter_loop(Module, Options, State, ServerName)</name> + <name since="">enter_loop(Module, Options, State, Timeout)</name> + <name since="">enter_loop(Module, Options, State, ServerName, Timeout)</name> <fsummary>Enter the <c>gen_server</c> receive loop.</fsummary> <type> <v>Module = atom()</v> <v>Options = [Option]</v> - <v> Option = {debug,Dbgs}</v> + <v> Option = {debug,Dbgs} | {hibernate_after,HibernateAfterTimeout}</v> <v> Dbgs = [Dbg]</v> <v> Dbg = trace | log | statistics</v> <v> | {log_to_file,FileName} | {install,{Func,FuncState}}</v> @@ -244,9 +248,9 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>multi_call(Name, Request) -> Result</name> - <name>multi_call(Nodes, Name, Request) -> Result</name> - <name>multi_call(Nodes, Name, Request, Timeout) -> Result</name> + <name since="">multi_call(Name, Request) -> Result</name> + <name since="">multi_call(Nodes, Name, Request) -> Result</name> + <name since="">multi_call(Nodes, Name, Request, Timeout) -> Result</name> <fsummary>Make a synchronous call to many generic servers.</fsummary> <type> <v>Nodes = [Node]</v> @@ -303,7 +307,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>reply(Client, Reply) -> Result</name> + <name since="">reply(Client, Reply) -> Result</name> <fsummary>Send a reply to a client.</fsummary> <type> <v>Client - see below</v> @@ -328,8 +332,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>start(Module, Args, Options) -> Result</name> - <name>start(ServerName, Module, Args, Options) -> Result</name> + <name since="">start(Module, Args, Options) -> Result</name> + <name since="">start(ServerName, Module, Args, Options) -> Result</name> <fsummary>Create a standalone <c>gen_server</c> process.</fsummary> <type> <v>ServerName = {local,Name} | {global,GlobalName}</v> @@ -339,7 +343,7 @@ gen_server:abcast -----> Module:handle_cast/2 <v>Module = atom()</v> <v>Args = term()</v> <v>Options = [Option]</v> - <v> Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}</v> + <v> Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}</v> <v> Dbgs = [Dbg]</v> <v> Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}</v> <v> SOpts = [term()]</v> @@ -357,8 +361,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>start_link(Module, Args, Options) -> Result</name> - <name>start_link(ServerName, Module, Args, Options) -> Result</name> + <name since="">start_link(Module, Args, Options) -> Result</name> + <name since="">start_link(ServerName, Module, Args, Options) -> Result</name> <fsummary>Create a <c>gen_server</c> process in a supervision tree. </fsummary> <type> @@ -369,7 +373,7 @@ gen_server:abcast -----> Module:handle_cast/2 <v>Module = atom()</v> <v>Args = term()</v> <v>Options = [Option]</v> - <v> Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}</v> + <v> Option = {debug,Dbgs} | {timeout,Time} | {hibernate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}</v> <v> Dbgs = [Dbg]</v> <v> Dbg = trace | log | statistics | {log_to_file,FileName} | {install,{Func,FuncState}}</v> <v> SOpts = [term()]</v> @@ -422,6 +426,12 @@ gen_server:abcast -----> Module:handle_cast/2 returns <c>{error,timeout}</c>.</p> </item> <item> + <p>If option <c>{hibernate_after,HibernateAfterTimeout}</c> is present, the <c>gen_server</c> + process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and + if no message is received, the process goes into hibernation automatically + (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>).</p> + </item> + <item> <p>If option <c>{debug,Dbgs}</c> is present, the corresponding <c>sys</c> function is called for each item in <c>Dbgs</c>; see @@ -456,8 +466,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>stop(ServerRef) -> ok</name> - <name>stop(ServerRef, Reason, Timeout) -> ok</name> + <name since="OTP 18.0">stop(ServerRef) -> ok</name> + <name since="OTP 18.0">stop(ServerRef, Reason, Timeout) -> ok</name> <fsummary>Synchronously stop a generic server.</fsummary> <type> <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> @@ -476,8 +486,7 @@ gen_server:abcast -----> Module:handle_cast/2 with the expected reason. Any other reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an error report to be issued using - <seealso marker="kernel:error_logger#format/2"> - <c>error_logger:format/2</c></seealso>. + <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. The default <c>Reason</c> is <c>normal</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies how many milliseconds to wait for the server to @@ -499,7 +508,7 @@ gen_server:abcast -----> Module:handle_cast/2 <funcs> <func> - <name>Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error, Reason}</name> + <name since="">Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error, Reason}</name> <fsummary>Update the internal state during upgrade/downgrade.</fsummary> <type> <v>OldVsn = Vsn | {down, Vsn}</v> @@ -509,6 +518,13 @@ gen_server:abcast -----> Module:handle_cast/2 <v>Reason = term()</v> </type> <desc> + <note> + <p>This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with <c>Change={advanced,Extra}</c> + specified in the <c>appup</c> file is made when <c>code_change/3</c> + isn't implemented the process will crash with an <c>undef</c> exit + reason.</p> + </note> <p>This function is called by a <c>gen_server</c> process when it is to update its internal state during a release upgrade/downgrade, that is, when the instruction <c>{update,Module,Change,...}</c>, @@ -534,7 +550,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:format_status(Opt, [PDict, State]) -> Status</name> + <name since="OTP R13B04">Module:format_status(Opt, [PDict, State]) -> Status</name> <fsummary>Optional function for providing a term describing the current <c>gen_server</c> status.</fsummary> <type> @@ -594,7 +610,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:handle_call(Request, From, State) -> Result</name> + <name since="">Module:handle_call(Request, From, State) -> Result</name> <fsummary>Handle a synchronous request.</fsummary> <type> <v>Request = term()</v> @@ -602,12 +618,15 @@ gen_server:abcast -----> Module:handle_cast/2 <v>State = term()</v> <v>Result = {reply,Reply,NewState} | {reply,Reply,NewState,Timeout}</v> <v> | {reply,Reply,NewState,hibernate}</v> + <v> | {reply,Reply,NewState,{continue,Continue}}</v> <v> | {noreply,NewState} | {noreply,NewState,Timeout}</v> <v> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> <v> | {stop,Reason,Reply,NewState} | {stop,Reason,NewState}</v> <v> Reply = term()</v> <v> NewState = term()</v> <v> Timeout = int()>=0 | infinity</v> + <v> Continue = term()</v> <v> Reason = term()</v> </type> <desc> @@ -658,16 +677,18 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:handle_cast(Request, State) -> Result</name> + <name since="">Module:handle_cast(Request, State) -> Result</name> <fsummary>Handle an asynchronous request.</fsummary> <type> <v>Request = term()</v> <v>State = term()</v> <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v> <v> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> <v> | {stop,Reason,NewState}</v> <v> NewState = term()</v> <v> Timeout = int()>=0 | infinity</v> + <v> Continue = term()</v> <v> Reason = term()</v> </type> <desc> @@ -682,19 +703,61 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:handle_info(Info, State) -> Result</name> + <name since="OTP 21.0">Module:handle_continue(Continue, State) -> Result</name> + <fsummary>Handle a continue instruction.</fsummary> + <type> + <v>Continue = term()</v> + <v>State = term()</v> + <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v> + <v> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> + <v> | {stop,Reason,NewState}</v> + <v> NewState = term()</v> + <v> Timeout = int()>=0 | infinity</v> + <v> Continue = term()</v> + <v> Reason = normal | term()</v> + </type> + <desc> + <note> + <p>This callback is optional, so callback modules need to + export it only if they return <c>{continue,Continue}</c> + from another callback. If continue is used and the callback + is not implemented, the process will exit with <c>undef</c> + error.</p> + </note> + <p>This function is called by a <c>gen_server</c> process whenever + a previous callback returns <c>{continue, Continue}</c>. + <c>handle_continue/2</c> is invoked immediately after the previous + callback, which makes it useful for performing work after + initialization or for splitting the work in a callback in + multiple steps, updating the process state along the way.</p> + <p>For a description of the other arguments and possible return values, + see <seealso marker="#Module:handle_call/3"> + <c>Module:handle_call/3</c></seealso>.</p> + </desc> + </func> + + <func> + <name since="">Module:handle_info(Info, State) -> Result</name> <fsummary>Handle an incoming message.</fsummary> <type> <v>Info = timeout | term()</v> <v>State = term()</v> <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v> <v> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> <v> | {stop,Reason,NewState}</v> <v> NewState = term()</v> <v> Timeout = int()>=0 | infinity</v> <v> Reason = normal | term()</v> </type> <desc> + <note> + <p>This callback is optional, so callback modules need not + export it. The <c>gen_server</c> module provides a default + implementation of this function that logs about the unexpected + <c>Info</c> message, drops it and returns <c>{noreply, State}</c>.</p> + </note> <p>This function is called by a <c>gen_server</c> process when a time-out occurs or when it receives any other message than a synchronous or asynchronous request (or a system message).</p> @@ -707,12 +770,12 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:init(Args) -> Result</name> + <name since="">Module:init(Args) -> Result</name> <fsummary>Initialize process and internal state.</fsummary> <type> <v>Args = term()</v> <v>Result = {ok,State} | {ok,State,Timeout} | {ok,State,hibernate}</v> - <v> | {stop,Reason} | ignore</v> + <v> | {ok,State,{continue,Continue}} | {stop,Reason} | ignore</v> <v> State = term()</v> <v> Timeout = int()>=0 | infinity</v> <v> Reason = term()</v> @@ -748,13 +811,18 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:terminate(Reason, State)</name> + <name since="">Module:terminate(Reason, State)</name> <fsummary>Clean up before termination.</fsummary> <type> <v>Reason = normal | shutdown | {shutdown,term()} | term()</v> <v>State = term()</v> </type> <desc> + <note> + <p>This callback is optional, so callback modules need not + export it. The <c>gen_server</c> module provides a default + implementation without cleanup.</p> + </note> <p>This function is called by a <c>gen_server</c> process when it is about to terminate. It is to be the opposite of <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> @@ -792,8 +860,7 @@ gen_server:abcast -----> Module:handle_cast/2 <c>shutdown</c>, or <c>{shutdown,Term}</c>, the <c>gen_server</c> process is assumed to terminate because of an error and an error report is issued using - <seealso marker="kernel:error_logger#format/2"> - <c>error_logger:format/2</c></seealso>.</p> + <seealso marker="kernel:logger"><c>logger(3)</c></seealso>.</p> </desc> </func> </funcs> @@ -801,7 +868,6 @@ gen_server:abcast -----> Module:handle_cast/2 <section> <title>See Also</title> <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>, - <seealso marker="gen_fsm"><c>gen_fsm(3)</c></seealso>, <seealso marker="gen_statem"><c>gen_statem(3)</c></seealso>, <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>, <seealso marker="supervisor"><c>supervisor(3)</c></seealso>, diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 5eb13db1aa..aaa26df18d 100644 --- a/lib/stdlib/doc/src/gen_statem.xml +++ b/lib/stdlib/doc/src/gen_statem.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2016-2017</year> + <year>2016</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,11 +28,72 @@ <date></date> <rev></rev> </header> - <module>gen_statem</module> + <module since="OTP 19.0">gen_statem</module> <modulesummary>Generic state machine behavior.</modulesummary> <description> <p> - This behavior module provides a state machine. Two + <c>gen_statem</c> provides a generic state machine behaviour + and replaces its predecessor + <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> + since Erlang/OTP 20.0. + </p> + <p> + This reference manual describes types generated from the types + in the <c>gen_statem</c> source code, so they are correct. + However, the generated descriptions also reflect the type hiearchy, + which makes them kind of hard to read. + </p> + <p> + To get an overview of the concepts and operation of <c>gen_statem</c>, + do read the + <seealso marker="doc/design_principles:statem"> + <c>gen_statem</c> Behaviour + </seealso> + in + <seealso marker="doc/design_principles:users_guide"> + OTP Design Principles + </seealso> + which frequently links back to this reference manual to avoid + containing detailed facts that may rot by age. + </p> + <note> + <p> + This behavior appeared in Erlang/OTP 19.0. + In OTP 19.1 a backwards incompatible change of + the return tuple from + <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + was made and the mandatory callback function + <seealso marker="#Module:callback_mode/0"> + <c>Module:callback_mode/0</c> + </seealso> + was introduced. In OTP 20.0 the + <seealso marker="#type-generic_timeout"><c>generic timeouts</c></seealso> + were added. + </p> + </note> + <p> + <c>gen_statem</c> has got the same features that + <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> + had and adds some really useful: + </p> + <list type="bulleted"> + <item>Co-located state code</item> + <item>Arbitrary term state</item> + <item>Event postponing</item> + <item>Self-generated events</item> + <item>State time-out</item> + <item>Multiple generic named time-outs</item> + <item>Absolute time-out time</item> + <item>Automatic state enter calls</item> + <item> + Reply from other state than the request, <c>sys</c> traceable + </item> + <item>Multiple <c>sys</c> traceable replies</item> + </list> + + + <p> + Two <seealso marker="#type-callback_mode"><em>callback modes</em></seealso> are supported: </p> @@ -50,36 +111,13 @@ </p> </item> </list> - <note> - <p> - This is a new behavior in Erlang/OTP 19.0. - It has been thoroughly reviewed, is stable enough - to be used by at least two heavy OTP applications, - and is here to stay. - Depending on user feedback, we do not expect - but can find it necessary to make minor - not backward compatible changes into Erlang/OTP 20.0. - </p> - </note> - <p> - The <c>gen_statem</c> behavior is intended to replace - <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> for new code. - It has the same features and adds some really useful: - </p> - <list type="bulleted"> - <item>State code is gathered.</item> - <item>The state can be any term.</item> - <item>Events can be postponed.</item> - <item>Events can be self-generated.</item> - <item>Automatic state enter code can be called.</item> - <item>A reply can be sent from a later state.</item> - <item>There can be multiple <c>sys</c> traceable replies.</item> - </list> <p> The callback model(s) for <c>gen_statem</c> differs from the one for <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>, - but it is still fairly easy to rewrite - from <c>gen_fsm</c> to <c>gen_statem</c>. + but it is still fairly easy to + <seealso marker="gen_fsm#Migration to gen_statem"> + rewrite from + </seealso> <c>gen_fsm</c> to <c>gen_statem</c>. </p> <p> A generic state machine process (<c>gen_statem</c>) implemented @@ -143,10 +181,10 @@ erlang:'!' -----> Module:StateName/3 is <c>state_functions</c>, the state must be an atom and is used as the state callback name; see <seealso marker="#Module:StateName/3"><c>Module:StateName/3</c></seealso>. - This gathers all code for a specific state + This co-locates all code for a specific state in one function as the <c>gen_statem</c> engine branches depending on state name. - Notice the fact that there is a mandatory callback function + Note the fact that the callback function <seealso marker="#Module:terminate/3"><c>Module:terminate/3</c></seealso> makes the state name <c>terminate</c> unusable in this mode. </p> @@ -202,8 +240,10 @@ erlang:'!' -----> Module:StateName/3 whenever a new state is entered; see <seealso marker="#type-state_enter"><c>state_enter()</c></seealso>. This is for writing code common to all state entries. - Another way to do it is to insert events at state transitions, - but you have to do so everywhere it is needed. + Another way to do it is to insert an event at the state transition, + and/or to use a dedicated state transition function, + but that is something you will have to remember + at every state transition to the state(s) that need it. </p> <note> <p>If you in <c>gen_statem</c>, for example, postpone @@ -247,6 +287,16 @@ erlang:'!' -----> Module:StateName/3 to use after every event; see <seealso marker="erts:erlang#hibernate/3"><c>erlang:hibernate/3</c></seealso>. </p> + <p> + There is also a server start option + <seealso marker="#type-hibernate_after_opt"> + <c>{hibernate_after, Timeout}</c> + </seealso> + for + <seealso marker="#start/3"><c>start/3,4</c></seealso> or + <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso> + that may be used to automatically hibernate the server. + </p> </description> <section> @@ -341,7 +391,7 @@ ok <p> To compare styles, here follows the same example using <seealso marker="#type-callback_mode"><em>callback mode</em></seealso> - <c>state_functions</c>, or rather the code to replace + <c>handle_event_function</c>, or rather the code to replace after function <c>init/1</c> of the <c>pushbutton.erl</c> example file above: </p> @@ -448,6 +498,21 @@ handle_event(_, _, State, Data) -> </desc> </datatype> <datatype> + <name name="hibernate_after_opt"/> + <desc> + <p> + hibernate_after option that can be used when starting + a <c>gen_statem</c> server through, + <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. + </p> + <p>If option<seealso marker="#type-hibernate_after_opt"><c>{hibernate_after,HibernateAfterTimeout}</c></seealso> is present, the <c>gen_statem</c> + process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and + if no message is received, the process goes into hibernation automatically + (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). + </p> + </desc> + </datatype> + <datatype> <name name="start_opt"/> <desc> <p> @@ -523,7 +588,23 @@ handle_event(_, _, State, Data) -> <name name="event_type"/> <desc> <p> - External events are of three types: + There are 3 categories of events: + <seealso marker="#type-external_event_type">external</seealso>, + <seealso marker="#type-timeout_event_type">timeout</seealso>, + and <c>internal</c>. + </p> + <p> + <c>internal</c> events can only be generated by the + state machine itself through the state transition action + <seealso marker="#type-action"><c>next_event</c></seealso>. + </p> + </desc> + </datatype> + <datatype> + <name name="external_event_type"/> + <desc> + <p> + External events are of 3 types: <c>{call,<anno>From</anno>}</c>, <c>cast</c>, or <c>info</c>. <seealso marker="#call/2">Calls</seealso> (synchronous) and @@ -531,10 +612,17 @@ handle_event(_, _, State, Data) -> originate from the corresponding API functions. For calls, the event contains whom to reply to. Type <c>info</c> originates from regular process messages sent - to the <c>gen_statem</c>. Also, the state machine - implementation can generate events of types - <c>timeout</c>, <c>state_timeout</c>, - and <c>internal</c> to itself. + to the <c>gen_statem</c>. + </p> + </desc> + </datatype> + <datatype> + <name name="timeout_event_type"/> + <desc> + <p> + There are 3 types of timeout events that the state machine + can generate for itself with the corresponding + <seealso marker="#type-timeout_action">timeout_action()</seealso>s. </p> </desc> </datatype> @@ -625,9 +713,9 @@ handle_event(_, _, State, Data) -> <p> If <seealso marker="#Module:code_change/4"><c>Module:code_change/4</c></seealso> - should transform the state to a state with a different - name it is still regarded as the same state so this - does not cause a state enter call. + should transform the state, + it is regarded as a state rename and not a state change, + which will not cause a state enter call. </p> <p> Note that a state enter call <em>will</em> be done @@ -645,12 +733,19 @@ handle_event(_, _, State, Data) -> <p> Transition options can be set by <seealso marker="#type-action">actions</seealso> - and they modify how the state transition is done: + and modify the state transition. + Here are the sequence of steps for a state transition: </p> <list type="ordered"> <item> <p> - If the state changes, is the initial state, + If + <seealso marker="#type-state_enter"> + <em>state enter calls</em> + </seealso> + are used, and either: + the state changes, it is the initial state, + or one of the callback results <seealso marker="#type-state_callback_result"> <c>repeat_state</c> </seealso> @@ -658,16 +753,21 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-state_callback_result"> <c>repeat_state_and_data</c> </seealso> - is used, and also - <seealso marker="#type-state_enter"><em>state enter calls</em></seealso> - are used, the <c>gen_statem</c> calls + is used; the <c>gen_statem</c> calls the new state callback with arguments - <seealso marker="#type-state_enter">(enter, OldState, Data)</seealso>. + <seealso marker="#type-state_enter"><c>(enter, OldState, Data)</c></seealso>. + </p> + <p> Any - <seealso marker="#type-enter_action"><c>actions</c></seealso> + <seealso marker="#type-enter_action">actions</seealso> returned from this call are handled as if they were - appended to the actions - returned by the state callback that changed states. + appended to the actions + returned by the state callback that caused the state entry. + </p> + <p> + Should this state enter call return any of + the mentioned <c>repeat_*</c> callback results + it is repeated again, with the updated <c>Data</c>. </p> </item> <item> @@ -696,20 +796,23 @@ handle_event(_, _, State, Data) -> All events stored with <seealso marker="#type-action"><c>action()</c></seealso> <c>next_event</c> - are inserted to be processed before the other queued events. + are inserted to be processed before previously queued events. </p> </item> <item> <p> - Timeout timers - <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> + Time-out timers + <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso>, + <seealso marker="#type-generic_timeout"><c>generic_timeout()</c></seealso> and - <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> + <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> are handled. Time-outs with zero time are guaranteed to be delivered to the state machine before any external - not yet received event so if there is such a timeout requested, + not yet received event so if there is such a time-out requested, the corresponding time-out zero event is enqueued as - the newest event. + the newest received event; + that is after already queued events + such as inserted and postponed events. </p> <p> Any event cancels an @@ -747,7 +850,7 @@ handle_event(_, _, State, Data) -> When a new message arrives the <seealso marker="#state callback">state callback</seealso> is called with the corresponding event, - and we start again from the top of this list. + and we start again from the top of this sequence. </p> </item> </list> @@ -772,62 +875,121 @@ handle_event(_, _, State, Data) -> <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso> before going into <c>receive</c> to wait for a new external event. - If there are enqueued events, - to prevent receiving any new event, an - <seealso marker="erts:erlang#garbage_collect/0"><c>erlang:garbage_collect/0</c></seealso> - is done instead to simulate - that the <c>gen_statem</c> entered hibernation - and immediately got awakened by the oldest enqueued event. </p> + <note> + <p> + If there are enqueued events to process + when hibrnation is requested, + this is optimized by not hibernating but instead calling + <seealso marker="erts:erlang#garbage_collect/0"> + <c>erlang:garbage_collect/0</c> + </seealso> + to simulate that the <c>gen_statem</c> entered hibernation + and immediately got awakened by an enqueued event. + </p> + </note> </desc> </datatype> <datatype> <name name="event_timeout"/> <desc> <p> - Generates an event of + Starts a timer set by + <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + <c>timeout</c>. + When the timer expires an event of <seealso marker="#type-event_type"><c>event_type()</c></seealso> - <c>timeout</c> - after this time (in milliseconds) unless another - event arrives or has arrived - in which case this time-out is cancelled. + <c>timeout</c> will be generated. + See + <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso> + for how <c>Time</c> and + <seealso marker="#type-timeout_option"><c>Options</c></seealso> + are interpreted. Future <c>erlang:start_timer/4</c> <c>Options</c> + will not necessarily be supported. + </p> + <p> + Any event that arrives cancels this time-out. Note that a retried or inserted event counts as arrived. So does a state time-out zero event, if it was generated - before this timer is requested. + before this time-out is requested. </p> <p> - If the value is <c>infinity</c>, no timer is started, as - it never would trigger anyway. + If <c>Time</c> is <c>infinity</c>, + no timer is started, as it never would expire anyway. </p> <p> - If the value is <c>0</c> no timer is actually started, + If <c>Time</c> is relative and <c>0</c> + no timer is actually started, instead the the time-out event is enqueued to ensure that it gets processed before any not yet - received external event. + received external event, but after already queued events. </p> <p> - Note that it is not possible or needed to cancel this time-out, + Note that it is not possible nor needed to cancel this time-out, as it is cancelled automatically by any other event. </p> </desc> </datatype> <datatype> + <name name="generic_timeout"/> + <desc> + <p> + Starts a timer set by + <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + <c>{timeout,Name}</c>. + When the timer expires an event of + <seealso marker="#type-event_type"><c>event_type()</c></seealso> + <c>{timeout,Name}</c> will be generated. + See + <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso> + for how <c>Time</c> and + <seealso marker="#type-timeout_option"><c>Options</c></seealso> + are interpreted. Future <c>erlang:start_timer/4</c> <c>Options</c> + will not necessarily be supported. + </p> + <p> + If <c>Time</c> is <c>infinity</c>, + no timer is started, as it never would expire anyway. + </p> + <p> + If <c>Time</c> is relative and <c>0</c> + no timer is actually started, + instead the the time-out event is enqueued to ensure + that it gets processed before any not yet + received external event. + </p> + <p> + Setting a timer with the same <c>Name</c> while it is running + will restart it with the new time-out value. + Therefore it is possible to cancel + a specific time-out by setting it to <c>infinity</c>. + </p> + </desc> + </datatype> + <datatype> <name name="state_timeout"/> <desc> <p> - Generates an event of + Starts a timer set by + <seealso marker="#type-enter_action"><c>enter_action()</c></seealso> + <c>state_timeout</c>. + When the timer expires an event of <seealso marker="#type-event_type"><c>event_type()</c></seealso> - <c>state_timeout</c> - after this time (in milliseconds) unless the <c>gen_statem</c> - changes states (<c>NewState =/= OldState</c>) - which case this time-out is cancelled. + <c>state_timeout</c> will be generated. + See + <seealso marker="erts:erlang#start_timer/4"><c>erlang:start_timer/4</c></seealso> + for how <c>Time</c> and + <seealso marker="#type-timeout_option"><c>Options</c></seealso> + are interpreted. Future <c>erlang:start_timer/4</c> <c>Options</c> + will not necessarily be supported. </p> <p> - If the value is <c>infinity</c>, no timer is started, as - it never would trigger anyway. + If <c>Time</c> is <c>infinity</c>, + no timer is started, as it never would expire anyway. </p> <p> - If the value is <c>0</c> no timer is actually started, + If <c>Time</c> is relative and <c>0</c> + no timer is actually started, instead the the time-out event is enqueued to ensure that it gets processed before any not yet received external event. @@ -840,6 +1002,22 @@ handle_event(_, _, State, Data) -> </desc> </datatype> <datatype> + <name name="timeout_option"/> + <desc> + <p> + If <c>Abs</c> is <c>true</c> an absolute timer is started, + and if it is <c>false</c> a relative, which is the default. + See + <seealso marker="erts:erlang#start_timer/4"> + <c>erlang:start_timer/4</c> + </seealso> + for details. + </p> + <p> + </p> + </desc> + </datatype> + <datatype> <name name="action"/> <desc> <p> @@ -858,7 +1036,9 @@ handle_event(_, _, State, Data) -> </p> <p> Actions that set - <seealso marker="#type-transition_option">transition options</seealso> + <seealso marker="#type-transition_option"> + transition options + </seealso> override any previous of the same type, so the last in the containing list wins. For example, the last @@ -870,7 +1050,9 @@ handle_event(_, _, State, Data) -> <item> <p> Sets the - <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> + <seealso marker="#type-transition_option"> + <c>transition_option()</c> + </seealso> <seealso marker="#type-postpone"><c>postpone()</c></seealso> for this state transition. This action is ignored when returned from @@ -883,7 +1065,11 @@ handle_event(_, _, State, Data) -> <tag><c>next_event</c></tag> <item> <p> - Stores the specified <c><anno>EventType</anno></c> + This action does not set any + <seealso marker="#type-transition_option"> + <c>transition_option()</c> + </seealso> + but instead stores the specified <c><anno>EventType</anno></c> and <c><anno>EventContent</anno></c> for insertion after all actions have been executed. </p> @@ -936,16 +1122,34 @@ handle_event(_, _, State, Data) -> for this state transition. </p> </item> - <tag><c>Timeout</c></tag> + </taglist> + </desc> + </datatype> + <datatype> + <name name="timeout_action"/> + <desc> + <p> + These state transition actions can be invoked by + returning them from the + <seealso marker="#state callback">state callback</seealso>, from + <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> + or by giving them to + <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. + </p> + <p> + These timeout actions sets timeout + <seealso marker="#type-transition_option">transition options</seealso>. + </p> + <taglist> + <tag><c>Time</c></tag> <item> <p> - Short for <c>{timeout,Timeout,Timeout}</c>, that is, + Short for <c>{timeout,Time,Time}</c>, that is, the time-out message is the time-out time. This form exists to make the <seealso marker="#state callback">state callback</seealso> - return value <c>{next_state,NextState,NewData,Timeout}</c> - allowed like for <c>gen_fsm</c>'s - <seealso marker="gen_fsm#Module:StateName/2"><c>Module:StateName/2</c></seealso>. + return value <c>{next_state,NextState,NewData,Time}</c> + allowed like for <c>gen_fsm</c>. </p> </item> <tag><c>timeout</c></tag> @@ -954,7 +1158,21 @@ handle_event(_, _, State, Data) -> Sets the <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> <seealso marker="#type-event_timeout"><c>event_timeout()</c></seealso> - to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>. + to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c> + and time-out options + <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>. + </p> + </item> + <tag><c>{timeout,<anno>Name</anno>}</c></tag> + <item> + <p> + Sets the + <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> + <seealso marker="#type-generic_timeout"><c>generic_timeout()</c></seealso> + to <c><anno>Time</anno></c> for <c><anno>Name</anno></c> + with <c><anno>EventContent</anno></c> + and time-out options + <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>. </p> </item> <tag><c>state_timeout</c></tag> @@ -963,7 +1181,9 @@ handle_event(_, _, State, Data) -> Sets the <seealso marker="#type-transition_option"><c>transition_option()</c></seealso> <seealso marker="#type-state_timeout"><c>state_timeout()</c></seealso> - to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c>. + to <c><anno>Time</anno></c> with <c><anno>EventContent</anno></c> + and time-out options + <seealso marker="#type-timeout_option"><c><anno>Options</anno></c></seealso>. </p> </item> </taglist> @@ -981,7 +1201,11 @@ handle_event(_, _, State, Data) -> <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso>. </p> <p> - It replies to a caller waiting for a reply in + It does not set any + <seealso marker="#type-transition_option"> + <c>transition_option()</c> + </seealso> + but instead replies to a caller waiting for a reply in <seealso marker="#call/2"><c>call/2</c></seealso>. <c><anno>From</anno></c> must be the term from argument <seealso marker="#type-event_type"><c>{call,<anno>From</anno>}</c></seealso> @@ -993,7 +1217,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> or <seealso marker="#enter_loop/5"><c>enter_loop/5,6</c></seealso> - would be weird on the border of whichcraft + would be weird on the border of witchcraft since there has been no earlier call to a <seealso marker="#state callback">state callback</seealso> in this server. @@ -1174,8 +1398,8 @@ handle_event(_, _, State, Data) -> <funcs> <func> - <name name="call" arity="2"/> - <name name="call" arity="3"/> + <name name="call" arity="2" since="OTP 19.0"/> + <name name="call" arity="3" since="OTP 19.0"/> <fsummary>Make a synchronous call to a <c>gen_statem</c>.</fsummary> <desc> <p> @@ -1224,7 +1448,7 @@ handle_event(_, _, State, Data) -> <c><anno>T</anno></c> is the time-out time. <c>{clean_timeout,<anno>T</anno>}</c> works like just <c>T</c> described in the note above - and uses a proxy process for <c>T < infinity</c>, + and uses a proxy process while <c>{dirty_timeout,<anno>T</anno>}</c> bypasses the proxy process which is more lightweight. </p> @@ -1234,8 +1458,12 @@ handle_event(_, _, State, Data) -> with <c>{dirty_timeout,<anno>T</anno>}</c> to avoid that the calling process dies when the call times out, you will have to be prepared to handle - a late reply. - So why not just allow the calling process to die? + a late reply. Note that there is an odd chance + to get a late reply even with + <c>{dirty_timeout,infinity}</c> or <c>infinity</c> + for example in the event of network problems. + So why not just let the calling process die + by not catching the exception? </p> </note> <p> @@ -1246,7 +1474,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="cast" arity="2"/> + <name name="cast" arity="2" since="OTP 19.0"/> <fsummary>Send an asynchronous event to a <c>gen_statem</c>.</fsummary> <desc> <p> @@ -1265,7 +1493,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="enter_loop" arity="4"/> + <name name="enter_loop" arity="4" since="OTP 19.1"/> <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary> <desc> <p> @@ -1279,7 +1507,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="enter_loop" arity="5"/> + <name name="enter_loop" arity="5" since="OTP 19.0"/> <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary> <desc> <p> @@ -1303,7 +1531,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="enter_loop" arity="6"/> + <name name="enter_loop" arity="6" since="OTP 19.0"/> <fsummary>Enter the <c>gen_statem</c> receive loop.</fsummary> <desc> <p> @@ -1360,8 +1588,8 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="reply" arity="1"/> - <name name="reply" arity="2"/> + <name name="reply" arity="1" since="OTP 19.0"/> + <name name="reply" arity="2" since="OTP 19.0"/> <fsummary>Reply to a caller.</fsummary> <desc> <p> @@ -1393,8 +1621,8 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="start" arity="3"/> - <name name="start" arity="4"/> + <name name="start" arity="3" since="OTP 19.0"/> + <name name="start" arity="4" since="OTP 19.0"/> <fsummary>Create a standalone <c>gen_statem</c> process.</fsummary> <desc> <p> @@ -1414,8 +1642,8 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="start_link" arity="3"/> - <name name="start_link" arity="4"/> + <name name="start_link" arity="3" since="OTP 19.0"/> + <name name="start_link" arity="4" since="OTP 19.0"/> <fsummary>Create a linked <c>gen_statem</c> process.</fsummary> <desc> <p> @@ -1461,6 +1689,13 @@ handle_event(_, _, State, Data) -> </p> </item> <item> + <p>If option<seealso marker="#type-hibernate_after_opt"><c>{hibernate_after,HibernateAfterTimeout}</c></seealso> is present, the <c>gen_statem</c> + process awaits any message for <c>HibernateAfterTimeout</c> milliseconds and + if no message is received, the process goes into hibernation automatically + (by calling <seealso marker="proc_lib#hibernate/3"><c>proc_lib:hibernate/3</c></seealso>). + </p> + </item> + <item> <p> If option <seealso marker="#type-debug_opt"><c>{debug,Dbgs}</c></seealso> @@ -1515,7 +1750,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="stop" arity="1"/> + <name name="stop" arity="1" since="OTP 19.0"/> <fsummary>Synchronously stop a generic server.</fsummary> <desc> <p> @@ -1526,7 +1761,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name name="stop" arity="3"/> + <name name="stop" arity="3" since="OTP 19.0"/> <fsummary>Synchronously stop a generic server.</fsummary> <desc> <p> @@ -1543,7 +1778,7 @@ handle_event(_, _, State, Data) -> with the expected reason. Any other reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an error report to be issued through - <seealso marker="kernel:error_logger#format/2"><c>error_logger:format/2</c></seealso>. + <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. The default <c><anno>Reason</anno></c> is <c>normal</c>. </p> <p> @@ -1572,7 +1807,7 @@ handle_event(_, _, State, Data) -> <funcs> <func> - <name>Module:callback_mode() -> CallbackMode</name> + <name since="OTP 19.1">Module:callback_mode() -> CallbackMode</name> <fsummary>Update the internal state during upgrade/downgrade.</fsummary> <type> <v> @@ -1623,7 +1858,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name>Module:code_change(OldVsn, OldState, OldData, Extra) -> + <name since="OTP 19.0">Module:code_change(OldVsn, OldState, OldData, Extra) -> Result </name> <fsummary>Update the internal state during upgrade/downgrade.</fsummary> @@ -1644,6 +1879,16 @@ handle_event(_, _, State, Data) -> <v>Reason = term()</v> </type> <desc> + <note> + <p> + This callback is optional, so callback modules need not export it. + If a release upgrade/downgrade with + <c>Change={advanced,Extra}</c> + specified in the <c>.appup</c> file is made + when <c>code_change/4</c> is not implemented + the process will crash with exit reason <c>undef</c>. + </p> + </note> <p> This function is called by a <c>gen_statem</c> when it is to update its internal state during a release upgrade/downgrade, @@ -1702,9 +1947,9 @@ handle_event(_, _, State, Data) -> </func> <func> - <name>Module:init(Args) -> Result(StateType)</name> + <name since="OTP 19.0">Module:init(Args) -> Result(StateType)</name> <fsummary> - Optional function for initializing process and internal state. + Initializing process and internal state. </fsummary> <type> <v>Args = term()</v> @@ -1720,7 +1965,7 @@ handle_event(_, _, State, Data) -> <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso> or <seealso marker="#start/3"><c>start/3,4</c></seealso>, - this optional function is called by the new process to initialize + this function is called by the new process to initialize the implementation state and server data. </p> <p> @@ -1729,19 +1974,22 @@ handle_event(_, _, State, Data) -> </p> <note> <p> - This callback is optional, so a callback module does not need - to export it, but most do. If this function is not exported, - the <c>gen_statem</c> should be started through + Note that if the <c>gen_statem</c> is started through <seealso marker="proc_lib"><c>proc_lib</c></seealso> and - <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>. + <seealso marker="#enter_loop/4"><c>enter_loop/4-6</c></seealso>, + this callback will never be called. + Since this callback is not optional it can + in that case be implemented as: </p> + <pre> +init(Args) -> erlang:error(not_implemented, [Args]).</pre> </note> </desc> </func> <func> - <name>Module:format_status(Opt, [PDict,State,Data]) -> + <name since="OTP 19.0">Module:format_status(Opt, [PDict,State,Data]) -> Status </name> <fsummary>Optional function for providing a term describing the @@ -1840,16 +2088,16 @@ handle_event(_, _, State, Data) -> </func> <func> - <name>Module:StateName(enter, OldState, Data) -> + <name since="OTP 19.0">Module:StateName(enter, OldState, Data) -> StateEnterResult(StateName) </name> - <name>Module:StateName(EventType, EventContent, Data) -> + <name since="OTP 19.0">Module:StateName(EventType, EventContent, Data) -> StateFunctionResult </name> - <name>Module:handle_event(enter, OldState, State, Data) -> + <name since="OTP 19.0">Module:handle_event(enter, OldState, State, Data) -> StateEnterResult(State) </name> - <name>Module:handle_event(EventType, EventContent, State, Data) -> + <name since="OTP 19.0">Module:handle_event(EventType, EventContent, State, Data) -> HandleEventResult </name> <fsummary>Handle an event.</fsummary> @@ -1940,16 +2188,20 @@ handle_event(_, _, State, Data) -> You may also not change states from this call. Should you return <c>{next_state,NextState, ...}</c> with <c>NextState =/= State</c> the <c>gen_statem</c> crashes. - It is possible to use <c>{repeat_state, ...}</c>, - <c>{repeat_state_and_data,_}</c> or - <c>repeat_state_and_data</c> but all of them makes little + Note that it is actually allowed to use + <c>{repeat_state, NewData, ...}</c> although it makes little sense since you immediately will be called again with a new <em>state enter call</em> making this just a weird way of looping, and there are better ways to loop in Erlang. + If you do not update <c>NewData</c> and have some + loop termination condition, or if you use + <c>{repeat_state_and_data, _}</c> or + <c>repeat_state_and_data</c> you have an infinite loop! You are advised to use <c>{keep_state,...}</c>, <c>{keep_state_and_data,_}</c> or - <c>keep_state_and_data</c> since you can not change states - from a <em>state enter call</em> anyway. + <c>keep_state_and_data</c> + since changing states from a <em>state enter call</em> + is not possible anyway. </p> <p> Note the fact that you can use @@ -1964,7 +2216,7 @@ handle_event(_, _, State, Data) -> </func> <func> - <name>Module:terminate(Reason, State, Data) -> Ignored</name> + <name since="OTP 19.0">Module:terminate(Reason, State, Data) -> Ignored</name> <fsummary>Clean up before termination.</fsummary> <type> <v>Reason = normal | shutdown | {shutdown,term()} | term()</v> @@ -2034,7 +2286,7 @@ handle_event(_, _, State, Data) -> <c>shutdown</c>, or <c>{shutdown,Term}</c>, the <c>gen_statem</c> is assumed to terminate because of an error and an error report is issued using - <seealso marker="kernel:error_logger#format/2"><c>error_logger:format/2</c></seealso>. + <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. </p> </desc> </func> diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml index 11a64c7f8a..d69e808586 100644 --- a/lib/stdlib/doc/src/io.xml +++ b/lib/stdlib/doc/src/io.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>io</module> + <module since="">io</module> <modulesummary>Standard I/O server interface functions.</modulesummary> <description> <p>This module provides an interface to standard Erlang I/O servers. @@ -104,8 +104,8 @@ <funcs> <func> - <name name="columns" arity="0"/> - <name name="columns" arity="1"/> + <name name="columns" arity="0" since=""/> + <name name="columns" arity="1" since=""/> <fsummary>Get the number of columns of an I/O device.</fsummary> <desc> <p>Retrieves the number of columns of the @@ -116,12 +116,12 @@ </func> <func> - <name name="format" arity="1"/> - <name name="format" arity="2"/> - <name name="format" arity="3"/> - <name name="fwrite" arity="1"/> - <name name="fwrite" arity="2"/> - <name name="fwrite" arity="3"/> + <name name="format" arity="1" since=""/> + <name name="format" arity="2" since=""/> + <name name="format" arity="3" since=""/> + <name name="fwrite" arity="1" since=""/> + <name name="fwrite" arity="2" since=""/> + <name name="fwrite" arity="3" since=""/> <fsummary>Write formatted output.</fsummary> <desc> <p>Writes the items in <c><anno>Data</anno></c> (<c>[]</c>) on the @@ -137,11 +137,11 @@ Hello world! ok</pre> <p>The general format of a control sequence is <c>~F.P.PadModC</c>.</p> - <p>Character <c>C</c> determines the type of control sequence - to be used, <c>F</c> and <c>P</c> are optional numeric - arguments. If <c>F</c>, <c>P</c>, or <c>Pad</c> is <c>*</c>, - the next argument in <c>Data</c> is used as the numeric value - of <c>F</c> or <c>P</c>.</p> + <p>The character <c>C</c> determines the type of control sequence + to be used. It is the only required field. All of <c>F</c>, + <c>P</c>, <c>Pad</c>, and <c>Mod</c> are optional. For example, + to use a <c>#</c> for <c>Pad</c> but use the default values for + <c>F</c> and <c>P</c>, you can write <c>~..#C</c>.</p> <list type="bulleted"> <item> <p><c>F</c> is the <c>field width</c> of the printed argument. A @@ -167,13 +167,26 @@ ok</pre> The default padding character is <c>' '</c> (space).</p> </item> <item> - <p><c>Mod</c> is the control sequence modifier. It is either a - single character (<c>t</c>, for Unicode - translation, and <c>l</c>, for stopping <c>p</c> and - <c>P</c> from detecting printable characters) - that changes the interpretation of <c>Data</c>.</p> + <p><c>Mod</c> is the control sequence modifier. This is + one or more characters that change the interpretation of + <c>Data</c>. The current modifiers are <c>t</c>, for Unicode + translation, and <c>l</c>, for stopping <c>p</c> and <c>P</c> + from detecting printable characters.</p> </item> </list> + <p>If <c>F</c>, <c>P</c>, or <c>Pad</c> is a <c>*</c> character, + the next argument in <c>Data</c> is used as the value. + For example:</p> + <pre> +1> <input>io:fwrite("~*.*.0f~n",[9, 5, 3.14159265]).</input> +003.14159 +ok</pre> + <p>To use a literal <c>*</c> character as <c>Pad</c>, it must be + passed as an argument:</p> + <pre> +2> <input>io:fwrite("~*.*.*f~n",[9, 5, $*, 3.14159265]).</input> +**3.14159 +ok</pre> <p><em>Available control sequences:</em></p> <taglist> <tag><c>~</c></tag> @@ -257,14 +270,17 @@ ok</pre> \x{400} ok 5> <input>io:fwrite("~s~n",[[1024]]).</input> -** exception exit: {badarg,[{io,format,[<0.26.0>,"~s~n",[[1024]]]}, - ...</pre> +** exception error: bad argument + in function io:format/3 + called as io:format(<0.53.0>,"~s~n",[[1024]])</pre> </item> <tag><c>w</c></tag> <item> <p>Writes data with the standard syntax. This is used to output Erlang terms. Atoms are printed within quotes if they contain embedded non-printable characters. + Atom characters > 255 are escaped unless the + Unicode translation modifier (<c>t</c>) is used. Floats are printed accurately as the shortest, correctly rounded string.</p> </item> @@ -274,10 +290,9 @@ ok <c>~w</c>, but breaks terms whose printed representation is longer than one line into many lines and indents each line sensibly. Left-justification is not supported. - It also tries to detect lists of - printable characters and to output these as strings. The - Unicode translation modifier is used for determining - what characters are printable, for example:</p> + It also tries to detect flat lists of + printable characters and output these as strings. + For example:</p> <pre> 1> <input>T = [{attributes,[[{id,age,1.50000},{mode,explicit},</input> <input>{typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},</input> @@ -299,7 +314,7 @@ ok {mode,implicit}] ok</pre> <p>The field width specifies the maximum line length. - Defaults to 80. The precision specifies the initial + It defaults to 80. The precision specifies the initial indentation of the term. It defaults to the number of characters printed on this line in the <em>same</em> call to <seealso marker="#write/1"><c>write/1</c></seealso> or @@ -317,11 +332,22 @@ Here T = [{attributes,[[{id,age,1.5}, {tag,{'PRIVATE',3}}, {mode,implicit}] ok</pre> + + <p>As from Erlang/OTP 21.0, a field width of value + <c>0</c> can be used for specifying that a line is + infinitely long, which means that no line breaks + are inserted. For example:</p> + + <pre> +5> <input>io:fwrite("~0p~n", [lists:seq(1, 30)]).</input> +[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30] +ok</pre> + <p>When the modifier <c>l</c> is specified, no detection of printable character lists takes place, for example:</p> <pre> -5> <input>S = [{a,"a"}, {b, "b"}].</input> -6> <input>io:fwrite("~15p~n", [S]).</input> +6> <input>S = [{a,"a"}, {b, "b"}], + io:fwrite("~15p~n", [S]).</input> [{a,"a"}, {b,"b"}] ok @@ -329,18 +355,53 @@ ok [{a,[97]}, {b,[98]}] ok</pre> - <p>Binaries that look like UTF-8 encoded strings are - output with the string syntax if the Unicode translation - modifier is specified:</p> + <p>The Unicode translation modifier <c>t</c> specifies how to treat + characters outside the Latin-1 range of codepoints, in + atoms, strings, and binaries. For example, printing an atom + containing a character > 255:</p> + <pre> +8> <input>io:fwrite("~p~n",[list_to_atom([1024])]).</input> +'\x{400}' +ok +9> <input>io:fwrite("~tp~n",[list_to_atom([1024])]).</input> +'Ѐ' +ok</pre> + <p>By default, Erlang only detects lists of characters + in the Latin-1 range as strings, but the <c>+pc unicode</c> + flag can be used to change this (see <seealso + marker="#printable_range/0"> + <c>printable_range/0</c></seealso> for details). For example:</p> <pre> -9> <input>io:fwrite("~p~n",[[1024]]).</input> +10> <input>io:fwrite("~p~n",[[214]]).</input> +"Ö" +ok +11> <input>io:fwrite("~p~n",[[1024]]).</input> +[1024] +ok +12> <input>io:fwrite("~tp~n",[[1024]]).</input> +[1024] +ok +</pre> + <p>but if Erlang was started with <c>+pc unicode</c>:</p> + <pre> +13> <input>io:fwrite("~p~n",[[1024]]).</input> [1024] -10> <input>io:fwrite("~tp~n",[[1024]]).</input> -"\x{400}" -11> <input>io:fwrite("~tp~n", [<<128,128>>]).</input> +ok +14> <input>io:fwrite("~tp~n",[[1024]]).</input> +"Ѐ" +ok</pre> + <p>Similarly, binaries that look like UTF-8 encoded strings + are output with the binary string syntax if the <c>t</c> + modifier is specified:</p> + <pre> +15> <input>io:fwrite("~p~n", [<<208,128>>]).</input> +<<208,128>> +ok +16> <input>io:fwrite("~tp~n", [<<208,128>>]).</input> +<<"Ѐ"/utf8>> +ok +17> <input>io:fwrite("~tp~n", [<<128,128>>]).</input> <<128,128>> -12> <input>io:fwrite("~tp~n", [<<208,128>>]).</input> -<<"\x{400}"/utf8>> ok</pre> </item> <tag><c>W</c></tag> @@ -452,12 +513,9 @@ ok</pre> abc def 'abc def' {foo,1} A ok 2> <input>io:fwrite("~s", [65]).</input> -** exception exit: {badarg,[{io,format,[<0.22.0>,"~s","A"]}, - {erl_eval,do_apply,5}, - {shell,exprs,6}, - {shell,eval_exprs,6}, - {shell,eval_loop,3}]} - in function io:o_request/2</pre> +** exception error: bad argument + in function io:format/3 + called as io:format(<0.53.0>,"~s","A")</pre> <p>In this example, an attempt was made to output the single character 65 with the aid of the string formatting directive <c>"~s"</c>.</p> @@ -465,8 +523,8 @@ ok </func> <func> - <name name="fread" arity="2"/> - <name name="fread" arity="3"/> + <name name="fread" arity="2" since=""/> + <name name="fread" arity="3" since=""/> <fsummary>Read formatted input.</fsummary> <type name="server_no_data"/> <desc> @@ -567,8 +625,6 @@ Prompt> <input><Characters beyond latin1 range not printable in this medium&g <item> <p>Similar to <c>s</c>, but the resulting string is converted into an atom.</p> - <p>The Unicode translation modifier is not allowed (atoms - cannot contain characters beyond the <c>latin1</c> range).</p> </item> <tag><c>c</c></tag> <item> @@ -634,8 +690,8 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in </func> <func> - <name name="get_chars" arity="2"/> - <name name="get_chars" arity="3"/> + <name name="get_chars" arity="2" since=""/> + <name name="get_chars" arity="3" since=""/> <fsummary>Read a specified number of characters.</fsummary> <type name="server_no_data"/> <desc> @@ -666,8 +722,8 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in </func> <func> - <name name="get_line" arity="1"/> - <name name="get_line" arity="2"/> + <name name="get_line" arity="1" since=""/> + <name name="get_line" arity="2" since=""/> <fsummary>Read a line.</fsummary> <type name="server_no_data"/> <desc> @@ -698,8 +754,8 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in </func> <func> - <name name="getopts" arity="0"/> - <name name="getopts" arity="1"/> + <name name="getopts" arity="0" since=""/> + <name name="getopts" arity="1" since=""/> <fsummary>Get the supported options and values from an I/O server. </fsummary> <desc> @@ -725,8 +781,8 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in </func> <func> - <name name="nl" arity="0"/> - <name name="nl" arity="1"/> + <name name="nl" arity="0" since=""/> + <name name="nl" arity="1" since=""/> <fsummary>Write a newline.</fsummary> <desc> <p>Writes new line to the standard output @@ -735,10 +791,10 @@ enter><input>:</input> <input>alan</input> <input>:</input> <input>joe</in </func> <func> - <name name="parse_erl_exprs" arity="1"/> - <name name="parse_erl_exprs" arity="2"/> - <name name="parse_erl_exprs" arity="3"/> - <name name="parse_erl_exprs" arity="4"/> + <name name="parse_erl_exprs" arity="1" since=""/> + <name name="parse_erl_exprs" arity="2" since=""/> + <name name="parse_erl_exprs" arity="3" since=""/> + <name name="parse_erl_exprs" arity="4" since="OTP R16B"/> <fsummary>Read, tokenize, and parse Erlang expressions.</fsummary> <type name="parse_ret"/> <type name="server_no_data"/> @@ -788,10 +844,10 @@ enter><input>abc("hey".</input> </func> <func> - <name name="parse_erl_form" arity="1"/> - <name name="parse_erl_form" arity="2"/> - <name name="parse_erl_form" arity="3"/> - <name name="parse_erl_form" arity="4"/> + <name name="parse_erl_form" arity="1" since=""/> + <name name="parse_erl_form" arity="2" since=""/> + <name name="parse_erl_form" arity="3" since=""/> + <name name="parse_erl_form" arity="4" since="OTP R16B"/> <fsummary>Read, tokenize, and parse an Erlang form.</fsummary> <type name="parse_form_ret"/> <type name="server_no_data"/> @@ -832,7 +888,7 @@ enter><input>abc("hey".</input> </func> <func> - <name name="printable_range" arity="0"/> + <name name="printable_range" arity="0" since="OTP R16B"/> <fsummary>Get user-requested printable character range.</fsummary> <desc> <p>Returns the user-requested range of printable Unicode characters.</p> @@ -862,8 +918,8 @@ enter><input>abc("hey".</input> </func> <func> - <name name="put_chars" arity="1"/> - <name name="put_chars" arity="2"/> + <name name="put_chars" arity="1" since=""/> + <name name="put_chars" arity="2" since=""/> <fsummary>Write a list of characters.</fsummary> <desc> <p>Writes the characters of <c><anno>CharData</anno></c> to the I/O @@ -872,8 +928,8 @@ enter><input>abc("hey".</input> </func> <func> - <name name="read" arity="1"/> - <name name="read" arity="2"/> + <name name="read" arity="1" since=""/> + <name name="read" arity="2" since=""/> <fsummary>Read a term.</fsummary> <type name="server_no_data"/> <desc> @@ -904,8 +960,8 @@ enter><input>abc("hey".</input> </func> <func> - <name name="read" arity="3"/> - <name name="read" arity="4"/> + <name name="read" arity="3" since=""/> + <name name="read" arity="4" since="OTP R16B"/> <fsummary>Read a term.</fsummary> <type name="server_no_data"/> <desc> @@ -941,8 +997,8 @@ enter><input>abc("hey".</input> </func> <func> - <name name="rows" arity="0"/> - <name name="rows" arity="1"/> + <name name="rows" arity="0" since=""/> + <name name="rows" arity="1" since=""/> <fsummary>Get the number of rows of an I/O device.</fsummary> <desc> <p>Retrieves the number of rows of <c><anno>IoDevice</anno></c> @@ -953,10 +1009,10 @@ enter><input>abc("hey".</input> </func> <func> - <name name="scan_erl_exprs" arity="1"/> - <name name="scan_erl_exprs" arity="2"/> - <name name="scan_erl_exprs" arity="3"/> - <name name="scan_erl_exprs" arity="4"/> + <name name="scan_erl_exprs" arity="1" since=""/> + <name name="scan_erl_exprs" arity="2" since=""/> + <name name="scan_erl_exprs" arity="3" since=""/> + <name name="scan_erl_exprs" arity="4" since="OTP R16B"/> <fsummary>Read and tokenize Erlang expressions.</fsummary> <type name="server_no_data"/> <desc> @@ -1004,10 +1060,10 @@ enter><input>1.0er.</input> </func> <func> - <name name="scan_erl_form" arity="1"/> - <name name="scan_erl_form" arity="2"/> - <name name="scan_erl_form" arity="3"/> - <name name="scan_erl_form" arity="4"/> + <name name="scan_erl_form" arity="1" since=""/> + <name name="scan_erl_form" arity="2" since=""/> + <name name="scan_erl_form" arity="3" since=""/> + <name name="scan_erl_form" arity="4" since="OTP R16B"/> <fsummary>Read and tokenize an Erlang form.</fsummary> <type name="server_no_data"/> <desc> @@ -1027,8 +1083,8 @@ enter><input>1.0er.</input> </func> <func> - <name name="setopts" arity="1"/> - <name name="setopts" arity="2"/> + <name name="setopts" arity="1" since=""/> + <name name="setopts" arity="2" since=""/> <fsummary>Set options.</fsummary> <desc> <p>Set options for the standard I/O device @@ -1142,8 +1198,8 @@ fun("") -> {yes, "quit", []}; </func> <func> - <name name="write" arity="1"/> - <name name="write" arity="2"/> + <name name="write" arity="1" since=""/> + <name name="write" arity="2" since=""/> <fsummary>Write a term.</fsummary> <desc> <p>Writes term <c><anno>Term</anno></c> to the standard output diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml index 931e50f6f2..4d527f8ed3 100644 --- a/lib/stdlib/doc/src/io_lib.xml +++ b/lib/stdlib/doc/src/io_lib.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>io_lib</module> + <module since="">io_lib</module> <modulesummary>I/O library functions.</modulesummary> <description> <p>This module contains functions for converting to and from @@ -52,6 +52,9 @@ </desc> </datatype> <datatype> + <name name="chars_limit"/> + </datatype> + <datatype> <name name="depth"/> </datatype> <datatype> @@ -96,7 +99,7 @@ <funcs> <func> - <name name="build_text" arity="1"/> + <name name="build_text" arity="1" since="OTP 18.0"/> <fsummary>Build the output text for a preparsed format list.</fsummary> <desc> <p>For details, see @@ -105,7 +108,7 @@ </func> <func> - <name name="char_list" arity="1"/> + <name name="char_list" arity="1" since=""/> <fsummary>Test for a list of characters.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of @@ -114,7 +117,7 @@ </func> <func> - <name name="deep_char_list" arity="1"/> + <name name="deep_char_list" arity="1" since=""/> <fsummary>Test for a deep list of characters.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep, @@ -123,7 +126,7 @@ </func> <func> - <name name="deep_latin1_char_list" arity="1"/> + <name name="deep_latin1_char_list" arity="1" since="OTP R16B"/> <fsummary>Test for a deep list of characters.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a, possibly deep, @@ -133,8 +136,8 @@ </func> <func> - <name name="format" arity="2"/> - <name name="fwrite" arity="2"/> + <name name="format" arity="2" since=""/> + <name name="fwrite" arity="2" since=""/> <fsummary>Write formatted output.</fsummary> <desc> <p>Returns a character list that represents <c><anno>Data</anno></c> @@ -147,13 +150,38 @@ format string (that is, <c>~ts</c> or <c>~tc</c>), the resulting list can contain characters beyond the ISO Latin-1 character range (that is, numbers > 255). If so, the - result is not an ordinary Erlang <c>string()</c>, but can well be + result is still an ordinary Erlang <c>string()</c>, and can well be used in any context where Unicode data is allowed.</p> </desc> </func> <func> - <name name="fread" arity="2"/> + <name name="format" arity="3" since="OTP 21.0"/> + <name name="fwrite" arity="3" since="OTP 21.0"/> + <fsummary>Write formatted output.</fsummary> + <desc> + <p>Returns a character list that represents <c><anno>Data</anno></c> + formatted in accordance with <c><anno>Format</anno></c> in + the same way as + <seealso marker="#fwrite/2"><c>fwrite/2</c></seealso> and + <seealso marker="#format/2"><c>format/2</c></seealso>, + but takes an extra argument, a list of options.</p> + <p>Valid option:</p> + <taglist> + <tag><c>{chars_limit, <anno>CharsLimit</anno>}</c></tag> + <item> + <p>A soft limit on the number of characters returned. + When the number of characters is reached, remaining + structures are replaced by "<c>...</c>". + <c><anno>CharsLimit</anno></c> defaults to -1, which + means no limit on the number of characters returned.</p> + </item> + </taglist> + </desc> + </func> + + <func> + <name name="fread" arity="2" since=""/> <fsummary>Read formatted input.</fsummary> <desc> <p>Tries to read <c><anno>String</anno></c> in accordance with the @@ -194,7 +222,7 @@ </func> <func> - <name name="fread" arity="3"/> + <name name="fread" arity="3" since=""/> <fsummary>Re-entrant formatted reader</fsummary> <desc> <p>This is the re-entrant formatted reader. The continuation of @@ -240,7 +268,7 @@ </func> <func> - <name name="indentation" arity="2"/> + <name name="indentation" arity="2" since=""/> <fsummary>Indentation after printing string.</fsummary> <desc> <p>Returns the indentation if <c><anno>String</anno></c> has been @@ -249,7 +277,7 @@ </func> <func> - <name name="latin1_char_list" arity="1"/> + <name name="latin1_char_list" arity="1" since="OTP R16B"/> <fsummary>Test for a list of ISO Latin-1 characters.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of @@ -258,7 +286,7 @@ </func> <func> - <name name="nl" arity="0"/> + <name name="nl" arity="0" since=""/> <fsummary>Write a newline.</fsummary> <desc> <p>Returns a character list that represents a new line character.</p> @@ -266,8 +294,8 @@ </func> <func> - <name name="print" arity="1"/> - <name name="print" arity="4"/> + <name name="print" arity="1" since=""/> + <name name="print" arity="4" since=""/> <fsummary>Pretty print a term.</fsummary> <desc> <p>Returns a list of characters that represents @@ -287,7 +315,7 @@ </func> <func> - <name name="printable_latin1_list" arity="1"/> + <name name="printable_latin1_list" arity="1" since="OTP R16B"/> <fsummary>Test for a list of printable ISO Latin-1 characters.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of @@ -296,7 +324,7 @@ </func> <func> - <name name="printable_list" arity="1"/> + <name name="printable_list" arity="1" since=""/> <fsummary>Test for a list of printable characters.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of @@ -310,7 +338,7 @@ </func> <func> - <name name="printable_unicode_list" arity="1"/> + <name name="printable_unicode_list" arity="1" since="OTP R16B"/> <fsummary>Test for a list of printable Unicode characters.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is a flat list of @@ -319,7 +347,7 @@ </func> <func> - <name name="scan_format" arity="2"/> + <name name="scan_format" arity="2" since="OTP 18.0"/> <fsummary>Parse all control sequences in the format string.</fsummary> <desc> <p>Returns a list corresponding to the specified format string, @@ -345,7 +373,7 @@ </func> <func> - <name name="unscan_format" arity="1"/> + <name name="unscan_format" arity="1" since="OTP 18.0"/> <fsummary>Revert a preparsed format list to a plain character list and a list of arguments.</fsummary> <desc> @@ -355,27 +383,35 @@ </func> <func> - <name name="write" arity="1"/> - <name name="write" arity="2"/> + <name name="write" arity="1" since=""/> + <name name="write" arity="2" clause_i="1" since=""/> + <name name="write" arity="2" clause_i="2" since="OTP 20.0"/> <fsummary>Write a term.</fsummary> <desc> <p>Returns a character list that represents <c><anno>Term</anno></c>. - Argument <c><anno>Depth</anno></c> controls the depth of the + Option <c><anno>Depth</anno></c> controls the depth of the structures written. When the specified depth is reached, everything below this level is replaced by "<c>...</c>". <c><anno>Depth</anno></c> defaults to -1, which means - no limitation.</p> + no limitation. Option <c><anno>CharsLimit</anno></c> puts a + soft limit on the number of characters returned. When the + number of characters is reached, remaining structures are + replaced by "<c>...</c>". <c><anno>CharsLimit</anno></c> + defaults to -1, which means no limit on the number of + characters returned.</p> <p><em>Example:</em></p> <pre> 1> <input>lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9})).</input> "{1,[2],[3],[4,5],6,7,8,9}" 2> <input>lists:flatten(io_lib:write({1,[2],[3],[4,5],6,7,8,9}, 5)).</input> -"{1,[2],[3],[...],...}"</pre> +"{1,[2],[3],[...],...}" +3> <input>lists:flatten(io_lib:write({[1,2,3],[4,5],6,7,8,9}, [{chars_limit,20}])).</input> +"{[1,2|...],[4|...],...}"</pre> </desc> </func> <func> - <name name="write_atom" arity="1"/> + <name name="write_atom" arity="1" since=""/> <fsummary>Write an atom.</fsummary> <desc> <p>Returns the list of characters needed to print atom @@ -384,7 +420,17 @@ </func> <func> - <name name="write_char" arity="1"/> + <name name="write_atom_as_latin1" arity="1" since="OTP 20.0"/> + <fsummary>Write an atom.</fsummary> + <desc> + <p>Returns the list of characters needed to print atom + <c><anno>Atom</anno></c>. Non-Latin-1 characters + are escaped.</p> + </desc> + </func> + + <func> + <name name="write_char" arity="1" since=""/> <fsummary>Write a character.</fsummary> <desc> <p>Returns the list of characters needed to print a character @@ -393,7 +439,7 @@ </func> <func> - <name name="write_char_as_latin1" arity="1"/> + <name name="write_char_as_latin1" arity="1" since="OTP R16B"/> <fsummary>Write a character.</fsummary> <desc> <p>Returns the list of characters needed to print a character @@ -403,7 +449,7 @@ </func> <func> - <name name="write_latin1_char" arity="1"/> + <name name="write_latin1_char" arity="1" since="OTP R16B"/> <fsummary>Write an ISO Latin-1 character.</fsummary> <desc> <p>Returns the list of characters needed to print a character @@ -412,7 +458,7 @@ </func> <func> - <name name="write_latin1_string" arity="1"/> + <name name="write_latin1_string" arity="1" since="OTP R16B"/> <fsummary>Write an ISO Latin-1 string.</fsummary> <desc> <p>Returns the list of characters needed to print @@ -421,7 +467,7 @@ </func> <func> - <name name="write_string" arity="1"/> + <name name="write_string" arity="1" since=""/> <fsummary>Write a string.</fsummary> <desc> <p>Returns the list of characters needed to print @@ -430,7 +476,7 @@ </func> <func> - <name name="write_string_as_latin1" arity="1"/> + <name name="write_string_as_latin1" arity="1" since="OTP R16B"/> <fsummary>Write a string.</fsummary> <desc> <p>Returns the list of characters needed to print diff --git a/lib/stdlib/doc/src/lib.xml b/lib/stdlib/doc/src/lib.xml deleted file mode 100644 index 58dad7c9e0..0000000000 --- a/lib/stdlib/doc/src/lib.xml +++ /dev/null @@ -1,103 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>lib</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - </header> - <module>lib</module> - <modulesummary>Useful library functions.</modulesummary> - <description> - <warning> - <p>This module is retained for backward compatibility. It can disappear - without warning in a future Erlang/OTP release.</p> - </warning> - </description> - - <funcs> - <func> - <name name="error_message" arity="2"/> - <fsummary>Print error message.</fsummary> - <desc> - <p>Prints error message <c><anno>Args</anno></c> in accordance with - <c><anno>Format</anno></c>. Similar to - <seealso marker="io#format/1"><c>io:format/2</c></seealso>.</p> - </desc> - </func> - - <func> - <name name="flush_receive" arity="0"/> - <fsummary>Flush messages.</fsummary> - <desc> - <p>Flushes the message buffer of the current process.</p> - </desc> - </func> - - <func> - <name name="nonl" arity="1"/> - <fsummary>Remove last newline.</fsummary> - <desc> - <p>Removes the last newline character, if any, in - <c><anno>String1</anno></c>.</p> - </desc> - </func> - - <func> - <name name="progname" arity="0"/> - <fsummary>Return name of Erlang start script.</fsummary> - <desc> - <p>Returns the name of the script that started the current - Erlang session.</p> - </desc> - </func> - - <func> - <name name="send" arity="2"/> - <fsummary>Send a message.</fsummary> - <desc> - <p>Makes it possible to send a message using the <c>apply/3</c> BIF.</p> - </desc> - </func> - - <func> - <name name="sendw" arity="2"/> - <fsummary>Send a message and wait for an answer.</fsummary> - <desc> - <p>As <seealso marker="#send/2"><c>send/2</c></seealso>, - but waits for an answer. It is implemented as follows:</p> - <code type="none"> -sendw(To, Msg) -> - To ! {self(),Msg}, - receive - Reply -> Reply - end.</code> - <p>The returned message is not necessarily a reply to the sent - message.</p> - </desc> - </func> - </funcs> -</erlref> - diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml index 60dbae70c2..2755fb3dce 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>2016</year> + <year>1996</year><year>2019</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date>1996-09-28</date> <rev>A</rev> </header> - <module>lists</module> + <module since="">lists</module> <modulesummary>List processing functions.</modulesummary> <description> <p>This module contains functions for list processing.</p> @@ -63,7 +63,7 @@ <funcs> <func> - <name name="all" arity="2"/> + <name name="all" arity="2" since=""/> <fsummary>Return <c>true</c> if all elements in a list satisfy <c>Pred</c>.</fsummary> <desc> @@ -74,7 +74,7 @@ </func> <func> - <name name="any" arity="2"/> + <name name="any" arity="2" since=""/> <fsummary>Return <c>true</c> if any of the elements in a list satisfies <c>Pred</c>.</fsummary> <desc> @@ -85,7 +85,7 @@ </func> <func> - <name name="append" arity="1"/> + <name name="append" arity="1" since=""/> <fsummary>Append a list of lists.</fsummary> <desc> <p>Returns a list in which all the sublists of @@ -98,7 +98,7 @@ </func> <func> - <name name="append" arity="2"/> + <name name="append" arity="2" since=""/> <fsummary>Append two lists.</fsummary> <desc> <p>Returns a new list <c><anno>List3</anno></c>, which is made from @@ -113,7 +113,7 @@ </func> <func> - <name name="concat" arity="1"/> + <name name="concat" arity="1" since=""/> <fsummary>Concatenate a list of atoms.</fsummary> <desc> <p>Concatenates the text representation of the elements of @@ -127,7 +127,7 @@ </func> <func> - <name name="delete" arity="2"/> + <name name="delete" arity="2" since=""/> <fsummary>Delete an element from a list.</fsummary> <desc> <p>Returns a copy of <c><anno>List1</anno></c> where the first element @@ -137,7 +137,7 @@ </func> <func> - <name name="droplast" arity="1"/> + <name name="droplast" arity="1" since="OTP 17.0"/> <fsummary>Drop the last element of a list.</fsummary> <desc> <p>Drops the last element of a <c><anno>List</anno></c>. The list is to @@ -147,7 +147,7 @@ </func> <func> - <name name="dropwhile" arity="2"/> + <name name="dropwhile" arity="2" since=""/> <fsummary>Drop elements from a list while a predicate is <c>true</c>. </fsummary> <desc> @@ -159,7 +159,7 @@ </func> <func> - <name name="duplicate" arity="2"/> + <name name="duplicate" arity="2" since=""/> <fsummary>Make <c>N</c> copies of element.</fsummary> <desc> <p>Returns a list containing <c><anno>N</anno></c> copies of term @@ -172,7 +172,7 @@ </func> <func> - <name name="filter" arity="2"/> + <name name="filter" arity="2" since=""/> <fsummary>Select elements that satisfy a predicate.</fsummary> <desc> <p><c><anno>List2</anno></c> is a list of all elements @@ -182,12 +182,12 @@ </func> <func> - <name name="filtermap" arity="2"/> + <name name="filtermap" arity="2" since="OTP R16B01"/> <fsummary>Filter and map elements that satisfy a function.</fsummary> <desc> <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> on successive elements <c>Elem</c> of <c><anno>List1</anno></c>. - <c><anno>Fun</anno>/2</c> must return either a Boolean or a tuple + <c><anno>Fun</anno>/1</c> must return either a Boolean or a tuple <c>{true, <anno>Value</anno>}</c>. The function returns the list of elements for which <c><anno>Fun</anno></c> returns a new value, where a value of <c>true</c> is synonymous with @@ -211,7 +211,7 @@ filtermap(Fun, List1) -> </func> <func> - <name name="flatlength" arity="1"/> + <name name="flatlength" arity="1" since=""/> <fsummary>Length of flattened deep list.</fsummary> <desc> <p>Equivalent to <c>length(flatten(<anno>DeepList</anno>))</c>, but @@ -220,7 +220,7 @@ filtermap(Fun, List1) -> </func> <func> - <name name="flatmap" arity="2"/> + <name name="flatmap" arity="2" since=""/> <fsummary>Map and flatten in one pass.</fsummary> <desc> <p>Takes a function from <c><anno>A</anno></c>s to lists of @@ -241,7 +241,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="flatten" arity="1"/> + <name name="flatten" arity="1" since=""/> <fsummary>Flatten a deep list.</fsummary> <desc> <p>Returns a flattened version of <c><anno>DeepList</anno></c>.</p> @@ -249,7 +249,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="flatten" arity="2"/> + <name name="flatten" arity="2" since=""/> <fsummary>Flatten a deep list.</fsummary> <desc> <p>Returns a flattened version of <c><anno>DeepList</anno></c> with tail @@ -258,7 +258,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="foldl" arity="3"/> + <name name="foldl" arity="3" since=""/> <fsummary>Fold a function over a list.</fsummary> <desc> <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>, <anno>AccIn</anno>)</c> @@ -278,7 +278,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="foldr" arity="3"/> + <name name="foldr" arity="3" since=""/> <fsummary>Fold a function over a list.</fsummary> <desc> <p>Like <seealso marker="#foldl/3"><c>foldl/3</c></seealso>, but the @@ -297,7 +297,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="join" arity="2"/> + <name name="join" arity="2" since="OTP 19.0"/> <fsummary>Insert an element between elements in a list</fsummary> <desc> <p>Inserts <c><anno>Sep</anno></c> between each element in <c><anno>List1</anno></c>. Has no @@ -312,7 +312,7 @@ flatmap(Fun, List1) -> </desc> </func> <func> - <name name="foreach" arity="2"/> + <name name="foreach" arity="2" since=""/> <fsummary>Apply a function to each element of a list.</fsummary> <desc> <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> for each element @@ -324,7 +324,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keydelete" arity="3"/> + <name name="keydelete" arity="3" since=""/> <fsummary>Delete an element from a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -336,7 +336,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keyfind" arity="3"/> + <name name="keyfind" arity="3" since=""/> <fsummary>Search for an element in a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -349,7 +349,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keymap" arity="3"/> + <name name="keymap" arity="3" since=""/> <fsummary>Map a function over a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -368,7 +368,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keymember" arity="3"/> + <name name="keymember" arity="3" since=""/> <fsummary>Test for membership of a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -379,7 +379,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keymerge" arity="3"/> + <name name="keymerge" arity="3" since=""/> <fsummary>Merge two key-sorted lists of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -395,7 +395,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keyreplace" arity="4"/> + <name name="keyreplace" arity="4" since=""/> <fsummary>Replace an element in a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -407,7 +407,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keysearch" arity="3"/> + <name name="keysearch" arity="3" since=""/> <fsummary>Search for an element in a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -425,7 +425,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keysort" arity="2"/> + <name name="keysort" arity="2" since=""/> <fsummary>Sort a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -436,7 +436,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keystore" arity="4"/> + <name name="keystore" arity="4" since=""/> <fsummary>Store an element in a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -452,7 +452,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="keytake" arity="3"/> + <name name="keytake" arity="3" since=""/> <fsummary>Extract an element from a list of tuples.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -467,7 +467,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="last" arity="1"/> + <name name="last" arity="1" since=""/> <fsummary>Return last element in a list.</fsummary> <desc> <p>Returns the last element in <c><anno>List</anno></c>.</p> @@ -475,7 +475,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="map" arity="2"/> + <name name="map" arity="2" since=""/> <fsummary>Map a function over a list.</fsummary> <desc> <p>Takes a function from <c><anno>A</anno></c>s to @@ -488,7 +488,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="mapfoldl" arity="3"/> + <name name="mapfoldl" arity="3" since=""/> <fsummary>Map and fold in one pass.</fsummary> <desc> <p>Combines the operations of @@ -504,7 +504,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="mapfoldr" arity="3"/> + <name name="mapfoldr" arity="3" since=""/> <fsummary>Map and fold in one pass.</fsummary> <desc> <p>Combines the operations of @@ -514,7 +514,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="max" arity="1"/> + <name name="max" arity="1" since=""/> <fsummary>Return maximum element of a list.</fsummary> <desc> <p>Returns the first element of <c><anno>List</anno></c> that compares @@ -524,7 +524,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="member" arity="2"/> + <name name="member" arity="2" since=""/> <fsummary>Test for membership of a list.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Elem</anno></c> matches some element @@ -533,7 +533,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="merge" arity="1"/> + <name name="merge" arity="1" since=""/> <fsummary>Merge a list of sorted lists.</fsummary> <desc> <p>Returns the sorted list formed by merging all the sublists of @@ -546,7 +546,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="merge" arity="2"/> + <name name="merge" arity="2" since=""/> <fsummary>Merge two sorted lists.</fsummary> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> @@ -559,7 +559,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="merge" arity="3"/> + <name name="merge" arity="3" since=""/> <fsummary>Merge two sorted list.</fsummary> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> @@ -577,7 +577,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="merge3" arity="3"/> + <name name="merge3" arity="3" since=""/> <fsummary>Merge three sorted lists.</fsummary> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>, @@ -593,7 +593,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="min" arity="1"/> + <name name="min" arity="1" since=""/> <fsummary>Return minimum element of a list.</fsummary> <desc> <p>Returns the first element of <c><anno>List</anno></c> that compares @@ -603,7 +603,7 @@ flatmap(Fun, List1) -> </func> <func> - <name name="nth" arity="2"/> + <name name="nth" arity="2" since=""/> <fsummary>Return the <c>N</c>th element of a list.</fsummary> <type_desc variable="N">1..length(<anno>List</anno>)</type_desc> <desc> @@ -617,7 +617,7 @@ c</pre> </func> <func> - <name name="nthtail" arity="2"/> + <name name="nthtail" arity="2" since=""/> <fsummary>Return the <c>N</c>th tail of a list.</fsummary> <type_desc variable="N">0..length(<anno>List</anno>)</type_desc> <desc> @@ -638,7 +638,7 @@ c</pre> </func> <func> - <name name="partition" arity="2"/> + <name name="partition" arity="2" since=""/> <fsummary>Partition a list into two lists based on a predicate.</fsummary> <desc> <p>Partitions <c><anno>List</anno></c> into two lists, where the first @@ -658,7 +658,7 @@ c</pre> </func> <func> - <name name="prefix" arity="2"/> + <name name="prefix" arity="2" since=""/> <fsummary>Test for list prefix.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>List1</anno></c> is a prefix of @@ -667,7 +667,7 @@ c</pre> </func> <func> - <name name="reverse" arity="1"/> + <name name="reverse" arity="1" since=""/> <fsummary>Reverse a list.</fsummary> <desc> <p>Returns a list with the elements in <c><anno>List1</anno></c> @@ -676,7 +676,7 @@ c</pre> </func> <func> - <name name="reverse" arity="2"/> + <name name="reverse" arity="2" since=""/> <fsummary>Reverse a list appending a tail.</fsummary> <desc> <p>Returns a list with the elements in <c><anno>List1</anno></c> @@ -689,8 +689,20 @@ c</pre> </func> <func> - <name name="seq" arity="2"/> - <name name="seq" arity="3"/> + <name name="search" arity="2" since="OTP 21.0"/> + <fsummary>Find the first element that satisfies a predicate.</fsummary> + <desc> + <p>If there is a <c><anno>Value</anno></c> in <c><anno>List</anno></c> + such that <c><anno>Pred</anno>(<anno>Value</anno>)</c> returns + <c>true</c>, returns <c>{value, <anno>Value</anno>}</c> + for the first such <c><anno>Value</anno></c>, + otherwise returns <c>false</c>.</p> + </desc> + </func> + + <func> + <name name="seq" arity="2" since=""/> + <name name="seq" arity="3" since=""/> <fsummary>Generate a sequence of integers.</fsummary> <desc> <p>Returns a sequence of integers that starts with @@ -736,7 +748,7 @@ length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr</code> </func> <func> - <name name="sort" arity="1"/> + <name name="sort" arity="1" since=""/> <fsummary>Sort a list.</fsummary> <desc> <p>Returns a list containing the sorted elements of @@ -745,7 +757,7 @@ length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr</code> </func> <func> - <name name="sort" arity="2"/> + <name name="sort" arity="2" since=""/> <fsummary>Sort a list.</fsummary> <desc> <p>Returns a list containing the sorted elements of @@ -759,7 +771,7 @@ length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr</code> </func> <func> - <name name="split" arity="2"/> + <name name="split" arity="2" since=""/> <fsummary>Split a list into two lists.</fsummary> <type_desc variable="N">0..length(<anno>List1</anno>)</type_desc> <desc> @@ -771,7 +783,7 @@ length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr</code> </func> <func> - <name name="splitwith" arity="2"/> + <name name="splitwith" arity="2" since=""/> <fsummary>Split a list into two lists based on a predicate.</fsummary> <desc> <p>Partitions <c><anno>List</anno></c> into two lists according to @@ -792,7 +804,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="sublist" arity="2"/> + <name name="sublist" arity="2" since=""/> <fsummary>Return a sublist of a certain length, starting at the first position.</fsummary> <desc> @@ -804,7 +816,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="sublist" arity="3"/> + <name name="sublist" arity="3" since=""/> <fsummary>Return a sublist starting at a specified position and with a specified number of elements.</fsummary> <type_desc variable="Start">1..(length(<anno>List1</anno>)+1)</type_desc> @@ -826,7 +838,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="subtract" arity="2"/> + <name name="subtract" arity="2" since=""/> <fsummary>Subtract the element in one list from another list.</fsummary> <desc> <p>Returns a new list <c><anno>List3</anno></c> that is a copy of @@ -838,19 +850,11 @@ splitwith(Pred, List) -> > <input>lists:subtract("123212", "212").</input> "312".</pre> <p><c>lists:subtract(A, B)</c> is equivalent to <c>A -- B</c>.</p> - <warning> - <p>The complexity of <c>lists:subtract(A, B)</c> is proportional to - <c>length(A)*length(B)</c>, meaning that it is very slow if both - <c>A</c> and <c>B</c> are long lists. (If both lists are long, it - is a much better choice to use ordered lists and - <seealso marker="ordsets#subtract/2"> - <c>ordsets:subtract/2</c></seealso>.</p> - </warning> </desc> </func> <func> - <name name="suffix" arity="2"/> + <name name="suffix" arity="2" since=""/> <fsummary>Test for list suffix.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>List1</anno></c> is a suffix of @@ -859,7 +863,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="sum" arity="1"/> + <name name="sum" arity="1" since=""/> <fsummary>Return the sum of elements in a list.</fsummary> <desc> <p>Returns the sum of the elements in <c><anno>List</anno></c>.</p> @@ -867,7 +871,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="takewhile" arity="2"/> + <name name="takewhile" arity="2" since=""/> <fsummary>Take elements from a list while a predicate is <c>true</c>. </fsummary> <desc> @@ -880,7 +884,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="ukeymerge" arity="3"/> + <name name="ukeymerge" arity="3" since=""/> <fsummary>Merge two key-sorted lists of tuples, removing duplicates. </fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> @@ -898,7 +902,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="ukeysort" arity="2"/> + <name name="ukeysort" arity="2" since=""/> <fsummary>Sort a list of tuples, removing duplicates.</fsummary> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> <desc> @@ -910,7 +914,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="umerge" arity="1"/> + <name name="umerge" arity="1" since=""/> <fsummary>Merge a list of sorted lists, removing duplicates.</fsummary> <desc> <p>Returns the sorted list formed by merging all the sublists @@ -923,7 +927,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="umerge" arity="2"/> + <name name="umerge" arity="2" since=""/> <fsummary>Merge two sorted lists, removing duplicates.</fsummary> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> @@ -937,7 +941,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="umerge" arity="3"/> + <name name="umerge" arity="3" since=""/> <fsummary>Merge two sorted lists, removing duplicates.</fsummary> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> @@ -954,7 +958,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="umerge3" arity="3"/> + <name name="umerge3" arity="3" since=""/> <fsummary>Merge three sorted lists, removing duplicates.</fsummary> <desc> <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>, @@ -969,7 +973,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="unzip" arity="1"/> + <name name="unzip" arity="1" since=""/> <fsummary>Unzip a list of two-tuples into two lists.</fsummary> <desc> <p>"Unzips" a list of two-tuples into two lists, where the first @@ -979,7 +983,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="unzip3" arity="1"/> + <name name="unzip3" arity="1" since=""/> <fsummary>Unzip a list of three-tuples into three lists.</fsummary> <desc> <p>"Unzips" a list of three-tuples into three lists, where @@ -990,7 +994,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="usort" arity="1"/> + <name name="usort" arity="1" since=""/> <fsummary>Sort a list, removing duplicates.</fsummary> <desc> <p>Returns a list containing the sorted elements of @@ -1000,7 +1004,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="usort" arity="2"/> + <name name="usort" arity="2" since=""/> <fsummary>Sort a list, removing duplicates.</fsummary> <desc> <p>Returns a list containing the sorted elements of @@ -1015,7 +1019,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="zip" arity="2"/> + <name name="zip" arity="2" since=""/> <fsummary>Zip two lists into a list of two-tuples.</fsummary> <desc> <p>"Zips" two lists of equal length into one list of two-tuples, @@ -1026,7 +1030,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="zip3" arity="3"/> + <name name="zip3" arity="3" since=""/> <fsummary>Zip three lists into a list of three-tuples.</fsummary> <desc> <p>"Zips" three lists of equal length into one list of @@ -1038,7 +1042,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="zipwith" arity="3"/> + <name name="zipwith" arity="3" since=""/> <fsummary>Zip two lists into one list according to a fun.</fsummary> <desc> <p>Combines the elements of two lists of equal length into one list. @@ -1055,7 +1059,7 @@ splitwith(Pred, List) -> </func> <func> - <name name="zipwith3" arity="4"/> + <name name="zipwith3" arity="4" since=""/> <fsummary>Zip three lists into one list according to a fun.</fsummary> <desc> <p>Combines the elements of three lists of equal length into one diff --git a/lib/stdlib/doc/src/log_mf_h.xml b/lib/stdlib/doc/src/log_mf_h.xml index edc3d31025..b922006cc0 100644 --- a/lib/stdlib/doc/src/log_mf_h.xml +++ b/lib/stdlib/doc/src/log_mf_h.xml @@ -34,7 +34,7 @@ <rev>A</rev> <file>log_mf_h.xml</file> </header> - <module>log_mf_h</module> + <module since="">log_mf_h</module> <modulesummary>An event handler that logs events to disk.</modulesummary> <description> <p>This module is a <c>gen_event</c> handler module that can be installed @@ -60,8 +60,8 @@ <funcs> <func> - <name name="init" arity="3"/> - <name name="init" arity="4"/> + <name name="init" arity="3" since=""/> + <name name="init" arity="4" since=""/> <fsummary>Initiate the event handler.</fsummary> <desc> <p>Initiates the event handler. Returns <c><anno>Args</anno></c>, which diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml index 8c7270816b..e2a62cb397 100644 --- a/lib/stdlib/doc/src/maps.xml +++ b/lib/stdlib/doc/src/maps.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2013</year><year>2016</year> + <year>2013</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -27,22 +27,37 @@ <date>2014-02-28</date> <rev>A</rev> </header> - <module>maps</module> + <module since="OTP 17.0">maps</module> <modulesummary>Maps processing functions.</modulesummary> <description> <p>This module contains functions for maps processing.</p> </description> + <datatypes> + <datatype> + <name name="iterator"/> + <desc> + <p>An iterator representing the key value associations in a map.</p> + <p>Created using <seealso marker="#iterator-1"><c>maps:iterator/1</c></seealso>.</p> + <p>Consumed by <seealso marker="#next-1"><c>maps:next/1</c></seealso>, + <seealso marker="#filter-2"><c>maps:filter/2</c></seealso>, + <seealso marker="#fold-3"><c>maps:fold/3</c></seealso> and + <seealso marker="#map-2"><c>maps:map/2</c></seealso>.</p> + </desc> + </datatype> + </datatypes> + <funcs> <func> - <name name="filter" arity="2"/> + <name name="filter" arity="2" since="OTP 18.0"/> <fsummary>Select pairs that satisfy a predicate.</fsummary> <desc> - <p>Returns a map <c><anno>Map2</anno></c> for which predicate - <c><anno>Pred</anno></c> holds true in <c><anno>Map1</anno></c>.</p> + <p>Returns a map <c><anno>Map</anno></c> for which predicate + <c><anno>Pred</anno></c> holds true in <c><anno>MapOrIter</anno></c>.</p> <p>The call fails with a <c>{badmap,Map}</c> exception if - <c><anno>Map1</anno></c> is not a map, or with <c>badarg</c> if - <c><anno>Pred</anno></c> is not a function of arity 2.</p> + <c><anno>MapOrIter</anno></c> is not a map or valid iterator, + or with <c>badarg</c> if <c><anno>Pred</anno></c> is not a + function of arity 2.</p> <p><em>Example:</em></p> <code type="none"> > M = #{a => 2, b => 3, c=> 4, "a" => 1, "b" => 2, "c" => 4}, @@ -53,7 +68,7 @@ </func> <func> - <name name="find" arity="2"/> + <name name="find" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a tuple <c>{ok, Value}</c>, where <c><anno>Value</anno></c> @@ -72,16 +87,20 @@ </func> <func> - <name name="fold" arity="3"/> + <name name="fold" arity="3" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Calls <c>F(K, V, AccIn)</c> for every <c><anno>K</anno></c> to value - <c><anno>V</anno></c> association in <c><anno>Map</anno></c> in + <c><anno>V</anno></c> association in <c><anno>MapOrIter</anno></c> in any order. Function <c>fun F/3</c> must return a new accumulator, which is passed to the next successive call. This function returns the final value of the accumulator. The initial accumulator value <c><anno>Init</anno></c> is returned if the map is empty.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>MapOrIter</anno></c> is not a map or valid iterator, + or with <c>badarg</c> if <c><anno>Fun</anno></c> is not a + function of arity 3.</p> <p><em>Example:</em></p> <code type="none"> > Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end, @@ -92,7 +111,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Takes a list of key-value tuples elements and builds a map. The @@ -109,7 +128,7 @@ </func> <func> - <name name="get" arity="2"/> + <name name="get" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns value <c><anno>Value</anno></c> associated with @@ -128,7 +147,7 @@ </func> <func> - <name name="get" arity="3"/> + <name name="get" arity="3" since="OTP 17.1"/> <fsummary></fsummary> <desc> <p>Returns value <c><anno>Value</anno></c> associated with @@ -149,7 +168,7 @@ val1 </func> <func> - <name name="is_key" arity="2"/> + <name name="is_key" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns <c>true</c> if map <c><anno>Map</anno></c> contains @@ -169,7 +188,33 @@ false</code> </func> <func> - <name name="keys" arity="1"/> + <name name="iterator" arity="1" since="OTP 21.0"/> + <fsummary>Create a map iterator.</fsummary> + <desc> + <p>Returns a map iterator <c><anno>Iterator</anno></c> that can + be used by <seealso marker="#next-1"><c>maps:next/1</c></seealso> + to traverse the key-value associations in a map. When iterating + over a map, the memory usage is guaranteed to be bounded no matter + the size of the map.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> M = #{ a => 1, b => 2 }. +#{a => 1,b => 2} +> I = maps:iterator(M), ok. +ok +> {K1, V1, I2} = maps:next(I), {K1, V1}. +{a,1} +> {K2, V2, I3} = maps:next(I2),{K2, V2}. +{b,2} +> maps:next(I3). +none</code> + </desc> + </func> + + <func> + <name name="keys" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a complete list of keys, in any order, which resides @@ -185,15 +230,19 @@ false</code> </func> <func> - <name name="map" arity="2"/> + <name name="map" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> - <p>Produces a new map <c><anno>Map2</anno></c> by calling function + <p>Produces a new map <c><anno>Map</anno></c> by calling function <c>fun F(K, V1)</c> for every <c><anno>K</anno></c> to value - <c><anno>V1</anno></c> association in <c><anno>Map1</anno></c> in + <c><anno>V1</anno></c> association in <c><anno>MapOrIter</anno></c> in any order. Function <c>fun F/2</c> must return value <c><anno>V2</anno></c> to be associated with key <c><anno>K</anno></c> - for the new map <c><anno>Map2</anno></c>.</p> + for the new map <c><anno>Map</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>MapOrIter</anno></c> is not a map or valid iterator, + or with <c>badarg</c> if <c><anno>Fun</anno></c> is not a + function of arity 2.</p> <p><em>Example:</em></p> <code type="none"> > Fun = fun(K,V1) when is_list(K) -> V1*2 end, @@ -204,7 +253,7 @@ false</code> </func> <func> - <name name="merge" arity="2"/> + <name name="merge" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Merges two maps into a single map <c><anno>Map3</anno></c>. If two @@ -222,7 +271,7 @@ false</code> </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a new empty map.</p> @@ -234,7 +283,36 @@ false</code> </func> <func> - <name name="put" arity="3"/> + <name name="next" arity="1" since="OTP 21.0"/> + <fsummary>Get the next key and value from an iterator.</fsummary> + <desc> + <p>Returns the next key-value association in + <c><anno>Iterator</anno></c> and a new iterator for the + remaining associations in the iterator. + </p> + <p> + If there are no more associations in the iterator, + <c>none</c> is returned. + </p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{a => 1, b => 2, c => 3}. +#{a => 1,b => 2,c => 3} +> I = maps:iterator(Map), ok. +ok +> {K1, V1, I1} = maps:next(I), {K1, V1}. +{a,1} +> {K2, V2, I2} = maps:next(I1), {K2, V2}. +{b,2} +> {K3, V3, I3} = maps:next(I2), {K3, V3}. +{c,3} +> maps:next(I3). +none</code> + </desc> + </func> + + <func> + <name name="put" arity="3" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Associates <c><anno>Key</anno></c> with value @@ -258,7 +336,7 @@ false</code> </func> <func> - <name name="remove" arity="2"/> + <name name="remove" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Removes the <c><anno>Key</anno></c>, if it exists, and its @@ -278,7 +356,7 @@ false</code> </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns the number of key-value associations in @@ -292,7 +370,7 @@ false</code> </func> <func> - <name name="take" arity="2"/> + <name name="take" arity="2" since="OTP 19.0"/> <fsummary></fsummary> <desc> <p>The function removes the <c><anno>Key</anno></c>, if it @@ -317,7 +395,7 @@ error</code> </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a list of pairs representing the key-value associations of @@ -334,7 +412,7 @@ error</code> </func> <func> - <name name="update" arity="3"/> + <name name="update" arity="3" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>If <c><anno>Key</anno></c> exists in <c><anno>Map1</anno></c>, the @@ -354,7 +432,7 @@ error</code> </func> <func> - <name name="update_with" arity="3"/> + <name name="update_with" arity="3" since="OTP 19.0"/> <fsummary></fsummary> <desc> <p>Update a value in a <c><anno>Map1</anno></c> associated @@ -373,7 +451,7 @@ error</code> </func> <func> - <name name="update_with" arity="4"/> + <name name="update_with" arity="4" since="OTP 19.0"/> <fsummary></fsummary> <desc> <p>Update a value in a <c><anno>Map1</anno></c> associated @@ -393,7 +471,7 @@ error</code> </func> <func> - <name name="values" arity="1"/> + <name name="values" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a complete list of values, in arbitrary order, contained in @@ -409,7 +487,7 @@ error</code> </func> <func> - <name name="with" arity="2"/> + <name name="with" arity="2" since="OTP 17.3"/> <fsummary></fsummary> <desc> <p>Returns a new map <c><anno>Map2</anno></c> with the keys <c>K1</c> @@ -426,7 +504,7 @@ error</code> </func> <func> - <name name="without" arity="2"/> + <name name="without" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a new map <c><anno>Map2</anno></c> without keys <c>K1</c> diff --git a/lib/stdlib/doc/src/math.xml b/lib/stdlib/doc/src/math.xml index 1358ce5cbf..d89310e2c8 100644 --- a/lib/stdlib/doc/src/math.xml +++ b/lib/stdlib/doc/src/math.xml @@ -34,7 +34,7 @@ <rev>B</rev> <file>math.xml</file> </header> - <module>math</module> + <module since="">math</module> <modulesummary>Mathematical functions.</modulesummary> <description> <p>This module provides an interface to a number of mathematical @@ -50,25 +50,28 @@ <funcs> <func> - <name name="acos" arity="1"/> - <name name="acosh" arity="1"/> - <name name="asin" arity="1"/> - <name name="asinh" arity="1"/> - <name name="atan" arity="1"/> - <name name="atan2" arity="2"/> - <name name="atanh" arity="1"/> - <name name="cos" arity="1"/> - <name name="cosh" arity="1"/> - <name name="exp" arity="1"/> - <name name="log" arity="1"/> - <name name="log10" arity="1"/> - <name name="log2" arity="1"/> - <name name="pow" arity="2"/> - <name name="sin" arity="1"/> - <name name="sinh" arity="1"/> - <name name="sqrt" arity="1"/> - <name name="tan" arity="1"/> - <name name="tanh" arity="1"/> + <name name="acos" arity="1" since=""/> + <name name="acosh" arity="1" since=""/> + <name name="asin" arity="1" since=""/> + <name name="asinh" arity="1" since=""/> + <name name="atan" arity="1" since=""/> + <name name="atan2" arity="2" since=""/> + <name name="atanh" arity="1" since=""/> + <name name="ceil" arity="1" since="OTP 20.0"/> + <name name="cos" arity="1" since=""/> + <name name="cosh" arity="1" since=""/> + <name name="exp" arity="1" since=""/> + <name name="floor" arity="1" since="OTP 20.0"/> + <name name="fmod" arity="2" since="OTP 20.0"/> + <name name="log" arity="1" since=""/> + <name name="log10" arity="1" since=""/> + <name name="log2" arity="1" since="OTP 18.0"/> + <name name="pow" arity="2" since=""/> + <name name="sin" arity="1" since=""/> + <name name="sinh" arity="1" since=""/> + <name name="sqrt" arity="1" since=""/> + <name name="tan" arity="1" since=""/> + <name name="tanh" arity="1" since=""/> <fsummary>Diverse math functions.</fsummary> <type variable="X" name_i="6"/> <type variable="Y" name_i="6"/> @@ -79,7 +82,7 @@ </func> <func> - <name name="erf" arity="1"/> + <name name="erf" arity="1" since=""/> <fsummary>Error function.</fsummary> <desc> <p>Returns the error function of <c><anno>X</anno></c>, where:</p> @@ -89,7 +92,7 @@ erf(X) = 2/sqrt(pi)*integral from 0 to X of exp(-t*t) dt.</pre> </func> <func> - <name name="erfc" arity="1"/> + <name name="erfc" arity="1" since=""/> <fsummary>Another error function.</fsummary> <desc> <p><c>erfc(X)</c> returns <c>1.0</c> - <c>erf(X)</c>, computed by @@ -98,7 +101,7 @@ erf(X) = 2/sqrt(pi)*integral from 0 to X of exp(-t*t) dt.</pre> </func> <func> - <name name="pi" arity="0"/> + <name name="pi" arity="0" since=""/> <fsummary>A useful number.</fsummary> <desc> <p>A useful number.</p> diff --git a/lib/stdlib/doc/src/ms_transform.xml b/lib/stdlib/doc/src/ms_transform.xml index 0a05fa37c5..65cc150507 100644 --- a/lib/stdlib/doc/src/ms_transform.xml +++ b/lib/stdlib/doc/src/ms_transform.xml @@ -32,7 +32,7 @@ <rev>C</rev> <file>ms_transform.xml</file> </header> - <module>ms_transform</module> + <module since="">ms_transform</module> <modulesummary>A parse transformation that translates fun syntax into match specifications.</modulesummary> <description> @@ -731,7 +731,7 @@ ets:select(Table, [{{'$1',test,'$2'},[],['$_']}]).</code> <funcs> <func> - <name name="format_error" arity="1"/> + <name name="format_error" arity="1" since=""/> <fsummary>Error formatting function as required by the parse transformation interface.</fsummary> <desc> <p>Takes an error code returned by one of the other functions @@ -741,7 +741,7 @@ ets:select(Table, [{{'$1',test,'$2'},[],['$_']}]).</code> </func> <func> - <name name="parse_transform" arity="2"/> + <name name="parse_transform" arity="2" since=""/> <fsummary>Transforms Erlang abstract format containing calls to ets/dbg:fun2ms/1 into literal match specifications.</fsummary> <type_desc variable="Options">Option list, required but not used. @@ -762,7 +762,7 @@ ets:select(Table, [{{'$1',test,'$2'},[],['$_']}]).</code> </func> <func> - <name name="transform_from_shell" arity="3"/> + <name name="transform_from_shell" arity="3" since=""/> <fsummary>Used when transforming funs created in the shell into match_specifications.</fsummary> <type_desc variable="BoundEnvironment">List of variable bindings in the diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml index bb35224182..f677438154 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>2016</year> + <year>2004</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,1273 @@ </header> <p>This document describes the changes made to the STDLIB application.</p> +<section><title>STDLIB 3.8.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>Fixed a performance regression when reading files + opened with the <c>compressed</c> flag.</p> + <p> + Own Id: OTP-15706 Aux Id: ERIERL-336 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug in the Erlang Pretty Printer: long atom + names in combination with <c><<>></c> could + cause a crash. </p> + <p> + Own Id: OTP-15592 Aux Id: ERL-818 </p> + </item> + <item> + <p> Fix bugs that could cause wrong results or bad + performance when formatting lists of characters using the + control sequences <c>p</c> or <c>P</c> and limiting the + output with the option <c>chars_limit</c>. </p> + <p> + Own Id: OTP-15639</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improved ETS documentation about safe table traversal and + the partially bound key optimization for + <c>ordered_set</c>.</p> + <p> + Own Id: OTP-15545 Aux Id: PR-2103, PR-2139 </p> + </item> + <item> + <p> Optimize <c>calendar:gregorian_days_to_date/1</c>. + </p> + <p> + Own Id: OTP-15572 Aux Id: PR-2121 </p> + </item> + <item> + <p> Optimize functions + <c>calendar:rfc3339_to_system_time()</c> and + <c>calendar:system_time_to_rfc3339()</c>. </p> + <p> + Own Id: OTP-15630</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.7.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Optimize pretty printing of terms. The slower + behaviour was introduced in Erlang/OTP 20. </p> + <p> + Own Id: OTP-15573 Aux Id: ERIERL-306 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Document <c>bit_size</c> in match specifications and + allow it in <c>ets:fun2ms</c>.</p> + <p> + Own Id: OTP-15343 Aux Id: PR-1962 </p> + </item> + <item> + <p>The <c>beam()</c> type in <c>beam_lib</c> is defined + as <c>module() | file:filename() | binary()</c>. The + <c>module()</c> is misleading. Giving the module name as + an atom will only work if the BEAM file is in a current + directory.</p> + <p>To avoid confusion, <c>module()</c> has been removed + from the type. That means that there will be a Dialyzer + warning for code that call <c>beam_lib</c> with an atom + as filename, but the calls will still work.</p> + <p> + Own Id: OTP-15378 Aux Id: ERL-696 </p> + </item> + <item> + <p> + <c>unicode_util</c> crashed on certain emoji grapheme + clusters in binary strings.</p> + <p> + Own Id: OTP-15428 Aux Id: ERL-777 </p> + </item> + <item> + <p>When an external fun was used, warnings for unused + variables could be suppressed.</p> + <p> + Own Id: OTP-15437 Aux Id: ERL-762 </p> + </item> + <item> + <p> + Fix reduction count in lists:member/2</p> + <p> + Own Id: OTP-15474 Aux Id: ERIERL-229 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>When specified, the <c>+{source,Name}</c> option will + now override the actual file name in stack traces, + instead of only affecting the return value of + <c>Mod:module_info()</c>.</p> + <p>The <c>+deterministic</c> flag will also affect stack + traces now, omitting all path information except the file + name, fixing a long-standing issue where deterministic + builds required deterministic paths.</p> + <p> + Own Id: OTP-15245 Aux Id: ERL-706 </p> + </item> + <item> + <p>List subtraction (The <c>--</c> operator) will now + yield properly on large inputs.</p> + <p> + Own Id: OTP-15371</p> + </item> + <item> + <p> + <c>calendar:system_time_to_rfc3339/1,2</c> no longer + remove trailing zeros from fractions.</p> + <p> + Own Id: OTP-15464</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>The specs of <c>filename:basedir/2,3</c> are + corrected.</p> + <p> + Own Id: OTP-15252 Aux Id: ERL-667 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> Let <c>dets:open_file()</c> exit with a <c>badarg</c> + message if given a raw file name (a binary). </p> + <p> + Own Id: OTP-15253 Aux Id: OTP-13229, ERL-55 </p> + </item> + <item> + <p> The <c>Format</c> argument of the formatting + functions in modules <c>io</c> and <c>io_lib</c> is + accepted even if it is, for example, a list of binaries. + This is how it used to be before Erlang/OTP 21.0. </p> + <p> + Own Id: OTP-15304</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.5.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug that could cause a crash when formatting a + list of non-characters using the control sequences + <c>p</c> or <c>P</c> and limiting the output with the + option <c>chars_limit</c>. </p> + <p> + Own Id: OTP-15159</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p><c>gen_statem</c> improvements.</p> <p> When using an + exception that is valid but not allowed in a state enter + call, the reason has been changed from + <c>{bad_action_from_state_function,Action}</c> to + <c>{bad_state_enter_action_from_state_function,Action}</c>. + </p><p> Timer parsing has been improved. Many erroneous + timeout tuples was not handled correctly. </p><p> The + documentation has been updated, in particular the User's + Guide and the pointer to it from the Reference Manual is + much more obvious. </p> + <p> + Own Id: OTP-14015</p> + </item> + <item> + <p> + The type specifications for <c>file:posix/0</c> and + <c>inet:posix/0</c> have been updated according to which + errors file and socket operations should be able to + return.</p> + <p> + Own Id: OTP-14019 Aux Id: ERL-550 </p> + </item> + <item> + <p> File operations used to accept <seealso + marker="kernel:file#type-name_all">filenames</seealso> + containing null characters (integer value zero). This + caused the name to be truncated and in some cases + arguments to primitive operations to be mixed up. + Filenames containing null characters inside the filename + are now <em>rejected</em> and will cause primitive file + operations to fail. </p> <p> Also environment variable + operations used to accept <seealso + marker="kernel:os#type-env_var_name">names</seealso> and + <seealso + marker="kernel:os#type-env_var_value">values</seealso> of + environment variables containing null characters (integer + value zero). This caused operations to silently produce + erroneous results. Environment variable names and values + containing null characters inside the name or value are + now <em>rejected</em> and will cause environment variable + operations to fail. </p> <p>Primitive environment + variable operations also used to accept the <c>$=</c> + character in environment variable names causing various + problems. <c>$=</c> characters in environment variable + names are now also <em>rejected</em>. </p> <p>Also + <seealso + marker="kernel:os#cmd/1"><c>os:cmd/1</c></seealso> now + reject null characters inside its <seealso + marker="kernel:os#type-os_command">command</seealso>. + </p> <p><seealso + marker="erts:erlang#open_port/2"><c>erlang:open_port/2</c></seealso> + will also reject null characters inside the port name + from now on.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14543 Aux Id: ERL-370 </p> + </item> + <item> + <p> Make <c>io_lib:unscan_format/1</c> work with pad char + and default precision. </p> + <p> + Own Id: OTP-14958 Aux Id: PR-1735 </p> + </item> + <item> + <p> The control sequence modifiers <c>t</c> and <c>l</c> + can be used together in the same control sequence which + makes it possible to have Unicode atoms and no detection + of printable character lists at the same time. </p> + <p> + Own Id: OTP-14971 Aux Id: PR-1743 </p> + </item> + <item> + <p> Fix a bug in the Erlang code linter: the check of + guard expressions no longer returns <c>false</c> if the + map syntax is used. The bug affected the Erlang shell, + the Debugger, and other modules evaluating abstract code. + </p> + <p> + Own Id: OTP-15035 Aux Id: ERL-613 </p> + </item> + <item> + <p> + A sys debug fun of type {Fun,State} should not be + possible to install twice. This was, however, possible if + the current State was 'undefined', which was mistaken for + non-existing fun. This has been corrected.</p> + <p> + Own Id: OTP-15049</p> + </item> + <item> + <p> + Fix <c>io:putchars/2</c> stacktrace rewriting at errors + to point to a valid function.</p> + <p> + Own Id: OTP-15101</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The <c>gen_server</c> has gotten a new callback + <c>handle_continue/2</c> for check pointing the state. + This is useful at least when implementing behaviours on + top of <c>gen_server</c> and for some start up scenarios.</p> + <p> + Own Id: OTP-13019 Aux Id: PR-1490 </p> + </item> + <item> + <p> The semantics of timeout parameter + <c>{clean_timeout,infinity}</c> to + <c>gen_statem:call/3</c> has been changed to use a proxy + process for the call. With this change + <c>clean_timeout</c> implicates a proxy process with no + exceptions. This may be a hard to observe + incompatibility: in the presence of network problems a + late reply could arrive in the caller's message queue + when catching errors. That will not happen after this + correction. </p><p> The semantics of timeout parameter + <c>infinity</c> has not been changed. </p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13073 Aux Id: PR-1595 </p> + </item> + <item> + <p>A new logging API is added to Erlang/OTP, see the + <seealso + marker="kernel:logger"><c>logger(3)</c></seealso> manual + page, and section <seealso + marker="kernel:logger_chapter">Logging</seealso> in the + Kernel User's Guide.</p> + <p>Calls to <c>error_logger</c> are automatically + redirected to the new API, and legacy error logger event + handlers can still be used. It is, however, recommended + to use the Logger API directly when writing new code.</p> + <p>Notice the following potential incompatibilities:</p> + <list> <item><p>Kernel configuration parameters + <c>error_logger</c> still works, but is overruled if the + default handler's output destination is configured with + Kernel configuration parameter <c>logger</c>.</p> <p>In + general, parameters for configuring error logger are + overwritten by new parameters for configuring + Logger.</p></item> <item><p>The concept of SASL error + logging is deprecated, meaning that by default the SASL + application does not affect which log events are + logged.</p> <p>By default, supervisor reports and crash + reports are logged by the default Logger handler started + by Kernel, and end up at the same destination (terminal + or file) as other standard log event from Erlang/OTP.</p> + <p>Progress reports are not logged by default, but can be + enabled by setting the primary log level to info, for + example with the Kernel configuration parameter + <c>logger_level</c>.</p> <p>To obtain backwards + compatibility with the SASL error logging functionality + from earlier releases, set Kernel configuration parameter + <c>logger_sasl_compatible</c> to <c>true</c>. This + prevents the default Logger handler from logging any + supervisor-, crash-, or progress reports. Instead, SASL + adds a separate Logger handler during application start, + which takes care of these log events. The SASL + configuration parameters <c>sasl_error_logger</c> and + <c>sasl_errlog_type</c> specify the destination (terminal + or file) and severity level to log for these + events.</p></item></list> + <p> + Since Logger is new in Erlang/OTP 21.0, we do reserve the + right to introduce changes to the Logger API and + functionality in patches following this release. These + changes might or might not be backwards compatible with + the initial version.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13295</p> + </item> + <item> + <p> Add functions + <c>calendar:system_time_to_local_time/2</c> and + <c>calendar:system_time_to_universal_time/2</c>. </p> + <p> + Own Id: OTP-13413</p> + </item> + <item> + <p> Functions <c>rand:uniform_real/0</c> and + <c>rand:uniform_real_s/1</c> have been added. They + produce uniformly distributed numbers in the range <c>0.0 + =< X < 1.0</c> that are as close to random real + numbers as Normalized IEEE 754 Double Precision allows. + Because the random real number exactly <c>0.0</c> is + infinitely improbable they will never return exactly + <c>0.0</c>. </p><p> These properties are useful when you + need to call for example <c>math:log(X)</c> or <c>1 / + X</c> on a random value <c>X</c>, since that will never + fail with a number from these new functions. </p> + <p> + Own Id: OTP-13764 Aux Id: PR-1574 </p> + </item> + <item> + <p> + Added maps:iterator/0 and maps:next/1 to be used for + iterating over the key-value associations in a map.</p> + <p> + Own Id: OTP-14012</p> + </item> + <item> + <p>Changed the default behaviour of <c>.erlang</c> + loading: <c>.erlang</c> is no longer loaded from the + current directory. <c>c:erlangrc(PathList)</c> can be + used to search and load an <c>.erlang</c> file from user + specified directories.</p> <p><c>escript</c>, + <c>erlc</c>, <c>dialyzer</c> and <c>typer</c> no longer + load an <c>.erlang</c> at all.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14439</p> + </item> + <item> + <p> + Added new uri_string module to stdlib for handling URIs + (RFC 3986).</p> + <p> + Own Id: OTP-14496</p> + </item> + <item> + <p> + Update Unicode specification to version 10.0.</p> + <p> + Own Id: OTP-14503</p> + </item> + <item> + <p><c>filelib:wildcard()</c> now allows characters with a + special meaning to be escaped using backslashes.</p> + <p>This is an incompatible change, but note that the use + of backslashes in wildcards would already work + differently on Windows and Unix. Existing calls to + <c>filelib:wildcard()</c> needs to be updated. On + Windows, directory separators must always be written as a + slash.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14577</p> + </item> + <item> + <p> + The supervisor now stores its child specifications in a + map instead of a list. This causes a significant + improvement when starting many children under a + non-simple_one_for_one supervisor.</p> + <p> + Own Id: OTP-14586</p> + </item> + <item> + <p> The <c>base64</c> module is optimized. </p> <p> Note + that the functions <c>encode/1</c>, <c>decode/1</c>, and + <c>mime_decode/1</c> fail unless called with an argument + of the documented type. They used to accept any + <c>iodata()</c>. </p> + <p> + Own Id: OTP-14624 Aux Id: PR-1565 </p> + </item> + <item> + <p> Add function <c>lists:search/2</c>. </p> + <p> + Own Id: OTP-14675 Aux Id: PR-102 </p> + </item> + <item> + <p> + uri_string module extended with functions for handling + application/x-www-form-urlencoded query strings based on + the HTML5 specification.</p> + <p> + Own Id: OTP-14747</p> + </item> + <item> + <p> Add functions + <c>calendar:rfc3339_to_system_time/1,2</c> and + <c>calendar:system_time_to_rfc3339/1,2</c>. </p> + <p> + Own Id: OTP-14764</p> + </item> + <item> + <p> The stack traces returned by the functions of the + <c>erl_eval</c> module more accurately reflect where the + exception occurred. </p> + <p> + Own Id: OTP-14826 Aux Id: PR 1540 </p> + </item> + <item> + <p> Add options <c>atime</c>, <c>mtime</c>, <c>ctime</c>, + <c>uid</c>, and <c>gid</c> to the <c>erl_tar:add/3,4</c> + functions. </p> + <p> + Own Id: OTP-14834 Aux Id: PR 1608 </p> + </item> + <item> + <p>Added <c>ets:whereis/1</c> for retrieving the table + identifier of a named table.</p> + <p> + Own Id: OTP-14884</p> + </item> + <item> + <p> + Improved URI normalization functions in the uri_string + module.</p> + <p> + Own Id: OTP-14910</p> + </item> + <item> + <p> The new functions <c>io_lib:fwrite/3</c> and + <c>io_lib:format/3</c> take a third argument, an option + list. The only option is <c>chars_limit</c>, which is + used for limiting the number of returned characters. The + limit is soft, which means that the number of returned + characters exceeds the limit with at most a smallish + amount. If the limit is set, the functions + <c>format/3</c> and <c>fwrite/3</c> try to distribute the + number of characters evenly over the control sequences + <c>pPswW</c>. Furthermore, the control sequences + <c>pPwP</c> try to distribute the number of characters + evenly over substructures. </p> <p> A modification of the + control sequences <c>pPwW</c> is that even if there is no + limit on the number of returned characters, all + associations of a map are printed to the same depth. The + aim is to give a more consistent output as the order of + map keys is not defined. As before, if the depth is less + than the number of associations of a map, the selection + of associations to print is arbitrary. </p> + <p> + Own Id: OTP-14983</p> + </item> + <item> + <p> Add functions <c>ordsets:is_empty/1</c> and + <c>sets:is_empty/1</c>. </p> + <p> + Own Id: OTP-14996 Aux Id: ERL-557, PR-1703 </p> + </item> + <item> + <p> + Improve performance of <c>string:uppercase/1</c>, + <c>string:lowercase/1</c> and <c>string:casefold/1</c> + when handling ASCII characters.</p> + <p> + Own Id: OTP-14998</p> + </item> + <item> + <p>External funs with literal values for module, name, + and arity (e.g. <c>erlang:abs/1</c>) are now treated as + literals. That means more efficient code that produces + less garbage on the heap.</p> + <p> + Own Id: OTP-15003</p> + </item> + <item> + <p> + sys:statistics(Pid,get) did not report 'out' messages + from gen_server. This is now corrected.</p> + <p> + Own Id: OTP-15047</p> + </item> + <item> + <p> + A sys debug function can now have the format + {Id,Fun,State} in addition to the old {Fun,State}. This + allows installing multiple instances of a debug fun.</p> + <p> + Own Id: OTP-15048</p> + </item> + <item> + <p> The <c>lib</c> module is removed:</p> <list + type="bulleted"> <item><c>lib:error_message/2</c> is + removed.</item> <item><c>lib:flush_receive/0</c> is + removed.</item> <item><c>lib:nonl/1</c> is + removed.</item> <item><c>lib:progname/0</c> is replaced + by <c>ct:get_progname/0</c>.</item> + <item><c>lib:send/2</c> is removed.</item> + <item><c>lib:sendw/2</c> is removed.</item> </list> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15072 Aux Id: PR 1786, OTP-15114 </p> + </item> + <item> + <p> + Function <c>ets:delete_all_objects/1</c> now yields the + scheduler thread for large tables that take significant + time to clear. This to improve real time characteristics + of other runnable processes.</p> + <p> + Own Id: OTP-15078</p> + </item> + <item> + <p> In control sequences of the functions + <c>io:fwrite/2,3</c> and <c>io_lib:fwrite/2,3</c> + containing <c>p</c> or <c>P</c>, a field width of value + <c>0</c> means that no line breaks are inserted. This is + in contrast to the old behaviour, where <c>0</c> used to + insert line breaks after every subterm. To insert line + breaks after every subterm, a field width of value + <c>1</c> can be used. </p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15103 Aux Id: ERL-607 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.4.5.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>List subtraction (The <c>--</c> operator) will now + yield properly on large inputs.</p> + <p> + Own Id: OTP-15371</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.4.5</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The <c>Module:init/1</c> function in <c>gen_statem</c> + may return an actions list containing any action, but an + erroneous check only allowed state enter actions so e.g + <c>{next_event,internal,event}</c> caused a server crash. + This bug has been fixed.</p> + <p> + Own Id: OTP-13995</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.4.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Correct <c>filelib:find_source()</c> and + <c>filelib:find_file()</c> to by default also search one + level below <c>src</c>. This is in accordance with the + Design Principles which states that an application can + have Erlang source files one level below the <c>src</c> + directory. </p> + <p> + Own Id: OTP-14832 Aux Id: ERL-527 </p> + </item> + <item> + <p> The contract of <c>erl_tar:table/2</c> is corrected. + </p> + <p> + Own Id: OTP-14860 Aux Id: PR 1670 </p> + </item> + <item> + <p> Correct a few contracts. </p> + <p> + Own Id: OTP-14889</p> + </item> + <item> + <p> + Fix string:prefix/2 to handle an empty string as second + argument.</p> + <p> + Own Id: OTP-14942 Aux Id: PR-1702 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.4.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Make <c>ets:i/1</c> exit cleaner when ^D is input + while browsing a table. Only the old Erlang shell is + affected (<c>erl(1)</c> flag <c>-oldshell</c>). </p> + <p> + Own Id: OTP-14663</p> + </item> + <item> + <p> + Fixed handling of windows UNC paths in module + <c>filename</c>.</p> + <p> + Own Id: OTP-14693</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improve performance of the new string functionality when + handling ASCII characters.</p> + <p> + Own Id: OTP-14670</p> + </item> + <item> + <p> + Added a clarification to the documentation of + <c>unicode:characters_to_list/2</c>.</p> + <p> + Own Id: OTP-14798</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.4.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Fix a bug in the Erlang shell where recursively + defined records with typed fields could cause a loop. + </p> + <p> + Own Id: OTP-14488 Aux Id: PR-1489 </p> + </item> + <item> + <p> + Make edlin handle grapheme clusters instead of codepoints + to improve the handling multi-codepoints characters.</p> + <p> + Own Id: OTP-14542</p> + </item> + <item> + <p>There could be false warnings for + <c>erlang:get_stacktrace/0</c> being used outside of a + <c>try</c> block when using multiple <c>catch</c> + clauses.</p> + <p> + Own Id: OTP-14600 Aux Id: ERL-478 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The Erlang code linter no longer checks that the + functions mentioned in <c>nowarn_deprecated_function</c> + options are declared in the module. </p> + <p> + Own Id: OTP-14378</p> + </item> + <item> + <p> + General Unicode improvements.</p> + <p> + Own Id: OTP-14462</p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.4.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> A bug in <c>proc_lib:format()</c> introduced in + Erlang/OTP 20.0 is corrected. </p> + <p> + Own Id: OTP-14482 Aux Id: PR-1488 </p> + </item> + <item> + <p> + Fix string:len/1 to be compatible with previous versions.</p> + <p> + Own Id: OTP-14487 Aux Id: ERIERL-40 </p> + </item> + <item> + <p> + In OTP-20.0, the behavior of c, make, and ct_make was + changed so that in some cases the beam files by default + would be written to the directory where the source files + were found. This is now changed back to the old behavior + so beam files are by default written to current + directory.</p> + <p> + Own Id: OTP-14489 Aux Id: ERL-438 </p> + </item> + </list> + </section> + +</section> + +<section><title>STDLIB 3.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p>For many releases, it has been legal to override a BIF + with a local function having the same name. However, + calling a local function with the same name as guard BIF + as filter in a list comprehension was not allowed.</p> + <p> + Own Id: OTP-13690</p> + </item> + <item> + <p> A new (default) pseudo-random number generator + algorithm Xoroshiro116+ has been implemented in the + <c>rand</c> module. </p><p> The old algorithm + implementations had a number of flaws so they are all + deprecated, but corrected versions of two of them have + been added. See the documentation. </p> + <p> + Own Id: OTP-14295 Aux Id: PR-1372 </p> + </item> + <item> + <p> The Erlang shell, <c>qlc:string_to_handle()</c>, and + the Debugger (the Evaluator area and Edit variable window + of the Bindings area) can parse pids, ports, references, + and external funs, as long as they can be created in the + running system. </p> + <p> + Own Id: OTP-14296</p> + </item> + <item> + <p>Internal code change: Calls to <c>catch</c> followed + by a call to <c>erlang:get_stacktrace/0</c> has been + rewritten to use <c>try</c> instead of <c>catch</c> to + make the code future-proof.</p> + <p> + Own Id: OTP-14400</p> + </item> + <item> + <p> The <c>ms_transform</c> module, used by + <c>ets:fun2ms/1</c> and <c>dbg:fun2ms/1</c>, evaluates + constant arithmetic expressions. This is necessary since + the Erlang compiler, which normally evaluates constant + expressions, does not recognize the format generated by + <c>ms_transform</c>. </p> + <p> + Own Id: OTP-14454 Aux Id: ERIERL-29 </p> + </item> + <item> + <p> The state machine engine <c>gen_statem</c> can now + handle generic time-outs (multiple named) as well as + absolute time-out time. See the documentation. </p><p> + The <c>gen_statem</c> callback <c>Module:init/1</c> has + become mandatory to harmonize with other <c>gen_*</c> + modules. This may be an incompatibility for + <c>gen_statem</c> callback modules that use + <c>gen_statem:enter_loop/4-6</c>. </p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14531</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improved unicode support for strings. Added normalization + functions in the <c>unicode</c> module. Extended the + <c>string</c> module API with new functions with improved + unicode handling and that works on grapheme clusters. The + new functions operates on the <c>unicode:chardata()</c> + type, thus they also accept <c>UTF-8 binaries</c> as + input. </p> + <p> + The old string API have been marked as obsolete. The + return values have been changed for some error cases.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10289 Aux Id: OTP-10309 </p> + </item> + <item> + <p>There are two new guard BIFs '<c>floor/1</c>' and + '<c>ceil/1</c>'. They both return integers. In the + '<c>math</c>' module, there are two new BIFs with the + same names that return floating point values.</p> + <p> + Own Id: OTP-13692</p> + </item> + <item> + <p> + Making code_change, terminate and handle_info callbacks + optional in the OTP behaviours.</p> + <p> + Own Id: OTP-13801</p> + </item> + <item> + <p> The support for Dets files created with Erlang/OTP R7 + and earlier is removed. </p> + <p> + Own Id: OTP-13830</p> + </item> + <item> + <p>Replaced usage of deprecated symbolic <seealso + marker="erts:erlang#type-time_unit"><c>time + unit</c></seealso> representations.</p> + <p> + Own Id: OTP-13831 Aux Id: OTP-13735 </p> + </item> + <item> + <p>The function <c>fmod/2</c> has been added to the + <c>math</c> module.</p> + <p> + Own Id: OTP-14000</p> + </item> + <item> + <p>The EXIT signals received from processes using + <c>proc_lib</c> now looks like EXIT signals from + processes that were spawned using <c>spawn_link</c>. In + particular, that means that the stack trace is now + included in the EXIT signal so that it can see where the + process crashed.</p> + <p> + Own Id: OTP-14001</p> + </item> + <item> + <p><c>sets:add_element/2</c> is faster when adding an + element that is already present, and + <c>sets:del_element/2</c> is faster when the element to + be deleted is not present. This optimization can make + certain operations, such as sets:union/2 with many + overlapping elements, up to two orders of magnitude + faster.</p> + <p> + Own Id: OTP-14035</p> + </item> + <item> + <p> + Add information in doc about supervisor shutdown reason + when maximum restart frequency is reached.</p> + <p> + Own Id: OTP-14037 Aux Id: PR-1233 </p> + </item> + <item> + <p> + Added <c>rand:jump/[0|1]</c> functions.</p> + <p> + Own Id: OTP-14038 Aux Id: PR-1235 </p> + </item> + <item> + <p>Functions for detecting changed code has been added. + <c>code:modified_modules/0</c> returns all currently + loaded modules that have changed on disk. + <c>code:module_status/1</c> returns the status for a + module. In the shell and in <c>c</c> module, <c>mm/0</c> + is short for <c>code:modified_modules/0</c>, and + <c>lm/0</c> reloads all currently loaded modules that + have changed on disk.</p> + <p> + Own Id: OTP-14059</p> + </item> + <item> + <p>Each assert macro in <c>assert.hrl</c> now has a + corresponding version with an extra argument, for adding + comments to assertions. These can for example be printed + as part of error reports, to clarify the meaning of the + check that failed.</p> + <p> + Own Id: OTP-14066</p> + </item> + <item> + <p><c>error_logger_tty_h</c> and + <c>error_logger_file_h</c> now inserts the node + information for nonlocal messages before the message + itself instead of after, both for readability and so as + not to change the line termination property at the end of + the message.</p> + <p> + Own Id: OTP-14068</p> + </item> + <item> + <p>The Erlang code linter checks for badly formed type + constraints. </p> + <p> + Own Id: OTP-14070 Aux Id: PR-1214 </p> + </item> + <item> + <p>By default, there will now be a warning when + <c>export_all</c> is used. The warning can be disabled + using <c>nowarn_export_all</c>.</p> + <p> + Own Id: OTP-14071</p> + </item> + <item> + <p>When a <c>gen_server</c> process crashes, the + stacktrace for the client will be printed to facilitate + debugging.</p> + <p> + Own Id: OTP-14089</p> + </item> + <item> + <p>Optimized ETS operations by changing table identifier + type from integer to reference. The reference enables a + more direct mapping to the table with less potential lock + contention and makes especially creation and deletion of + tables scale much better.</p> <p>The change of the opaque + type for the ETS table identifiers may cause failure in + code that make faulty assumptions about this opaque + type.</p> <note> <p> The number of tables stored at one + Erlang node <em>used</em> to be limited. This is no + longer the case (except by memory usage). The previous + default limit was about 1400 tables and could be + increased by setting the environment variable + <c>ERL_MAX_ETS_TABLES</c> before starting the Erlang + runtime system. This hard limit has been removed, but it + is currently useful to set the <c>ERL_MAX_ETS_TABLES</c> + anyway. It should be set to an approximate of the maximum + amount of tables used. This since an internal table for + named tables is sized using this value. If large amounts + of named tables are used and <c>ERL_MAX_ETS_TABLES</c> + hasn't been increased, the performance of named table + lookup will degrade. </p> </note> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14094</p> + </item> + <item> + <p><c>take/2</c> has been added to <c>dict</c>, + <c>orddict</c>, and <c>gb_trees</c>. <c>take_any/2</c> + has been added to <c>gb_trees</c>.</p> + <p> + Own Id: OTP-14102</p> + </item> + <item> + <p> + Extend gen_event API to handle options as well.</p> + <p> + Own Id: OTP-14123</p> + </item> + <item> + <p> + Advice on how to tune the supervisor restart frequency + (intensity and period) is added to System Documentation - + Design Principles - Supervisor Behaviour.</p> + <p> + Own Id: OTP-14168 Aux Id: PR-1289 </p> + </item> + <item> + <p> + gen_fsm is deprecated and is replaced by gen_statem, + however for backwards compatibility reasons gen_fsm may + continue to exist as an undocumented feature for quite + some time.</p> + <p> + Own Id: OTP-14183</p> + </item> + <item> + <p>The shell functions <c>c/1</c> and <c>c/2</c> have + been extended so that if the argument is a module name + instead of a file name, it automatically locates the + .beam file and the corresponding source file, and then + recompiles the module using the same compiler options + (plus any options passed to c/2). If compilation fails, + the old beam file is preserved. Also adds <c>c(Mod, Opts, + Filter)</c>, where the Filter argument allows you to + remove old compiler options before the new options are + added.</p> <p>New utility functions <c>file_find/2/3</c> + and <c>find_source/1/2/3</c> have been added to + <c>filelib</c>.</p> + <p> + Own Id: OTP-14190</p> + </item> + <item> + <p><c>erl_tar</c> in previous versions of OTP only + supports the USTAR format. That limited path names to at + most 255 bytes, and did not support Unicode characters in + names in a portable way.</p> + <p><c>erl_tar</c> now has support for reading tar + archives in the formats currently in common use, such as + v7, STAR, USTAR, PAX, and GNU tar's extensions to the + STAR/USTAR format. When writing tar archives, + <c>erl_tar</c> can now write them in the <c>PAX</c> + format if necessary (for example, to support very long + filenames or filenames with Unicode characters). If + possible, <c>erl_tar</c> will still write tar archives in + the USTAR for maximum portability.</p> + <p> + Own Id: OTP-14226</p> + </item> + <item> + <p><c>base64:mime_decode/1</c> has been optimized so that + it is now almost as fast as<c>base64:decode/1</c>; it + used be noticeably slower.</p> + <p> + Own Id: OTP-14245</p> + </item> + <item> + <p><c>erl_tar</c> will now strip any leading '<c>/</c>' + from pathnames when extracting files from a tar archive + and write a message to the error logger. There is also + new check for directory traversal attacks; if a relative + path points above the current working directory the + extraction will be aborted.</p> + <p> + Own Id: OTP-14278</p> + </item> + <item> + <p> Miscellaneous updates due to atoms containing + arbitrary Unicode characters. </p> + <p> + Own Id: OTP-14285</p> + </item> + <item> + <p> + The Crypto application now supports generation of + cryptographically strong random numbers (floats < 1.0 + and integer arbitrary ranges) as a plugin to the 'rand' + module.</p> + <p> + Own Id: OTP-14317 Aux Id: PR-1372 </p> + </item> + <item> + <p> + Add new function <c>ets:select_replace/2</c> which + performs atomic "compare-and-swap" operations for ETS + objects using match specifications.</p> + <p> + Own Id: OTP-14319 Aux Id: PR-1076 </p> + </item> + <item> + <p> The Erlang code linter checks for bad <c>dialyzer</c> + attributes. It also checks for bad type variables in type + declarations. </p> + <p> + Own Id: OTP-14323</p> + </item> + <item> + <p> Two new functions has been implemented in the + <c>rand</c> module; <c>normal/2</c> and + <c>normal_s/3</c>, that both produce normal distribution + (pseudo) random numbers with mean value and variance + according to arguments. </p> + <p> + Own Id: OTP-14328 Aux Id: PR-1382 </p> + </item> + <item> + <p> + Upgraded the OTP internal PCRE library from version 8.33 + to version 8.40. This library is used for implementation + of the <seealso marker="stdlib:re"><c>re</c></seealso> + regular expressions module.</p> + <p> + Besides various bug fixes, the new version allows for + better stack protection. In order to utilize this + feature, the stack size of normal scheduler threads is + now by default set to 128 kilo words on all platforms. + The stack size of normal scheduler threads can be set + upon system start by passing the <seealso + marker="erts:erl#sched_thread_stack_size"><c>+sss</c></seealso> + command line argument to the <seealso + marker="erts:erl"><c>erl</c></seealso> command.</p> + <p> + See <url + href="http://pcre.org/original/changelog.txt">http://pcre.org/original/changelog.txt</url> + for information about changes made to PCRE between the + versions 8.33 and 8.40.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14331 Aux Id: ERL-208 </p> + </item> + <item> + <p> + Added function <c>re:version/0</c> which returns + information about the OTP internal PCRE version used for + implementation of the <c>re</c> module.</p> + <p> + Own Id: OTP-14347 Aux Id: PR-1412 </p> + </item> + <item> + <p>The format of debug information that is stored in BEAM + files (when <c>debug_info</c> is used) has been changed. + The purpose of the change is to better support other + BEAM-based languages such as Elixir or LFE.</p> + <p>All tools included in OTP (dialyzer, debugger, cover, + and so on) will handle both the new format and the + previous format. Tools that retrieve the debug + information using <c>beam_lib:chunk(Beam, + [abstract_code])</c> will continue to work with both the + new and old format. Tools that call + <c>beam_lib:chunk(Beam, ["Abst"])</c> will not work with + the new format.</p> + <p>For more information, see the description of + <c>debug_info</c> in the documentation for + <c>beam_lib</c> and the description of the + <c>{debug_info,{Backend,Data}}</c> option in the + documentation for <c>compile</c>.</p> + <p> + Own Id: OTP-14369 Aux Id: PR-1367 </p> + </item> + <item> + <p> + Add option hibernate_after to gen_server, gen_statem and + gen_event. Also added to the deprecated gen_fsm + behaviour.</p> + <p> + Own Id: OTP-14405</p> + </item> + <item> + <p> The size of crash reports created by + <c>gen_server</c>, <c>gen_statem</c> and <c>proc_lib</c> + is limited with aid of the Kernel application variable + <c>error_logger_format_depth</c>. The purpose is to limit + the size of the messages sent to the <c>error_logger</c> + process when processes with huge message queues or states + crash. </p> <p>The crash report generated by + <c>proc_lib</c> includes the new tag + <c>message_queue_len</c>. The neighbour report also + includes the new tag <c>current_stacktrace</c>. Finally, + the neighbour report no longer includes the tags + <c>messages</c> and <c>dictionary</c>. </p> <p> The new + function <c>error_logger:get_format_depth/0</c> can be + used to retrieve the value of the Kernel application + variable <c>error_logger_format_depth</c>. </p> + <p> + Own Id: OTP-14417</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 3.3</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -566,6 +1833,21 @@ </section> +<section><title>STDLIB 2.8.0.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>List subtraction (The <c>--</c> operator) will now + yield properly on large inputs.</p> + <p> + Own Id: OTP-15371</p> + </item> + </list> + </section> + +</section> + <section><title>STDLIB 2.8</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -3267,7 +4549,7 @@ <p> Two bugs in io:format for ~F.~Ps has been corrected. When length(S) >= abs(F) > P, the precision P was incorrectly - ignored. When F == P > lenght(S) the result was + ignored. When F == P > length(S) the result was incorrectly left adjusted. Bug found by Ali Yakout who also provided a fix.</p> <p> @@ -6735,4 +8017,3 @@ </section> </section> </chapter> - diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index d048983c61..27ccccee7e 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -32,13 +32,13 @@ <rev>B</rev> <file>orddict.xml</file> </header> - <module>orddict</module> + <module since="">orddict</module> <modulesummary>Key-value dictionary as ordered list.</modulesummary> <description> <p>This module provides a <c>Key</c>-<c>Value</c> dictionary. An <c>orddict</c> is a representation of a dictionary, where a list of pairs is used to store the keys and values. The list is - ordered after the keys.</p> + ordered after the keys in the <em>Erlang term order</em>.</p> <p>This module provides the same interface as the <seealso marker="dict"><c>dict(3)</c></seealso> module @@ -61,7 +61,7 @@ <funcs> <func> - <name name="append" arity="3"/> + <name name="append" arity="3" since=""/> <fsummary>Append a value to keys in a dictionary.</fsummary> <desc> <p>Appends a new <c><anno>Value</anno></c> to the current list @@ -73,7 +73,7 @@ </func> <func> - <name name="append_list" arity="3"/> + <name name="append_list" arity="3" since=""/> <fsummary>Append new values to keys in a dictionary.</fsummary> <desc> <p>Appends a list of values <c><anno>ValList</anno></c> to @@ -85,7 +85,7 @@ </func> <func> - <name name="erase" arity="2"/> + <name name="erase" arity="2" since=""/> <fsummary>Erase a key from a dictionary.</fsummary> <desc> <p>Erases all items with a specified key from a dictionary.</p> @@ -93,7 +93,7 @@ </func> <func> - <name name="fetch" arity="2"/> + <name name="fetch" arity="2" since=""/> <fsummary>Look up values in a dictionary.</fsummary> <desc> <p>Returns the value associated with <c><anno>Key</anno></c> @@ -105,7 +105,7 @@ </func> <func> - <name name="fetch_keys" arity="1"/> + <name name="fetch_keys" arity="1" since=""/> <fsummary>Return all keys in a dictionary.</fsummary> <desc> <p>Returns a list of all keys in a dictionary.</p> @@ -113,7 +113,16 @@ </func> <func> - <name name="filter" arity="2"/> + <name name="take" arity="2" since="OTP 20.0"/> + <fsummary>Return value and new dictionary without element with this value.</fsummary> + <desc> + <p>This function returns value from dictionary and new dictionary without this value. + Returns <c>error</c> if the key is not present in the dictionary.</p> + </desc> + </func> + + <func> + <name name="filter" arity="2" since=""/> <fsummary>Select elements that satisfy a predicate.</fsummary> <desc> <p><c><anno>Orddict2</anno></c> is a dictionary of all keys and values @@ -124,7 +133,7 @@ </func> <func> - <name name="find" arity="2"/> + <name name="find" arity="2" since=""/> <fsummary>Search for a key in a dictionary.</fsummary> <desc> <p>Searches for a key in a dictionary. Returns @@ -136,7 +145,7 @@ </func> <func> - <name name="fold" arity="3"/> + <name name="fold" arity="3" since=""/> <fsummary>Fold a function over a dictionary.</fsummary> <desc> <p>Calls <c><anno>Fun</anno></c> on successive keys and values of @@ -148,7 +157,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since=""/> <fsummary>Convert a list of pairs to a dictionary.</fsummary> <desc> <p>Converts the <c><anno>Key</anno></c>-<c><anno>Value</anno></c> list @@ -157,7 +166,7 @@ </func> <func> - <name name="is_empty" arity="1"/> + <name name="is_empty" arity="1" since="OTP 17.0"/> <fsummary>Return true if the dictionary is empty.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Orddict</anno></c> has no elements, @@ -166,7 +175,7 @@ </func> <func> - <name name="is_key" arity="2"/> + <name name="is_key" arity="2" since=""/> <fsummary>Test if a key is in a dictionary.</fsummary> <desc> <p>Tests if <c><anno>Key</anno></c> is contained in @@ -175,7 +184,7 @@ </func> <func> - <name name="map" arity="2"/> + <name name="map" arity="2" since=""/> <fsummary>Map a function over a dictionary.</fsummary> <desc> <p>Calls <c><anno>Fun</anno></c> on successive keys and values of @@ -184,7 +193,7 @@ </func> <func> - <name name="merge" arity="3"/> + <name name="merge" arity="3" since=""/> <fsummary>Merge two dictionaries.</fsummary> <desc> <p>Merges two dictionaries, <c><anno>Orddict1</anno></c> and @@ -203,7 +212,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Create a dictionary.</fsummary> <desc> <p>Creates a new dictionary.</p> @@ -211,7 +220,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Return the number of elements in an ordered dictionary. </fsummary> <desc> @@ -220,7 +229,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="store" arity="3"/> + <name name="store" arity="3" since=""/> <fsummary>Store a value in a dictionary.</fsummary> <desc> <p>Stores a <c><anno>Key</anno></c>-<c><anno>Value</anno></c> pair in a @@ -231,7 +240,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert a dictionary to a list of pairs.</fsummary> <desc> <p>Converts a dictionary to a list representation.</p> @@ -239,7 +248,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="update" arity="3"/> + <name name="update" arity="3" since=""/> <fsummary>Update a value in a dictionary.</fsummary> <desc> <p>Updates a value in a dictionary by calling <c><anno>Fun</anno></c> @@ -249,7 +258,7 @@ merge(Fun, D1, D2) -> </func> <func> - <name name="update" arity="4"/> + <name name="update" arity="4" since=""/> <fsummary>Update a value in a dictionary.</fsummary> <desc> <p>Updates a value in a dictionary by calling <c><anno>Fun</anno></c> @@ -264,7 +273,7 @@ append(Key, Val, D) -> </func> <func> - <name name="update_counter" arity="3"/> + <name name="update_counter" arity="3" since=""/> <fsummary>Increment a value in a dictionary.</fsummary> <desc> <p>Adds <c><anno>Increment</anno></c> to the value associated with diff --git a/lib/stdlib/doc/src/ordsets.xml b/lib/stdlib/doc/src/ordsets.xml index 148281fcf7..fbe334c009 100644 --- a/lib/stdlib/doc/src/ordsets.xml +++ b/lib/stdlib/doc/src/ordsets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,14 +32,15 @@ <rev>A</rev> <file>ordsets.xml</file> </header> - <module>ordsets</module> + <module since="">ordsets</module> <modulesummary>Functions for manipulating sets as ordered lists. </modulesummary> <description> <p>Sets are collections of elements with no duplicate elements. An <c>ordset</c> is a representation of a set, where an ordered list is used to store the elements of the set. An ordered list - is more efficient than an unordered list.</p> + is more efficient than an unordered list. Elements are ordered + according to the <em>Erlang term order</em>.</p> <p>This module provides the same interface as the <seealso marker="sets"><c>sets(3)</c></seealso> module @@ -59,7 +60,7 @@ <funcs> <func> - <name name="add_element" arity="2"/> + <name name="add_element" arity="2" since=""/> <fsummary>Add an element to an <c>Ordset</c>.</fsummary> <desc> <p>Returns a new ordered set formed from <c><anno>Ordset1</anno></c> @@ -68,7 +69,7 @@ </func> <func> - <name name="del_element" arity="2"/> + <name name="del_element" arity="2" since=""/> <fsummary>Remove an element from an <c>Ordset</c>.</fsummary> <desc> <p>Returns <c><anno>Ordset1</anno></c>, but with @@ -77,7 +78,7 @@ </func> <func> - <name name="filter" arity="2"/> + <name name="filter" arity="2" since=""/> <fsummary>Filter set elements.</fsummary> <desc> <p>Filters elements in <c><anno>Ordset1</anno></c> with boolean function @@ -86,7 +87,7 @@ </func> <func> - <name name="fold" arity="3"/> + <name name="fold" arity="3" since=""/> <fsummary>Fold over set elements.</fsummary> <desc> <p>Folds <c><anno>Function</anno></c> over every element in @@ -96,7 +97,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since=""/> <fsummary>Convert a list into an <c>Ordset</c>.</fsummary> <desc> <p>Returns an ordered set of the elements in <c><anno>List</anno></c>. @@ -105,7 +106,7 @@ </func> <func> - <name name="intersection" arity="1"/> + <name name="intersection" arity="1" since=""/> <fsummary>Return the intersection of a list of <c>Ordsets</c></fsummary> <desc> <p>Returns the intersection of the non-empty list of sets.</p> @@ -113,7 +114,7 @@ </func> <func> - <name name="intersection" arity="2"/> + <name name="intersection" arity="2" since=""/> <fsummary>Return the intersection of two <c>Ordsets</c>.</fsummary> <desc> <p>Returns the intersection of <c><anno>Ordset1</anno></c> and @@ -122,7 +123,7 @@ </func> <func> - <name name="is_disjoint" arity="2"/> + <name name="is_disjoint" arity="2" since=""/> <fsummary>Check whether two <c>Ordsets</c> are disjoint.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Ordset1</anno></c> and @@ -132,7 +133,7 @@ </func> <func> - <name name="is_element" arity="2"/> + <name name="is_element" arity="2" since=""/> <fsummary>Test for membership of an <c>Ordset</c>.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Element</anno></c> is an element of @@ -141,7 +142,16 @@ </func> <func> - <name name="is_set" arity="1"/> + <name name="is_empty" arity="1" since="OTP 21.0"/> + <fsummary>Test for empty set.</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Ordset</anno></c> is an empty set, + otherwise <c>false</c>.</p> + </desc> + </func> + + <func> + <name name="is_set" arity="1" since=""/> <fsummary>Test for an <c>Ordset</c>.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Ordset</anno></c> is an ordered set @@ -150,7 +160,7 @@ </func> <func> - <name name="is_subset" arity="2"/> + <name name="is_subset" arity="2" since=""/> <fsummary>Test for subset.</fsummary> <desc> <p>Returns <c>true</c> when every element of <c><anno>Ordset1</anno></c> @@ -160,7 +170,7 @@ </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Return an empty set.</fsummary> <desc> <p>Returns a new empty ordered set.</p> @@ -168,7 +178,7 @@ </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Return the number of elements in a set.</fsummary> <desc> <p>Returns the number of elements in <c><anno>Ordset</anno></c>.</p> @@ -176,7 +186,7 @@ </func> <func> - <name name="subtract" arity="2"/> + <name name="subtract" arity="2" since=""/> <fsummary>Return the difference of two <c>Ordsets</c>.</fsummary> <desc> <p>Returns only the elements of <c><anno>Ordset1</anno></c> that are not @@ -185,7 +195,7 @@ </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert an <c>Ordset</c> into a list.</fsummary> <desc> <p>Returns the elements of <c><anno>Ordset</anno></c> as a list.</p> @@ -193,7 +203,7 @@ </func> <func> - <name name="union" arity="1"/> + <name name="union" arity="1" since=""/> <fsummary>Return the union of a list of <c>Ordsets</c>.</fsummary> <desc> <p>Returns the merged (union) set of the list of sets.</p> @@ -201,7 +211,7 @@ </func> <func> - <name name="union" arity="2"/> + <name name="union" arity="2" since=""/> <fsummary>Return the union of two <c>Ordsets</c>.</fsummary> <desc> <p>Returns the merged (union) set of <c><anno>Ordset1</anno></c> and diff --git a/lib/stdlib/doc/src/part_notes.xml b/lib/stdlib/doc/src/part_notes.xml deleted file mode 100644 index 461de749dd..0000000000 --- a/lib/stdlib/doc/src/part_notes.xml +++ /dev/null @@ -1,39 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>2004</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>STDLIB Release Notes</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - </header> - <description> - <p>The Standard Erlang Libraries application, <em>STDLIB</em>, - contains modules for manipulating lists, strings and files etc.</p> - <p>For information about older versions, see - <url href="part_notes_history_frame.html">Release Notes History</url>.</p> - </description> - <xi:include href="notes.xml"/> -</part> - diff --git a/lib/stdlib/doc/src/part_notes_history.xml b/lib/stdlib/doc/src/part_notes_history.xml deleted file mode 100644 index 8fd048a41e..0000000000 --- a/lib/stdlib/doc/src/part_notes_history.xml +++ /dev/null @@ -1,39 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part> - <header> - <copyright> - <year>2006</year> - <year>2016</year> - <holder>Ericsson AB, All Rights Reserved</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - The Initial Developer of the Original Code is Ericsson AB. - </legalnotice> - - <title>STDLIB Release Notes History</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - </header> - <description> - <p>The Standard Erlang Libraries application, <em>STDLIB</em>, - contains modules for manipulating lists, strings and files etc.</p> - </description> - <include file="notes_history"></include> -</part> - diff --git a/lib/stdlib/doc/src/pool.xml b/lib/stdlib/doc/src/pool.xml index 05d12ade28..675ee08bfb 100644 --- a/lib/stdlib/doc/src/pool.xml +++ b/lib/stdlib/doc/src/pool.xml @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>pool</module> + <module since="">pool</module> <modulesummary>Load distribution facility.</modulesummary> <description> <p>This module can be used to run a set of Erlang nodes as a pool @@ -54,7 +54,7 @@ <funcs> <func> - <name name="attach" arity="1"/> + <name name="attach" arity="1" since=""/> <fsummary>Ensure that a pool master is running.</fsummary> <desc> <p>Ensures that a pool master is running and includes @@ -63,7 +63,7 @@ </func> <func> - <name name="get_node" arity="0"/> + <name name="get_node" arity="0" since=""/> <fsummary>Return the node with the expected lowest future load.</fsummary> <desc> <p>Returns the node with the expected lowest future load.</p> @@ -71,7 +71,7 @@ </func> <func> - <name name="get_nodes" arity="0"/> + <name name="get_nodes" arity="0" since=""/> <fsummary>Return a list of the current member nodes of the pool. </fsummary> <desc> @@ -80,7 +80,7 @@ </func> <func> - <name name="pspawn" arity="3"/> + <name name="pspawn" arity="3" since=""/> <fsummary>Spawn a process on the pool node with expected lowest future load.</fsummary> <desc> @@ -90,7 +90,7 @@ </func> <func> - <name name="pspawn_link" arity="3"/> + <name name="pspawn_link" arity="3" since=""/> <fsummary>Spawn and link to a process on the pool node with expected lowest future load.</fsummary> <desc> @@ -100,8 +100,8 @@ </func> <func> - <name name="start" arity="1"/> - <name name="start" arity="2"/> + <name name="start" arity="1" since=""/> + <name name="start" arity="2" since=""/> <fsummary>>Start a new pool.</fsummary> <desc> <p>Starts a new pool. The file <c>.hosts.erlang</c> is read to @@ -122,7 +122,7 @@ </func> <func> - <name name="stop" arity="0"/> + <name name="stop" arity="0" since=""/> <fsummary>Stop the pool and kill all the slave nodes.</fsummary> <desc> <p>Stops the pool and kills all the slave nodes.</p> diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml index da03c39a26..aeb9f48735 100644 --- a/lib/stdlib/doc/src/proc_lib.xml +++ b/lib/stdlib/doc/src/proc_lib.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>proc_lib</module> + <module since="">proc_lib</module> <modulesummary>Functions for asynchronous and synchronous start of processes adhering to the OTP design principles.</modulesummary> <description> @@ -36,7 +36,7 @@ the <seealso marker="doc/design_principles:des_princ"> OTP Design Principles</seealso>. Specifically, the functions in this module are used by the OTP standard behaviors (for example, - <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_statem</c>) + <c>gen_server</c> and <c>gen_statem</c>) when starting new processes. The functions can also be used to start <em>special processes</em>, user-defined processes that comply to the OTP design principles. For an example, @@ -59,13 +59,18 @@ <p>When a process that is started using <c>proc_lib</c> terminates abnormally (that is, with another exit reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c>), a <em>crash report</em> - is generated, which is written to terminal by the default SASL - event handler. That is, the crash report is normally only visible - if the SASL application is started; see - <seealso marker="sasl:sasl_app"><c>sasl(6)</c></seealso> and section + is generated, which is written to terminal by the default logger + handler setup by Kernel. For more information about how crash reports + were logged prior to Erlang/OTP 21.0, see <seealso marker="sasl:error_logging">SASL Error Logging</seealso> in the SASL User's Guide.</p> + <p>Unlike in "plain Erlang", <c>proc_lib</c> processes will not generate + <em>error reports</em>, which are written to the terminal by the + emulator. All exceptions are + converted to <em>exits</em> which are ignored by the default + <c>logger</c> handler.</p> + <p>The crash report contains the previously stored information, such as ancestors and initial function, the termination reason, and information about other processes that terminate as a result @@ -97,7 +102,7 @@ <funcs> <func> - <name name="format" arity="1"/> + <name name="format" arity="1" since=""/> <fsummary>Format a crash report.</fsummary> <desc> <p>Equivalent to <seealso marker="#format/2"> @@ -106,15 +111,25 @@ </func> <func> - <name name="format" arity="2"/> + <name name="format" arity="2" since="OTP R16B"/> <fsummary>Format a crash report.</fsummary> <desc> - <p>This function can be used by a user-defined event handler to + <note> + <p>This function is deprecated in the sense that + the <c>error_logger</c> is no longer the preferred + interface for logging in Erlang/OTP. A + new <seealso marker="kernel:logger_chapter">logging + API</seealso> was added in Erlang/OTP 21.0, but + legacy <c>error_logger</c> handlers can still be used. New + Logger handlers do not need to use this function, since + the formatting callback (<c>report_cb</c>) is included as + metadata in the log event.</p> + </note> + <p>This function can be used by a user-defined legacy + <c>error_logger</c> event handler to format a crash report. The crash report is sent using - <seealso marker="kernel:error_logger#error_report/2"> - <c>error_logger:error_report(crash_report, - <anno>CrashReport</anno>)</c></seealso>. - That is, the event to be handled is of the format + <seealso marker="kernel:logger"> + <c>logger(3)</c></seealso>, and the event to be handled is of the format <c>{error_report, GL, {Pid, crash_report, <anno>CrashReport</anno>}}</c>, where <c>GL</c> is the group leader pid of process @@ -123,10 +138,22 @@ </func> <func> - <name name="format" arity="3"/> + <name name="format" arity="3" since="OTP 18.1"/> <fsummary>Format a crash report.</fsummary> <desc> - <p>This function can be used by a user-defined event handler to + <note> + <p>This function is deprecated in the sense that + the <c>error_logger</c> is no longer the preferred + interface for logging in Erlang/OTP. A + new <seealso marker="kernel:logger_chapter">logging + API</seealso> was added in Erlang/OTP 21.0, but + legacy <c>error_logger</c> handlers can still be used. New + Logger handlers do not need to used this function, since + the formatting callback (<c>report_cb</c>) is included as + metadata in the log event.</p> + </note> + <p>This function can be used by a user-defined legacy + <c>error_logger</c> event handler to format a crash report. When <anno>Depth</anno> is specified as a positive integer, it is used in the format string to limit the output as follows: <c>io_lib:format("~P", @@ -135,7 +162,7 @@ </func> <func> - <name name="hibernate" arity="3"/> + <name name="hibernate" arity="3" since=""/> <fsummary>Hibernate a process until a message is sent to it.</fsummary> <desc> <p>This function does the same as (and does call) the @@ -149,8 +176,8 @@ </func> <func> - <name name="init_ack" arity="1"/> - <name name="init_ack" arity="2"/> + <name name="init_ack" arity="1" since=""/> + <name name="init_ack" arity="2" since=""/> <fsummary>Used by a process when it has started.</fsummary> <desc> <p>This function must be used by a process that has been started by @@ -187,7 +214,7 @@ init(Parent) -> </func> <func> - <name name="initial_call" arity="1"/> + <name name="initial_call" arity="1" since=""/> <fsummary>Extract the initial call of a <c>proc_lib</c>spawned process. </fsummary> <desc> @@ -217,10 +244,10 @@ init(Parent) -> </func> <func> - <name name="spawn" arity="1"/> - <name name="spawn" arity="2"/> - <name name="spawn" arity="3"/> - <name name="spawn" arity="4"/> + <name name="spawn" arity="1" since=""/> + <name name="spawn" arity="2" since=""/> + <name name="spawn" arity="3" since=""/> + <name name="spawn" arity="4" since=""/> <fsummary>Spawn a new process.</fsummary> <type variable="Node"/> <type variable="Fun" name_i="1"/> @@ -235,10 +262,10 @@ init(Parent) -> </func> <func> - <name name="spawn_link" arity="1"/> - <name name="spawn_link" arity="2"/> - <name name="spawn_link" arity="3"/> - <name name="spawn_link" arity="4"/> + <name name="spawn_link" arity="1" since=""/> + <name name="spawn_link" arity="2" since=""/> + <name name="spawn_link" arity="3" since=""/> + <name name="spawn_link" arity="4" since=""/> <fsummary>Spawn and link to a new process.</fsummary> <type variable="Node"/> <type variable="Fun" name_i="1"/> @@ -254,10 +281,10 @@ init(Parent) -> </func> <func> - <name name="spawn_opt" arity="2"/> - <name name="spawn_opt" arity="3"/> - <name name="spawn_opt" arity="4"/> - <name name="spawn_opt" arity="5"/> + <name name="spawn_opt" arity="2" since=""/> + <name name="spawn_opt" arity="3" since=""/> + <name name="spawn_opt" arity="4" since=""/> + <name name="spawn_opt" arity="5" since=""/> <fsummary>Spawn a new process with specified options.</fsummary> <type variable="Node"/> <type variable="Fun" name_i="1"/> @@ -279,12 +306,12 @@ init(Parent) -> </func> <func> - <name name="start" arity="3"/> - <name name="start" arity="4"/> - <name name="start" arity="5"/> - <name name="start_link" arity="3"/> - <name name="start_link" arity="4"/> - <name name="start_link" arity="5"/> + <name name="start" arity="3" since=""/> + <name name="start" arity="4" since=""/> + <name name="start" arity="5" since=""/> + <name name="start_link" arity="3" since=""/> + <name name="start_link" arity="4" since=""/> + <name name="start_link" arity="5" since=""/> <fsummary>Start a new process synchronously.</fsummary> <desc> <p>Starts a new process synchronously. Spawns the process and @@ -314,7 +341,7 @@ init(Parent) -> </func> <func> - <name name="stop" arity="1"/> + <name name="stop" arity="1" since="OTP 18.0"/> <fsummary>Terminate a process synchronously.</fsummary> <type variable="Process"/> <desc> @@ -324,7 +351,7 @@ init(Parent) -> </func> <func> - <name name="stop" arity="3"/> + <name name="stop" arity="3" since="OTP 18.0"/> <fsummary>Terminate a process synchronously.</fsummary> <type variable="Process"/> <type variable="Reason"/> @@ -348,7 +375,7 @@ init(Parent) -> </func> <func> - <name name="translate_initial_call" arity="1"/> + <name name="translate_initial_call" arity="1" since=""/> <fsummary>Extract and translate the initial call of a <c>proc_lib</c>spawned process.</fsummary> <desc> @@ -389,6 +416,8 @@ init(Parent) -> <title>See Also</title> <p><seealso marker="kernel:error_logger"> <c>error_logger(3)</c></seealso></p> + <p><seealso marker="kernel:logger"> + <c>logger(3)</c></seealso></p> </section> </erlref> diff --git a/lib/stdlib/doc/src/proplists.xml b/lib/stdlib/doc/src/proplists.xml index fe6b8cc3bf..4465103469 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2002</year><year>2016</year> + <year>2002</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>proplists.xml</file> </header> - <module>proplists</module> + <module since="">proplists</module> <modulesummary>Support functions for property lists.</modulesummary> <description> <p>Property lists are ordinary lists containing entries in the form @@ -57,11 +57,16 @@ <datatype> <name name="property"/> </datatype> + + <datatype> + <name name="proplist"/> + </datatype> + </datatypes> <funcs> <func> - <name name="append_values" arity="2"/> + <name name="append_values" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Similar to @@ -79,7 +84,7 @@ append_values(a, [{a, [1,2]}, {b, 0}, {a, 3}, {c, -1}, {a, [4]}])</code> </func> <func> - <name name="compact" arity="1"/> + <name name="compact" arity="1" since=""/> <fsummary></fsummary> <desc> <p>Minimizes the representation of all entries in the list. This is @@ -91,7 +96,7 @@ append_values(a, [{a, [1,2]}, {b, 0}, {a, 3}, {c, -1}, {a, [4]}])</code> </func> <func> - <name name="delete" arity="2"/> + <name name="delete" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Deletes all entries associated with <c><anno>Key</anno></c> from @@ -100,7 +105,7 @@ append_values(a, [{a, [1,2]}, {b, 0}, {a, 3}, {c, -1}, {a, [4]}])</code> </func> <func> - <name name="expand" arity="2"/> + <name name="expand" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Expands particular properties to corresponding sets of @@ -133,7 +138,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="get_all_values" arity="2"/> + <name name="get_all_values" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Similar to @@ -145,7 +150,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="get_bool" arity="2"/> + <name name="get_bool" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Returns the value of a boolean key/value option. If @@ -159,7 +164,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="get_keys" arity="1"/> + <name name="get_keys" arity="1" since=""/> <fsummary></fsummary> <desc> <p>Returns an unordered list of the keys used in @@ -168,7 +173,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="get_value" arity="2"/> + <name name="get_value" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Equivalent to @@ -177,7 +182,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="get_value" arity="3"/> + <name name="get_value" arity="3" since=""/> <fsummary></fsummary> <desc> <p>Returns the value of a simple key/value property in @@ -194,7 +199,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="is_defined" arity="2"/> + <name name="is_defined" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Returns <c>true</c> if <c><anno>List</anno></c> contains at least @@ -204,7 +209,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="lookup" arity="2"/> + <name name="lookup" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Returns the first entry associated with <c><anno>Key</anno></c> in @@ -219,7 +224,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="lookup_all" arity="2"/> + <name name="lookup_all" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Returns the list of all entries associated with @@ -231,7 +236,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="normalize" arity="2"/> + <name name="normalize" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Passes <c><anno>ListIn</anno></c> through a sequence of @@ -263,7 +268,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="property" arity="1"/> + <name name="property" arity="1" since=""/> <fsummary></fsummary> <desc> <p>Creates a normal form (minimal) representation of a property. If @@ -276,7 +281,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="property" arity="2"/> + <name name="property" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Creates a normal form (minimal) representation of a simple key/value @@ -289,7 +294,7 @@ expand([{{foo, true}, [bar, baz]}], [{foo, false}, fie, foo, fum])</code> </func> <func> - <name name="split" arity="2"/> + <name name="split" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Partitions <c><anno>List</anno></c> into a list of sublists and a @@ -310,7 +315,7 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</code> </func> <func> - <name name="substitute_aliases" arity="2"/> + <name name="substitute_aliases" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Substitutes keys of properties. For each entry in @@ -332,7 +337,7 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</code> </func> <func> - <name name="substitute_negations" arity="2"/> + <name name="substitute_negations" arity="2" since=""/> <fsummary></fsummary> <desc> <p>Substitutes keys of boolean-valued properties and @@ -344,7 +349,7 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</code> with <c>{K2, true}</c>, thus changing the name of the option and simultaneously negating the value specified by <seealso marker="#get_bool/2"> - <c>get_bool(Key, <anno>ListIn</anno></c></seealso>. + <c>get_bool(Key, <anno>ListIn</anno>)</c></seealso>. If the same <c>K1</c> occurs more than once in <c><anno>Negations</anno></c>, only the first occurrence is used.</p> <p>For example, <c>substitute_negations([{no_foo, foo}], L)</c> @@ -360,7 +365,7 @@ split([{c, 2}, {e, 1}, a, {c, 3, 4}, d, {b, 5}, b], [a, b, c])</code> </func> <func> - <name name="unfold" arity="1"/> + <name name="unfold" arity="1" since=""/> <fsummary></fsummary> <desc> <p>Unfolds all occurrences of atoms in <c><anno>ListIn</anno></c> to diff --git a/lib/stdlib/doc/src/qlc.xml b/lib/stdlib/doc/src/qlc.xml index fe14a6334c..fe60c2e9bb 100644 --- a/lib/stdlib/doc/src/qlc.xml +++ b/lib/stdlib/doc/src/qlc.xml @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>qlc.xml</file> </header> - <module>qlc</module> + <module since="">qlc</module> <modulesummary>Query interface to Mnesia, ETS, Dets, and so on. </modulesummary> <description> @@ -720,7 +720,7 @@ ets:match_spec_run(ets:lookup(86033, {2,2}), <funcs> <func> - <name name="append" arity="1"/> + <name name="append" arity="1" since=""/> <fsummary>Return a query handle.</fsummary> <desc> <p>Returns a query handle. When evaluating query handle @@ -731,7 +731,7 @@ ets:match_spec_run(ets:lookup(86033, {2,2}), </func> <func> - <name name="append" arity="2"/> + <name name="append" arity="2" since=""/> <fsummary>Return a query handle.</fsummary> <desc> <p>Returns a query handle. When evaluating query handle @@ -744,8 +744,8 @@ ets:match_spec_run(ets:lookup(86033, {2,2}), </func> <func> - <name name="cursor" arity="1"/> - <name name="cursor" arity="2"/> + <name name="cursor" arity="1" since=""/> + <name name="cursor" arity="2" since=""/> <fsummary>Create a query cursor.</fsummary> <desc> <p>Creates a query cursor and @@ -777,7 +777,7 @@ ok</pre> </func> <func> - <name name="delete_cursor" arity="1"/> + <name name="delete_cursor" arity="1" since=""/> <fsummary>Delete a query cursor.</fsummary> <desc> <p>Deletes a query cursor. Only the owner of the cursor can @@ -786,10 +786,10 @@ ok</pre> </func> <func> - <name name="e" arity="1"/> - <name name="e" arity="2"/> - <name name="eval" arity="1"/> - <name name="eval" arity="2"/> + <name name="e" arity="1" since=""/> + <name name="e" arity="2" since=""/> + <name name="eval" arity="1" since=""/> + <name name="eval" arity="2" since=""/> <fsummary>Return all answers to a query.</fsummary> <desc> <p>Evaluates a query handle in the @@ -805,8 +805,8 @@ ok</pre> </func> <func> - <name name="fold" arity="3"/> - <name name="fold" arity="4"/> + <name name="fold" arity="3" since=""/> + <name name="fold" arity="4" since=""/> <fsummary>Fold a function over the answers to a query.</fsummary> <desc> <p>Calls <c><anno>Function</anno></c> on successive answers to @@ -830,7 +830,7 @@ ok</pre> </func> <func> - <name name="format_error" arity="1"/> + <name name="format_error" arity="1" since=""/> <fsummary>Return an English description of a an error tuple.</fsummary> <desc> <p>Returns a descriptive string in English of an error tuple @@ -841,8 +841,8 @@ ok</pre> </func> <func> - <name name="info" arity="1"/> - <name name="info" arity="2"/> + <name name="info" arity="1" since=""/> + <name name="info" arity="2" since=""/> <fsummary>Return code describing a query handle.</fsummary> <desc> <p>Returns information about a @@ -946,8 +946,8 @@ end</pre> </func> <func> - <name name="keysort" arity="2"/> - <name name="keysort" arity="3"/> + <name name="keysort" arity="2" since=""/> + <name name="keysort" arity="3" since=""/> <fsummary>Return a query handle.</fsummary> <desc> <p>Returns a query handle. When evaluating query handle @@ -967,8 +967,8 @@ end</pre> </func> <func> - <name name="next_answers" arity="1"/> - <name name="next_answers" arity="2"/> + <name name="next_answers" arity="1" since=""/> + <name name="next_answers" arity="2" since=""/> <fsummary>Return some or all answers to a query.</fsummary> <desc> <p>Returns some or all of the remaining answers to a query @@ -983,8 +983,8 @@ end</pre> </func> <func> - <name name="q" arity="1"/> - <name name="q" arity="2"/> + <name name="q" arity="1" since=""/> + <name name="q" arity="2" since=""/> <fsummary>Return a handle for a query list comprehension.</fsummary> <desc> <p>Returns a query handle for a QLC. @@ -1188,8 +1188,8 @@ ets:match_spec_run( </func> <func> - <name name="sort" arity="1"/> - <name name="sort" arity="2"/> + <name name="sort" arity="1" since=""/> + <name name="sort" arity="2" since=""/> <fsummary>Return a query handle.</fsummary> <desc> <p>Returns a query handle. When evaluating query handle @@ -1208,9 +1208,9 @@ ets:match_spec_run( </func> <func> - <name name="string_to_handle" arity="1"/> - <name name="string_to_handle" arity="2"/> - <name name="string_to_handle" arity="3"/> + <name name="string_to_handle" arity="1" since=""/> + <name name="string_to_handle" arity="2" since=""/> + <name name="string_to_handle" arity="3" since=""/> <fsummary>Return a handle for a query list comprehension.</fsummary> <desc> <p>A string version of <seealso marker="#q/1"><c>q/1,2</c></seealso>. @@ -1238,7 +1238,7 @@ ets:match_spec_run( </func> <func> - <name name="table" arity="2"/> + <name name="table" arity="2" since=""/> <fsummary>Return a query handle for a table.</fsummary> <desc> <p>Returns a query handle for a QLC table. diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml index 9f3aff03a3..83a8afea81 100644 --- a/lib/stdlib/doc/src/queue.xml +++ b/lib/stdlib/doc/src/queue.xml @@ -32,7 +32,7 @@ <rev>B</rev> <file>queue.xml</file> </header> - <module>queue</module> + <module since="">queue</module> <modulesummary>Abstract data type for FIFO queues.</modulesummary> <description> <p>This module provides (double-ended) FIFO queues @@ -113,7 +113,7 @@ <funcs> <func> - <name name="filter" arity="2"/> + <name name="filter" arity="2" since=""/> <fsummary>Filter a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> that is the result of calling @@ -134,7 +134,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since=""/> <fsummary>Convert a list to a queue.</fsummary> <desc> <p>Returns a queue containing the items in <c><anno>L</anno></c> in the @@ -144,7 +144,7 @@ </func> <func> - <name name="in" arity="2"/> + <name name="in" arity="2" since=""/> <fsummary>Insert an item at the rear of a queue.</fsummary> <desc> <p>Inserts <c><anno>Item</anno></c> at the rear of queue @@ -154,7 +154,7 @@ </func> <func> - <name name="in_r" arity="2"/> + <name name="in_r" arity="2" since=""/> <fsummary>Insert an item at the front of a queue.</fsummary> <desc> <p>Inserts <c><anno>Item</anno></c> at the front of queue @@ -164,7 +164,7 @@ </func> <func> - <name name="is_empty" arity="1"/> + <name name="is_empty" arity="1" since=""/> <fsummary>Test if a queue is empty.</fsummary> <desc> <p>Tests if <c><anno>Q</anno></c> is empty and returns <c>true</c> if @@ -173,7 +173,7 @@ </func> <func> - <name name="is_queue" arity="1"/> + <name name="is_queue" arity="1" since=""/> <fsummary>Test if a term is a queue.</fsummary> <desc> <p>Tests if <c><anno>Term</anno></c> is a queue and returns <c>true</c> @@ -182,7 +182,7 @@ </func> <func> - <name name="join" arity="2"/> + <name name="join" arity="2" since=""/> <fsummary>Join two queues.</fsummary> <desc> <p>Returns a queue <c><anno>Q3</anno></c> that is the result of joining @@ -192,7 +192,7 @@ </func> <func> - <name name="len" arity="1"/> + <name name="len" arity="1" since=""/> <fsummary>Get the length of a queue.</fsummary> <desc> <p>Calculates and returns the length of queue <c><anno>Q</anno></c>.</p> @@ -200,7 +200,7 @@ </func> <func> - <name name="member" arity="2"/> + <name name="member" arity="2" since=""/> <fsummary>Test if an item is in a queue.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Item</anno></c> matches some element @@ -209,7 +209,7 @@ </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Create an empty queue.</fsummary> <desc> <p>Returns an empty queue.</p> @@ -217,7 +217,7 @@ </func> <func> - <name name="out" arity="1"/> + <name name="out" arity="1" since=""/> <fsummary>Remove the front item from a queue.</fsummary> <desc> <p>Removes the item at the front of queue <c><anno>Q1</anno></c>. @@ -230,7 +230,7 @@ </func> <func> - <name name="out_r" arity="1"/> + <name name="out_r" arity="1" since=""/> <fsummary>Remove the rear item from a queue.</fsummary> <desc> <p>Removes the item at the rear of queue <c><anno>Q1</anno></c>. @@ -242,7 +242,7 @@ </func> <func> - <name name="reverse" arity="1"/> + <name name="reverse" arity="1" since=""/> <fsummary>Reverse a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> containing the items of @@ -251,7 +251,7 @@ </func> <func> - <name name="split" arity="2"/> + <name name="split" arity="2" since=""/> <fsummary>Split a queue in two.</fsummary> <desc> <p>Splits <c><anno>Q1</anno></c> in two. The <c><anno>N</anno></c> @@ -261,7 +261,7 @@ </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert a queue to a list.</fsummary> <desc> <p>Returns a list of the items in the queue in the same order; @@ -276,7 +276,7 @@ <funcs> <func> - <name name="drop" arity="1"/> + <name name="drop" arity="1" since=""/> <fsummary>Remove the front item from a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing @@ -286,7 +286,7 @@ </func> <func> - <name name="drop_r" arity="1"/> + <name name="drop_r" arity="1" since=""/> <fsummary>Remove the rear item from a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing @@ -296,7 +296,7 @@ </func> <func> - <name name="get" arity="1"/> + <name name="get" arity="1" since=""/> <fsummary>Return the front item of a queue.</fsummary> <desc> <p>Returns <c><anno>Item</anno></c> at the front of queue @@ -306,7 +306,7 @@ </func> <func> - <name name="get_r" arity="1"/> + <name name="get_r" arity="1" since=""/> <fsummary>Return the rear item of a queue.</fsummary> <desc> <p>Returns <c><anno>Item</anno></c> at the rear of queue @@ -316,7 +316,7 @@ </func> <func> - <name name="peek" arity="1"/> + <name name="peek" arity="1" since=""/> <fsummary>Return the front item of a queue.</fsummary> <desc> <p>Returns tuple <c>{value, <anno>Item</anno>}</c>, where @@ -326,7 +326,7 @@ </func> <func> - <name name="peek_r" arity="1"/> + <name name="peek_r" arity="1" since=""/> <fsummary>Return the rear item of a queue.</fsummary> <desc> <p>Returns tuple <c>{value, <anno>Item</anno>}</c>, where @@ -342,7 +342,7 @@ <funcs> <func> - <name name="cons" arity="2"/> + <name name="cons" arity="2" since=""/> <fsummary>Insert an item at the head of a queue.</fsummary> <desc> <p>Inserts <c><anno>Item</anno></c> at the head of queue @@ -352,7 +352,7 @@ </func> <func> - <name name="daeh" arity="1"/> + <name name="daeh" arity="1" since=""/> <fsummary>Return the tail item of a queue.</fsummary> <desc> <p>Returns the tail item of queue <c><anno>Q</anno></c>.</p> @@ -361,7 +361,7 @@ </func> <func> - <name name="head" arity="1"/> + <name name="head" arity="1" since=""/> <fsummary>Return the item at the head of a queue.</fsummary> <desc> <p>Returns <c><anno>Item</anno></c> from the head of queue @@ -371,7 +371,7 @@ </func> <func> - <name name="init" arity="1"/> + <name name="init" arity="1" since=""/> <fsummary>Remove the tail item from a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing @@ -381,7 +381,7 @@ </func> <func> - <name name="lait" arity="1"/> + <name name="lait" arity="1" since=""/> <fsummary>Remove the tail item from a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing @@ -392,7 +392,7 @@ </func> <func> - <name name="last" arity="1"/> + <name name="last" arity="1" since=""/> <fsummary>Return the tail item of a queue.</fsummary> <desc> <p>Returns the tail item of queue <c><anno>Q</anno></c>.</p> @@ -401,7 +401,7 @@ </func> <func> - <name name="liat" arity="1"/> + <name name="liat" arity="1" since=""/> <fsummary>Remove the tail item from a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing @@ -411,7 +411,7 @@ </func> <func> - <name name="snoc" arity="2"/> + <name name="snoc" arity="2" since=""/> <fsummary>Insert an item at the tail of a queue.</fsummary> <desc> <p>Inserts <c><anno>Item</anno></c> as the tail item of queue @@ -421,7 +421,7 @@ </func> <func> - <name name="tail" arity="1"/> + <name name="tail" arity="1" since=""/> <fsummary>Remove the head item from a queue.</fsummary> <desc> <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing diff --git a/lib/stdlib/doc/src/rand.xml b/lib/stdlib/doc/src/rand.xml index eb7870e367..27d2d99f3c 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2015</year><year>2016</year> + <year>2015</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,36 +32,98 @@ <rev>A</rev> <file>rand.xml</file> </header> - <module>rand</module> + <module since="OTP 18.0">rand</module> <modulesummary>Pseudo random number generation.</modulesummary> <description> - <p>This module provides a random number generator. The module contains - a number of algorithms. The uniform distribution algorithms use the - <url href="http://xorshift.di.unimi.it">scrambled Xorshift algorithms by - Sebastiano Vigna</url>. The normal distribution algorithm uses the - <url href="http://www.jstatsoft.org/v05/i08">Ziggurat Method by Marsaglia - and Tsang</url>.</p> + <p> + This module provides a pseudo random number generator. + The module contains a number of algorithms. + The uniform distribution algorithms use the + <url href="http://xorshift.di.unimi.it"> + xoroshiro116+ and xorshift1024* algorithms by Sebastiano Vigna. + </url> + The normal distribution algorithm uses the + <url href="http://www.jstatsoft.org/v05/i08"> + Ziggurat Method by Marsaglia and Tsang + </url> + on top of the uniform distribution algorithm. + </p> + <p>For some algorithms, jump functions are provided for generating + non-overlapping sequences for parallel computations. + The jump functions perform calculations + equivalent to perform a large number of repeated calls + for calculating new states. </p> <p>The following algorithms are provided:</p> <taglist> - <tag><c>exsplus</c></tag> + <tag><c>exrop</c></tag> <item> - <p>Xorshift116+, 58 bits precision and period of 2^116-1</p> + <p>Xoroshiro116+, 58 bits precision and period of 2^116-1</p> + <p>Jump function: equivalent to 2^64 calls</p> </item> - <tag><c>exs64</c></tag> + <tag><c>exs1024s</c></tag> <item> - <p>Xorshift64*, 64 bits precision and a period of 2^64-1</p> + <p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p> + <p>Jump function: equivalent to 2^512 calls</p> </item> - <tag><c>exs1024</c></tag> + <tag><c>exsp</c></tag> <item> - <p>Xorshift1024*, 64 bits precision and a period of 2^1024-1</p> + <p>Xorshift116+, 58 bits precision and period of 2^116-1</p> + <p>Jump function: equivalent to 2^64 calls</p> + <p> + This is a corrected version of the previous default algorithm, + that now has been superseded by Xoroshiro116+ (<c>exrop</c>). + Since there is no native 58 bit rotate instruction this + algorithm executes a little (say < 15%) faster than <c>exrop</c>. + See the + <url href="http://xorshift.di.unimi.it">algorithms' homepage</url>. + </p> </item> </taglist> - <p>The default algorithm is <c>exsplus</c>. If a specific algorithm is + <p> + The default algorithm is <c>exrop</c> (Xoroshiro116+). + If a specific algorithm is required, ensure to always use <seealso marker="#seed-1"> - <c>seed/1</c></seealso> to initialize the state.</p> + <c>seed/1</c></seealso> to initialize the state. + </p> + + <p> + Undocumented (old) algorithms are deprecated but still implemented + so old code relying on them will produce + the same pseudo random sequences as before. + </p> + + <note> + <p> + There were a number of problems in the implementation + of the now undocumented algorithms, which is why + they are deprecated. The new algorithms are a bit slower + but do not have these problems: + </p> + <p> + Uniform integer ranges had a skew in the probability distribution + that was not noticable for small ranges but for large ranges + less than the generator's precision the probability to produce + a low number could be twice the probability for a high. + </p> + <p> + Uniform integer ranges larger than or equal to the generator's + precision used a floating point fallback that only calculated + with 52 bits which is smaller than the requested range + and therefore were not all numbers in the requested range + even possible to produce. + </p> + <p> + Uniform floats had a non-uniform density so small values + i.e less than 0.5 had got smaller intervals decreasing + as the generated value approached 0.0 although still uniformly + distributed for sufficiently large subranges. The new algorithms + produces uniformly distributed floats on the form N * 2.0^(-53) + hence equally spaced. + </p> + </note> <p>Every time a random number is requested, a state is used to calculate it and a new state is produced. The state can either be @@ -71,8 +133,9 @@ variable <c>rand_seed</c> to remember the current state.</p> <p>If a process calls - <seealso marker="#uniform-0"><c>uniform/0</c></seealso> or - <seealso marker="#uniform-1"><c>uniform/1</c></seealso> without + <seealso marker="#uniform-0"><c>uniform/0</c></seealso>, + <seealso marker="#uniform-1"><c>uniform/1</c></seealso> or + <seealso marker="#uniform_real-0"><c>uniform_real/0</c></seealso> without setting a seed first, <seealso marker="#seed-1"><c>seed/1</c></seealso> is called automatically with the default algorithm and creates a non-constant seed.</p> @@ -91,54 +154,126 @@ R1 = rand:uniform(),</pre> <p>Use a specified algorithm:</p> <pre> -_ = rand:seed(exs1024), +_ = rand:seed(exs1024s), R2 = rand:uniform(),</pre> <p>Use a specified algorithm with a constant seed:</p> <pre> -_ = rand:seed(exs1024, {123, 123534, 345345}), +_ = rand:seed(exs1024s, {123, 123534, 345345}), R3 = rand:uniform(),</pre> <p>Use the functional API with a non-constant seed:</p> <pre> -S0 = rand:seed_s(exsplus), +S0 = rand:seed_s(exrop), {R4, S1} = rand:uniform_s(S0),</pre> + <p>Textbook basic form Box-Muller standard normal deviate</p> + + <pre> +R5 = rand:uniform_real(), +R6 = rand:uniform(), +SND0 = math:sqrt(-2 * math:log(R5)) * math:cos(math:pi() * R6)</pre> + <p>Create a standard normal deviate:</p> <pre> -{SND0, S2} = rand:normal_s(S1),</pre> +{SND1, S2} = rand:normal_s(S1),</pre> + + <p>Create a normal deviate with mean -3 and variance 0.5:</p> + + <pre> +{ND0, S3} = rand:normal_s(-3, 0.5, S2),</pre> <note> - <p>This random number generator is not cryptographically - strong. If a strong cryptographic random number generator is - needed, use one of functions in the - <seealso marker="crypto:crypto"><c>crypto</c></seealso> - module, for example, <seealso marker="crypto:crypto"> - <c>crypto:strong_rand_bytes/1</c></seealso>.</p> + <p>The builtin random number generator algorithms are not + cryptographically strong. If a cryptographically strong + random number generator is needed, use something like + <seealso marker="crypto:crypto#rand_seed-0"><c>crypto:rand_seed/0</c></seealso>. + </p> </note> + <p> + For all these generators the lowest bit(s) has got + a slightly less random behaviour than all other bits. + 1 bit for <c>exrop</c> (and <c>exsp</c>), + and 3 bits for <c>exs1024s</c>. + See for example the explanation in the + <url href="http://xoroshiro.di.unimi.it/xoroshiro128plus.c"> + Xoroshiro128+ + </url> + generator source code: + </p> + <pre> +Beside passing BigCrush, this generator passes the PractRand test suite +up to (and included) 16TB, with the exception of binary rank tests, +which fail due to the lowest bit being an LFSR; all other bits pass all +tests. We suggest to use a sign test to extract a random Boolean value.</pre> + <p> + If this is a problem; to generate a boolean + use something like this: + </p> + <pre>(rand:uniform(16) > 8)</pre> + <p> + And for a general range, with <c>N = 1</c> for <c>exrop</c>, + and <c>N = 3</c> for <c>exs1024s</c>: + </p> + <pre>(((rand:uniform(Range bsl N) - 1) bsr N) + 1)</pre> + <p> + The floating point generating functions in this module + waste the lowest bits when converting from an integer + so they avoid this snag. + </p> + + </description> <datatypes> <datatype> + <name name="builtin_alg"/> + </datatype> + <datatype> <name name="alg"/> </datatype> <datatype> + <name name="alg_handler"/> + </datatype> + <datatype> + <name name="alg_state"/> + </datatype> + <datatype> <name name="state"/> <desc><p>Algorithm-dependent state.</p></desc> </datatype> <datatype> <name name="export_state"/> - <desc><p>Algorithm-dependent state that can be printed or saved to - file.</p></desc> + <desc> + <p> + Algorithm-dependent state that can be printed or saved to file. + </p> + </desc> + </datatype> + <datatype> + <name name="exs64_state"/> + <desc><p>Algorithm specific internal state</p></desc> + </datatype> + <datatype> + <name name="exsplus_state"/> + <desc><p>Algorithm specific internal state</p></desc> + </datatype> + <datatype> + <name name="exs1024_state"/> + <desc><p>Algorithm specific internal state</p></desc> + </datatype> + <datatype> + <name name="exrop_state"/> + <desc><p>Algorithm specific internal state</p></desc> </datatype> </datatypes> <funcs> <func> - <name name="export_seed" arity="0"/> + <name name="export_seed" arity="0" since="OTP 18.0"/> <fsummary>Export the random number generation state.</fsummary> <desc><marker id="export_seed-0"/> <p>Returns the random number state in an external format. @@ -147,7 +282,7 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="export_seed_s" arity="1"/> + <name name="export_seed_s" arity="1" since="OTP 18.0"/> <fsummary>Export the random number generation state.</fsummary> <desc><marker id="export_seed_s-1"/> <p>Returns the random number generator state in an external format. @@ -156,7 +291,34 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="normal" arity="0"/> + <name name="jump" arity="0" since="OTP 20.0"/> + <fsummary>Return the seed after performing jump calculation + to the state in the process dictionary.</fsummary> + <desc><marker id="jump-0" /> + <p>Returns the state + after performing jump calculation + to the state in the process dictionary.</p> + <p>This function generates a <c>not_implemented</c> error exception + when the jump function is not implemented for + the algorithm specified in the state + in the process dictionary.</p> + </desc> + </func> + + <func> + <name name="jump" arity="1" since="OTP 20.0"/> + <fsummary>Return the seed after performing jump calculation.</fsummary> + <desc><marker id="jump-1" /> + <p>Returns the state after performing jump calculation + to the given state. </p> + <p>This function generates a <c>not_implemented</c> error exception + when the jump function is not implemented for + the algorithm specified in the state.</p> + </desc> + </func> + + <func> + <name name="normal" arity="0" since="OTP 18.0"/> <fsummary>Return a standard normal distributed random float.</fsummary> <desc> <p>Returns a standard normal deviate float (that is, the mean @@ -166,7 +328,16 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="normal_s" arity="1"/> + <name name="normal" arity="2" since="OTP 20.0"/> + <fsummary>Return a normal distributed random float.</fsummary> + <desc> + <p>Returns a normal N(Mean, Variance) deviate float + and updates the state in the process dictionary.</p> + </desc> + </func> + + <func> + <name name="normal_s" arity="1" since="OTP 18.0"/> <fsummary>Return a standard normal distributed random float.</fsummary> <desc> <p>Returns, for a specified state, a standard normal @@ -176,12 +347,24 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="seed" arity="1"/> + <name name="normal_s" arity="3" since="OTP 20.0"/> + <fsummary>Return a normal distributed random float.</fsummary> + <desc> + <p>Returns, for a specified state, a normal N(Mean, Variance) + deviate float and a new state.</p> + </desc> + </func> + + <func> + <name name="seed" arity="1" since="OTP 18.0"/> <fsummary>Seed random number generator.</fsummary> <desc> <marker id="seed-1"/> - <p>Seeds random number generation with the specifed algorithm and - time-dependent data if <anno>AlgOrExpState</anno> is an algorithm.</p> + <p> + Seeds random number generation with the specifed algorithm and + time-dependent data if <c><anno>AlgOrStateOrExpState</anno></c> + is an algorithm. + </p> <p>Otherwise recreates the exported seed in the process dictionary, and returns the state. See also <seealso marker="#export_seed-0"><c>export_seed/0</c></seealso>.</p> @@ -189,7 +372,7 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="seed" arity="2"/> + <name name="seed" arity="2" since="OTP 18.0"/> <fsummary>Seed the random number generation.</fsummary> <desc> <p>Seeds random number generation with the specified algorithm and @@ -198,11 +381,14 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="seed_s" arity="1"/> + <name name="seed_s" arity="1" since="OTP 18.0"/> <fsummary>Seed random number generator.</fsummary> <desc> - <p>Seeds random number generation with the specifed algorithm and - time-dependent data if <anno>AlgOrExpState</anno> is an algorithm.</p> + <p> + Seeds random number generation with the specifed algorithm and + time-dependent data if <c><anno>AlgOrStateOrExpState</anno></c> + is an algorithm. + </p> <p>Otherwise recreates the exported seed and returns the state. See also <seealso marker="#export_seed-0"> <c>export_seed/0</c></seealso>.</p> @@ -210,7 +396,7 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="seed_s" arity="2"/> + <name name="seed_s" arity="2" since="OTP 18.0"/> <fsummary>Seed the random number generation.</fsummary> <desc> <p>Seeds random number generation with the specified algorithm and @@ -219,43 +405,193 @@ S0 = rand:seed_s(exsplus), </func> <func> - <name name="uniform" arity="0"/> + <name name="uniform" arity="0" since="OTP 18.0"/> <fsummary>Return a random float.</fsummary> <desc><marker id="uniform-0"/> - <p>Returns a random float uniformly distributed in the value - range <c>0.0 < <anno>X</anno> < 1.0</c> and - updates the state in the process dictionary.</p> + <p> + Returns a random float uniformly distributed in the value + range <c>0.0 =< <anno>X</anno> < 1.0</c> and + updates the state in the process dictionary. + </p> + <p> + The generated numbers are on the form N * 2.0^(-53), + that is; equally spaced in the interval. + </p> + <warning> + <p> + This function may return exactly <c>0.0</c> which can be + fatal for certain applications. If that is undesired + you can use <c>(1.0 - rand:uniform())</c> to get the + interval <c>0.0 < <anno>X</anno> =< 1.0</c>, or instead use + <seealso marker="#uniform_real-0"><c>uniform_real/0</c></seealso>. + </p> + <p> + If neither endpoint is desired you can test and re-try + like this: + </p> + <pre> +my_uniform() -> + case rand:uniform() of + 0.0 -> my_uniform(); + X -> X + end +end.</pre> + </warning> </desc> </func> <func> - <name name="uniform" arity="1"/> + <name name="uniform_real" arity="0" since="OTP 21.0"/> + <fsummary>Return a random float.</fsummary> + <desc><marker id="uniform_real-0"/> + <p> + Returns a random float + uniformly distributed in the value range + <c>DBL_MIN =< <anno>X</anno> < 1.0</c> + and updates the state in the process dictionary. + </p> + <p> + Conceptually, a random real number <c>R</c> is generated + from the interval <c>0 =< R < 1</c> and then the + closest rounded down normalized number + in the IEEE 754 Double precision format + is returned. + </p> + <note> + <p> + The generated numbers from this function has got better + granularity for small numbers than the regular + <seealso marker="#uniform-0"><c>uniform/0</c></seealso> + because all bits in the mantissa are random. + This property, in combination with the fact that exactly zero + is never returned is useful for algoritms doing for example + <c>1.0 / <anno>X</anno></c> or <c>math:log(<anno>X</anno>)</c>. + </p> + </note> + <p> + See + <seealso marker="#uniform_real_s-1"><c>uniform_real_s/1</c></seealso> + for more explanation. + </p> + </desc> + </func> + + <func> + <name name="uniform" arity="1" since="OTP 18.0"/> <fsummary>Return a random integer.</fsummary> <desc><marker id="uniform-1"/> <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>, a random integer uniformly distributed in the value range - <c>1 <= <anno>X</anno> <= <anno>N</anno></c> and + <c>1 =< <anno>X</anno> =< <anno>N</anno></c> and updates the state in the process dictionary.</p> </desc> </func> <func> - <name name="uniform_s" arity="1"/> + <name name="uniform_s" arity="1" since="OTP 18.0"/> + <fsummary>Return a random float.</fsummary> + <desc> + <p> + Returns, for a specified state, random float + uniformly distributed in the value range <c>0.0 =< + <anno>X</anno> < 1.0</c> and a new state. + </p> + <p> + The generated numbers are on the form N * 2.0^(-53), + that is; equally spaced in the interval. + </p> + <warning> + <p> + This function may return exactly <c>0.0</c> which can be + fatal for certain applications. If that is undesired + you can use <c>(1.0 - rand:uniform(State))</c> to get the + interval <c>0.0 < <anno>X</anno> =< 1.0</c>, or instead use + <seealso marker="#uniform_real_s-1"><c>uniform_real_s/1</c></seealso>. + </p> + <p> + If neither endpoint is desired you can test and re-try + like this: + </p> + <pre> +my_uniform(State) -> + case rand:uniform(State) of + {0.0, NewState} -> my_uniform(NewState); + Result -> Result + end +end.</pre> + </warning> + </desc> + </func> + + <func> + <name name="uniform_real_s" arity="1" since="OTP 21.0"/> <fsummary>Return a random float.</fsummary> <desc> - <p>Returns, for a specified state, random float - uniformly distributed in the value range <c>0.0 < - <anno>X</anno> < 1.0</c> and a new state.</p> + <p> + Returns, for a specified state, a random float + uniformly distributed in the value range + <c>DBL_MIN =< <anno>X</anno> < 1.0</c> + and updates the state in the process dictionary. + </p> + <p> + Conceptually, a random real number <c>R</c> is generated + from the interval <c>0 =< R < 1</c> and then the + closest rounded down normalized number + in the IEEE 754 Double precision format + is returned. + </p> + <note> + <p> + The generated numbers from this function has got better + granularity for small numbers than the regular + <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso> + because all bits in the mantissa are random. + This property, in combination with the fact that exactly zero + is never returned is useful for algoritms doing for example + <c>1.0 / <anno>X</anno></c> or <c>math:log(<anno>X</anno>)</c>. + </p> + </note> + <p> + The concept implicates that the probability to get + exactly zero is extremely low; so low that this function + is in fact guaranteed to never return zero. The smallest + number that it might return is <c>DBL_MIN</c>, which is + 2.0^(-1022). + </p> + <p> + The value range stated at the top of this function + description is technically correct, but + <c>0.0 =< <anno>X</anno> < 1.0</c> + is a better description of the generated numbers' + statistical distribution. Except that exactly 0.0 + is never returned, which is not possible to observe + statistically. + </p> + <p> + For example; for all sub ranges + <c>N*2.0^(-53) =< X < (N+1)*2.0^(-53)</c> + where + <c>0 =< integer(N) < 2.0^53</c> + the probability is the same. + Compare that with the form of the numbers generated by + <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso>. + </p> + <p> + Having to generate extra random bits for + small numbers costs a little performance. + This function is about 20% slower than the regular + <seealso marker="#uniform_s-1"><c>uniform_s/1</c></seealso> + </p> </desc> </func> <func> - <name name="uniform_s" arity="2"/> + <name name="uniform_s" arity="2" since="OTP 18.0"/> <fsummary>Return a random integer.</fsummary> <desc> <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c> and a state, a random integer uniformly distributed in the value - range <c>1 <= <anno>X</anno> <= <anno>N</anno></c> and a + range <c>1 =< <anno>X</anno> =< <anno>N</anno></c> and a new state.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/random.xml b/lib/stdlib/doc/src/random.xml index 8d090d20b3..f0261ed009 100644 --- a/lib/stdlib/doc/src/random.xml +++ b/lib/stdlib/doc/src/random.xml @@ -32,7 +32,7 @@ <rev>A</rev> <file>random.xml</file> </header> - <module>random</module> + <module since="">random</module> <modulesummary>Pseudo-random number generation.</modulesummary> <description> <p>This module provides a random number generator. The method is attributed @@ -73,7 +73,7 @@ <funcs> <func> - <name name="seed" arity="0"/> + <name name="seed" arity="0" since=""/> <fsummary>Seed random number generation with default values.</fsummary> <desc> <p>Seeds random number generation with default (fixed) values @@ -82,7 +82,7 @@ </func> <func> - <name name="seed" arity="1"/> + <name name="seed" arity="1" since=""/> <fsummary>Seed random number generator.</fsummary> <desc> <p><c>seed({<anno>A1</anno>, <anno>A2</anno>, <anno>A3</anno>})</c> @@ -92,7 +92,7 @@ </func> <func> - <name name="seed" arity="3"/> + <name name="seed" arity="3" since=""/> <fsummary>Seed random number generator.</fsummary> <desc> <p>Seeds random number generation with integer values in the process @@ -116,7 +116,7 @@ random:seed(erlang:phash2([node()]), </func> <func> - <name name="seed0" arity="0"/> + <name name="seed0" arity="0" since=""/> <fsummary>Return default state for random number generation.</fsummary> <desc> <p>Returns the default state.</p> @@ -124,7 +124,7 @@ random:seed(erlang:phash2([node()]), </func> <func> - <name name="uniform" arity="0"/> + <name name="uniform" arity="0" since=""/> <fsummary>Return a random float.</fsummary> <desc> <p>Returns a random float uniformly distributed between <c>0.0</c> @@ -133,7 +133,7 @@ random:seed(erlang:phash2([node()]), </func> <func> - <name name="uniform" arity="1"/> + <name name="uniform" arity="1" since=""/> <fsummary>Return a random integer.</fsummary> <desc> <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c>, @@ -144,7 +144,7 @@ random:seed(erlang:phash2([node()]), </func> <func> - <name name="uniform_s" arity="1"/> + <name name="uniform_s" arity="1" since=""/> <fsummary>Return a random float.</fsummary> <desc> <p>Returns, for a specified state, a random float uniformly @@ -153,7 +153,7 @@ random:seed(erlang:phash2([node()]), </func> <func> - <name name="uniform_s" arity="2"/> + <name name="uniform_s" arity="2" since=""/> <fsummary>Return a random integer.</fsummary> <desc> <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c> and a diff --git a/lib/stdlib/doc/src/re.xml b/lib/stdlib/doc/src/re.xml index 7f4f0aa18c..b04434492d 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>2016</year> + <year>2017</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -34,7 +34,7 @@ <rev>A</rev> <file>re.xml</file> </header> - <module>re</module> + <module since="">re</module> <modulesummary>Perl-like regular expressions for Erlang.</modulesummary> <description> <p>This module contains regular expression matching functions for @@ -45,9 +45,10 @@ <p>The matching algorithms of the library are based on the PCRE library, but not all of the PCRE library is interfaced and - some parts of the library go beyond what PCRE offers. The sections of - the PCRE documentation that are relevant to this module are included - here.</p> + some parts of the library go beyond what PCRE offers. Currently + PCRE version 8.40 (release date 2017-01-11) is used. The sections + of the PCRE documentation that are relevant to this module are + included here.</p> <note> <p>The Erlang literal syntax for strings uses the "\" @@ -78,7 +79,15 @@ <funcs> <func> - <name name="compile" arity="1"/> + <name name="version" arity="0" since="OTP 20.0"/> + <fsummary>Gives the PCRE version of the system in a string format</fsummary> + <desc> + <p>The return of this function is a string with the PCRE version of the system that was used in the Erlang/OTP compilation.</p> + </desc> + </func> + + <func> + <name name="compile" arity="1" since=""/> <fsummary>Compile a regular expression into a match program</fsummary> <desc> <p>The same as <c>compile(<anno>Regexp</anno>,[])</c></p> @@ -86,7 +95,7 @@ </func> <func> - <name name="compile" arity="2"/> + <name name="compile" arity="2" since=""/> <fsummary>Compile a regular expression into a match program.</fsummary> <desc> <p>Compiles a regular expression, with the syntax @@ -149,13 +158,25 @@ </item> <tag><c>extended</c></tag> <item> - <p>Whitespace data characters in the pattern are ignored except - when escaped or inside a character class. Whitespace does not - include character 'vt' (ASCII 11). Characters between an - unescaped <c>#</c> outside a character class and the next newline, - inclusive, are also ignored. This is equivalent to Perl option - <c>/x</c> and can be changed within a pattern by a <c>(?x)</c> - option setting.</p> + <p>If this option is set, most white space characters in the + pattern are totally ignored except when escaped or inside a + character class. However, white space is not allowed within + sequences such as <c>(?></c> that introduce various + parenthesized subpatterns, nor within a numerical quantifier + such as <c>{1,3}</c>. However, ignorable white space is permitted + between an item and a following quantifier and between a + quantifier and a following + that indicates possessiveness. + </p> + <p>White space did not used to include the VT character (code + 11), because Perl did not treat this character as white space. + However, Perl changed at release 5.18, so PCRE followed at + release 8.34, and VT is now treated as white space. + </p> + <p>This also causes characters between an unescaped # + outside a character class and the next newline, inclusive, to + be ignored. This is equivalent to Perl's <c>/x</c> option, and it + can be changed within a pattern by a <c>(?x)</c> option setting. + </p> <p>With this option, comments inside complicated patterns can be included. However, notice that this applies only to data characters. Whitespace characters can never appear within special @@ -283,7 +304,7 @@ </func> <func> - <name name="inspect" arity="2"/> + <name name="inspect" arity="2" since="OTP 17.0"/> <fsummary>Inspects a compiled regular expression.</fsummary> <desc> <p>Takes a compiled regular expression and an item, and returns the @@ -327,7 +348,7 @@ </func> <func> - <name name="replace" arity="3"/> + <name name="replace" arity="3" since=""/> <fsummary>Match a subject against regular expression and replace matching elements with Replacement.</fsummary> <desc> @@ -337,7 +358,7 @@ </func> <func> - <name name="replace" arity="4"/> + <name name="replace" arity="4" since=""/> <fsummary>Match a subject against regular expression and replace matching elements with Replacement.</fsummary> <desc> @@ -387,7 +408,7 @@ re:replace("abcd","c","[\\&]",[{return,list}]).</code> </func> <func> - <name name="run" arity="2"/> + <name name="run" arity="2" since=""/> <fsummary>Match a subject against regular expression and capture subpatterns.</fsummary> <desc> @@ -396,7 +417,7 @@ re:replace("abcd","c","[\\&]",[{return,list}]).</code> </func> <func> - <name name="run" arity="3"/> + <name name="run" arity="3" since=""/> <fsummary>Match a subject against regular expression and capture subpatterns.</fsummary> <type_desc variable="CompileOpt">See <seealso marker="#compile_options"> @@ -971,7 +992,7 @@ re:run("cacb","c(a|b)",[global,{capture,[1],list}]).</code> </func> <func> - <name name="split" arity="2"/> + <name name="split" arity="2" since=""/> <fsummary>Split a string by tokens specified as a regular expression. </fsummary> <desc> @@ -980,7 +1001,7 @@ re:run("cacb","c(a|b)",[global,{capture,[1],list}]).</code> </func> <func> - <name name="split" arity="3"/> + <name name="split" arity="3" since=""/> <fsummary>Split a string by tokens specified as a regular expression</fsummary> <type_desc variable="CompileOpt">See <seealso marker="#compile_options"> <c>compile/2</c></seealso>.</type_desc> @@ -1321,6 +1342,8 @@ re:split("Erlang","[lg]",[{return,list},{parts,4}]).</code> VM. Notice that the recursion limit does not affect the stack depth of the VM, as PCRE for Erlang is compiled in such a way that the match function never does recursion on the C stack.</p> + <p>Note that <c>LIMIT_MATCH</c> and <c>LIMIT_RECURSION</c> can only reduce + the value of the limits set by the caller, not increase them.</p> </section> <section> @@ -1444,12 +1467,17 @@ Pattern PCRE matches Perl matches <tag>\n</tag><item>Line feed (hex 0A)</item> <tag>\r</tag><item>Carriage return (hex 0D)</item> <tag>\t</tag><item>Tab (hex 09)</item> + <tag>\0dd</tag><item>Character with octal code 0dd</item> <tag>\ddd</tag><item>Character with octal code ddd, or back reference </item> + <tag>\o{ddd..}</tag><item>character with octal code ddd..</item> <tag>\xhh</tag><item>Character with hex code hh</item> <tag>\x{hhh..}</tag><item>Character with hex code hhh..</item> </taglist> + <note><p>Note that \0dd is always an octal code, and that \8 and \9 are + the literal characters "8" and "9".</p></note> + <p>The precise effect of \cx on ASCII characters is as follows: if x is a lowercase letter, it is converted to upper case. Then bit 6 of the character (hex 40) is inverted. Thus \cA to \cZ become hex 01 to hex 1A @@ -1461,50 +1489,38 @@ Pattern PCRE matches Perl matches <p>The \c facility was designed for use with ASCII characters, but with the extension to Unicode it is even less useful than it once was.</p> - <p>By default, after \x, from zero to two hexadecimal digits are read - (letters can be in upper or lower case). Any number of hexadecimal digits - can appear between \x{ and }, but the character code is constrained as - follows:</p> - - <taglist> - <tag>8-bit non-Unicode mode</tag> - <item>< 0x100</item> - <tag>8-bit UTF-8 mode</tag> - <item>< 0x10ffff and a valid code point</item> - </taglist> - - <p>Invalid Unicode code points are the range 0xd800 to 0xdfff (the so-called - "surrogate" code points), and 0xffef.</p> - - <p>If characters other than hexadecimal digits appear between \x{ and }, - or if there is no terminating }, this form of escape is not recognized. - Instead, the initial \x is interpreted as a basic hexadecimal escape, - with no following digits, giving a character whose value is zero.</p> - - <p>Characters whose value is < 256 can be defined by either of the two - syntaxes for \x. There is no difference in the way they are handled. For - example, \xdc is the same as \x{dc}.</p> - <p>After \0 up to two further octal digits are read. If there are fewer than - two digits, only those that are present are used. Thus the sequence - \0\x\07 specifies two binary zeros followed by a BEL character (code value - 7). Ensure to supply two digits after the initial zero if the pattern - character that follows is itself an octal digit.</p> + two digits, just those that are present are used. Thus the sequence + \0\x\015 specifies two binary zeros followed by a CR character (code value + 13). Make sure you supply two digits after the initial zero if the pattern + character that follows is itself an octal digit.</p> + + <p>The escape \o must be followed by a sequence of octal digits, enclosed + in braces. An error occurs if this is not the case. This escape is a recent + addition to Perl; it provides way of specifying character code points as + octal numbers greater than 0777, and it also allows octal numbers and back + references to be unambiguously specified.</p> + + <p>For greater clarity and unambiguity, it is best to avoid following \ by + a digit greater than zero. Instead, use \o{} or \x{} to specify character + numbers, and \g{} to specify back references. The following paragraphs + describe the old, ambiguous syntax.</p> <p>The handling of a backslash followed by a digit other than 0 is - complicated. Outside a character class, PCRE reads it and any following - digits as a decimal number. If the number is < 10, or if there have + complicated, and Perl has changed in recent releases, causing PCRE also + to change. Outside a character class, PCRE reads the digit and any following + digits as a decimal number. If the number is < 8, or if there have been at least that many previous capturing left parentheses in the expression, the entire sequence is taken as a <em>back reference</em>. A description of how this works is provided later, following the discussion of parenthesized subpatterns.</p> - <p>Inside a character class, or if the decimal number is > 9 and there - have not been that many capturing subpatterns, PCRE re-reads up to three - octal digits following the backslash, and uses them to generate a data - character. Any subsequent digits stand for themselves. The value of the - character is constrained in the same way as characters specified in - hexadecimal. For example:</p> + <p>Inside a character class, or if the decimal number following \ is > + 7 and there have not been that many capturing subpatterns, PCRE handles + \8 and \9 as the literal characters "8" and "9", and otherwise re-reads + up to three octal digits following the backslash, and using them to + generate a data character. Any subsequent digits stand for themselves. + For example:</p> <taglist> <tag>\040</tag> @@ -1526,12 +1542,38 @@ Pattern PCRE matches Perl matches <tag>\377</tag> <item>Can be a back reference, otherwise value 255 (decimal)</item> <tag>\81</tag> - <item>Either a back reference, or a binary zero followed by the two - characters "8" and "1"</item> + <item>Either a back reference, or the two characters "8" and "1"</item> </taglist> - <p>Notice that octal values >= 100 must not be introduced by a leading - zero, as no more than three octal digits are ever read.</p> + <p>Notice that octal values >= 100 that are specified using this syntax + must not be introduced by a leading zero, as no more than three octal digits + are ever read.</p> + + <p>By default, after \x that is not followed by {, from zero to two + hexadecimal digits are read (letters can be in upper or lower case). Any + number of hexadecimal digits may appear between \x{ and }. If a character + other than a hexadecimal digit appears between \x{ and }, or if there is no + terminating }, an error occurs. + </p> + + <p>Characters whose value is less than 256 can be defined by either of the + two syntaxes for \x. There is no difference in the way they are handled. For + example, \xdc is exactly the same as \x{dc}.</p> + + <p><em>Constraints on character values</em></p> + + <p>Characters that are specified using octal or hexadecimal numbers are + limited to certain values, as follows:</p> + <taglist> + <tag>8-bit non-UTF mode</tag> + <item><p>< 0x100</p></item> + <tag>8-bit UTF-8 mode</tag> + <item><p>< 0x10ffff and a valid codepoint</p></item> + </taglist> + <p>Invalid Unicode codepoints are the range 0xd800 to 0xdfff (the + so-called "surrogate" codepoints), and 0xffef.</p> + + <p><em>Escape sequences in character classes</em></p> <p>All the sequences that define a single character value can be used both inside and outside character classes. Also, inside a character class, \b @@ -1597,11 +1639,14 @@ Pattern PCRE matches Perl matches appropriate type. If the current matching point is at the end of the subject string, all fail, as there is no character to match.</p> - <p>For compatibility with Perl, \s does not match the VT character - (code 11). This makes it different from the Posix "space" class. The \s - characters are HT (9), LF (10), FF (12), CR (13), and space (32). If "use - locale;" is included in a Perl script, \s can match the VT character. In - PCRE, it never does.</p> + <p>For compatibility with Perl, \s did not used to match the VT character (code + 11), which made it different from the the POSIX "space" class. However, Perl + added VT at release 5.18, and PCRE followed suit at release 8.34. The default + \s characters are now HT (9), LF (10), VT (11), FF (12), CR (13), and space + (32), which are defined as white space in the "C" locale. This list may vary if + locale-specific matching is taking place. For example, in some locales the + "non-breaking space" character (\xA0) is recognized as white space, and in + others the VT character is not.</p> <p>A "word" character is an underscore or any character that is a letter or a digit. By default, the definition of letters and digits is controlled by @@ -1619,9 +1664,9 @@ Pattern PCRE matches Perl matches <taglist> <tag>\d</tag><item>Any character that \p{Nd} matches (decimal digit) </item> - <tag>\s</tag><item>Any character that \p{Z} matches, plus HT, LF, FF, CR + <tag>\s</tag><item>Any character that \p{Z} or \h or \v </item> - <tag>\w</tag><item>Any character that \p{L} or \p{N} matches, plus + <tag>\w</tag><item>Any character that matches \p{L} or \p{N} matches, plus underscore</item> </taglist> @@ -1769,6 +1814,7 @@ Pattern PCRE matches Perl matches <item>Avestan</item> <item>Balinese</item> <item>Bamum</item> + <item>Bassa_Vah</item> <item>Batak</item> <item>Bengali</item> <item>Bopomofo</item> @@ -1777,6 +1823,7 @@ Pattern PCRE matches Perl matches <item>Buhid</item> <item>Canadian_Aboriginal</item> <item>Carian</item> + <item>Caucasian_Albanian</item> <item>Chakma</item> <item>Cham</item> <item>Cherokee</item> @@ -1787,11 +1834,14 @@ Pattern PCRE matches Perl matches <item>Cyrillic</item> <item>Deseret</item> <item>Devanagari</item> + <item>Duployan</item> <item>Egyptian_Hieroglyphs</item> + <item>Elbasan</item> <item>Ethiopic</item> <item>Georgian</item> <item>Glagolitic</item> <item>Gothic</item> + <item>Grantha</item> <item>Greek</item> <item>Gujarati</item> <item>Gurmukhi</item> @@ -1811,40 +1861,56 @@ Pattern PCRE matches Perl matches <item>Kayah_Li</item> <item>Kharoshthi</item> <item>Khmer</item> + <item>Khojki</item> + <item>Khudawadi</item> <item>Lao</item> <item>Latin</item> <item>Lepcha</item> <item>Limbu</item> + <item>Linear_A</item> <item>Linear_B</item> <item>Lisu</item> <item>Lycian</item> <item>Lydian</item> + <item>Mahajani</item> <item>Malayalam</item> <item>Mandaic</item> + <item>Manichaean</item> <item>Meetei_Mayek</item> + <item>Mende_Kikakui</item> <item>Meroitic_Cursive</item> <item>Meroitic_Hieroglyphs</item> <item>Miao</item> + <item>Modi</item> <item>Mongolian</item> + <item>Mro</item> <item>Myanmar</item> + <item>Nabataean</item> <item>New_Tai_Lue</item> <item>Nko</item> <item>Ogham</item> + <item>Ol_Chiki</item> <item>Old_Italic</item> + <item>Old_North_Arabian</item> + <item>Old_Permic</item> <item>Old_Persian</item> <item>Oriya</item> <item>Old_South_Arabian</item> <item>Old_Turkic</item> - <item>Ol_Chiki</item> <item>Osmanya</item> + <item>Pahawh_Hmong</item> + <item>Palmyrene</item> + <item>Pau_Cin_Hau</item> <item>Phags_Pa</item> <item>Phoenician</item> + <item>Psalter_Pahlavi</item> <item>Rejang</item> <item>Runic</item> <item>Samaritan</item> <item>Saurashtra</item> <item>Sharada</item> <item>Shavian</item> + <item>Siddham</item> <item>Sinhala</item> <item>Sora_Sompeng</item> <item>Sundanese</item> @@ -1862,8 +1928,10 @@ Pattern PCRE matches Perl matches <item>Thai</item> <item>Tibetan</item> <item>Tifinagh</item> + <item>Tirhuta</item> <item>Ugaritic</item> <item>Vai</item> + <item>Warang_Citi</item> <item>Yi</item> </list> @@ -2001,10 +2069,10 @@ Pattern PCRE matches Perl matches <p>In addition to the standard Unicode properties described earlier, PCRE supports four more that make it possible to convert traditional escape - sequences, such as \w and \s, and Posix character classes to use Unicode + sequences, such as \w and \s to use Unicode properties. PCRE uses these non-standard, non-Perl properties internally - when <c>PCRE_UCP</c> is set. However, they can also be used explicitly. - The properties are as follows:</p> + when the <c>ucp</c> option is passed. However, they can also be used + explicitly. The properties are as follows:</p> <taglist> <tag>Xan</tag> @@ -2030,6 +2098,16 @@ Pattern PCRE matches Perl matches </item> </taglist> + <p>Perl and POSIX space are now the same. Perl added VT to its space + character set at release 5.18 and PCRE changed at release 8.34.</p> + + <p>Xan matches characters that have either the L (letter) or the N (number) + property. Xps matches the characters tab, linefeed, vertical tab, form feed, + or carriage return, and any other character that has the Z (separator) + property. Xsp is the same as Xps; it used to exclude vertical tab, for Perl + compatibility, but Perl changed, and so PCRE followed at release 8.34. Xwd + matches the same characters as Xan, plus underscore. + </p> <p>There is another non-standard property, Xuc, which matches any character that can be represented by a Universal Character Name in C++ and other programming languages. These are the characters $, @, ` (grave accent), @@ -2062,7 +2140,9 @@ foo\Kbar</code> <p>Perl documents that the use of \K within assertions is "not well defined". In PCRE, \K is acted upon when it occurs inside positive - assertions, but is ignored in negative assertions.</p> + assertions, but is ignored in negative assertions. Note that when a + pattern such as (?=ab\K) matches, the reported start of the match can + be greater than the end of the match.</p> <p><em>Simple Assertions</em></p> @@ -2301,7 +2381,8 @@ foo\Kbar</code> m, inclusive. If a minus character is required in a class, it must be escaped with a backslash or appear in a position where it cannot be interpreted as indicating a range, typically as the first or last - character in the class.</p> + character in the class, or immediately after a range. For example, [b-d-z] + matches letters in the range b to d, a hyphen character, or z.</p> <p>The literal character "]" cannot be the end character of a range. A pattern such as [W-]46] is interpreted as a class of two characters ("W" @@ -2311,6 +2392,11 @@ foo\Kbar</code> followed by two other characters. The octal or hexadecimal representation of "]" can also be used to end a range.</p> + <p>An error is generated if a POSIX character class (see below) or an + escape sequence other than one that defines a single character appears at + a point where a range ending character is expected. For example, [z-\xff] + is valid, but [A-\d] and [A-[:digit:]] are not.</p> + <p>Ranges operate in the collating sequence of character values. They can also be used for characters specified numerically, for example, [\000-\037]. Ranges can include any characters that are valid for the @@ -2353,7 +2439,8 @@ foo\Kbar</code> range)</item> <item>Circumflex (only at the start)</item> <item>Opening square bracket (only when it can be interpreted as - introducing a Posix class name; see the next section)</item> + introducing a Posix class name, or for a special compatibility + feature; see the next two sections)</item> <item>Terminating closing square bracket</item> </list> @@ -2385,16 +2472,18 @@ foo\Kbar</code> <tag>print</tag><item>Printing characters, including space</item> <tag>punct</tag><item>Printing characters, excluding letters, digits, and space</item> - <tag>space</tag><item>Whitespace (not quite the same as \s)</item> + <tag>space</tag><item>Whitespace (the same as \s from PCRE 8.34)</item> <tag>upper</tag><item>Uppercase letters</item> <tag>word</tag><item>"Word" characters (same as \w)</item> <tag>xdigit</tag><item>Hexadecimal digits</item> </taglist> - <p>The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), - and space (32). Notice that this list includes the VT character (code 11). - This makes "space" different to \s, which does not include VT (for Perl - compatibility).</p> + <p>The default "space" characters are HT (9), LF (10), VT (11), FF (12), + CR (13), and space (32). If locale-specific matching is taking place, the + list of space characters may be different; there may be fewer or more of + them. "Space" used to be different to \s, which did not include VT, for + Perl compatibility. However, Perl changed at release 5.18, and PCRE followed + at release 8.34. "Space" and \s now match the same set of characters.</p> <p>The name "word" is a Perl extension, and "blank" is a GNU extension from Perl 5.8. Another Perl extension is negation, which is indicated by a ^ @@ -2408,11 +2497,11 @@ foo\Kbar</code> "ch" is a "collating element", but these are not supported, and an error is given if they are encountered.</p> - <p>By default, in UTF modes, characters with values > 255 do not match + <p>By default, characters with values > 255 do not match any of the Posix character classes. However, if option <c>PCRE_UCP</c> is passed to <c>pcre_compile()</c>, some of the classes are changed so that - Unicode character properties are used. This is achieved by replacing the - Posix classes by other sequences, as follows:</p> + Unicode character properties are used. This is achieved by replacing + certain Posix classes by other sequences, as follows:</p> <taglist> <tag>[:alnum:]</tag><item>Becomes <em>\p{Xan}</em></item> @@ -2425,9 +2514,49 @@ foo\Kbar</code> <tag>[:word:]</tag><item>Becomes <em>\p{Xwd}</em></item> </taglist> - <p>Negated versions, such as [:^alpha:], use \P instead of \p. The other - Posix classes are unchanged, and match only characters with code points - < 256.</p> + <p>Negated versions, such as [:^alpha:], use \P instead of \p. Three other + POSIX classes are handled specially in UCP mode:</p> + <taglist> + <tag>[:graph:]</tag> + <item><p>This matches characters that have glyphs that mark the page + when printed. In Unicode property terms, it matches all characters with + the L, M, N, P, S, or Cf properties, except for:</p> + <taglist> + <tag>U+061C</tag><item><p>Arabic Letter Mark</p></item> + <tag>U+180E</tag><item><p>Mongolian Vowel Separator</p></item> + <tag>U+2066 - U+2069</tag><item><p>Various "isolate"s</p></item> + </taglist> + </item> + <tag>[:print:]</tag> + <item><p>This matches the same characters as [:graph:] plus space + characters that are not controls, that is, characters with the Zs + property.</p></item> + <tag>[:punct:]</tag><item><p>This matches all characters that have + the Unicode P (punctuation) property, plus those characters whose code + points are less than 128 that have the S (Symbol) property.</p></item> + </taglist> + <p>The other POSIX classes are unchanged, and match only characters with + code points less than 128. + </p> + + <p><em>Compatibility Feature for Word Boundaries</em></p> + + <p>In the POSIX.2 compliant library that was included in 4.4BSD Unix, + the ugly syntax [[:<:]] and [[:>:]] is used for matching "start + of word" and "end of word". PCRE treats these items as follows:</p> + <taglist> + <tag>[[:<:]]</tag><item><p>is converted to \b(?=\w)</p></item> + <tag>[[:>:]]</tag><item><p>is converted to \b(?<=\w)</p></item> + </taglist> + <p>Only these exact character sequences are recognized. A sequence such as + [a[:<:]b] provokes error for an unrecognized POSIX class name. This + support is not compatible with Perl. It is provided to help migrations from + other environments, and is best not used in any new patterns. Note that \b + matches at the start and the end of a word (see "Simple assertions" above), + and in a Perl-style pattern the preceding or following character normally + shows which is wanted, without the need for the assertions that are used + above in order to give exactly the POSIX behaviour.</p> + </section> <section> @@ -2476,8 +2605,7 @@ gilbert|sullivan</code> <p>When one of these option changes occurs at top-level (that is, not inside subpattern parentheses), the change applies to the remainder of the - pattern that follows. If the change is placed right at the start of a - pattern, PCRE extracts it into the global options.</p> + pattern that follows.</p> <p>An option change within a subpattern (see section <seealso marker="#sect11">Subpatterns</seealso>) affects only that part of the subpattern that follows it. So, the following matches abc and aBc and @@ -2645,9 +2773,9 @@ the ((?:red|white) (king|queen))</code> parentheses from other parts of the pattern, such as back references, recursion, and conditions, can be made by name and by number.</p> - <p>Names consist of up to 32 alphanumeric characters and underscores. Named - capturing parentheses are still allocated numbers as well as names, - exactly as if the names were not present. + <p>Names consist of up to 32 alphanumeric characters and underscores, but + must start with a non-digit. Named capturing parentheses are still allocated + numbers as well as names, exactly as if the names were not present. The <c>capture</c> specification to <seealso marker="#run/3"> <c>run/3</c></seealso> can use named values if they are present in the regular expression.</p> @@ -3118,7 +3246,14 @@ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</code> purposes of numbering the capturing subpatterns in the whole pattern. However, substring capturing is done only for positive assertions. (Perl sometimes, but not always, performs capturing in negative assertions.)</p> - + <warning> + <p>If a positive assertion containing one or more capturing subpatterns + succeeds, but failure to match later in the pattern causes backtracking over + this assertion, the captures within the assertion are reset only if no higher + numbered captures are already set. This is, unfortunately, a fundamental + limitation of the current implementation, and as PCRE1 is now in + maintenance-only status, it is unlikely ever to change.</p> + </warning> <p>For compatibility with Perl, assertion subpatterns can be repeated. However, it makes no sense to assert the same thing many times, the side effect of capturing parentheses can occasionally be useful. In practice, @@ -3371,12 +3506,7 @@ abcd$</code> <p>Perl uses the syntax (?(<name>)...) or (?('name')...) to test for a used subpattern by name. For compatibility with earlier versions of PCRE, which had this facility before Perl, the syntax (?(name)...) is also - recognized. However, there is a possible ambiguity with this syntax, as - subpattern names can consist entirely of digits. PCRE looks first for a - named subpattern; if it cannot find one and the name consists entirely of - digits, PCRE looks for a subpattern of that number, which must be > 0. - Using subpattern names that consist entirely of digits is not - recommended.</p> + recognized.</p> <p>Rewriting the previous example to use a named subpattern gives:</p> @@ -3958,11 +4088,13 @@ a+(*COMMIT)b</code> 2> re:run("xyzabc","(*COMMIT)abc",[{capture,all,list},no_start_optimize]). nomatch</code> - <p>PCRE knows that any match must start with "a", so the optimization skips - along the subject to "a" before running the first match attempt, which - succeeds. When the optimization is disabled by option - <c>no_start_optimize</c>, the match starts at "x" and so the (*COMMIT) - causes it to fail without trying any other starting points.</p> + <p>For this pattern, PCRE knows that any match must start with "a", so the + optimization skips along the subject to "a" before applying the pattern to the + first set of data. The match attempt then succeeds. In the second call the + <c>no_start_optimize</c> disables the optimization that skips along to the + first character. The pattern is now applied starting at "x", and so the + (*COMMIT) causes the match to fail without trying any other starting + points.</p> <p>The following verb causes the match to fail at the current starting position in the subject if there is a later matching failure that causes @@ -4138,7 +4270,7 @@ A (B(*THEN)C | (*FAIL)) | D</code> ...(*COMMIT)(*PRUNE)...</code> <p>If there is a matching failure to the right, backtracking onto (*PRUNE) - cases it to be triggered, and its action is taken. There can never be a + causes it to be triggered, and its action is taken. There can never be a backtrack onto (*COMMIT).</p> <p><em>Backtracking Verbs in Repeated Groups</em></p> diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml index 878a3babc5..8d61833d1f 100644 --- a/lib/stdlib/doc/src/ref_man.xml +++ b/lib/stdlib/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -66,7 +66,6 @@ <xi:include href="gen_statem.xml"/> <xi:include href="io.xml"/> <xi:include href="io_lib.xml"/> - <xi:include href="lib.xml"/> <xi:include href="lists.xml"/> <xi:include href="log_mf_h.xml"/> <xi:include href="maps.xml"/> @@ -93,6 +92,7 @@ <xi:include href="sys.xml"/> <xi:include href="timer.xml"/> <xi:include href="unicode.xml"/> + <xi:include href="uri_string.xml"/> <xi:include href="win32reg.xml"/> <xi:include href="zip.xml"/> </application> diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 44dc104645..07ce41b7a7 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2016</year> + <year>2000</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>sets.xml</file> </header> - <module>sets</module> + <module since="">sets</module> <modulesummary>Functions for set manipulation.</modulesummary> <description> <p>Sets are collections of elements with no duplicate elements. @@ -40,7 +40,7 @@ <p>This module provides the same interface as the <seealso marker="ordsets"><c>ordsets(3)</c></seealso> module - but with a defined representation. One difference is + but with an undefined representation. One difference is that while this module considers two elements as different if they do not match (<c>=:=</c>), <c>ordsets</c> considers two elements as different if and only if they do not compare equal (<c>==</c>).</p> @@ -59,7 +59,7 @@ <funcs> <func> - <name name="add_element" arity="2"/> + <name name="add_element" arity="2" since=""/> <fsummary>Add an element to a <c>Set</c>.</fsummary> <desc> <p>Returns a new set formed from <c><anno>Set1</anno></c> with @@ -68,7 +68,7 @@ </func> <func> - <name name="del_element" arity="2"/> + <name name="del_element" arity="2" since=""/> <fsummary>Remove an element from a <c>Set</c>.</fsummary> <desc> <p>Returns <c><anno>Set1</anno></c>, but with @@ -77,7 +77,7 @@ </func> <func> - <name name="filter" arity="2"/> + <name name="filter" arity="2" since=""/> <fsummary>Filter set elements.</fsummary> <desc> <p>Filters elements in <c><anno>Set1</anno></c> with boolean function @@ -86,7 +86,7 @@ </func> <func> - <name name="fold" arity="3"/> + <name name="fold" arity="3" since=""/> <fsummary>Fold over set elements.</fsummary> <desc> <p>Folds <c><anno>Function</anno></c> over every element in @@ -96,7 +96,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since=""/> <fsummary>Convert a list into a <c>Set</c>.</fsummary> <desc> <p>Returns a set of the elements in <c><anno>List</anno></c>.</p> @@ -104,7 +104,7 @@ </func> <func> - <name name="intersection" arity="1"/> + <name name="intersection" arity="1" since=""/> <fsummary>Return the intersection of a list of <c>Sets</c>.</fsummary> <desc> <p>Returns the intersection of the non-empty list of sets.</p> @@ -112,7 +112,7 @@ </func> <func> - <name name="intersection" arity="2"/> + <name name="intersection" arity="2" since=""/> <fsummary>Return the intersection of two <c>Sets</c>.</fsummary> <desc> <p>Returns the intersection of <c><anno>Set1</anno></c> and @@ -121,7 +121,7 @@ </func> <func> - <name name="is_disjoint" arity="2"/> + <name name="is_disjoint" arity="2" since=""/> <fsummary>Check whether two <c>Sets</c> are disjoint.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> and @@ -131,7 +131,7 @@ </func> <func> - <name name="is_element" arity="2"/> + <name name="is_element" arity="2" since=""/> <fsummary>Test for membership of a <c>Set</c>.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Element</anno></c> is an element of @@ -140,7 +140,16 @@ </func> <func> - <name name="is_set" arity="1"/> + <name name="is_empty" arity="1" since="OTP 21.0"/> + <fsummary>Test for empty set.</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Set</anno></c> is an empty set, + otherwise <c>false</c>.</p> + </desc> + </func> + + <func> + <name name="is_set" arity="1" since=""/> <fsummary>Test for a <c>Set</c>.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set</anno></c> is a set of @@ -149,7 +158,7 @@ </func> <func> - <name name="is_subset" arity="2"/> + <name name="is_subset" arity="2" since=""/> <fsummary>Test for subset.</fsummary> <desc> <p>Returns <c>true</c> when every element of <c><anno>Set1</anno></c> is @@ -158,7 +167,7 @@ </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since=""/> <fsummary>Return an empty set.</fsummary> <desc> <p>Returns a new empty set.</p> @@ -166,7 +175,7 @@ </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since=""/> <fsummary>Return the number of elements in a set.</fsummary> <desc> <p>Returns the number of elements in <c><anno>Set</anno></c>.</p> @@ -174,7 +183,7 @@ </func> <func> - <name name="subtract" arity="2"/> + <name name="subtract" arity="2" since=""/> <fsummary>Return the difference of two <c>Sets</c>.</fsummary> <desc> <p>Returns only the elements of <c><anno>Set1</anno></c> that are not @@ -183,7 +192,7 @@ </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since=""/> <fsummary>Convert a <c>Set</c>into a list.</fsummary> <desc> <p>Returns the elements of <c><anno>Set</anno></c> as a list. @@ -192,7 +201,7 @@ </func> <func> - <name name="union" arity="1"/> + <name name="union" arity="1" since=""/> <fsummary>Return the union of a list of <c>Sets</c>.</fsummary> <desc> <p>Returns the merged (union) set of the list of sets.</p> @@ -200,7 +209,7 @@ </func> <func> - <name name="union" arity="2"/> + <name name="union" arity="2" since=""/> <fsummary>Return the union of two <c>Sets</c>.</fsummary> <desc> <p>Returns the merged (union) set of <c><anno>Set1</anno></c> and diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml index d6e8036d4e..50a0968531 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>A</rev> <file>shell.xml</file> </header> - <module>shell</module> + <module since="">shell</module> <modulesummary>The Erlang shell.</modulesummary> <description> <p>This module provides an Erlang shell.</p> @@ -165,12 +165,12 @@ <item> <p>Evaluates <c>shell_default:help()</c>.</p> </item> - <tag><c>c(File)</c></tag> + <tag><c>c(Mod)</c></tag> <item> - <p>Evaluates <c>shell_default:c(File)</c>. This compiles - and loads code in <c>File</c> and purges old versions of - code, if necessary. Assumes that the file and module names - are the same.</p> + <p>Evaluates <c>shell_default:c(Mod)</c>. This compiles and + loads the module <c>Mod</c> and purges old versions of the + code, if necessary. <c>Mod</c> can be either a module name or a + a source file path, with or without <c>.erl</c> extension.</p> </item> <tag><c>catch_exception(Bool)</c></tag> <item> @@ -569,7 +569,7 @@ Hello Number: 3378 <pre> 42> <input>E = ets:new(t, []).</input> -17</pre> +#Ref<0.1662103692.2407923716.214192></pre> <p>Command 42 creates an ETS table.</p> @@ -602,7 +602,7 @@ false</pre> <pre> 47> <input>E = ets:new(t, []).</input> -18 +#Ref<0.1662103692.2407923716.214197> 48> <input>ets:insert({d,1,2}).</input> * exception error: undefined function ets:insert/1</pre> @@ -617,10 +617,23 @@ true</pre> <p>Command 49 successfully inserts the tuple into the ETS table.</p> <pre> -50> <input>halt().</input> +50> <input>ets:insert(#Ref<0.1662103692.2407923716.214197>, {e,3,4}).</input> +true</pre> + + <p>Command 50 inserts another tuple into the ETS table. This time + the first argument is the table identifier itself. The shell can + parse commands with pids (<c><0.60.0></c>), ports + (<c>#Port<0.536></c>), references + (<c>#Ref<0.1662103692.2407792644.214210></c>), and external + functions (<c>#Fun<a.b.1></c>), but the command fails unless + the corresponding pid, port, reference, or function can be created + in the running system.</p> + + <pre> +51> <input>halt().</input> strider 2></pre> - <p>Command 50 exits the Erlang runtime system.</p> + <p>Command 51 exits the Erlang runtime system.</p> </section> <section> @@ -854,14 +867,14 @@ q - quit erlang <c>{history, N}</c>, where <c>N</c> is the current command number. The function is to return a list of characters or an atom. This constraint is because of the Erlang I/O protocol. Unicode characters - beyond code point 255 are allowed in the list. Notice + beyond code point 255 are allowed in the list and the atom. Notice that in restricted mode the call <c>Mod:Func(L)</c> must be allowed or the default shell prompt function is called.</p> </section> <funcs> <func> - <name>catch_exception(Bool) -> boolean()</name> + <name since="">catch_exception(Bool) -> boolean()</name> <fsummary>Set the exception handling of the shell.</fsummary> <type> <v>Bool = boolean()</v> @@ -879,7 +892,7 @@ q - quit erlang </func> <func> - <name name="history" arity="1"/> + <name name="history" arity="1" since=""/> <fsummary>Set the number of previous commands to keep.</fsummary> <desc> <p>Sets the number of previous commands to keep in the @@ -889,7 +902,7 @@ q - quit erlang </func> <func> - <name name="prompt_func" arity="1"/> + <name name="prompt_func" arity="1" since="OTP R13B04"/> <fsummary>Set the shell prompt.</fsummary> <desc> <p>Sets the shell prompt function to <c><anno>PromptFunc</anno></c>. @@ -898,7 +911,7 @@ q - quit erlang </func> <func> - <name name="results" arity="1"/> + <name name="results" arity="1" since=""/> <fsummary>Set the number of previous results to keep.</fsummary> <desc> <p>Sets the number of results from previous commands to keep in @@ -908,7 +921,7 @@ q - quit erlang </func> <func> - <name name="start_restricted" arity="1"/> + <name name="start_restricted" arity="1" since=""/> <fsummary>Exit a normal shell and starts a restricted shell.</fsummary> <desc> <p>Exits a normal shell and starts a restricted shell. @@ -923,7 +936,7 @@ q - quit erlang </func> <func> - <name name="stop_restricted" arity="0"/> + <name name="stop_restricted" arity="0" since=""/> <fsummary>Exit a restricted shell and starts a normal shell.</fsummary> <desc> <p>Exits a restricted shell and starts a normal shell. The function @@ -932,7 +945,7 @@ q - quit erlang </func> <func> - <name name="strings" arity="1"/> + <name name="strings" arity="1" since="OTP R16B"/> <fsummary>Set the shell's string recognition flag.</fsummary> <desc> <p>Sets pretty printing of lists to <c><anno>Strings</anno></c>. diff --git a/lib/stdlib/doc/src/slave.xml b/lib/stdlib/doc/src/slave.xml index e53ec8231b..80fb28b548 100644 --- a/lib/stdlib/doc/src/slave.xml +++ b/lib/stdlib/doc/src/slave.xml @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>slave</module> + <module since="">slave</module> <modulesummary>Functions for starting and controlling slave nodes. </modulesummary> <description> @@ -68,7 +68,7 @@ <funcs> <func> - <name>pseudo([Master | ServerList]) -> ok</name> + <name since="">pseudo([Master | ServerList]) -> ok</name> <fsummary>Start a number of pseudo servers.</fsummary> <type> <v>Master = node()</v> @@ -84,7 +84,7 @@ </func> <func> - <name name="pseudo" arity="2"/> + <name name="pseudo" arity="2" since=""/> <fsummary>Start a number of pseudo servers.</fsummary> <desc> <p>Starts a number of pseudo servers. A pseudo server is a @@ -102,7 +102,7 @@ rpc:call(N, slave, pseudo, [node(), [pxw_server]]).</code> </func> <func> - <name name="relay" arity="1"/> + <name name="relay" arity="1" since=""/> <fsummary>Run a pseudo server.</fsummary> <desc> <p>Runs a pseudo server. This function never returns any value @@ -113,9 +113,9 @@ rpc:call(N, slave, pseudo, [node(), [pxw_server]]).</code> </func> <func> - <name name="start" arity="1"/> - <name name="start" arity="2"/> - <name name="start" arity="3"/> + <name name="start" arity="1" since=""/> + <name name="start" arity="2" since=""/> + <name name="start" arity="3" since=""/> <fsummary>Start a slave node on a host.</fsummary> <desc> <p>Starts a slave node on host <c><anno>Host</anno></c>. Host names @@ -178,9 +178,9 @@ slave:start(H, Name, Arg).</code> </func> <func> - <name name="start_link" arity="1"/> - <name name="start_link" arity="2"/> - <name name="start_link" arity="3"/> + <name name="start_link" arity="1" since=""/> + <name name="start_link" arity="2" since=""/> + <name name="start_link" arity="3" since=""/> <fsummary>Start and link to a slave node on a host.</fsummary> <desc> <p>Starts a slave node in the same way as <c>start/1,2,3</c>, @@ -193,7 +193,7 @@ slave:start(H, Name, Arg).</code> </func> <func> - <name name="stop" arity="1"/> + <name name="stop" arity="1" since=""/> <fsummary>Stop (kill) a node.</fsummary> <desc> <p>Stops (kills) a node.</p> diff --git a/lib/stdlib/doc/src/sofs.xml b/lib/stdlib/doc/src/sofs.xml index 4cf1984d46..a0759d2f52 100644 --- a/lib/stdlib/doc/src/sofs.xml +++ b/lib/stdlib/doc/src/sofs.xml @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>sofs.xml</file> </header> - <module>sofs</module> + <module since="">sofs</module> <modulesummary>Functions for manipulating sets of sets.</modulesummary> <description> <p>This module provides operations on finite sets and @@ -456,8 +456,8 @@ fun(S) -> sofs:partition(1, S) end <funcs> <func> - <name name="a_function" arity="1"/> - <name name="a_function" arity="2"/> + <name name="a_function" arity="1" since=""/> + <name name="a_function" arity="2" since=""/> <fsummary>Create a function.</fsummary> <desc> <p>Creates a <seealso marker="#function">function</seealso>. @@ -470,7 +470,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="canonical_relation" arity="1"/> + <name name="canonical_relation" arity="1" since=""/> <fsummary>Return the canonical map.</fsummary> <desc> <p>Returns the binary relation containing the elements @@ -490,7 +490,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="composite" arity="2"/> + <name name="composite" arity="2" since=""/> <fsummary>Return the composite of two functions.</fsummary> <desc> <p>Returns the <seealso marker="#composite">composite</seealso> of @@ -506,7 +506,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="constant_function" arity="2"/> + <name name="constant_function" arity="2" since=""/> <fsummary>Create the function that maps each element of a set onto another set.</fsummary> <desc> @@ -522,7 +522,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="converse" arity="1"/> + <name name="converse" arity="1" since=""/> <fsummary>Return the converse of a binary relation.</fsummary> <desc> <p>Returns the <seealso marker="#converse">converse</seealso> @@ -536,7 +536,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="difference" arity="2"/> + <name name="difference" arity="2" since=""/> <fsummary>Return the difference of two sets.</fsummary> <desc> <p>Returns the <seealso marker="#difference">difference</seealso> of @@ -545,8 +545,8 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="digraph_to_family" arity="1"/> - <name name="digraph_to_family" arity="2"/> + <name name="digraph_to_family" arity="1" since=""/> + <name name="digraph_to_family" arity="2" since=""/> <fsummary>Create a family from a directed graph.</fsummary> <desc> <p>Creates a <seealso marker="#family">family</seealso> from @@ -565,7 +565,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="domain" arity="1"/> + <name name="domain" arity="1" since=""/> <fsummary>Return the domain of a binary relation.</fsummary> <desc> <p>Returns the <seealso marker="#domain">domain</seealso> of @@ -579,7 +579,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="drestriction" arity="2"/> + <name name="drestriction" arity="2" since=""/> <fsummary>Return a restriction of a binary relation.</fsummary> <desc> <p>Returns the difference between the binary relation @@ -598,7 +598,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="drestriction" arity="3"/> + <name name="drestriction" arity="3" since=""/> <fsummary>Return a restriction of a relation.</fsummary> <desc> <p>Returns a subset of <c><anno>Set1</anno></c> containing those @@ -618,7 +618,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="empty_set" arity="0"/> + <name name="empty_set" arity="0" since=""/> <fsummary>Return the untyped empty set.</fsummary> <desc> <p>Returns the <seealso marker="#sets_definition">untyped empty @@ -628,7 +628,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="extension" arity="3"/> + <name name="extension" arity="3" since=""/> <fsummary>Extend the domain of a binary relation.</fsummary> <desc> <p>Returns the <seealso marker="#extension">extension</seealso> of @@ -648,8 +648,8 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family" arity="1"/> - <name name="family" arity="2"/> + <name name="family" arity="1" since=""/> + <name name="family" arity="2" since=""/> <fsummary>Create a family of subsets.</fsummary> <desc> <p>Creates a <seealso marker="#family">family of subsets</seealso>. @@ -662,7 +662,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_difference" arity="2"/> + <name name="family_difference" arity="2" since=""/> <fsummary>Return the difference of two families.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> and <c><anno>Family2</anno></c> @@ -683,7 +683,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_domain" arity="1"/> + <name name="family_domain" arity="1" since=""/> <fsummary>Return a family of domains.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is @@ -704,7 +704,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_field" arity="1"/> + <name name="family_field" arity="1" since=""/> <fsummary>Return a family of fields.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is @@ -728,7 +728,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_intersection" arity="1"/> + <name name="family_intersection" arity="1" since=""/> <fsummary>Return the intersection of a family of sets of sets.</fsummary> <desc> @@ -752,7 +752,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_intersection" arity="2"/> + <name name="family_intersection" arity="2" since=""/> <fsummary>Return the intersection of two families.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> and <c><anno>Family2</anno></c> @@ -772,7 +772,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_projection" arity="2"/> + <name name="family_projection" arity="2" since=""/> <fsummary>Return a family of modified subsets.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is @@ -791,7 +791,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_range" arity="1"/> + <name name="family_range" arity="1" since=""/> <fsummary>Return a family of ranges.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is @@ -812,7 +812,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_specification" arity="2"/> + <name name="family_specification" arity="2" since=""/> <fsummary>Select a subset of a family using a predicate.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is @@ -837,8 +837,8 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_to_digraph" arity="1"/> - <name name="family_to_digraph" arity="2"/> + <name name="family_to_digraph" arity="1" since=""/> + <name name="family_to_digraph" arity="2" since=""/> <fsummary>Create a directed graph from a family.</fsummary> <desc> <p>Creates a directed graph from @@ -863,7 +863,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_to_relation" arity="1"/> + <name name="family_to_relation" arity="1" since=""/> <fsummary>Create a binary relation from a family.</fsummary> <desc> <p>If <c><anno>Family</anno></c> is @@ -881,7 +881,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_union" arity="1"/> + <name name="family_union" arity="1" since=""/> <fsummary>Return the union of a family of sets of sets.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> is @@ -904,7 +904,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="family_union" arity="2"/> + <name name="family_union" arity="2" since=""/> <fsummary>Return the union of two families.</fsummary> <desc> <p>If <c><anno>Family1</anno></c> and <c><anno>Family2</anno></c> @@ -926,7 +926,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="field" arity="1"/> + <name name="field" arity="1" since=""/> <fsummary>Return the field of a binary relation.</fsummary> <desc> <p>Returns the <seealso marker="#field">field</seealso> of the @@ -942,7 +942,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="from_external" arity="2"/> + <name name="from_external" arity="2" since=""/> <fsummary>Create a set.</fsummary> <desc> <p>Creates a set from the <seealso marker="#external_set">external @@ -955,7 +955,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="from_sets" arity="1" clause_i="1"/> + <name name="from_sets" arity="1" clause_i="1" since=""/> <fsummary>Create a set out of a list of sets.</fsummary> <desc> <p>Returns the <seealso marker="#sets_definition">unordered @@ -971,7 +971,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="from_sets" arity="1" clause_i="2"/> + <name name="from_sets" arity="1" clause_i="2" since=""/> <fsummary>Create an ordered set out of a tuple of sets.</fsummary> <desc> <p>Returns the <seealso marker="#sets_definition">ordered @@ -981,8 +981,8 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="from_term" arity="1"/> - <name name="from_term" arity="2"/> + <name name="from_term" arity="1" since=""/> + <name name="from_term" arity="2" since=""/> <fsummary>Create a set.</fsummary> <desc> <p><marker id="from_term"></marker>Creates an element @@ -1031,7 +1031,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="image" arity="2"/> + <name name="image" arity="2" since=""/> <fsummary>Return the image of a set under a binary relation.</fsummary> <desc> <p>Returns the <seealso marker="#image">image</seealso> of @@ -1047,7 +1047,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="intersection" arity="1"/> + <name name="intersection" arity="1" since=""/> <fsummary>Return the intersection of a set of sets.</fsummary> <desc> <p>Returns @@ -1059,7 +1059,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="intersection" arity="2"/> + <name name="intersection" arity="2" since=""/> <fsummary>Return the intersection of two sets.</fsummary> <desc> <p>Returns @@ -1069,7 +1069,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="intersection_of_family" arity="1"/> + <name name="intersection_of_family" arity="1" since=""/> <fsummary>Return the intersection of a family.</fsummary> <desc> <p>Returns the intersection of @@ -1086,7 +1086,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="inverse" arity="1"/> + <name name="inverse" arity="1" since=""/> <fsummary>Return the inverse of a function.</fsummary> <desc> <p>Returns the <seealso marker="#inverse">inverse</seealso> @@ -1100,7 +1100,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="inverse_image" arity="2"/> + <name name="inverse_image" arity="2" since=""/> <fsummary>Return the inverse image of a set under a binary relation.</fsummary> <desc> @@ -1117,7 +1117,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="is_a_function" arity="1"/> + <name name="is_a_function" arity="1" since=""/> <fsummary>Test for a function.</fsummary> <desc> <p>Returns <c>true</c> if the binary relation <c><anno>BinRel</anno></c> @@ -1127,7 +1127,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="is_disjoint" arity="2"/> + <name name="is_disjoint" arity="2" since=""/> <fsummary>Test for disjoint sets.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> @@ -1138,7 +1138,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="is_empty_set" arity="1"/> + <name name="is_empty_set" arity="1" since=""/> <fsummary>Test for an empty set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>AnySet</anno></c> is an empty @@ -1147,7 +1147,7 @@ fun(S) -> sofs:partition(1, S) end </func> <func> - <name name="is_equal" arity="2"/> + <name name="is_equal" arity="2" since=""/> <fsummary>Test two sets for equality.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>AnySet1</anno></c> @@ -1164,7 +1164,7 @@ true</pre> </func> <func> - <name name="is_set" arity="1"/> + <name name="is_set" arity="1" since=""/> <fsummary>Test for an unordered set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>AnySet</anno></c> is @@ -1175,7 +1175,7 @@ true</pre> </func> <func> - <name name="is_sofs_set" arity="1"/> + <name name="is_sofs_set" arity="1" since=""/> <fsummary>Test for an unordered set.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Term</anno></c> is @@ -1185,7 +1185,7 @@ true</pre> </func> <func> - <name name="is_subset" arity="2"/> + <name name="is_subset" arity="2" since=""/> <fsummary>Test two sets for subset.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> is @@ -1195,7 +1195,7 @@ true</pre> </func> <func> - <name name="is_type" arity="1"/> + <name name="is_type" arity="1" since=""/> <fsummary>Test for a type.</fsummary> <desc> <p>Returns <c>true</c> if term <c><anno>Term</anno></c> is @@ -1204,7 +1204,7 @@ true</pre> </func> <func> - <name name="join" arity="4"/> + <name name="join" arity="4" since=""/> <fsummary>Return the join of two relations.</fsummary> <desc> <p>Returns the <seealso marker="#natural_join">natural @@ -1221,7 +1221,7 @@ true</pre> </func> <func> - <name name="multiple_relative_product" arity="2"/> + <name name="multiple_relative_product" arity="2" since=""/> <fsummary>Return the multiple relative product of a tuple of binary relations and a relation.</fsummary> <desc> @@ -1242,7 +1242,7 @@ true</pre> </func> <func> - <name name="no_elements" arity="1"/> + <name name="no_elements" arity="1" since=""/> <fsummary>Return the number of elements of a set.</fsummary> <desc> <p>Returns the number of elements of the ordered or unordered @@ -1251,7 +1251,7 @@ true</pre> </func> <func> - <name name="partition" arity="1"/> + <name name="partition" arity="1" since=""/> <fsummary>Return the coarsest partition given a set of sets.</fsummary> <desc> <p>Returns the <seealso marker="#partition">partition</seealso> of @@ -1268,7 +1268,7 @@ true</pre> </func> <func> - <name name="partition" arity="2"/> + <name name="partition" arity="2" since=""/> <fsummary>Return a partition of a set.</fsummary> <desc> <p>Returns the <seealso marker="#partition">partition</seealso> of @@ -1284,7 +1284,7 @@ true</pre> </func> <func> - <name name="partition" arity="3"/> + <name name="partition" arity="3" since=""/> <fsummary>Return a partition of a set.</fsummary> <desc> <p>Returns a pair of sets that, regarded as constituting a @@ -1307,7 +1307,7 @@ true</pre> </func> <func> - <name name="partition_family" arity="2"/> + <name name="partition_family" arity="2" since=""/> <fsummary>Return a family indexing a partition.</fsummary> <desc> <p>Returns <seealso marker="#family">family</seealso> @@ -1328,7 +1328,7 @@ true</pre> </func> <func> - <name name="product" arity="1"/> + <name name="product" arity="1" since=""/> <fsummary>Return the Cartesian product of a tuple of sets.</fsummary> <desc> <p>Returns the <seealso marker="#Cartesian_product_tuple">Cartesian @@ -1347,7 +1347,7 @@ true</pre> </func> <func> - <name name="product" arity="2"/> + <name name="product" arity="2" since=""/> <fsummary>Return the Cartesian product of two sets.</fsummary> <desc> <p>Returns the <seealso marker="#Cartesian_product">Cartesian @@ -1365,7 +1365,7 @@ true</pre> </func> <func> - <name name="projection" arity="2"/> + <name name="projection" arity="2" since=""/> <fsummary>Return a set of substituted elements.</fsummary> <desc> <p>Returns the set created by substituting each element of @@ -1384,7 +1384,7 @@ true</pre> </func> <func> - <name name="range" arity="1"/> + <name name="range" arity="1" since=""/> <fsummary>Return the range of a binary relation.</fsummary> <desc> <p>Returns the <seealso marker="#range">range</seealso> of the @@ -1398,8 +1398,8 @@ true</pre> </func> <func> - <name name="relation" arity="1"/> - <name name="relation" arity="2"/> + <name name="relation" arity="1" since=""/> + <name name="relation" arity="2" since=""/> <fsummary>Create a relation.</fsummary> <desc> <p>Creates a <seealso marker="#relation">relation</seealso>. @@ -1417,7 +1417,7 @@ true</pre> </func> <func> - <name name="relation_to_family" arity="1"/> + <name name="relation_to_family" arity="1" since=""/> <fsummary>Create a family from a binary relation.</fsummary> <desc> <p>Returns <seealso marker="#family">family</seealso> @@ -1435,8 +1435,8 @@ true</pre> </func> <func> - <name name="relative_product" arity="1"/> - <name name="relative_product" arity="2" clause_i="1"/> + <name name="relative_product" arity="1" since=""/> + <name name="relative_product" arity="2" clause_i="1" since=""/> <fsummary>Return the relative product of a list of binary relations and a binary relation.</fsummary> <desc> @@ -1466,7 +1466,7 @@ true</pre> </func> <func> - <name name="relative_product" arity="2" clause_i="2"/> + <name name="relative_product" arity="2" clause_i="2" since=""/> <fsummary>Return the relative product of two binary relations.</fsummary> <desc> @@ -1477,7 +1477,7 @@ true</pre> </func> <func> - <name name="relative_product1" arity="2"/> + <name name="relative_product1" arity="2" since=""/> <fsummary>Return the relative_product of two binary relations.</fsummary> <desc> @@ -1498,7 +1498,7 @@ true</pre> </func> <func> - <name name="restriction" arity="2"/> + <name name="restriction" arity="2" since=""/> <fsummary>Return a restriction of a binary relation.</fsummary> <desc> <p>Returns the <seealso marker="#restriction">restriction</seealso> of @@ -1514,7 +1514,7 @@ true</pre> </func> <func> - <name name="restriction" arity="3"/> + <name name="restriction" arity="3" since=""/> <fsummary>Return a restriction of a set.</fsummary> <desc> <p>Returns a subset of <c><anno>Set1</anno></c> containing those @@ -1530,8 +1530,8 @@ true</pre> </func> <func> - <name name="set" arity="1"/> - <name name="set" arity="2"/> + <name name="set" arity="1" since=""/> + <name name="set" arity="2" since=""/> <fsummary>Create a set of atoms or any type of sets.</fsummary> <desc> <p>Creates an <seealso marker="#sets_definition">unordered @@ -1543,7 +1543,7 @@ true</pre> </func> <func> - <name name="specification" arity="2"/> + <name name="specification" arity="2" since=""/> <fsummary>Select a subset using a predicate.</fsummary> <desc> <p>Returns the set containing every element @@ -1564,7 +1564,7 @@ true</pre> </func> <func> - <name name="strict_relation" arity="1"/> + <name name="strict_relation" arity="1" since=""/> <fsummary>Return the strict relation corresponding to a given relation.</fsummary> <desc> @@ -1580,7 +1580,7 @@ true</pre> </func> <func> - <name name="substitution" arity="2"/> + <name name="substitution" arity="2" since=""/> <fsummary>Return a function with a given set as domain.</fsummary> <desc> <p>Returns a function, the domain of which @@ -1629,7 +1629,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="symdiff" arity="2"/> + <name name="symdiff" arity="2" since=""/> <fsummary>Return the symmetric difference of two sets.</fsummary> <desc> <p>Returns the <seealso marker="#symmetric_difference">symmetric @@ -1645,7 +1645,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="symmetric_partition" arity="2"/> + <name name="symmetric_partition" arity="2" since=""/> <fsummary>Return a partition of two sets.</fsummary> <desc> <p>Returns a triple of sets:</p> @@ -1666,7 +1666,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="to_external" arity="1"/> + <name name="to_external" arity="1" since=""/> <fsummary>Return the elements of a set.</fsummary> <desc> <p>Returns the <seealso marker="#external_set">external @@ -1675,7 +1675,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="to_sets" arity="1"/> + <name name="to_sets" arity="1" since=""/> <fsummary>Return a list or a tuple of the elements of a set.</fsummary> <desc> <p>Returns the elements of the ordered set <c><anno>ASet</anno></c> @@ -1686,7 +1686,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="type" arity="1"/> + <name name="type" arity="1" since=""/> <fsummary>Return the type of a set.</fsummary> <desc> <p>Returns the <seealso marker="#type">type</seealso> of an @@ -1695,7 +1695,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="union" arity="1"/> + <name name="union" arity="1" since=""/> <fsummary>Return the union of a set of sets.</fsummary> <desc> <p>Returns the <seealso marker="#union_n">union</seealso> of the @@ -1704,7 +1704,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="union" arity="2"/> + <name name="union" arity="2" since=""/> <fsummary>Return the union of two sets.</fsummary> <desc> <p>Returns the <seealso marker="#union">union</seealso> of @@ -1713,7 +1713,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="union_of_family" arity="1"/> + <name name="union_of_family" arity="1" since=""/> <fsummary>Return the union of a family.</fsummary> <desc> <p>Returns the union of <seealso marker="#family">family</seealso> @@ -1727,7 +1727,7 @@ images2(SetOfSets, BinRel) -> </func> <func> - <name name="weak_relation" arity="1"/> + <name name="weak_relation" arity="1" since=""/> <fsummary>Return the weak relation corresponding to a given relation.</fsummary> <desc> diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml index 45b207b13d..fd2d625685 100644 --- a/lib/stdlib/doc/src/specs.xml +++ b/lib/stdlib/doc/src/specs.xml @@ -33,7 +33,6 @@ <xi:include href="../specs/specs_gen_statem.xml"/> <xi:include href="../specs/specs_io.xml"/> <xi:include href="../specs/specs_io_lib.xml"/> - <xi:include href="../specs/specs_lib.xml"/> <xi:include href="../specs/specs_lists.xml"/> <xi:include href="../specs/specs_log_mf_h.xml"/> <xi:include href="../specs/specs_maps.xml"/> @@ -60,6 +59,7 @@ <xi:include href="../specs/specs_sys.xml"/> <xi:include href="../specs/specs_timer.xml"/> <xi:include href="../specs/specs_unicode.xml"/> + <xi:include href="../specs/specs_uri_string.xml"/> <xi:include href="../specs/specs_win32reg.xml"/> <xi:include href="../specs/specs_zip.xml"/> </specs> diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml index dddedf1132..d102191a57 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>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,72 +32,707 @@ <rev>A</rev> <file>string.xml</file> </header> - <module>string</module> + <module since="">string</module> <modulesummary>String processing functions.</modulesummary> <description> <p>This module provides functions for string processing.</p> + <p>A string in this module is represented by <seealso marker="unicode#type-chardata"> + <c>unicode:chardata()</c></seealso>, that is, a list of codepoints, + binaries with UTF-8-encoded codepoints + (<em>UTF-8 binaries</em>), or a mix of the two.</p> + <code> +"abcd" is a valid string +<<"abcd">> is a valid string +["abcd"] is a valid string +<<"abc..åäö"/utf8>> is a valid string +<<"abc..åäö">> is NOT a valid string, + but a binary with Latin-1-encoded codepoints +[<<"abc">>, "..åäö"] is a valid string +[atom] is NOT a valid string</code> + <p> + This module operates on grapheme clusters. A <em>grapheme cluster</em> + is a user-perceived character, which can be represented by several + codepoints. + </p> + <code> +"å" [229] or [97, 778] +"e̊" [101, 778]</code> + <p> + The string length of "ß↑e̊" is 3, even though it is represented by the + codepoints <c>[223,8593,101,778]</c> or the UTF-8 binary + <c><<195,159,226,134,145,101,204,138>></c>. + </p> + <p> + Grapheme clusters for codepoints of class <c>prepend</c> + and non-modern (or decomposed) Hangul is not handled for performance + reasons in + <seealso marker="#find/3"><c>find/3</c></seealso>, + <seealso marker="#replace/3"><c>replace/3</c></seealso>, + <seealso marker="#split/2"><c>split/2</c></seealso>, + <seealso marker="#lexemes/2"><c>split/2</c></seealso> and + <seealso marker="#trim/3"><c>trim/3</c></seealso>. + </p> + <p> + Splitting and appending strings is to be done on grapheme clusters + borders. + There is no verification that the results of appending strings are + valid or normalized. + </p> + <p> + Most of the functions expect all input to be normalized to one form, + see for example <seealso marker="unicode#characters_to_nfc_list/1"> + <c>unicode:characters_to_nfc_list/1</c></seealso>. + </p> + <p> + Language or locale specific handling of input is not considered + in any function. + </p> + <p> + The functions can crash for non-valid input strings. For example, + the functions expect UTF-8 binaries but not all functions + verify that all binaries are encoded correctly. + </p> + <p> + Unless otherwise specified the return value type is the same as + the input type. That is, binary input returns binary output, + list input returns a list output, and mixed input can return a + mixed output.</p> + <code> +1> string:trim(" sarah "). +"sarah" +2> string:trim(<<" sarah ">>). +<<"sarah">> +3> string:lexemes("foo bar", " "). +["foo","bar"] +4> string:lexemes(<<"foo bar">>, " "). +[<<"foo">>,<<"bar">>]</code> + <p>This module has been reworked in Erlang/OTP 20 to + handle <seealso marker="unicode#type-chardata"> + <c>unicode:chardata()</c></seealso> and operate on grapheme + clusters. The <seealso marker="#oldapi"> <c>old + functions</c></seealso> that only work on Latin-1 lists as input + are still available but should not be used, they will be + deprecated in a future release. + </p> </description> + <datatypes> + <datatype> + <name name="direction"/> + <name name="grapheme_cluster"/> + <desc> + <p>A user-perceived character, consisting of one or more + codepoints.</p> + </desc> + </datatype> + </datatypes> + + <funcs> + + <func> + <name name="casefold" arity="1" since="OTP 20.0"/> + <fsummary>Convert a string to a comparable string.</fsummary> + <desc> + <p> + Converts <c><anno>String</anno></c> to a case-agnostic + comparable string. Function <c>casefold/1</c> is preferred + over <c>lowercase/1</c> when two strings are to be compared + for equality. See also <seealso marker="#equal/4"><c>equal/4</c></seealso>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:casefold("Ω and ẞ SHARP S").</input> +"ω and ss sharp s"</pre> + </desc> + </func> + + <func> + <name name="chomp" arity="1" since="OTP 20.0"/> + <fsummary>Remove trailing end of line control characters.</fsummary> + <desc> + <p> + Returns a string where any trailing <c>\n</c> or + <c>\r\n</c> have been removed from <c><anno>String</anno></c>. + </p> + <p><em>Example:</em></p> + <pre> +182> <input>string:chomp(<<"\nHello\n\n">>).</input> +<<"\nHello">> +183> <input>string:chomp("\nHello\r\r\n").</input> +"\nHello\r"</pre> + </desc> + </func> + + <func> + <name name="equal" arity="2" since=""/> + <name name="equal" arity="3" since="OTP 20.0"/> + <name name="equal" arity="4" since="OTP 20.0"/> + <fsummary>Test string equality.</fsummary> + <desc> + <p> + Returns <c>true</c> if <c><anno>A</anno></c> and + <c><anno>B</anno></c> are equal, otherwise <c>false</c>. + </p> + <p> + If <c><anno>IgnoreCase</anno></c> is <c>true</c> + the function does <seealso marker="#casefold/1"> + <c>casefold</c>ing</seealso> on the fly before the equality test. + </p> + <p>If <c><anno>Norm</anno></c> is not <c>none</c> + the function applies normalization on the fly before the equality test. + There are four available normalization forms: + <seealso marker="unicode#characters_to_nfc_list/1"> <c>nfc</c></seealso>, + <seealso marker="unicode#characters_to_nfd_list/1"> <c>nfd</c></seealso>, + <seealso marker="unicode#characters_to_nfkc_list/1"> <c>nfkc</c></seealso>, and + <seealso marker="unicode#characters_to_nfkd_list/1"> <c>nfkd</c></seealso>. + </p> + <p>By default, + <c><anno>IgnoreCase</anno></c> is <c>false</c> and + <c><anno>Norm</anno></c> is <c>none</c>.</p> + <p><em>Example:</em></p> + <pre> +1> <input>string:equal("åäö", <<"åäö"/utf8>>).</input> +true +2> <input>string:equal("åäö", unicode:characters_to_nfd_binary("åäö")).</input> +false +3> <input>string:equal("åäö", unicode:characters_to_nfd_binary("ÅÄÖ"), true, nfc).</input> +true</pre> + </desc> + </func> + + <func> + <name name="find" arity="2" since="OTP 20.0"/> + <name name="find" arity="3" since="OTP 20.0"/> + <fsummary>Find start of substring.</fsummary> + <desc> + <p> + Removes anything before <c><anno>SearchPattern</anno></c> in <c><anno>String</anno></c> + and returns the remainder of the string or <c>nomatch</c> if <c><anno>SearchPattern</anno></c> is not + found. + <c><anno>Dir</anno></c>, which can be <c>leading</c> or + <c>trailing</c>, indicates from which direction characters + are to be searched. + </p> + <p> + By default, <c><anno>Dir</anno></c> is <c>leading</c>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:find("ab..cd..ef", ".").</input> +"..cd..ef" +2> <input>string:find(<<"ab..cd..ef">>, "..", trailing).</input> +<<"..ef">> +3> <input>string:find(<<"ab..cd..ef">>, "x", leading).</input> +nomatch +4> <input>string:find("ab..cd..ef", "x", trailing).</input> +nomatch</pre> + </desc> + </func> + + <func> + <name name="is_empty" arity="1" since="OTP 20.0"/> + <fsummary>Check if the string is empty.</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>String</anno></c> is the + empty string, otherwise <c>false</c>.</p> + <p><em>Example:</em></p> + <pre> +1> <input>string:is_empty("foo").</input> +false +2> <input>string:is_empty(["",<<>>]).</input> +true</pre> + </desc> + </func> + + <func> + <name name="length" arity="1" since="OTP 20.0"/> + <fsummary>Calculate length of the string.</fsummary> + <desc> + <p> + Returns the number of grapheme clusters in <c><anno>String</anno></c>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:length("ß↑e̊").</input> +3 +2> <input>string:length(<<195,159,226,134,145,101,204,138>>).</input> +3</pre> + </desc> + </func> + + <func> + <name name="lexemes" arity="2" since="OTP 20.0"/> + <fsummary>Split string into lexemes.</fsummary> + <desc> + <p> + Returns a list of lexemes in <c><anno>String</anno></c>, separated + by the grapheme clusters in <c><anno>SeparatorList</anno></c>. + </p> + <p> + Notice that, as shown in this example, two or more + adjacent separator graphemes clusters in <c><anno>String</anno></c> + are treated as one. That is, there are no empty + strings in the resulting list of lexemes. + See also <seealso marker="#split/3"><c>split/3</c></seealso> which returns + empty strings. + </p> + <p>Notice that <c>[$\r,$\n]</c> is one grapheme cluster.</p> + <p><em>Example:</em></p> + <pre> +1> <input>string:lexemes("abc de̊fxxghix jkl\r\nfoo", "x e" ++ [[$\r,$\n]]).</input> +["abc","de̊f","ghi","jkl","foo"] +2> <input>string:lexemes(<<"abc de̊fxxghix jkl\r\nfoo"/utf8>>, "x e" ++ [$\r,$\n]).</input> +[<<"abc">>,<<"de̊f"/utf8>>,<<"ghi">>,<<"jkl\r\nfoo">>]</pre> + </desc> + </func> + + <func> + <name name="lowercase" arity="1" since="OTP 20.0"/> + <fsummary>Convert a string to lowercase</fsummary> + <desc> + <p> + Converts <c><anno>String</anno></c> to lowercase. + </p> + <p> + Notice that function <seealso marker="#casefold/1"><c>casefold/1</c></seealso> + should be used when converting a string to + be tested for equality. + </p> + <p><em>Example:</em></p> + <pre> +2> <input>string:lowercase(string:uppercase("Michał")).</input> +"michał"</pre> + </desc> + </func> + + <func> + <name name="next_codepoint" arity="1" since="OTP 20.0"/> + <fsummary>Pick the first codepoint.</fsummary> + <desc> + <p> + Returns the first codepoint in <c><anno>String</anno></c> + and the rest of <c><anno>String</anno></c> in the tail. Returns + an empty list if <c><anno>String</anno></c> is empty or an + <c>{error, String}</c> tuple if the next byte is invalid. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:next_codepoint(unicode:characters_to_binary("e̊fg")).</input> +[101|<<"̊fg"/utf8>>]</pre> + </desc> + </func> + + <func> + <name name="next_grapheme" arity="1" since="OTP 20.0"/> + <fsummary>Pick the first grapheme cluster.</fsummary> + <desc> + <p> + Returns the first grapheme cluster in <c><anno>String</anno></c> + and the rest of <c><anno>String</anno></c> in the tail. Returns + an empty list if <c><anno>String</anno></c> is empty or an + <c>{error, String}</c> tuple if the next byte is invalid. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:next_grapheme(unicode:characters_to_binary("e̊fg")).</input> +["e̊"|<<"fg">>]</pre> + </desc> + </func> + + <func> + <name name="nth_lexeme" arity="3" since="OTP 20.0"/> + <fsummary>Pick the nth lexeme.</fsummary> + <desc> + <p>Returns lexeme number <c><anno>N</anno></c> in + <c><anno>String</anno></c>, where lexemes are separated by + the grapheme clusters in <c><anno>SeparatorList</anno></c>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:nth_lexeme("abc.de̊f.ghiejkl", 3, ".e").</input> +"ghi"</pre> + </desc> + </func> + + <func> + <name name="pad" arity="2" since="OTP 20.0"/> + <name name="pad" arity="3" since="OTP 20.0"/> + <name name="pad" arity="4" since="OTP 20.0"/> + <fsummary>Pad a string to given length.</fsummary> + <desc> + <p> + Pads <c><anno>String</anno></c> to <c><anno>Length</anno></c> with + grapheme cluster <c><anno>Char</anno></c>. + <c><anno>Dir</anno></c>, which can be <c>leading</c>, <c>trailing</c>, + or <c>both</c>, indicates where the padding should be added. + </p> + <p>By default, <c><anno>Char</anno></c> is <c>$\s</c> and + <c><anno>Dir</anno></c> is <c>trailing</c>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:pad(<<"He̊llö"/utf8>>, 8).</input> +[<<72,101,204,138,108,108,195,182>>,32,32,32] +2> <input>io:format("'~ts'~n",[string:pad("He̊llö", 8, leading)]).</input> +' He̊llö' +3> <input>io:format("'~ts'~n",[string:pad("He̊llö", 8, both)]).</input> +' He̊llö '</pre> + </desc> + </func> + + <func> + <name name="prefix" arity="2" since="OTP 20.0"/> + <fsummary>Remove prefix from string.</fsummary> + <desc> + <p> + If <c><anno>Prefix</anno></c> is the prefix of + <c><anno>String</anno></c>, removes it and returns the + remainder of <c><anno>String</anno></c>, otherwise returns + <c>nomatch</c>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:prefix(<<"prefix of string">>, "pre").</input> +<<"fix of string">> +2> <input>string:prefix("pre", "prefix").</input> +nomatch</pre> + </desc> + </func> + + <func> + <name name="replace" arity="3" since="OTP 20.0"/> + <name name="replace" arity="4" since="OTP 20.0"/> + <fsummary>Replace a pattern in string.</fsummary> + <desc> + <p> + Replaces <c><anno>SearchPattern</anno></c> in <c><anno>String</anno></c> + with <c><anno>Replacement</anno></c>. + <c><anno>Where</anno></c>, default <c>leading</c>, indicates whether + the <c>leading</c>, the <c>trailing</c> or <c>all</c> encounters of + <c><anno>SearchPattern</anno></c> are to be replaced. + </p> + <p>Can be implemented as:</p> + <pre>lists:join(Replacement, split(String, SearchPattern, Where)).</pre> + <p><em>Example:</em></p> + <pre> +1> <input>string:replace(<<"ab..cd..ef">>, "..", "*").</input> +[<<"ab">>,"*",<<"cd..ef">>] +2> <input>string:replace(<<"ab..cd..ef">>, "..", "*", all).</input> +[<<"ab">>,"*",<<"cd">>,"*",<<"ef">>]</pre> + </desc> + </func> + + <func> + <name name="reverse" arity="1" since="OTP 20.0"/> + <fsummary>Reverses a string</fsummary> + <desc> + <p> + Returns the reverse list of the grapheme clusters in <c><anno>String</anno></c>. + </p> + <p><em>Example:</em></p> + <pre> +1> Reverse = <input>string:reverse(unicode:characters_to_nfd_binary("ÅÄÖ")).</input> +[[79,776],[65,776],[65,778]] +2> <input>io:format("~ts~n",[Reverse]).</input> +ÖÄÅ</pre> + </desc> + </func> + + <func> + <name name="slice" arity="2" since="OTP 20.0"/> + <name name="slice" arity="3" since="OTP 20.0"/> + <fsummary>Extract a part of string</fsummary> + <desc> + <p>Returns a substring of <c><anno>String</anno></c> of + at most <c><anno>Length</anno></c> grapheme clusters, starting at position + <c><anno>Start</anno></c>.</p> + <p>By default, <c><anno>Length</anno></c> is <c>infinity</c>.</p> + <p><em>Example:</em></p> + <pre> +1> <input>string:slice(<<"He̊llö Wörld"/utf8>>, 4).</input> +<<"ö Wörld"/utf8>> +2> <input>string:slice(["He̊llö ", <<"Wörld"/utf8>>], 4,4).</input> +"ö Wö" +3> <input>string:slice(["He̊llö ", <<"Wörld"/utf8>>], 4,50).</input> +"ö Wörld"</pre> + </desc> + </func> + + <func> + <name name="split" arity="2" since="OTP 20.0"/> + <name name="split" arity="3" since="OTP 20.0"/> + <fsummary>Split a string into substrings.</fsummary> + <desc> + <p> + Splits <c><anno>String</anno></c> where <c><anno>SearchPattern</anno></c> + is encountered and return the remaining parts. + <c><anno>Where</anno></c>, default <c>leading</c>, indicates whether + the <c>leading</c>, the <c>trailing</c> or <c>all</c> encounters of + <c><anno>SearchPattern</anno></c> will split <c><anno>String</anno></c>. + </p> + <p><em>Example:</em></p> + <pre> +0> <input>string:split("ab..bc..cd", "..").</input> +["ab","bc..cd"] +1> <input>string:split(<<"ab..bc..cd">>, "..", trailing).</input> +[<<"ab..bc">>,<<"cd">>] +2> <input>string:split(<<"ab..bc....cd">>, "..", all).</input> +[<<"ab">>,<<"bc">>,<<>>,<<"cd">>]</pre> + </desc> + </func> + + <func> + <name name="take" arity="2" since="OTP 20.0"/> + <name name="take" arity="3" since="OTP 20.0"/> + <name name="take" arity="4" since="OTP 20.0"/> + <fsummary>Take leading or trailing parts.</fsummary> + <desc> + <p>Takes characters from <c><anno>String</anno></c> as long as + the characters are members of set <c><anno>Characters</anno></c> + or the complement of set <c><anno>Characters</anno></c>. + <c><anno>Dir</anno></c>, + which can be <c>leading</c> or <c>trailing</c>, indicates from + which direction characters are to be taken. + </p> + <p><em>Example:</em></p> + <pre> +5> <input>string:take("abc0z123", lists:seq($a,$z)).</input> +{"abc","0z123"} +6> <input>string:take(<<"abc0z123">>, lists:seq($0,$9), true, leading).</input> +{<<"abc">>,<<"0z123">>} +7> <input>string:take("abc0z123", lists:seq($0,$9), false, trailing).</input> +{"abc0z","123"} +8> <input>string:take(<<"abc0z123">>, lists:seq($a,$z), true, trailing).</input> +{<<"abc0z">>,<<"123">>}</pre> + </desc> + </func> + + <func> + <name name="titlecase" arity="1" since="OTP 20.0"/> + <fsummary>Convert a string to titlecase.</fsummary> + <desc> + <p> + Converts <c><anno>String</anno></c> to titlecase. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:titlecase("ß is a SHARP s").</input> +"Ss is a SHARP s"</pre> + </desc> + </func> + + <func> + <name name="to_float" arity="1" since=""/> + <fsummary>Return a float whose text representation is the integers + (ASCII values) of a string.</fsummary> + <desc> + <p>Argument <c><anno>String</anno></c> is expected to start with a + valid text represented float (the digits are ASCII values). + Remaining characters in the string after the float are returned in + <c><anno>Rest</anno></c>.</p> + <p><em>Example:</em></p> + <pre> +> <input>{F1,Fs} = string:to_float("1.0-1.0e-1"),</input> +> <input>{F2,[]} = string:to_float(Fs),</input> +> <input>F1+F2.</input> +0.9 +> <input>string:to_float("3/2=1.5").</input> +{error,no_float} +> <input>string:to_float("-1.5eX").</input> +{-1.5,"eX"}</pre> + </desc> + </func> + + <func> + <name name="to_integer" arity="1" since=""/> + <fsummary>Return an integer whose text representation is the integers + (ASCII values) of a string.</fsummary> + <desc> + <p>Argument <c><anno>String</anno></c> is expected to start with a + valid text represented integer (the digits are ASCII values). + Remaining characters in the string after the integer are returned in + <c><anno>Rest</anno></c>.</p> + <p><em>Example:</em></p> + <pre> +> <input>{I1,Is} = string:to_integer("33+22"),</input> +> <input>{I2,[]} = string:to_integer(Is),</input> +> <input>I1-I2.</input> +11 +> <input>string:to_integer("0.5").</input> +{0,".5"} +> <input>string:to_integer("x=2").</input> +{error,no_integer}</pre> + </desc> + </func> + + <func> + <name name="to_graphemes" arity="1" since="OTP 20.0"/> + <fsummary>Convert a string to a list of grapheme clusters.</fsummary> + <desc> + <p> + Converts <c><anno>String</anno></c> to a list of grapheme clusters. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:to_graphemes("ß↑e̊").</input> +[223,8593,[101,778]] +2> <input>string:to_graphemes(<<"ß↑e̊"/utf8>>).</input> +[223,8593,[101,778]]</pre> + </desc> + </func> + + <func> + <name name="trim" arity="1" since="OTP 20.0"/> + <name name="trim" arity="2" since="OTP 20.0"/> + <name name="trim" arity="3" since="OTP 20.0"/> + <fsummary>Trim leading or trailing, or both, characters.</fsummary> + <desc> + <p> + Returns a string, where leading or trailing, or both, + <c><anno>Characters</anno></c> have been removed. + <c><anno>Dir</anno></c> which can be <c>leading</c>, <c>trailing</c>, + or <c>both</c>, indicates from which direction characters + are to be removed. + </p> + <p> Default <c><anno>Characters</anno></c> is the set of + nonbreakable whitespace codepoints, defined as + Pattern_White_Space in + <url href="http://unicode.org/reports/tr31/">Unicode Standard Annex #31</url>. + <c>By default, <anno>Dir</anno></c> is <c>both</c>. + </p> + <p> + Notice that <c>[$\r,$\n]</c> is one grapheme cluster according + to the Unicode Standard. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>string:trim("\t Hello \n").</input> +"Hello" +2> <input>string:trim(<<"\t Hello \n">>, leading).</input> +<<"Hello \n">> +3> <input>string:trim(<<".Hello.\n">>, trailing, "\n.").</input> +<<".Hello">></pre> + </desc> + </func> + + <func> + <name name="uppercase" arity="1" since="OTP 20.0"/> + <fsummary>Convert a string to uppercase.</fsummary> + <desc> + <p> + Converts <c><anno>String</anno></c> to uppercase. + </p> + <p>See also <seealso marker="#titlecase/1"><c>titlecase/1</c></seealso>.</p> + <p><em>Example:</em></p> + <pre> +1> <input>string:uppercase("Michał").</input> +"MICHAŁ"</pre> + </desc> + </func> + + </funcs> + + <section> + <marker id="oldapi"/> + <title>Obsolete API functions</title> + <p>Here follows the function of the old API. + These functions only work on a list of Latin-1 characters. + </p> + <note><p> + The functions are kept for backward compatibility, but are + not recommended. + They will be deprecated in a future release. + </p> + <p>Any undocumented functions in <c>string</c> are not to be used.</p> + </note> + </section> + <funcs> <func> - <name name="centre" arity="2"/> - <name name="centre" arity="3"/> + <name name="centre" arity="2" since=""/> + <name name="centre" arity="3" since=""/> <fsummary>Center a string.</fsummary> <desc> <p>Returns a string, where <c><anno>String</anno></c> is centered in the string and surrounded by blanks or <c><anno>Character</anno></c>. The resulting string has length <c><anno>Number</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#pad/3"><c>pad/3</c></seealso>. + </p> </desc> </func> <func> - <name name="chars" arity="2"/> - <name name="chars" arity="3"/> - <fsummary>Returns a string consisting of numbers of characters.</fsummary> + <name name="chars" arity="2" since=""/> + <name name="chars" arity="3" since=""/> + <fsummary>Return a string consisting of numbers of characters.</fsummary> <desc> <p>Returns a string consisting of <c><anno>Number</anno></c> characters <c><anno>Character</anno></c>. Optionally, the string can end with string <c><anno>Tail</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="lists#duplicate/2"><c>lists:duplicate/2</c></seealso>.</p> </desc> </func> <func> - <name name="chr" arity="2"/> + <name name="chr" arity="2" since=""/> <fsummary>Return the index of the first occurrence of a character in a string.</fsummary> <desc> <p>Returns the index of the first occurrence of <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>Character</anno></c> does not occur.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#find/2"><c>find/2</c></seealso>.</p> </desc> </func> <func> - <name name="concat" arity="2"/> + <name name="concat" arity="2" since=""/> <fsummary>Concatenate two strings.</fsummary> <desc> <p>Concatenates <c><anno>String1</anno></c> and <c><anno>String2</anno></c> to form a new string <c><anno>String3</anno></c>, which is returned.</p> + <p> + This function is <seealso marker="#oldapi">obsolete</seealso>. + Use <c>[<anno>String1</anno>, <anno>String2</anno>]</c> as + <c>Data</c> argument, and call + <seealso marker="unicode#characters_to_list/2"> + <c>unicode:characters_to_list/2</c></seealso> or + <seealso marker="unicode#characters_to_binary/2"> + <c>unicode:characters_to_binary/2</c></seealso> + to flatten the output. + </p> </desc> </func> <func> - <name name="copies" arity="2"/> + <name name="copies" arity="2" since=""/> <fsummary>Copy a string.</fsummary> <desc> <p>Returns a string containing <c><anno>String</anno></c> repeated <c><anno>Number</anno></c> times.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="lists#duplicate/2"><c>lists:duplicate/2</c></seealso>.</p> </desc> </func> <func> - <name name="cspan" arity="2"/> + <name name="cspan" arity="2" since=""/> <fsummary>Span characters at start of a string.</fsummary> <desc> <p>Returns the length of the maximum initial segment of <c><anno>String</anno></c>, which consists entirely of characters not from <c><anno>Chars</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#take/3"><c>take/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:cspan("\t abcdef", " \t"). @@ -106,20 +741,14 @@ </func> <func> - <name name="equal" arity="2"/> - <fsummary>Test string equality.</fsummary> - <desc> - <p>Returns <c>true</c> if <c><anno>String1</anno></c> and - <c><anno>String2</anno></c> are equal, otherwise <c>false</c>.</p> - </desc> - </func> - - <func> - <name name="join" arity="2"/> + <name name="join" arity="2" since=""/> <fsummary>Join a list of strings with separator.</fsummary> <desc> <p>Returns a string with the elements of <c><anno>StringList</anno></c> separated by the string in <c><anno>Separator</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="lists#join/2"><c>lists:join/2</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > join(["one", "two", "three"], ", "). @@ -128,8 +757,8 @@ </func> <func> - <name name="left" arity="2"/> - <name name="left" arity="3"/> + <name name="left" arity="2" since=""/> + <name name="left" arity="3" since=""/> <fsummary>Adjust left end of a string.</fsummary> <desc> <p>Returns <c><anno>String</anno></c> with the length adjusted in @@ -137,6 +766,10 @@ fixed. If <c>length(<anno>String</anno>)</c> < <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#pad/2"><c>pad/2</c></seealso> or + <seealso marker="#pad/3"><c>pad/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:left("Hello",10,$.). @@ -145,27 +778,33 @@ </func> <func> - <name name="len" arity="1"/> + <name name="len" arity="1" since=""/> <fsummary>Return the length of a string.</fsummary> <desc> <p>Returns the number of characters in <c><anno>String</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#length/1"><c>length/1</c></seealso>.</p> </desc> </func> <func> - <name name="rchr" arity="2"/> + <name name="rchr" arity="2" since=""/> <fsummary>Return the index of the last occurrence of a character in a string.</fsummary> <desc> <p>Returns the index of the last occurrence of <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>Character</anno></c> does not occur.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#find/3"><c>find/3</c></seealso>.</p> </desc> </func> <func> - <name name="right" arity="2"/> - <name name="right" arity="3"/> + <name name="right" arity="2" since=""/> + <name name="right" arity="3" since=""/> <fsummary>Adjust right end of a string.</fsummary> <desc> <p>Returns <c><anno>String</anno></c> with the length adjusted in @@ -173,6 +812,9 @@ fixed. If the length of <c>(<anno>String</anno>)</c> < <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#pad/3"><c>pad/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:right("Hello", 10, $.). @@ -181,13 +823,16 @@ </func> <func> - <name name="rstr" arity="2"/> + <name name="rstr" arity="2" since=""/> <fsummary>Find the index of a substring.</fsummary> <desc> <p>Returns the position where the last occurrence of <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>SubString</anno></c> does not exist in <c><anno>String</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#find/3"><c>find/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:rstr(" Hello Hello World World ", "Hello World"). @@ -196,12 +841,15 @@ </func> <func> - <name name="span" arity="2"/> + <name name="span" arity="2" since=""/> <fsummary>Span characters at start of a string.</fsummary> <desc> <p>Returns the length of the maximum initial segment of <c><anno>String</anno></c>, which consists entirely of characters from <c><anno>Chars</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#take/2"><c>take/2</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:span("\t abcdef", " \t"). @@ -210,13 +858,16 @@ </func> <func> - <name name="str" arity="2"/> + <name name="str" arity="2" since=""/> <fsummary>Find the index of a substring.</fsummary> <desc> <p>Returns the position where the first occurrence of <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. Returns <c>0</c> if <c><anno>SubString</anno></c> does not exist in <c><anno>String</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#find/2"><c>find/2</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:str(" Hello Hello World World ", "Hello World"). @@ -225,17 +876,20 @@ </func> <func> - <name name="strip" arity="1"/> - <name name="strip" arity="2"/> - <name name="strip" arity="3"/> + <name name="strip" arity="1" since=""/> + <name name="strip" arity="2" since=""/> + <name name="strip" arity="3" since=""/> <fsummary>Strip leading or trailing characters.</fsummary> <desc> - <p>Returns a string, where leading and/or trailing blanks or a + <p>Returns a string, where leading or trailing, or both, blanks or a number of <c><anno>Character</anno></c> have been removed. <c><anno>Direction</anno></c>, which can be <c>left</c>, <c>right</c>, or <c>both</c>, indicates from which direction blanks are to be removed. <c>strip/1</c> is equivalent to <c>strip(String, both)</c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#trim/3"><c>trim/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:strip("...Hello.....", both, $.). @@ -244,13 +898,16 @@ </func> <func> - <name name="sub_string" arity="2"/> - <name name="sub_string" arity="3"/> + <name name="sub_string" arity="2" since=""/> + <name name="sub_string" arity="3" since=""/> <fsummary>Extract a substring.</fsummary> <desc> <p>Returns a substring of <c><anno>String</anno></c>, starting at position <c><anno>Start</anno></c> to the end of the string, or to and including position <c><anno>Stop</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#slice/3"><c>slice/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> sub_string("Hello World", 4, 8). @@ -259,13 +916,16 @@ sub_string("Hello World", 4, 8). </func> <func> - <name name="substr" arity="2"/> - <name name="substr" arity="3"/> + <name name="substr" arity="2" since=""/> + <name name="substr" arity="3" since=""/> <fsummary>Return a substring of a string.</fsummary> <desc> <p>Returns a substring of <c><anno>String</anno></c>, starting at position <c><anno>Start</anno></c>, and ending at the end of the string or at length <c><anno>Length</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#slice/3"><c>slice/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > substr("Hello World", 4, 5). @@ -274,13 +934,16 @@ sub_string("Hello World", 4, 8). </func> <func> - <name name="sub_word" arity="2"/> - <name name="sub_word" arity="3"/> + <name name="sub_word" arity="2" since=""/> + <name name="sub_word" arity="3" since=""/> <fsummary>Extract subword.</fsummary> <desc> <p>Returns the word in position <c><anno>Number</anno></c> of <c><anno>String</anno></c>. Words are separated by blanks or <c><anno>Character</anno></c>s.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#nth_lexeme/3"><c>nth_lexeme/3</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > string:sub_word(" Hello old boy !",3,$o). @@ -289,54 +952,10 @@ sub_string("Hello World", 4, 8). </func> <func> - <name name="to_float" arity="1"/> - <fsummary>Returns a float whose text representation is the integers - (ASCII values) in a string.</fsummary> - <desc> - <p>Argument <c><anno>String</anno></c> is expected to start with a - valid text represented float (the digits are ASCII values). - Remaining characters in the string after the float are returned in - <c><anno>Rest</anno></c>.</p> - <p><em>Example:</em></p> - <code type="none"> -> {F1,Fs} = string:to_float("1.0-1.0e-1"), -> {F2,[]} = string:to_float(Fs), -> F1+F2. -0.9 -> string:to_float("3/2=1.5"). -{error,no_float} -> string:to_float("-1.5eX"). -{-1.5,"eX"}</code> - </desc> - </func> - - <func> - <name name="to_integer" arity="1"/> - <fsummary>Returns an integer whose text representation is the integers - (ASCII values) in a string.</fsummary> - <desc> - <p>Argument <c><anno>String</anno></c> is expected to start with a - valid text represented integer (the digits are ASCII values). - Remaining characters in the string after the integer are returned in - <c><anno>Rest</anno></c>.</p> - <p><em>Example:</em></p> - <code type="none"> -> {I1,Is} = string:to_integer("33+22"), -> {I2,[]} = string:to_integer(Is), -> I1-I2. -11 -> string:to_integer("0.5"). -{0,".5"} -> string:to_integer("x=2"). -{error,no_integer}</code> - </desc> - </func> - - <func> - <name name="to_lower" arity="1" clause_i="1"/> - <name name="to_lower" arity="1" clause_i="2"/> - <name name="to_upper" arity="1" clause_i="1"/> - <name name="to_upper" arity="1" clause_i="2"/> + <name name="to_lower" arity="1" clause_i="1" since=""/> + <name name="to_lower" arity="1" clause_i="2" since=""/> + <name name="to_upper" arity="1" clause_i="1" since=""/> + <name name="to_upper" arity="1" clause_i="2" since=""/> <fsummary>Convert case of string (ISO/IEC 8859-1).</fsummary> <type variable="String" name_i="1"/> <type variable="Result" name_i="1"/> @@ -346,11 +965,16 @@ sub_string("Hello World", 4, 8). <p>The specified string or character is case-converted. Notice that the supported character set is ISO/IEC 8859-1 (also called Latin 1); all values outside this set are unchanged</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso> use + <seealso marker="#lowercase/1"><c>lowercase/1</c></seealso>, + <seealso marker="#uppercase/1"><c>uppercase/1</c></seealso>, + <seealso marker="#titlecase/1"><c>titlecase/1</c></seealso> or + <seealso marker="#casefold/1"><c>casefold/1</c></seealso>.</p> </desc> </func> <func> - <name name="tokens" arity="2"/> + <name name="tokens" arity="2" since=""/> <fsummary>Split string into tokens.</fsummary> <desc> <p>Returns a list of tokens in <c><anno>String</anno></c>, separated @@ -363,16 +987,22 @@ sub_string("Hello World", 4, 8). adjacent separator characters in <c><anno>String</anno></c> are treated as one. That is, there are no empty strings in the resulting list of tokens.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#lexemes/2"><c>lexemes/2</c></seealso>.</p> </desc> </func> <func> - <name name="words" arity="1"/> - <name name="words" arity="2"/> + <name name="words" arity="1" since=""/> + <name name="words" arity="2" since=""/> <fsummary>Count blank separated words.</fsummary> <desc> <p>Returns the number of words in <c><anno>String</anno></c>, separated by blanks or <c><anno>Character</anno></c>.</p> + <p>This function is <seealso marker="#oldapi">obsolete</seealso>. + Use + <seealso marker="#lexemes/2"><c>lexemes/2</c></seealso>.</p> <p><em>Example:</em></p> <code type="none"> > words(" Hello old boy!", $o). @@ -387,10 +1017,7 @@ sub_string("Hello World", 4, 8). other. The reason is that this string package is the combination of two earlier packages and all functions of both packages have been retained.</p> - - <note> - <p>Any undocumented functions in <c>string</c> are not to be used.</p> - </note> </section> + </erlref> diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index 294196f746..f15b1a2dd3 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>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>supervisor</module> + <module since="">supervisor</module> <modulesummary>Generic supervisor behavior.</modulesummary> <description> <p>This behavior module provides a supervisor, a process that @@ -36,7 +36,6 @@ process can either be another supervisor or a worker process. Worker processes are normally implemented using one of the <seealso marker="gen_event"><c>gen_event</c></seealso>, - <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>, <seealso marker="gen_server"><c>gen_server</c></seealso>, or <seealso marker="gen_statem"><c>gen_statem</c></seealso> behaviors. A supervisor implemented using this module has @@ -133,8 +132,10 @@ sup_flags() = #{strategy => strategy(), % optional map. Assuming the values <c>MaxR</c> for <c>intensity</c> and <c>MaxT</c> for <c>period</c>, then, if more than <c>MaxR</c> restarts occur within <c>MaxT</c> seconds, the supervisor - terminates all child processes and then itself. <c>intensity</c> - defaults to <c>1</c> and <c>period</c> defaults to <c>5</c>.</p> + terminates all child processes and then itself. The termination + reason for the supervisor itself in that case will be <c>shutdown</c>. + <c>intensity</c> defaults to <c>1</c> and <c>period</c> defaults to + <c>5</c>.</p> <marker id="child_spec"/> <p>The type definition of a child specification is as follows:</p> @@ -207,8 +208,16 @@ child_spec() = #{id => child_id(), % mandatory the child process is unconditionally terminated using <c>exit(Child,kill)</c>.</p> <p>If the child process is another supervisor, the shutdown time - is to be set to <c>infinity</c> to give the subtree ample - time to shut down. It is also allowed to set it to <c>infinity</c>, + must be set to <c>infinity</c> to give the subtree ample + time to shut down.</p> + <warning> + <p>Setting the shutdown time to anything other + than <c>infinity</c> for a child of type <c>supervisor</c> + can cause a race condition where the child in question + unlinks its own children, but fails to terminate them + before it is killed.</p> + </warning> + <p>It is also allowed to set it to <c>infinity</c>, if the child process is a worker.</p> <warning> <p>Be careful when setting the shutdown time to @@ -235,8 +244,8 @@ child_spec() = #{id => child_id(), % mandatory <p><c>modules</c> is used by the release handler during code replacement to determine which processes are using a certain module. As a rule of thumb, if the child process is a - <c>supervisor</c>, <c>gen_server</c>, - <c>gen_statem</c>, or <c>gen_fsm</c>, + <c>supervisor</c>, <c>gen_server</c> or, + <c>gen_statem</c>, this is to be a list with one element <c>[Module]</c>, where <c>Module</c> is the callback module. If the child process is an event manager (<c>gen_event</c>) with a @@ -309,7 +318,7 @@ child_spec() = #{id => child_id(), % mandatory <funcs> <func> - <name name="check_childspecs" arity="1"/> + <name name="check_childspecs" arity="1" since=""/> <fsummary>Check if children specifications are syntactically correct. </fsummary> <desc> @@ -320,7 +329,7 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="count_children" arity="1"/> + <name name="count_children" arity="1" since="OTP R13B04"/> <fsummary>Return counts for the number of child specifications, active children, supervisors, and workers.</fsummary> <desc> @@ -357,7 +366,7 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="delete_child" arity="2"/> + <name name="delete_child" arity="2" since=""/> <fsummary>Delete a child specification from a supervisor.</fsummary> <desc> <p>Tells supervisor <c><anno>SupRef</anno></c> to delete the child @@ -378,7 +387,7 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="get_childspec" arity="2"/> + <name name="get_childspec" arity="2" since="OTP 18.0"/> <fsummary>Return the child specification map for the specified child.</fsummary> <desc> @@ -391,7 +400,7 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="restart_child" arity="2"/> + <name name="restart_child" arity="2" since=""/> <fsummary>Restart a terminated child process belonging to a supervisor. </fsummary> <desc> @@ -427,7 +436,7 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="start_child" arity="2"/> + <name name="start_child" arity="2" since=""/> <fsummary>Dynamically add a child process to a supervisor.</fsummary> <type name="startchild_ret"/> <type name="startchild_err"/> @@ -494,8 +503,8 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="start_link" arity="2"/> - <name name="start_link" arity="3"/> + <name name="start_link" arity="2" since=""/> + <name name="start_link" arity="3" since=""/> <fsummary>Create a supervisor process.</fsummary> <type name="startlink_ret"/> <type name="startlink_err"/> @@ -575,7 +584,7 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="terminate_child" arity="2"/> + <name name="terminate_child" arity="2" since=""/> <fsummary>Terminate a child process belonging to a supervisor.</fsummary> <desc> <p>Tells supervisor <c><anno>SupRef</anno></c> to terminate the @@ -612,7 +621,7 @@ child_spec() = #{id => child_id(), % mandatory </func> <func> - <name name="which_children" arity="1"/> + <name name="which_children" arity="1" since=""/> <fsummary>Return information about all children specifications and child processes belonging to a supervisor.</fsummary> <desc> @@ -657,7 +666,7 @@ child_spec() = #{id => child_id(), % mandatory <funcs> <func> - <name>Module:init(Args) -> Result</name> + <name since="">Module:init(Args) -> Result</name> <fsummary>Return a supervisor specification.</fsummary> <type> <v>Args = term()</v> @@ -704,7 +713,6 @@ child_spec() = #{id => child_id(), % mandatory <section> <title>See Also</title> <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>, - <seealso marker="gen_fsm"><c>gen_fsm(3)</c></seealso>, <seealso marker="gen_statem"><c>gen_statem(3)</c></seealso>, <seealso marker="gen_server"><c>gen_server(3)</c></seealso>, <seealso marker="sys"><c>sys(3)</c></seealso></p> diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml index c4c1b37548..ee5d97fea1 100644 --- a/lib/stdlib/doc/src/supervisor_bridge.xml +++ b/lib/stdlib/doc/src/supervisor_bridge.xml @@ -30,7 +30,7 @@ <date></date> <rev></rev> </header> - <module>supervisor_bridge</module> + <module since="">supervisor_bridge</module> <modulesummary>Generic supervisor bridge behavior.</modulesummary> <description> <p>This behavior module provides a supervisor bridge, a process @@ -57,8 +57,8 @@ <funcs> <func> - <name name="start_link" arity="2"/> - <name name="start_link" arity="3"/> + <name name="start_link" arity="2" since=""/> + <name name="start_link" arity="3" since=""/> <fsummary>Create a supervisor bridge process.</fsummary> <desc> <p>Creates a supervisor bridge process, linked to the calling process, @@ -133,7 +133,7 @@ <funcs> <func> - <name>Module:init(Args) -> Result</name> + <name since="">Module:init(Args) -> Result</name> <fsummary>Initialize process and start subsystem.</fsummary> <type> <v>Args = term()</v> @@ -164,7 +164,7 @@ </func> <func> - <name>Module:terminate(Reason, State)</name> + <name since="">Module:terminate(Reason, State)</name> <fsummary>Clean up and stop subsystem.</fsummary> <type> <v>Reason = shutdown | term()</v> diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 0fed649660..6fc508b853 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2017</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev></rev> <file>sys.xml</file> </header> - <module>sys</module> + <module since="">sys</module> <modulesummary>A functional interface to system messages.</modulesummary> <description> <p>This module contains functions for sending system messages used by @@ -102,7 +102,7 @@ then treated in the debug function. For example, <c>trace</c> formats the system events to the terminal. </p> - <p>Three predefined system events are used when a + <p>Four predefined system events are used when a process receives or sends a message. The process can also define its own system events. It is always up to the process itself to format these events.</p> @@ -129,8 +129,8 @@ <funcs> <func> - <name name="change_code" arity="4"/> - <name name="change_code" arity="5"/> + <name name="change_code" arity="4" since=""/> + <name name="change_code" arity="5" since=""/> <fsummary>Send the code change system message to the process.</fsummary> <desc> <p>Tells the process to change code. The process must be @@ -143,8 +143,8 @@ </func> <func> - <name name="get_state" arity="1"/> - <name name="get_state" arity="2"/> + <name name="get_state" arity="1" since="OTP R16B01"/> + <name name="get_state" arity="2" since="OTP R16B01"/> <fsummary>Get the state of the process.</fsummary> <desc> <p>Gets the state of the process.</p> @@ -168,12 +168,6 @@ </item> <item> <p>For a - <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> - process, <c><anno>State</anno></c> is the tuple - <c>{CurrentStateName, CurrentStateData}</c>.</p> - </item> - <item> - <p>For a <seealso marker="gen_statem"><c>gen_statem</c></seealso> process, <c><anno>State</anno></c> is the tuple <c>{CurrentState,CurrentData}</c>.</p> @@ -222,7 +216,7 @@ <p>Function <c>system_get_state/1</c> is primarily useful for user-defined behaviors and modules that implement OTP <seealso marker="#special_process">special processes</seealso>. - The <c>gen_server</c>, <c>gen_fsm</c>, + The <c>gen_server</c>, <c>gen_statem</c>, and <c>gen_event</c> OTP behavior modules export this function, so callback modules for those behaviors need not to supply their own.</p> @@ -233,8 +227,8 @@ </func> <func> - <name name="get_status" arity="1"/> - <name name="get_status" arity="2"/> + <name name="get_status" arity="1" since=""/> + <name name="get_status" arity="2" since=""/> <fsummary>Get the status of the process.</fsummary> <desc> <p>Gets the status of the process.</p> @@ -246,11 +240,6 @@ process returns the state of the callback module.</p> </item> <item> - <p>A <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> - process returns information, such as its current - state name and state data.</p> - </item> - <item> <p>A <seealso marker="gen_statem"><c>gen_statem</c></seealso> process returns information, such as its current state name and state data.</p> @@ -262,14 +251,12 @@ </item> </list> <p>Callback modules for <c>gen_server</c>, - <c>gen_fsm</c>, <c>gen_statem</c>, and <c>gen_event</c> + <c>gen_statem</c>, and <c>gen_event</c> can also change the value of <c><anno>Misc</anno></c> by exporting a function <c>format_status/2</c>, which contributes module-specific information. For details, see <seealso marker="gen_server#Module:format_status/2"> <c>gen_server:format_status/2</c></seealso>, - <seealso marker="gen_fsm#Module:format_status/2"> - <c>gen_fsm:format_status/2</c></seealso>, <seealso marker="gen_statem#Module:format_status/2"> <c>gen_statem:format_status/2</c></seealso>, and <seealso marker="gen_event#Module:format_status/2"> @@ -278,8 +265,8 @@ </func> <func> - <name name="install" arity="2"/> - <name name="install" arity="3"/> + <name name="install" arity="2" since=""/> + <name name="install" arity="3" since=""/> <fsummary>Install a debug function in the process.</fsummary> <desc> <p>Enables installation of alternative debug functions. An example of @@ -289,13 +276,15 @@ <p><c><anno>Func</anno></c> is called whenever a system event is generated. This function is to return <c>done</c>, or a new <c>Func</c> state. In the first case, the function is removed. It is - also removed if the function fails.</p> + also removed if the function fails. If one debug function should be + installed more times, a unique <c><anno>FuncId</anno></c> must be + specified for each installation.</p> </desc> </func> <func> - <name name="log" arity="2"/> - <name name="log" arity="3"/> + <name name="log" arity="2" since=""/> + <name name="log" arity="3" since=""/> <fsummary>Log system events in memory.</fsummary> <desc> <p>Turns the logging of system events on or off. If on, a @@ -313,21 +302,21 @@ </func> <func> - <name name="log_to_file" arity="2"/> - <name name="log_to_file" arity="3"/> + <name name="log_to_file" arity="2" since=""/> + <name name="log_to_file" arity="3" since=""/> <fsummary>Log system events to the specified file.</fsummary> <desc> <p>Enables or disables the logging of all system events in text format to the file. The events are formatted with a function that is defined by the process that generated the event (with a call to <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>). - </p> + The file is opened with encoding UTF-8.</p> </desc> </func> <func> - <name name="no_debug" arity="1"/> - <name name="no_debug" arity="2"/> + <name name="no_debug" arity="1" since=""/> + <name name="no_debug" arity="2" since=""/> <fsummary>Turn off debugging.</fsummary> <desc> <p>Turns off all debugging for the process. This includes @@ -338,19 +327,19 @@ </func> <func> - <name name="remove" arity="2"/> - <name name="remove" arity="3"/> + <name name="remove" arity="2" since=""/> + <name name="remove" arity="3" since=""/> <fsummary>Remove a debug function from the process.</fsummary> <desc> <p>Removes an installed debug function from the - process. <c><anno>Func</anno></c> must be the same as previously - installed.</p> + process. <c><anno>Func</anno></c> or <c><anno>FuncId</anno></c> must be + the same as previously installed.</p> </desc> </func> <func> - <name name="replace_state" arity="2"/> - <name name="replace_state" arity="3"/> + <name name="replace_state" arity="2" since="OTP R16B01"/> + <name name="replace_state" arity="3" since="OTP R16B01"/> <fsummary>Replace the state of the process.</fsummary> <desc> <p>Replaces the state of the process, and returns the new state.</p> @@ -373,13 +362,6 @@ is a new instance of that state.</p> </item> <item> - <p>For a <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> process, - <c><anno>State</anno></c> is the tuple <c>{CurrentStateName, - CurrentStateData}</c>, and <c><anno>NewState</anno></c> is a - similar tuple, which can contain - a new state name, new state data, or both.</p> - </item> - <item> <p>For a <seealso marker="gen_statem"><c>gen_statem</c></seealso> process, <c><anno>State</anno></c> is the tuple <c>{CurrentState,CurrentData}</c>, @@ -422,7 +404,7 @@ return its <c><anno>State</anno></c> argument.</p> <p>If a <c><anno>StateFun</anno></c> function crashes or throws an exception, the original state of the process is unchanged for - <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_statem</c> processes. + <c>gen_server</c>, and <c>gen_statem</c> processes. For <c>gen_event</c> processes, a crashing or failing <c><anno>StateFun</anno></c> function means that only the state of the particular event handler it was @@ -462,15 +444,15 @@ user-defined behaviors and modules that implement OTP <seealso marker="#special_process">special processes</seealso>. The OTP behavior modules <c>gen_server</c>, - <c>gen_fsm</c>, <c>gen_statem</c>, and <c>gen_event</c> + <c>gen_statem</c>, and <c>gen_event</c> export this function, so callback modules for those behaviors need not to supply their own.</p> </desc> </func> <func> - <name name="resume" arity="1"/> - <name name="resume" arity="2"/> + <name name="resume" arity="1" since=""/> + <name name="resume" arity="2" since=""/> <fsummary>Resume a suspended process.</fsummary> <desc> <p>Resumes a suspended process.</p> @@ -478,8 +460,8 @@ </func> <func> - <name name="statistics" arity="2"/> - <name name="statistics" arity="3"/> + <name name="statistics" arity="2" since=""/> + <name name="statistics" arity="3" since=""/> <fsummary>Enable or disable the collections of statistics.</fsummary> <desc> <p>Enables or disables the collection of statistics. If @@ -489,8 +471,8 @@ </func> <func> - <name name="suspend" arity="1"/> - <name name="suspend" arity="2"/> + <name name="suspend" arity="1" since=""/> + <name name="suspend" arity="2" since=""/> <fsummary>Suspend the process.</fsummary> <desc> <p>Suspends the process. When the process is suspended, it @@ -500,8 +482,8 @@ </func> <func> - <name name="terminate" arity="2"/> - <name name="terminate" arity="3"/> + <name name="terminate" arity="2" since="OTP 18.0"/> + <name name="terminate" arity="3" since="OTP 18.0"/> <fsummary>Terminate the process.</fsummary> <desc> <p>Orders the process to terminate with the @@ -512,8 +494,8 @@ </func> <func> - <name name="trace" arity="2"/> - <name name="trace" arity="3"/> + <name name="trace" arity="2" since=""/> + <name name="trace" arity="3" since=""/> <fsummary>Print all system events on <c>standard_io</c>.</fsummary> <desc> <p>Prints all system events on <c>standard_io</c>. The events are @@ -536,7 +518,7 @@ <funcs> <func> - <name name="debug_options" arity="1"/> + <name name="debug_options" arity="1" since=""/> <fsummary>Convert a list of options to a debug structure.</fsummary> <desc> <p>Can be used by a process that initiates a debug @@ -547,7 +529,7 @@ </func> <func> - <name name="get_debug" arity="3"/> + <name name="get_debug" arity="3" since=""/> <fsummary>Get the data associated with a debug option.</fsummary> <desc> <p>Gets the data associated with a debug option. @@ -559,7 +541,7 @@ </func> <func> - <name name="handle_debug" arity="4"/> + <name name="handle_debug" arity="4" since=""/> <fsummary>Generate a system event.</fsummary> <desc> <p>This function is called by a process when it generates a @@ -574,7 +556,7 @@ </func> <func> - <name name="handle_system_msg" arity="6"/> + <name name="handle_system_msg" arity="6" since=""/> <fsummary>Take care of system messages.</fsummary> <desc> <p>This function is used by a process module to take care of system @@ -612,7 +594,7 @@ </func> <func> - <name name="print_log" arity="1"/> + <name name="print_log" arity="1" since=""/> <fsummary>Print the logged events in the debug structure.</fsummary> <desc> <p>Prints the logged system events in the debug structure, @@ -623,7 +605,7 @@ </func> <func> - <name>Module:system_code_change(Misc, Module, OldVsn, Extra) -> + <name since="">Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}</name> <fsummary>Called when the process is to perform a code change.</fsummary> <type> @@ -646,7 +628,7 @@ </func> <func> - <name>Module:system_continue(Parent, Debug, Misc) -> none()</name> + <name since="">Module:system_continue(Parent, Debug, Misc) -> none()</name> <fsummary>Called when the process is to continue its execution.</fsummary> <type> <v>Parent = pid()</v> @@ -662,7 +644,7 @@ </func> <func> - <name>Module:system_get_state(Misc) -> {ok, State}</name> + <name since="OTP 17.0">Module:system_get_state(Misc) -> {ok, State}</name> <fsummary>Called when the process is to return its current state. </fsummary> <type> @@ -679,7 +661,7 @@ </func> <func> - <name>Module:system_replace_state(StateFun, Misc) -> + <name since="OTP 17.0">Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}</name> <fsummary>Called when the process is to replace its current state. </fsummary> @@ -699,7 +681,7 @@ </func> <func> - <name>Module:system_terminate(Reason, Parent, Debug, Misc) -> none()</name> + <name since="">Module:system_terminate(Reason, Parent, Debug, Misc) -> none()</name> <fsummary>Called when the process is to terminate.</fsummary> <type> <v>Reason = term()</v> diff --git a/lib/stdlib/doc/src/timer.xml b/lib/stdlib/doc/src/timer.xml index fcaccdb2cb..165eecfbb0 100644 --- a/lib/stdlib/doc/src/timer.xml +++ b/lib/stdlib/doc/src/timer.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <rev>D</rev> <file>timer.xml</file> </header> - <module>timer</module> + <module since="">timer</module> <modulesummary>Timer functions.</modulesummary> <description> <p>This module provides useful functions related to time. Unless otherwise @@ -62,7 +62,7 @@ <funcs> <func> - <name name="apply_after" arity="4"/> + <name name="apply_after" arity="4" since=""/> <fsummary>Apply <c>Module:Function(Arguments)</c> after a specified <c>Time</c>.</fsummary> <desc> @@ -75,7 +75,7 @@ </func> <func> - <name name="apply_interval" arity="4"/> + <name name="apply_interval" arity="4" since=""/> <fsummary>Evaluate <c>Module:Function(Arguments)</c> repeatedly at intervals of <c>Time</c>.</fsummary> <desc> @@ -88,7 +88,7 @@ </func> <func> - <name name="cancel" arity="1"/> + <name name="cancel" arity="1" since=""/> <fsummary>Cancel a previously requested time-out identified by <c>TRef</c>.</fsummary> <desc> @@ -101,8 +101,8 @@ </func> <func> - <name name="exit_after" arity="2"/> - <name name="exit_after" arity="3"/> + <name name="exit_after" arity="2" since=""/> + <name name="exit_after" arity="3" since=""/> <fsummary>Send an exit signal with <c>Reason</c> after a specified <c>Time</c>.</fsummary> <desc> @@ -117,7 +117,7 @@ </func> <func> - <name name="hms" arity="3"/> + <name name="hms" arity="3" since=""/> <fsummary>Convert <c>Hours</c>+<c>Minutes</c>+<c>Seconds</c> to <c>Milliseconds</c>.</fsummary> <desc> @@ -127,7 +127,7 @@ </func> <func> - <name name="hours" arity="1"/> + <name name="hours" arity="1" since=""/> <fsummary>Convert <c>Hours</c> to <c>Milliseconds</c>.</fsummary> <desc> <p>Returns the number of milliseconds in <c><anno>Hours</anno></c>.</p> @@ -135,8 +135,8 @@ </func> <func> - <name name="kill_after" arity="1"/> - <name name="kill_after" arity="2"/> + <name name="kill_after" arity="1" since=""/> + <name name="kill_after" arity="2" since=""/> <fsummary>Send an exit signal with <c>Reason</c> after a specified <c>Time</c>.</fsummary> <desc> @@ -148,7 +148,7 @@ </func> <func> - <name name="minutes" arity="1"/> + <name name="minutes" arity="1" since=""/> <fsummary>Converts <c>Minutes</c> to <c>Milliseconds</c>.</fsummary> <desc> <p>Returns the number of milliseconds in @@ -157,7 +157,7 @@ </func> <func> - <name name="now_diff" arity="2"/> + <name name="now_diff" arity="2" since=""/> <fsummary>Calculate time difference between time stamps.</fsummary> <type_desc variable="Tdiff">In microseconds</type_desc> <desc> @@ -173,7 +173,7 @@ </func> <func> - <name name="seconds" arity="1"/> + <name name="seconds" arity="1" since=""/> <fsummary>Convert <c>Seconds</c> to <c>Milliseconds</c>.</fsummary> <desc> <p>Returns the number of milliseconds in @@ -182,8 +182,8 @@ </func> <func> - <name name="send_after" arity="2"/> - <name name="send_after" arity="3"/> + <name name="send_after" arity="2" since=""/> + <name name="send_after" arity="3" since=""/> <fsummary>Send <c>Message</c> to <c>Pid</c> after a specified <c>Time</c>.</fsummary> <desc> @@ -206,8 +206,8 @@ </func> <func> - <name name="send_interval" arity="2"/> - <name name="send_interval" arity="3"/> + <name name="send_interval" arity="2" since=""/> + <name name="send_interval" arity="3" since=""/> <fsummary>Send <c>Message</c> repeatedly at intervals of <c>Time</c>. </fsummary> <desc> @@ -231,7 +231,7 @@ </func> <func> - <name name="sleep" arity="1"/> + <name name="sleep" arity="1" since=""/> <fsummary>Suspend the calling process for <c>Time</c> milliseconds. </fsummary> <desc> @@ -244,7 +244,7 @@ </func> <func> - <name name="start" arity="0"/> + <name name="start" arity="0" since=""/> <fsummary>Start a global timer server (named <c>timer_server</c>). </fsummary> <desc> @@ -258,9 +258,9 @@ </func> <func> - <name name="tc" arity="1"/> - <name name="tc" arity="2"/> - <name name="tc" arity="3"/> + <name name="tc" arity="1" since="OTP R14B03"/> + <name name="tc" arity="2" since="OTP R14B"/> + <name name="tc" arity="3" since=""/> <fsummary>Measure the real time it takes to evaluate <c>apply(Module, Function, Arguments)</c> or <c>apply(Fun, Arguments)</c>.</fsummary> <type_desc variable="Time">In microseconds</type_desc> @@ -270,8 +270,8 @@ <item> <p>Evaluates <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Arguments</anno>)</c> and measures the elapsed real time as - reported by <seealso marker="os:timestamp/0"> - <c>os:timestamp/0</c></seealso>.</p> + reported by <seealso marker="erts:erlang#monotonic_time/0"> + <c>erlang:monotonic_time/0</c></seealso>.</p> <p>Returns <c>{<anno>Time</anno>, <anno>Value</anno>}</c>, where <c><anno>Time</anno></c> is the elapsed real time in <em>microseconds</em>, and <c><anno>Value</anno></c> is what is diff --git a/lib/stdlib/doc/src/unicode.xml b/lib/stdlib/doc/src/unicode.xml index 93d0d37456..b7696a4b7e 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>2016</year> + <year>2017</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -30,7 +30,7 @@ <date></date> <rev></rev> </header> - <module>unicode</module> + <module since="">unicode</module> <modulesummary>Functions for converting Unicode characters.</modulesummary> <description> <p>This module contains functions for converting between different character @@ -50,8 +50,35 @@ external entities where this is required. When working inside the Erlang/OTP environment, it is recommended to keep binaries in UTF-8 when representing Unicode characters. ISO Latin-1 encoding is supported both - for backward compatibility and for communication - with external entities not supporting Unicode character sets.</p> + for backward compatibility and for communication + with external entities not supporting Unicode character sets.</p> + <p>Programs should always operate on a normalized form and compare + canonical-equivalent Unicode characters as equal. All characters + should thus be normalized to one form once on the system borders. + One of the following functions can convert characters to their + normalized forms <seealso marker="#characters_to_nfc_list/1"> + <c>characters_to_nfc_list/1</c></seealso>, + <seealso marker="#characters_to_nfc_binary/1"> + <c>characters_to_nfc_binary/1</c></seealso>, + <seealso marker="#characters_to_nfd_list/1"> + <c>characters_to_nfd_list/1</c></seealso> or + <seealso marker="#characters_to_nfd_binary/1"> + <c>characters_to_nfd_binary/1</c></seealso>. + For general text + <seealso marker="#characters_to_nfc_list/1"> + <c>characters_to_nfc_list/1</c></seealso> or + <seealso marker="#characters_to_nfc_binary/1"> + <c>characters_to_nfc_binary/1</c></seealso> is preferred, and + for identifiers one of the compatibility normalization + functions, such as + <seealso marker="#characters_to_nfkc_list/1"> + <c>characters_to_nfkc_list/1</c></seealso>, + is preferred for security reasons. + The normalization functions where introduced in OTP 20. + Additional information on normalization can be found in the + <url href="http://unicode.org/faq/normalization.html">Unicode FAQ</url>. + </p> + </description> <datatypes> @@ -112,7 +139,7 @@ <funcs> <func> - <name name="bom_to_encoding" arity="1"/> + <name name="bom_to_encoding" arity="1" since=""/> <fsummary>Identify UTF byte order marks in a binary.</fsummary> <type name="endian"/> <type_desc variable="Bin"> @@ -129,7 +156,7 @@ </func> <func> - <name name="characters_to_binary" arity="1"/> + <name name="characters_to_binary" arity="1" since=""/> <fsummary>Convert a collection of characters to a UTF-8 binary.</fsummary> <desc> <p>Same as <c>characters_to_binary(<anno>Data</anno>, unicode, @@ -138,7 +165,7 @@ </func> <func> - <name name="characters_to_binary" arity="2"/> + <name name="characters_to_binary" arity="2" since=""/> <fsummary>Convert a collection of characters to a UTF-8 binary.</fsummary> <desc> <p>Same as <c>characters_to_binary(<anno>Data</anno>, @@ -147,7 +174,7 @@ </func> <func> - <name name="characters_to_binary" arity="3"/> + <name name="characters_to_binary" arity="3" since=""/> <fsummary>Convert a collection of characters to a UTF-8 binary.</fsummary> <desc> <p>Behaves as <seealso marker="#characters_to_list/2"> @@ -184,7 +211,7 @@ </func> <func> - <name name="characters_to_list" arity="1"/> + <name name="characters_to_list" arity="1" since=""/> <fsummary>Convert a collection of characters to a list of Unicode characters.</fsummary> <desc> @@ -193,7 +220,7 @@ </func> <func> - <name name="characters_to_list" arity="2"/> + <name name="characters_to_list" arity="2" since=""/> <fsummary>Convert a collection of characters to a list of Unicode characters.</fsummary> <desc> @@ -212,8 +239,13 @@ <c><anno>InEncoding</anno></c>.</p> </item> </list> - <p>Only when <c><anno>InEncoding</anno></c> is one of the UTF - encodings, integers in the list are allowed to be > 255.</p> + <p> + Note that integers in the list always represent code points + regardless of <c><anno>InEncoding</anno></c> passed. If + <c><anno>InEncoding</anno> latin1</c> is passed, only code + points < 256 are allowed; otherwise, all valid unicode code + points are allowed. + </p> <p>If <c><anno>InEncoding</anno></c> is <c>latin1</c>, parameter <c><anno>Data</anno></c> corresponds to the <c>iodata()</c> type, but for <c>unicode</c>, parameter <c><anno>Data</anno></c> can @@ -335,7 +367,155 @@ decode_data(Data) -> </func> <func> - <name name="encoding_to_bom" arity="1"/> + <name name="characters_to_nfc_list" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a list of canonical equivalent + composed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Composed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding. + </p> + <p>The result is a list of characters.</p> + <code> +3> unicode:characters_to_nfc_list([<<"abc..a">>,[778],$a,[776],$o,[776]]). +"abc..åäö" +</code> + </desc> + </func> + + <func> + <name name="characters_to_nfc_binary" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a utf8 binary of canonical equivalent + composed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Composed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding.</p> + <p>The result is an utf8 encoded binary.</p> + <code> +4> unicode:characters_to_nfc_binary([<<"abc..a">>,[778],$a,[776],$o,[776]]). +<<"abc..åäö"/utf8>> +</code> + </desc> + </func> + + <func> + <name name="characters_to_nfd_list" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a list of canonical equivalent + decomposed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Decomposed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding. + </p> + <p>The result is a list of characters.</p> + <code> +1> unicode:characters_to_nfd_list("abc..åäö"). +[97,98,99,46,46,97,778,97,776,111,776] +</code> + </desc> + </func> + + <func> + <name name="characters_to_nfd_binary" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a utf8 binary of canonical equivalent + decomposed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of canonical equivalent Decomposed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding.</p> + <p>The result is an utf8 encoded binary.</p> + <code> +2> unicode:characters_to_nfd_binary("abc..åäö"). +<<97,98,99,46,46,97,204,138,97,204,136,111,204,136>> +</code> + </desc> + </func> + + <func> + <name name="characters_to_nfkc_list" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a list of canonical equivalent + composed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Composed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding. + </p> + <p>The result is a list of characters.</p> + <code> +3> unicode:characters_to_nfkc_list([<<"abc..a">>,[778],$a,[776],$o,[776],[65299,65298]]). +"abc..åäö32" +</code> + </desc> + </func> + + <func> + <name name="characters_to_nfkc_binary" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a utf8 binary of compatibly equivalent + composed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Composed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding.</p> + <p>The result is an utf8 encoded binary.</p> + <code> +4> unicode:characters_to_nfkc_binary([<<"abc..a">>,[778],$a,[776],$o,[776],[65299,65298]]). +<<"abc..åäö32"/utf8>> +</code> + </desc> + </func> + + <func> + <name name="characters_to_nfkd_list" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a list of compatibly equivalent + decomposed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Decomposed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding. + </p> + <p>The result is a list of characters.</p> + <code> +1> unicode:characters_to_nfkd_list(["abc..åäö",[65299,65298]]). +[97,98,99,46,46,97,778,97,776,111,776,51,50] +</code> + </desc> + </func> + + <func> + <name name="characters_to_nfkd_binary" arity="1" since="OTP 20.0"/> + <fsummary>Normalize characters to a utf8 binary of compatibly equivalent + decomposed Unicode characters.</fsummary> + <desc> + <p>Converts a possibly deep list of characters and binaries + into a Normalized Form of compatibly equivalent Decomposed + characters according to the Unicode standard.</p> + <p>Any binaries in the input must be encoded with utf8 + encoding.</p> + <p>The result is an utf8 encoded binary.</p> + <code> +2> unicode:characters_to_nfkd_binary(["abc..åäö",[65299,65298]]). +<<97,98,99,46,46,97,204,138,97,204,136,111,204,136,51,50>> +</code> + </desc> + </func> + + <func> + <name name="encoding_to_bom" arity="1" since=""/> <fsummary>Create a binary UTF byte order mark from encoding.</fsummary> <type_desc variable="Bin"> A <c>binary()</c> such that <c>byte_size(<anno>Bin</anno>) >= 4</c>. diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index efc8b75075..789e063c12 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>2016</year> + <year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -62,6 +62,13 @@ <item><p>In Erlang/OTP 17.0, the encoding default for Erlang source files was switched to UTF-8.</p></item> + + <item><p>In Erlang/OTP 20.0, atoms and function can contain + Unicode characters. Module names, application names, and node + names are still restricted to the ISO Latin-1 range.</p> + <p>Support was added for normalizations forms in + <c>unicode</c> and the <c>string</c> module now handles + utf8-encoded binaries.</p></item> </list> <p>This section outlines the current Unicode support and gives some @@ -106,23 +113,27 @@ </item> </list> - <p>So, a conversion function must know not only one character at a time, - but possibly the whole sentence, the natural language to translate to, - the differences in input and output string length, and so on. - Erlang/OTP has currently no Unicode <c>to_upper</c>/<c>to_lower</c> - functionality, but publicly available libraries address these issues.</p> - - <p>Another example is the accented characters, where the same glyph has two - different representations. The Swedish letter "ö" is one example. - The Unicode standard has a code point for it, but you can also write it - as "o" followed by "U+0308" (Combining Diaeresis, with the simplified - meaning that the last letter is to have "¨" above). They have the same - glyph. They are for most purposes the same, but have different - representations. For example, MacOS X converts all filenames to use - Combining Diaeresis, while most other programs (including Erlang) try to - hide that by doing the opposite when, for example, listing directories. - However it is done, it is usually important to normalize such - characters to avoid confusion.</p> + <p>So, a conversion function must know not only one character at a + time, but possibly the whole sentence, the natural language to + translate to, the differences in input and output string length, + and so on. Erlang/OTP has currently no Unicode + <c>uppercase</c>/<c>lowercase</c> functionality with language + specific handling, but publicly available libraries address these + issues.</p> + + <p>Another example is the accented characters, where the same + glyph has two different representations. The Swedish letter "ö" is + one example. The Unicode standard has a code point for it, but + you can also write it as "o" followed by "U+0308" (Combining + Diaeresis, with the simplified meaning that the last letter is to + have "¨" above). They have the same glyph, user perceived + character. They are for most purposes the same, but have different + representations. For example, MacOS X converts all filenames to + use Combining Diaeresis, while most other programs (including + Erlang) try to hide that by doing the opposite when, for example, + listing directories. However it is done, it is usually important + to normalize such characters to avoid confusion. + </p> <p>The list of examples can be made long. One need a kind of knowledge that was not needed when programs only considered one or two languages. The @@ -269,7 +280,7 @@ them. In some cases functionality has been added to already existing interfaces (as the <seealso marker="stdlib:string"><c>string</c></seealso> module now can - handle lists with any code points). In some cases new + handle strings with any code points). In some cases new functionality or options have been added (as in the <seealso marker="stdlib:io"><c>io</c></seealso> module, the file handling, the <seealso @@ -339,11 +350,13 @@ <tag>The language</tag> <item> <p>Having the source code in UTF-8 also allows you to write string - literals containing Unicode characters with code points > 255, - although atoms, module names, and function names are restricted to - the ISO Latin-1 range. Binary literals, where you use type + literals, function names, and atoms containing Unicode + characters with code points > 255. + Module names, application names, and node names are still restricted + to the ISO Latin-1 range. Binary literals, where you use type <c>/utf8</c>, can also be expressed using Unicode characters > 255. - Having module names using characters other than 7-bit ASCII can cause + Having module names or application names using characters other than + 7-bit ASCII can cause trouble on operating systems with inconsistent file naming schemes, and can hurt portability, so it is not recommended.</p> <p>EEP 40 suggests that the language is also to allow for Unicode @@ -432,15 +445,17 @@ external_charlist() = maybe_improper_list(char() | external_unicode_binary() | <section> <title>Basic Language Support</title> - <p><marker id="unicode_in_erlang"/>As from Erlang/OTP R16, Erlang source - files can be written in UTF-8 or bytewise (<c>latin1</c>) encoding. For - information about how to state the encoding of an Erlang source file, see - the <seealso marker="stdlib:epp#encoding"><c>epp(3)</c></seealso> module. - Strings and comments can be written using Unicode, but functions must - still be named using characters from the ISO Latin-1 character set, and - atoms are restricted to the same ISO Latin-1 range. These restrictions in - the language are of course independent of the encoding of the source - file.</p> + <p><marker id="unicode_in_erlang"/>As from Erlang/OTP R16, Erlang + source files can be written in UTF-8 or bytewise (<c>latin1</c>) + encoding. For information about how to state the encoding of an + Erlang source file, see the <seealso + marker="stdlib:epp#encoding"><c>epp(3)</c></seealso> module. As + from Erlang/OTP R16, strings and comments can be written using + Unicode. As from Erlang/OTP 20, also atoms and functions can be + written using Unicode. Modules, applications, and nodes must still be + named using characters from the ISO Latin-1 character set. (These + restrictions in the language are independent of the encoding of + the source file.)</p> <section> <title>Bit Syntax</title> @@ -704,8 +719,8 @@ Eshell V5.10.1 (abort with ^G) </section> <section> - <title>Unicode Filenames</title> <marker id="unicode_file_names"/> + <title>Unicode Filenames</title> <p>Most modern operating systems support Unicode filenames in some way. There are many different ways to do this and Erlang by default treats the different approaches differently:</p> @@ -766,7 +781,7 @@ Eshell V5.10.1 (abort with ^G) filenames or directory names. If the file system content is listed, you also get Unicode lists as return value. The support lies in the Kernel and STDLIB modules, which is why - most applications (that does not explicitly require the filenames + most applications (that do not explicitly require the filenames to be in the ISO Latin-1 range) benefit from the Unicode support without change.</p> @@ -840,8 +855,12 @@ Eshell V5.10.1 (abort with ^G) </note> <section> - <title>Notes About Raw Filenames</title> <marker id="notes-about-raw-filenames"/> + <title>Notes About Raw Filenames</title> + <note><p> + Note that raw filenames <em>not</em> necessarily are encoded the + same way as on the OS level. + </p></note> <p>Raw filenames were introduced together with Unicode filename support in ERTS 5.8.2 (Erlang/OTP R14B01). The reason "raw filenames" were introduced in the system was @@ -970,7 +989,7 @@ Eshell V5.10.1 (abort with ^G) <p>Fortunately, most textual data has been stored in lists and range checking has been sparse, so modules like <c>string</c> work well for - Unicode lists with little need for conversion or extension.</p> + Unicode strings with little need for conversion or extension.</p> <p>Some modules are, however, changed to be explicitly Unicode-aware. These modules include:</p> @@ -1021,18 +1040,17 @@ Eshell V5.10.1 (abort with ^G) has extensive support for Unicode text.</p></item> </taglist> - <p>The <seealso marker="stdlib:string"><c>string</c></seealso> module works - perfectly for Unicode strings and ISO Latin-1 strings, except the - language-dependent functions - <seealso marker="stdlib:string#to_upper/1"><c>string:to_upper/1</c></seealso> - and - <seealso marker="stdlib:string#to_lower/1"><c>string:to_lower/1</c></seealso>, - which are only correct for the ISO Latin-1 character set. These two - functions can never function correctly for Unicode characters in their - current form, as there are language and locale issues as well as - multi-character mappings to consider when converting text between cases. - Converting case in an international environment is a large subject not - yet addressed in OTP.</p> + <p>The <seealso marker="stdlib:string"><c>string</c></seealso> + module works perfectly for Unicode strings and ISO Latin-1 + strings, except the language-dependent functions <seealso + marker="stdlib:string#uppercase/1"><c>string:uppercase/1</c></seealso> + and <seealso + marker="stdlib:string#lowercase/1"><c>string:lowercase/1</c></seealso>. + These two functions can never function correctly for Unicode + characters in their current form, as there are language and locale + issues to consider when converting text between cases. Converting + case in an international environment is a large subject not yet + addressed in OTP.</p> </section> <section> diff --git a/lib/stdlib/doc/src/uri_string.xml b/lib/stdlib/doc/src/uri_string.xml new file mode 100644 index 0000000000..ad443486c5 --- /dev/null +++ b/lib/stdlib/doc/src/uri_string.xml @@ -0,0 +1,359 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2017</year><year>2018</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + </legalnotice> + + <title>uri_string</title> + <prepared>Péter Dimitrov</prepared> + <docno>1</docno> + <date>2018-02-07</date> + <rev>A</rev> + </header> + <module since="OTP 21.0">uri_string</module> + <modulesummary>URI processing functions.</modulesummary> + <description> + <p>This module contains functions for parsing and handling URIs + (<url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>) and + form-urlencoded query strings (<url href="https://www.w3.org/TR/html52/">HTML 5.2</url>). + </p> + <p> + Parsing and serializing non-UTF-8 form-urlencoded query strings are also supported + (<url href="https://www.w3.org/TR/html50/">HTML 5.0</url>). + </p> + <p>A URI is an identifier consisting of a sequence of characters matching the syntax + rule named <em>URI</em> in <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>. + </p> + <p> The generic URI syntax consists of a hierarchical sequence of components referred + to as the scheme, authority, path, query, and fragment:</p> + <pre> + URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] + hier-part = "//" authority path-abempty + / path-absolute + / path-rootless + / path-empty + scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) + authority = [ userinfo "@" ] host [ ":" port ] + userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) + + reserved = gen-delims / sub-delims + gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" + sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "=" + + unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + </pre><br></br> + <p>The interpretation of a URI depends only on the characters used and not on how those + characters are represented in a network protocol.</p> + <p>The functions implemented by this module cover the following use cases:</p> + <list type="bulleted"> + <item>Parsing URIs into its components and returing a map<br></br> + <seealso marker="#parse/1"><c>parse/1</c></seealso> + </item> + <item>Recomposing a map of URI components into a URI string<br></br> + <seealso marker="#recompose/1"><c>recompose/1</c></seealso> + </item> + <item>Changing inbound binary and percent-encoding of URIs<br></br> + <seealso marker="#transcode/2"><c>transcode/2</c></seealso> + </item> + <item>Transforming URIs into a normalized form<br></br> + <seealso marker="#normalize/1"><c>normalize/1</c></seealso><br></br> + <seealso marker="#normalize/2"><c>normalize/2</c></seealso> + </item> + <item>Composing form-urlencoded query strings from a list of key-value pairs<br></br> + <seealso marker="#compose_query/1"><c>compose_query/1</c></seealso><br></br> + <seealso marker="#compose_query/2"><c>compose_query/2</c></seealso> + </item> + <item>Dissecting form-urlencoded query strings into a list of key-value pairs<br></br> + <seealso marker="#dissect_query/1"><c>dissect_query/1</c></seealso> + </item> + </list> + <p>There are four different encodings present during the handling of URIs:</p> + <list type="bulleted"> + <item>Inbound binary encoding in binaries</item> + <item>Inbound percent-encoding in lists and binaries</item> + <item>Outbound binary encoding in binaries</item> + <item>Outbound percent-encoding in lists and binaries</item> + </list> + <p>Functions with <c>uri_string()</c> argument accept lists, binaries and + mixed lists (lists with binary elements) as input type. All of the functions but + <c>transcode/2</c> expects input as lists of unicode codepoints, UTF-8 encoded binaries + and UTF-8 percent-encoded URI parts ("%C3%B6" corresponds to the unicode character "ö").</p> + <p>Unless otherwise specified the return value type and encoding are the same as the input + type and encoding. That is, binary input returns binary output, list input returns a list + output but mixed input returns list output.</p> + <p>In case of lists there is only percent-encoding. In binaries, however, both binary encoding + and percent-encoding shall be considered. <c>transcode/2</c> provides the means to convert + between the supported encodings, it takes a <c>uri_string()</c> and a list of options + specifying inbound and outbound encodings.</p> + <p><url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> does not mandate any specific + character encoding and it is usually defined by the protocol or surrounding text. This library + takes the same assumption, binary and percent-encoding are handled as one configuration unit, + they cannot be set to different values.</p> + </description> + + <datatypes> + <datatype> + <name name="error"/> + <desc> + <p>Error tuple indicating the type of error. Possible values of the second component:</p> + <list type="bulleted"> + <item><c>invalid_character</c></item> + <item><c>invalid_encoding</c></item> + <item><c>invalid_input</c></item> + <item><c>invalid_map</c></item> + <item><c>invalid_percent_encoding</c></item> + <item><c>invalid_scheme</c></item> + <item><c>invalid_uri</c></item> + <item><c>invalid_utf8</c></item> + <item><c>missing_value</c></item> + </list> + <p>The third component is a term providing additional information about the + cause of the error.</p> + </desc> + </datatype> + <datatype> + <name name="uri_map"/> + <desc> + <p>Map holding the main components of a URI.</p> + </desc> + </datatype> + <datatype> + <name name="uri_string"/> + <desc> + <p>List of unicode codepoints, a UTF-8 encoded binary, or a mix of the two, + representing an <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> + compliant URI (<em>percent-encoded form</em>). + A URI is a sequence of characters from a very limited set: the letters of + the basic Latin alphabet, digits, and a few special characters.</p> + </desc> + </datatype> + </datatypes> + + <funcs> + + <func> + <name name="compose_query" arity="1" since="OTP 21.0"/> + <fsummary>Compose urlencoded query string.</fsummary> + <desc> + <p>Composes a form-urlencoded <c><anno>QueryString</anno></c> based on a + <c><anno>QueryList</anno></c>, a list of non-percent-encoded key-value pairs. + Form-urlencoding is defined in section + 4.10.21.6 of the <url href="https://www.w3.org/TR/html52/">HTML 5.2</url> + specification and in section 4.10.22.6 of the + <url href="https://www.w3.org/TR/html50/">HTML 5.0</url> specification for + non-UTF-8 encodings. + </p> + <p>See also the opposite operation <seealso marker="#dissect_query/1"> + <c>dissect_query/1</c></seealso>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>uri_string:compose_query([{"foo bar","1"},{"city","örebro"}]).</input> +<![CDATA["foo+bar=1&city=%C3%B6rebro"]]> +2> <![CDATA[uri_string:compose_query([{<<"foo bar">>,<<"1">>}, +2> {<<"city">>,<<"örebro"/utf8>>}]).]]> +<![CDATA[<<"foo+bar=1&city=%C3%B6rebro">>]]> + </pre> + </desc> + </func> + + <func> + <name name="compose_query" arity="2" since="OTP 21.0"/> + <fsummary>Compose urlencoded query string.</fsummary> + <desc> + <p>Same as <c>compose_query/1</c> but with an additional + <c><anno>Options</anno></c> parameter, that controls the encoding ("charset") + used by the encoding algorithm. There are two supported encodings: <c>utf8</c> + (or <c>unicode</c>) and <c>latin1</c>. + </p> + <p>Each character in the entry's name and value that cannot be expressed using + the selected character encoding, is replaced by a string consisting of a U+0026 + AMPERSAND character (<![CDATA[&]]>), a "#" (U+0023) character, one or more ASCII + digits representing the Unicode code point of the character in base ten, and + finally a ";" (U+003B) character. + </p> + <p>Bytes that are out of the range 0x2A, 0x2D, 0x2E, 0x30 to 0x39, 0x41 to 0x5A, 0x5F, + 0x61 to 0x7A, are percent-encoded (U+0025 PERCENT SIGN character (%) followed by + uppercase ASCII hex digits representing the hexadecimal value of the byte). + </p> + <p>See also the opposite operation <seealso marker="#dissect_query/1"> + <c>dissect_query/1</c></seealso>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>uri_string:compose_query([{"foo bar","1"},{"city","örebro"}],</input> +1> [{encoding, latin1}]). +<![CDATA["foo+bar=1&city=%F6rebro" +2> uri_string:compose_query([{<<"foo bar">>,<<"1">>}, +2> {<<"city">>,<<"東京"/utf8>>}], [{encoding, latin1}]).]]> +<![CDATA[<<"foo+bar=1&city=%26%2326481%3B%26%2320140%3B">>]]> + </pre> + </desc> + </func> + + <func> + <name name="dissect_query" arity="1" since="OTP 21.0"/> + <fsummary>Dissect query string.</fsummary> + <desc> + <p>Dissects an urlencoded <c><anno>QueryString</anno></c> and returns a + <c><anno>QueryList</anno></c>, a list of non-percent-encoded key-value pairs. + Form-urlencoding is defined in section + 4.10.21.6 of the <url href="https://www.w3.org/TR/html52/">HTML 5.2</url> + specification and in section 4.10.22.6 of the + <url href="https://www.w3.org/TR/html50/">HTML 5.0</url> specification for + non-UTF-8 encodings. + </p> + <p>See also the opposite operation <seealso marker="#compose_query/1"> + <c>compose_query/1</c></seealso>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input><![CDATA[uri_string:dissect_query("foo+bar=1&city=%C3%B6rebro").]]></input> +[{"foo bar","1"},{"city","örebro"}] +2> <![CDATA[uri_string:dissect_query(<<"foo+bar=1&city=%26%2326481%3B%26%2320140%3B">>).]]> +<![CDATA[[{<<"foo bar">>,<<"1">>}, + {<<"city">>,<<230,157,177,228,186,172>>}] ]]> + </pre> + </desc> + </func> + + <func> + <name name="normalize" arity="1" since="OTP 21.0"/> + <fsummary>Syntax-based normalization.</fsummary> + <desc> + <p>Transforms an <c><anno>URI</anno></c> into a normalized form + using Syntax-Based Normalization as defined by + <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>.</p> + <p>This function implements case normalization, percent-encoding + normalization, path segment normalization and scheme based normalization + for HTTP(S) with basic support for FTP, SSH, SFTP and TFTP.</p> + <p><em>Example:</em></p> + <pre> +1> <input>uri_string:normalize("/a/b/c/./../../g").</input> +"/a/g" +2> <![CDATA[uri_string:normalize(<<"mid/content=5/../6">>).]]> +<![CDATA[<<"mid/6">>]]> +3> uri_string:normalize("http://localhost:80"). +"https://localhost/" +4> <input>uri_string:normalize(#{scheme => "http",port => 80,path => "/a/b/c/./../../g",</input> +4> host => "localhost-örebro"}). +"http://localhost-%C3%B6rebro/a/g" + </pre> + </desc> + </func> + + <func> + <name name="normalize" arity="2" since="OTP 21.0"/> + <fsummary>Syntax-based normalization.</fsummary> + <desc> + <p>Same as <c>normalize/1</c> but with an additional + <c><anno>Options</anno></c> parameter, that controls if the normalized URI + shall be returned as an uri_map(). + There is one supported option: <c>return_map</c>. + </p> + <p><em>Example:</em></p> + <pre> +1> <input>uri_string:normalize("/a/b/c/./../../g", [return_map]).</input> +#{path => "/a/g"} +2> <![CDATA[uri_string:normalize(<<"mid/content=5/../6">>, [return_map]).]]> +<![CDATA[#{path => <<"mid/6">>}]]> +3> uri_string:normalize("http://localhost:80", [return_map]). +#{scheme => "http",path => "/",host => "localhost"} +4> <input>uri_string:normalize(#{scheme => "http",port => 80,path => "/a/b/c/./../../g",</input> +4> host => "localhost-örebro"}, [return_map]). +#{scheme => "http",path => "/a/g",host => "localhost-örebro"} + </pre> + </desc> + </func> + + <func> + <name name="parse" arity="1" since="OTP 21.0"/> + <fsummary>Parse URI into a map.</fsummary> + <desc> + <p>Parses an <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> + compliant <c>uri_string()</c> into a <c>uri_map()</c>, that holds the parsed + components of the <c>URI</c>. + If parsing fails, an error tuple is returned.</p> + <p>See also the opposite operation <seealso marker="#recompose/1"> + <c>recompose/1</c></seealso>.</p> + <p><em>Example:</em></p> + <pre> +1> <input>uri_string:parse("foo://[email protected]:8042/over/there?name=ferret#nose").</input> +#{fragment => "nose",host => "example.com", + path => "/over/there",port => 8042,query => "name=ferret", + scheme => foo,userinfo => "user"} +2> <![CDATA[uri_string:parse(<<"foo://[email protected]:8042/over/there?name=ferret">>).]]> +<![CDATA[#{host => <<"example.com">>,path => <<"/over/there">>, + port => 8042,query => <<"name=ferret">>,scheme => <<"foo">>, + userinfo => <<"user">>}]]> + </pre> + </desc> + </func> + + <func> + <name name="recompose" arity="1" since="OTP 21.0"/> + <fsummary>Recompose URI.</fsummary> + <desc> + <p>Creates an <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> compliant + <c><anno>URIString</anno></c> (percent-encoded), based on the components of + <c><anno>URIMap</anno></c>. + If the <c><anno>URIMap</anno></c> is invalid, an error tuple is returned.</p> + <p>See also the opposite operation <seealso marker="#parse/1"> + <c>parse/1</c></seealso>.</p> + <p><em>Example:</em></p> + <pre> +1> <input>URIMap = #{fragment => "nose", host => "example.com", path => "/over/there",</input> +1> port => 8042, query => "name=ferret", scheme => "foo", userinfo => "user"}. +#{fragment => "top",host => "example.com", + path => "/over/there",port => 8042,query => "?name=ferret", + scheme => foo,userinfo => "user"} + +2> <input>uri_string:recompose(URIMap).</input> +"foo://example.com:8042/over/there?name=ferret#nose"</pre> + </desc> + </func> + + <func> + <name name="transcode" arity="2" since="OTP 21.0"/> + <fsummary>Transcode URI.</fsummary> + <desc> + <p>Transcodes an <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> + compliant <c><anno>URIString</anno></c>, + where <c><anno>Options</anno></c> is a list of tagged tuples, specifying the inbound + (<c>in_encoding</c>) and outbound (<c>out_encoding</c>) encodings. <c>in_encoding</c> + and <c>out_encoding</c> specifies both binary encoding and percent-encoding for the + input and output data. Mixed encoding, where binary encoding is not the same as + percent-encoding, is not supported. + If an argument is invalid, an error tuple is returned.</p> + <p><em>Example:</em></p> + <pre> +1> <input><![CDATA[uri_string:transcode(<<"foo%00%00%00%F6bar"/utf32>>,]]></input> +1> [{in_encoding, utf32},{out_encoding, utf8}]). +<![CDATA[<<"foo%C3%B6bar"/utf8>>]]> +2> uri_string:transcode("foo%F6bar", [{in_encoding, latin1}, +2> {out_encoding, utf8}]). +"foo%C3%B6bar" + </pre> + </desc> + </func> + + </funcs> +</erlref> diff --git a/lib/stdlib/doc/src/user_guide.gif b/lib/stdlib/doc/src/user_guide.gif Binary files differdeleted file mode 100644 index e6275a803d..0000000000 --- a/lib/stdlib/doc/src/user_guide.gif +++ /dev/null diff --git a/lib/stdlib/doc/src/win32reg.xml b/lib/stdlib/doc/src/win32reg.xml index f4a4fa1626..5e2aed6062 100644 --- a/lib/stdlib/doc/src/win32reg.xml +++ b/lib/stdlib/doc/src/win32reg.xml @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>win32reg.xml</file> </header> - <module>win32reg</module> + <module since="">win32reg</module> <modulesummary>Provides access to the registry on Windows.</modulesummary> <description> <p>This module provides read and write access to the @@ -112,7 +112,7 @@ hkdd HKEY_DYN_DATA</pre> <funcs> <func> - <name name="change_key" arity="2"/> + <name name="change_key" arity="2" since=""/> <fsummary>Move to a key in the registry.</fsummary> <desc> <p>Changes the current key to another key. Works like <c>cd</c>. @@ -122,7 +122,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="change_key_create" arity="2"/> + <name name="change_key_create" arity="2" since=""/> <fsummary>Move to a key, create it if it is not there.</fsummary> <desc> <p>Creates a key, or just changes to it, if it is already there. Works @@ -133,7 +133,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="close" arity="1"/> + <name name="close" arity="1" since=""/> <fsummary>Close the registry.</fsummary> <desc> <p>Closes the registry. After that, the <c><anno>RegHandle</anno></c> @@ -142,7 +142,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="current_key" arity="1"/> + <name name="current_key" arity="1" since=""/> <fsummary>Return the path to the current key.</fsummary> <desc> <p>Returns the path to the current key. This is the equivalent of @@ -153,7 +153,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="delete_key" arity="1"/> + <name name="delete_key" arity="1" since=""/> <fsummary>Delete the current key.</fsummary> <desc> <p>Deletes the current key, if it is valid. Calls the Win32 API @@ -166,7 +166,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="delete_value" arity="2"/> + <name name="delete_value" arity="2" since=""/> <fsummary>Delete the named value on the current key.</fsummary> <desc> <p>Deletes a named value on the current key. The atom <c>default</c> is @@ -176,7 +176,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="expand" arity="1"/> + <name name="expand" arity="1" since=""/> <fsummary>Expand a string with environment variables.</fsummary> <desc> <p>Expands a string containing environment variables between percent @@ -189,7 +189,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="format_error" arity="1"/> + <name name="format_error" arity="1" since=""/> <fsummary>Convert a POSIX error code to a string.</fsummary> <desc> <p>Converts a POSIX error code to a string @@ -198,7 +198,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="open" arity="1"/> + <name name="open" arity="1" since=""/> <fsummary>Open the registry for reading or writing.</fsummary> <desc> <p>Opens the registry for reading or writing. The current key is the @@ -211,7 +211,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="set_value" arity="3"/> + <name name="set_value" arity="3" since=""/> <fsummary>Set value at the current registry key with specified name. </fsummary> <desc> @@ -230,7 +230,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="sub_keys" arity="1"/> + <name name="sub_keys" arity="1" since=""/> <fsummary>Get subkeys to the current key.</fsummary> <desc> <p>Returns a list of subkeys to the current key. Calls the Win32 @@ -240,7 +240,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="value" arity="2"/> + <name name="value" arity="2" since=""/> <fsummary>Get the named value on the current key.</fsummary> <desc> <p>Retrieves the named value (or default) on the current key. @@ -251,7 +251,7 @@ hkdd HKEY_DYN_DATA</pre> </func> <func> - <name name="values" arity="1"/> + <name name="values" arity="1" since=""/> <fsummary>Get all values on the current key.</fsummary> <desc> <p>Retrieves a list of all values on the current key. The values diff --git a/lib/stdlib/doc/src/zip.xml b/lib/stdlib/doc/src/zip.xml index 0b5eac1e16..bb2ed7727a 100644 --- a/lib/stdlib/doc/src/zip.xml +++ b/lib/stdlib/doc/src/zip.xml @@ -32,7 +32,7 @@ <rev>PA1</rev> <file>zip.xml</file> </header> - <module>zip</module> + <module since="">zip</module> <modulesummary>Utility for reading and creating 'zip' archives. </modulesummary> <description> @@ -180,7 +180,7 @@ <funcs> <func> - <name name="foldl" arity="3"/> + <name name="foldl" arity="3" since="OTP R14B"/> <fsummary>Fold a function over all files in a zip archive.</fsummary> <desc> <p>Calls <c><anno>Fun</anno>(<anno>FileInArchive</anno>, <anno>GetInfo @@ -234,10 +234,10 @@ </func> <func> - <name name="list_dir" arity="1"/> - <name name="list_dir" arity="2"/> - <name name="table" arity="1" /> - <name name="table" arity="2"/> + <name name="list_dir" arity="1" since=""/> + <name name="list_dir" arity="2" since=""/> + <name name="table" arity="1" since=""/> + <name name="table" arity="2" since=""/> <fsummary>Retrieve the name of all files in a zip archive.</fsummary> <desc> <p><c>list_dir/1</c> retrieves all filenames in the zip archive @@ -263,7 +263,7 @@ </func> <func> - <name name="t" arity="1"/> + <name name="t" arity="1" since=""/> <fsummary>Print the name of each file in a zip archive.</fsummary> <desc> <p>Prints all filenames in the zip archive <c><anno>Archive</anno></c> @@ -272,7 +272,7 @@ </func> <func> - <name name="tt" arity="1"/> + <name name="tt" arity="1" since=""/> <fsummary>Print name and information for each file in a zip archive. </fsummary> <desc> @@ -283,10 +283,10 @@ </func> <func> - <name name="unzip" arity="1"/> - <name name="unzip" arity="2"/> - <name name="extract" arity="1"/> - <name name="extract" arity="2"/> + <name name="unzip" arity="1" since=""/> + <name name="unzip" arity="2" since=""/> + <name name="extract" arity="1" since=""/> + <name name="extract" arity="2" since=""/> <fsummary>Extract files from a zip archive.</fsummary> <desc> <p><c>unzip/1</c> extracts all files from a zip archive.</p> @@ -353,10 +353,10 @@ </func> <func> - <name name="zip" arity="2"/> - <name name="zip" arity="3"/> - <name name="create" arity="2"/> - <name name="create" arity="3"/> + <name name="zip" arity="2" since=""/> + <name name="zip" arity="3" since=""/> + <name name="create" arity="2" since=""/> + <name name="create" arity="3" since=""/> <fsummary>Create a zip archive with options.</fsummary> <desc> <p>Creates a zip archive containing the files specified in @@ -481,7 +481,7 @@ </func> <func> - <name name="zip_close" arity="1"/> + <name name="zip_close" arity="1" since=""/> <fsummary>Close an open archive.</fsummary> <desc> <p>Closes a zip archive, previously opened with @@ -492,8 +492,8 @@ </func> <func> - <name name="zip_get" arity="1"/> - <name name="zip_get" arity="2"/> + <name name="zip_get" arity="1" since=""/> + <name name="zip_get" arity="2" since=""/> <fsummary>Extract files from an open archive.</fsummary> <desc> <p>Extracts one or all files from an open archive.</p> @@ -505,7 +505,7 @@ </func> <func> - <name name="zip_list_dir" arity="1"/> + <name name="zip_list_dir" arity="1" since=""/> <fsummary>Return a table of files in open zip archive.</fsummary> <desc> <p>Returns the file list of an open zip archive. The first returned @@ -514,8 +514,8 @@ </func> <func> - <name name="zip_open" arity="1"/> - <name name="zip_open" arity="2"/> + <name name="zip_open" arity="1" since=""/> + <name name="zip_open" arity="2" since=""/> <fsummary>Open an archive and return a handle to it.</fsummary> <desc> <p>Opens a zip archive, and reads and saves its directory. This |
