diff options
Diffstat (limited to 'lib/stdlib/doc')
67 files changed, 3431 insertions, 1728 deletions
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index e7ea38c5c3..4541b4a463 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2017. 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,6 +97,7 @@ XML_REF3_FILES = \ sys.xml \ timer.xml \ unicode.xml \ + uri_string.xml \ win32reg.xml \ zip.xml @@ -155,6 +155,7 @@ 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) @@ -162,7 +163,7 @@ clean clean_docs: 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 # ---------------------------------------------------- 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 33f29f38da..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>2017</year> + <year>2012</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -46,7 +46,7 @@ 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, 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 26d0724aaf..8bb4cf9101 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -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 @@ -180,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> @@ -267,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> @@ -275,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> @@ -283,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 @@ -293,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 @@ -312,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 @@ -327,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> @@ -341,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 @@ -359,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"/> @@ -398,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 @@ -409,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> @@ -422,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 @@ -449,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 @@ -458,7 +458,7 @@ 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> @@ -470,7 +470,7 @@ CryptoKeyFun(clear) -> term()</code> </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> @@ -483,7 +483,7 @@ CryptoKeyFun(clear) -> term()</code> </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> @@ -497,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 7666699183..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,9 +50,9 @@ </func> <func> - <name name="c" arity="1"/> - <name name="c" arity="2"/> - <name name="c" arity="3"/> + <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 module. @@ -80,7 +80,7 @@ </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 @@ -94,7 +94,16 @@ </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> @@ -102,7 +111,7 @@ </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, @@ -111,8 +120,8 @@ </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 @@ -122,7 +131,7 @@ </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 @@ -132,7 +141,7 @@ </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 @@ -145,7 +154,7 @@ </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> @@ -162,7 +171,7 @@ </func> <func> - <name name="lm" 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>). @@ -171,7 +180,7 @@ </func> <func> - <name name="ls" arity="0"/> + <name name="ls" arity="0" since=""/> <fsummary>List files in the current directory.</fsummary> <desc> <p>Lists files in the current directory.</p> @@ -179,7 +188,7 @@ </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> @@ -188,7 +197,7 @@ </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 @@ -197,7 +206,7 @@ </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> @@ -205,7 +214,7 @@ </func> <func> - <name name="mm" 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 @@ -214,7 +223,7 @@ </func> <func> - <name name="memory" arity="0"/> + <name name="memory" arity="0" since=""/> <fsummary>Memory allocation information.</fsummary> <desc> <p>Memory allocation information. Equivalent to @@ -223,8 +232,8 @@ </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 @@ -233,8 +242,8 @@ </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. @@ -246,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> @@ -254,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>, @@ -264,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> @@ -272,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, @@ -281,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 @@ -292,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 @@ -301,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> @@ -316,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> @@ -335,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 eb6e32aecf..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 @@ -188,7 +188,7 @@ <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> @@ -197,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> @@ -227,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 @@ -239,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> @@ -249,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. @@ -259,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 @@ -270,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> @@ -295,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 @@ -309,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> @@ -322,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> @@ -354,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> @@ -455,8 +455,8 @@ </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> @@ -516,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>. @@ -527,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>. @@ -539,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 @@ -554,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> @@ -563,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> @@ -590,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> @@ -606,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> @@ -622,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> @@ -654,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> @@ -667,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> @@ -683,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> @@ -702,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> @@ -735,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>, @@ -746,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 @@ -760,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, @@ -770,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 @@ -872,7 +872,7 @@ ok </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 @@ -883,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> @@ -917,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 @@ -945,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> @@ -962,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> @@ -984,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> @@ -1019,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> @@ -1036,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> @@ -1049,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> @@ -1064,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 @@ -1140,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> @@ -1153,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> @@ -1192,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 c229a18721..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,7 @@ </func> <func> - <name name="take" 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 @@ -116,7 +116,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>Dict2</anno></c> is a dictionary of all keys and values in @@ -127,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 @@ -139,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 @@ -153,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 @@ -162,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 @@ -171,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 @@ -180,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 @@ -190,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 @@ -209,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> @@ -217,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 @@ -226,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 @@ -237,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> @@ -245,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 @@ -255,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 @@ -269,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 db96beed6c..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> @@ -183,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 @@ -204,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 @@ -213,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 @@ -222,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 @@ -252,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 @@ -265,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 @@ -274,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 @@ -285,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> @@ -303,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 @@ -312,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> @@ -324,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 @@ -341,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 @@ -357,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 @@ -375,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 @@ -392,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 @@ -401,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 @@ -412,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 @@ -423,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"/> @@ -453,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> @@ -462,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"/> @@ -492,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> @@ -500,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> @@ -508,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 @@ -517,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> @@ -529,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 @@ -540,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>, @@ -553,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 b6aa75ed03..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,7 +42,7 @@ <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 to use explicit tuple 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 17cd0fb240..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,7 @@ <funcs> <func> - <name name="add_predefined_functions" arity="1"/> + <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 @@ -54,7 +54,7 @@ </func> <func> - <name name="arith_op" arity="2"/> + <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> @@ -63,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> @@ -73,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> @@ -82,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> @@ -91,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 @@ -100,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> @@ -109,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 @@ -120,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> @@ -129,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 337028568a..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>2017</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <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> @@ -90,8 +90,8 @@ <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; @@ -127,7 +127,7 @@ <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> @@ -136,6 +136,9 @@ <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> @@ -167,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> @@ -194,7 +233,7 @@ </func> <func> - <name>close(TarDescriptor)</name> + <name since="">close(TarDescriptor)</name> <fsummary>Close an open tar file.</fsummary> <type> <v>TarDescriptor = term()</v> @@ -206,7 +245,7 @@ </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> @@ -225,7 +264,7 @@ </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> @@ -276,7 +315,7 @@ </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() | {binary,binary()} | {file,Fd}</v> @@ -300,7 +339,7 @@ </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> @@ -372,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> @@ -479,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> @@ -526,7 +565,7 @@ 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()|{binary,binary()}|{file,file_descriptor()}</v> @@ -539,7 +578,7 @@ 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> @@ -551,7 +590,7 @@ 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()|{binary,binary()}|{file,file_descriptor()}</v> @@ -563,7 +602,7 @@ 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> diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 51e35cd2df..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>2017</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,14 +49,16 @@ associated with each key. A <c>bag</c> or <c>duplicate_bag</c> table can have many objects associated with each key.</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> before starting the Erlang runtime - system. This hard limit has been removed, but it is currently + <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 @@ -136,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> @@ -205,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 @@ -220,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> @@ -228,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> @@ -238,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>. @@ -248,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 @@ -260,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"> @@ -272,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"> @@ -304,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 @@ -319,7 +369,7 @@ </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. @@ -335,7 +385,7 @@ </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. @@ -351,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> @@ -365,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> @@ -434,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 @@ -452,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> @@ -461,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> @@ -469,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 @@ -487,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> @@ -540,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> @@ -612,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 @@ -642,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 @@ -674,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> @@ -693,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> @@ -725,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> @@ -740,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> @@ -780,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> @@ -803,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 @@ -817,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> @@ -849,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> @@ -864,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> @@ -879,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 @@ -894,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> @@ -913,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> @@ -929,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> @@ -961,7 +1023,7 @@ 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 terms.</fsummary> <desc> @@ -998,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>, @@ -1009,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 @@ -1074,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> @@ -1170,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 @@ -1182,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> @@ -1202,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 @@ -1218,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> @@ -1273,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 @@ -1290,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) -> @@ -1312,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 @@ -1322,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 @@ -1343,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> @@ -1438,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> @@ -1452,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> @@ -1476,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> @@ -1500,7 +1578,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> </func> <func> - <name name="select_replace" arity="2"/> + <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 @@ -1509,7 +1587,7 @@ is_integer(X), is_integer(Y), X + Y < 4711]]></code> 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 iteration as a whole, like all other select functions, + <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> @@ -1539,7 +1617,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </func> <func> - <name name="select_reverse" arity="1"/> + <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"> @@ -1572,7 +1650,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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> @@ -1584,7 +1662,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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> @@ -1602,7 +1680,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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 @@ -1613,7 +1691,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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> @@ -1638,7 +1716,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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 @@ -1649,7 +1727,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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 @@ -1696,7 +1774,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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> @@ -1704,7 +1782,7 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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 @@ -1782,8 +1860,8 @@ Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])), </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 @@ -1859,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> @@ -1874,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> @@ -1901,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> @@ -1912,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"/> @@ -1930,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 @@ -1961,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 @@ -1996,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"/> @@ -2037,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/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 11762a3c5a..5df415834f 100644 --- a/lib/stdlib/doc/src/filelib.xml +++ b/lib/stdlib/doc/src/filelib.xml @@ -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> @@ -70,7 +94,7 @@ <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> @@ -84,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> @@ -92,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 @@ -118,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> @@ -127,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> @@ -137,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> @@ -146,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> @@ -156,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 @@ -193,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> @@ -223,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> @@ -234,8 +263,8 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> </func> <func> - <name name="find_file" arity="2"/> - <name name="find_file" arity="3"/> + <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 @@ -249,7 +278,7 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> </desc> </func> <func> - <name name="find_source" arity="1"/> + <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 @@ -258,8 +287,8 @@ filelib:wildcard("lib/**/*.{erl,hrl}")</code> </desc> </func> <func> - <name name="find_source" arity="2"/> - <name name="find_source" arity="3"/> + <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 diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 1135a6dd80..ae42846c6b 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -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,8 +390,8 @@ 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. @@ -397,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 @@ -407,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> @@ -435,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> @@ -446,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 @@ -465,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> @@ -495,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 @@ -516,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 "." @@ -543,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 @@ -558,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 5cfff021c1..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,7 @@ </func> <func> - <name name="take" arity="2"/> + <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> @@ -120,7 +120,7 @@ </func> <func> - <name name="take_any" arity="2"/> + <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> @@ -131,7 +131,7 @@ </func> <func> - <name name="empty" arity="0"/> + <name name="empty" arity="0" since=""/> <fsummary>Return an empty tree.</fsummary> <desc> <p>Returns a new empty tree.</p> @@ -139,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> @@ -151,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 @@ -160,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 @@ -171,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> @@ -182,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 @@ -191,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, @@ -200,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 @@ -218,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> @@ -233,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> @@ -241,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 @@ -253,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>. @@ -263,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> @@ -275,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>, @@ -288,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> @@ -296,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 @@ -308,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>, @@ -321,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>, @@ -334,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> @@ -342,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> @@ -352,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 012737c390..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>2017</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,9 +349,9 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>start() -> Result</name> - <name>start(EventMgrName | Options) -> Result</name> - <name>start(EventMgrName, Options) -> 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> @@ -375,9 +375,9 @@ gen_event:stop -----> Module:terminate/2 </func> <func> - <name>start_link() -> Result</name> - <name>start_link(EventMgrName | Options) -> Result</name> - <name>start_link(EventMgrName, Options) -> 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> @@ -436,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} @@ -458,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 @@ -475,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} @@ -522,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} @@ -547,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> @@ -576,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> @@ -612,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> @@ -668,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> @@ -699,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> @@ -757,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> @@ -776,7 +775,7 @@ gen_event:stop -----> Module:terminate/2 <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>{noreply, State}</c>.</p> + <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 @@ -789,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> @@ -826,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> diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 7d137fc772..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>2017</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> @@ -166,7 +175,7 @@ gen_server:abcast -----> Module:handle_cast/2 </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> @@ -191,10 +200,10 @@ 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> @@ -239,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> @@ -298,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> @@ -323,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> @@ -352,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> @@ -457,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> @@ -477,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 @@ -500,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> @@ -542,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> @@ -602,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> @@ -610,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> @@ -666,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> @@ -690,13 +703,49 @@ 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> @@ -721,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> @@ -762,7 +811,7 @@ 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> @@ -811,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> diff --git a/lib/stdlib/doc/src/gen_statem.xml b/lib/stdlib/doc/src/gen_statem.xml index 574f488e91..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</year><year>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,34 +111,6 @@ </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 replaces - <seealso marker="gen_fsm"><c>gen_fsm</c> </seealso> in Erlang/OTP 20.0. - It has the same features and adds some really useful: - </p> - <list type="bulleted"> - <item>Gathered 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.</item> - <item>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>, @@ -148,7 +181,7 @@ 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. Note the fact that the callback function @@ -207,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 @@ -252,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> @@ -668,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 @@ -688,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> @@ -701,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> @@ -739,7 +796,7 @@ 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> @@ -753,7 +810,9 @@ handle_event(_, _, State, Data) -> delivered to the state machine before any external 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 @@ -791,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> @@ -816,13 +875,19 @@ 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> @@ -857,7 +922,7 @@ handle_event(_, _, State, Data) -> 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 nor needed to cancel this time-out, @@ -943,7 +1008,9 @@ handle_event(_, _, State, Data) -> 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> + <seealso marker="erts:erlang#start_timer/4"> + <c>erlang:start_timer/4</c> + </seealso> for details. </p> <p> @@ -969,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 @@ -981,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 @@ -994,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> @@ -1066,15 +1141,15 @@ handle_event(_, _, State, Data) -> <seealso marker="#type-transition_option">transition options</seealso>. </p> <taglist> - <tag><c>Timeout</c></tag> + <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 + return value <c>{next_state,NextState,NewData,Time}</c> + allowed like for <c>gen_fsm</c>. </p> </item> <tag><c>timeout</c></tag> @@ -1126,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> @@ -1319,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> @@ -1369,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> @@ -1379,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 let the calling process 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> @@ -1391,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> @@ -1410,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> @@ -1424,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> @@ -1448,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> @@ -1505,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> @@ -1538,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> @@ -1559,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> @@ -1667,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> @@ -1678,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> @@ -1695,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> @@ -1724,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> @@ -1775,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> @@ -1864,7 +1947,7 @@ 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> Initializing process and internal state. </fsummary> @@ -1891,7 +1974,7 @@ handle_event(_, _, State, Data) -> </p> <note> <p> - Note that if the <c>gen_statem</c> is started trough + 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>, @@ -1906,7 +1989,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> </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 @@ -2005,16 +2088,16 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> </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> @@ -2105,16 +2188,20 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> 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 @@ -2129,7 +2216,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> </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> @@ -2199,7 +2286,7 @@ init(Args) -> erlang:error(not_implemented, [Args]).</pre> <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 64fcf4379f..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>2017</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,8 +270,9 @@ 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> @@ -276,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> @@ -301,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 @@ -319,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 @@ -331,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> @@ -454,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> @@ -467,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> @@ -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 bc1d77ac83..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>2017</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> @@ -153,7 +156,32 @@ </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,28 +383,35 @@ </func> <func> - <name name="write" arity="1"/> - <name name="write" arity="2" clause_i="1"/> - <name name="write" arity="2" clause_i="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 @@ -385,7 +420,7 @@ </func> <func> - <name name="write_atom_as_latin1" 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 @@ -395,7 +430,7 @@ </func> <func> - <name name="write_char" arity="1"/> + <name name="write_char" arity="1" since=""/> <fsummary>Write a character.</fsummary> <desc> <p>Returns the list of characters needed to print a character @@ -404,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 @@ -414,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 @@ -423,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 @@ -432,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 @@ -441,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 55227aaee5..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>2017</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,7 +182,7 @@ </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 @@ -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 @@ -842,7 +854,7 @@ splitwith(Pred, List) -> </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 @@ -851,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> @@ -859,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> @@ -872,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> @@ -890,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> @@ -902,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 @@ -915,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> @@ -929,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> @@ -946,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>, @@ -961,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 @@ -971,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 @@ -982,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 @@ -992,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 @@ -1007,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, @@ -1018,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 @@ -1030,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. @@ -1047,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 b4f096217a..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,28 +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="ceil" arity="1"/> - <name name="cos" arity="1"/> - <name name="cosh" arity="1"/> - <name name="exp" arity="1"/> - <name name="floor" arity="1"/> - <name name="fmod" arity="2"/> - <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"/> @@ -82,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> @@ -92,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 @@ -101,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 3c7c8bf400..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>2017</year> + <year>2004</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,639 @@ </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> @@ -1200,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> @@ -7369,4 +8017,3 @@ </section> </section> </chapter> - diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 26bbf499c6..27ccccee7e 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -32,7 +32,7 @@ <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. @@ -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,7 @@ </func> <func> - <name name="take" 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. @@ -122,7 +122,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>Orddict2</anno></c> is a dictionary of all keys and values @@ -133,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 @@ -145,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 @@ -157,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 @@ -166,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, @@ -175,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 @@ -184,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 @@ -193,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 @@ -212,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> @@ -220,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> @@ -229,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 @@ -240,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> @@ -248,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> @@ -258,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> @@ -273,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 7b590932e4..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,7 +32,7 @@ <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> @@ -60,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> @@ -69,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 @@ -78,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 @@ -87,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 @@ -97,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>. @@ -106,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> @@ -114,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 @@ -123,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 @@ -133,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 @@ -142,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 @@ -151,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> @@ -161,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> @@ -169,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> @@ -177,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 @@ -186,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> @@ -194,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> @@ -202,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/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 cb152d1935..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>2017</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> @@ -59,18 +59,17 @@ <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 and do not require SASL to be started. All exceptions are + emulator. All exceptions are converted to <em>exits</em> which are ignored by the default - <c>error_logger</c> handler.</p> + <c>logger</c> handler.</p> <p>The crash report contains the previously stored information, such as ancestors and initial function, the termination reason, and @@ -103,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"> @@ -112,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 @@ -129,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", @@ -141,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 @@ -155,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 @@ -193,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> @@ -223,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"/> @@ -241,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"/> @@ -260,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"/> @@ -285,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 @@ -320,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> @@ -330,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"/> @@ -354,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> @@ -395,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 f9a54bf804..4465103469 100644 --- a/lib/stdlib/doc/src/proplists.xml +++ b/lib/stdlib/doc/src/proplists.xml @@ -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 @@ -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 89fb858823..27d2d99f3c 100644 --- a/lib/stdlib/doc/src/rand.xml +++ b/lib/stdlib/doc/src/rand.xml @@ -32,7 +32,7 @@ <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> @@ -133,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> @@ -168,10 +169,17 @@ R3 = rand:uniform(),</pre> 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> @@ -265,7 +273,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> <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. @@ -274,7 +282,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </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. @@ -283,7 +291,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="jump" 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" /> @@ -298,7 +306,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="jump" arity="1"/> + <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 @@ -310,7 +318,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal" arity="0"/> + <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 @@ -320,7 +328,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal" arity="2"/> + <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 @@ -329,7 +337,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal_s" arity="1"/> + <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 @@ -339,7 +347,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="normal_s" arity="3"/> + <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) @@ -348,7 +356,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </func> <func> - <name name="seed" arity="1"/> + <name name="seed" arity="1" since="OTP 18.0"/> <fsummary>Seed random number generator.</fsummary> <desc> <marker id="seed-1"/> @@ -364,7 +372,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </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 @@ -373,7 +381,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </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> @@ -388,7 +396,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </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 @@ -397,7 +405,7 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> </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> @@ -414,7 +422,8 @@ tests. We suggest to use a sign test to extract a random Boolean value.</pre> 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>. + 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 @@ -432,7 +441,43 @@ end.</pre> </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>, @@ -443,7 +488,7 @@ end.</pre> </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> @@ -460,7 +505,8 @@ end.</pre> 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>. + 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 @@ -478,7 +524,69 @@ end.</pre> </func> <func> - <name name="uniform_s" arity="2"/> + <name name="uniform_real_s" arity="1" since="OTP 21.0"/> + <fsummary>Return a random float.</fsummary> + <desc> + <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" since="OTP 18.0"/> <fsummary>Return a random integer.</fsummary> <desc> <p>Returns, for a specified integer <c><anno>N</anno> >= 1</c> 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 078ca0e38c..b04434492d 100644 --- a/lib/stdlib/doc/src/re.xml +++ b/lib/stdlib/doc/src/re.xml @@ -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 @@ -79,7 +79,7 @@ <funcs> <func> - <name name="version" arity="0"/> + <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> @@ -87,7 +87,7 @@ </func> <func> - <name name="compile" arity="1"/> + <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> @@ -95,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 @@ -304,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 @@ -348,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> @@ -358,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> @@ -408,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> @@ -417,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"> @@ -992,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> @@ -1001,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> 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 4934bed365..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>2017</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. @@ -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 2593d3690b..50a0968531 100644 --- a/lib/stdlib/doc/src/shell.xml +++ b/lib/stdlib/doc/src/shell.xml @@ -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> @@ -874,7 +874,7 @@ q - quit erlang <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> @@ -892,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 @@ -902,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>. @@ -911,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 @@ -921,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. @@ -936,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 @@ -945,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 9d5edd9ecf..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>2017</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,7 +32,7 @@ <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> @@ -111,8 +111,8 @@ <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 Erlang/OTP 21. + are still available but should not be used, they will be + deprecated in a future release. </p> </description> @@ -130,7 +130,7 @@ <funcs> <func> - <name name="casefold" arity="1"/> + <name name="casefold" arity="1" since="OTP 20.0"/> <fsummary>Convert a string to a comparable string.</fsummary> <desc> <p> @@ -147,7 +147,7 @@ </func> <func> - <name name="chomp" arity="1"/> + <name name="chomp" arity="1" since="OTP 20.0"/> <fsummary>Remove trailing end of line control characters.</fsummary> <desc> <p> @@ -164,9 +164,9 @@ </func> <func> - <name name="equal" arity="2"/> - <name name="equal" arity="3"/> - <name name="equal" arity="4"/> + <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> @@ -201,8 +201,8 @@ true</pre> </func> <func> - <name name="find" arity="2"/> - <name name="find" arity="3"/> + <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> @@ -230,7 +230,7 @@ nomatch</pre> </func> <func> - <name name="is_empty" arity="1"/> + <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 @@ -245,7 +245,7 @@ true</pre> </func> <func> - <name name="length" arity="1"/> + <name name="length" arity="1" since="OTP 20.0"/> <fsummary>Calculate length of the string.</fsummary> <desc> <p> @@ -261,7 +261,7 @@ true</pre> </func> <func> - <name name="lexemes" arity="2"/> + <name name="lexemes" arity="2" since="OTP 20.0"/> <fsummary>Split string into lexemes.</fsummary> <desc> <p> @@ -287,7 +287,7 @@ true</pre> </func> <func> - <name name="lowercase" arity="1"/> + <name name="lowercase" arity="1" since="OTP 20.0"/> <fsummary>Convert a string to lowercase</fsummary> <desc> <p> @@ -306,7 +306,7 @@ true</pre> </func> <func> - <name name="next_codepoint" arity="1"/> + <name name="next_codepoint" arity="1" since="OTP 20.0"/> <fsummary>Pick the first codepoint.</fsummary> <desc> <p> @@ -323,7 +323,7 @@ true</pre> </func> <func> - <name name="next_grapheme" arity="1"/> + <name name="next_grapheme" arity="1" since="OTP 20.0"/> <fsummary>Pick the first grapheme cluster.</fsummary> <desc> <p> @@ -340,7 +340,7 @@ true</pre> </func> <func> - <name name="nth_lexeme" arity="3"/> + <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 @@ -355,9 +355,9 @@ true</pre> </func> <func> - <name name="pad" arity="2"/> - <name name="pad" arity="3"/> - <name name="pad" arity="4"/> + <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> @@ -381,7 +381,7 @@ true</pre> </func> <func> - <name name="prefix" arity="2"/> + <name name="prefix" arity="2" since="OTP 20.0"/> <fsummary>Remove prefix from string.</fsummary> <desc> <p> @@ -400,8 +400,8 @@ nomatch</pre> </func> <func> - <name name="replace" arity="3"/> - <name name="replace" arity="4"/> + <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> @@ -423,7 +423,7 @@ nomatch</pre> </func> <func> - <name name="reverse" arity="1"/> + <name name="reverse" arity="1" since="OTP 20.0"/> <fsummary>Reverses a string</fsummary> <desc> <p> @@ -439,8 +439,8 @@ ÖÄÅ</pre> </func> <func> - <name name="slice" arity="2"/> - <name name="slice" arity="3"/> + <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 @@ -459,8 +459,8 @@ ÖÄÅ</pre> </func> <func> - <name name="split" arity="2"/> - <name name="split" arity="3"/> + <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> @@ -482,9 +482,9 @@ ÖÄÅ</pre> </func> <func> - <name name="take" arity="2"/> - <name name="take" arity="3"/> - <name name="take" arity="4"/> + <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 @@ -508,7 +508,7 @@ ÖÄÅ</pre> </func> <func> - <name name="titlecase" arity="1"/> + <name name="titlecase" arity="1" since="OTP 20.0"/> <fsummary>Convert a string to titlecase.</fsummary> <desc> <p> @@ -522,7 +522,7 @@ ÖÄÅ</pre> </func> <func> - <name name="to_float" arity="1"/> + <name name="to_float" arity="1" since=""/> <fsummary>Return a float whose text representation is the integers (ASCII values) of a string.</fsummary> <desc> @@ -544,7 +544,7 @@ ÖÄÅ</pre> </func> <func> - <name name="to_integer" arity="1"/> + <name name="to_integer" arity="1" since=""/> <fsummary>Return an integer whose text representation is the integers (ASCII values) of a string.</fsummary> <desc> @@ -566,7 +566,7 @@ ÖÄÅ</pre> </func> <func> - <name name="to_graphemes" arity="1"/> + <name name="to_graphemes" arity="1" since="OTP 20.0"/> <fsummary>Convert a string to a list of grapheme clusters.</fsummary> <desc> <p> @@ -582,9 +582,9 @@ ÖÄÅ</pre> </func> <func> - <name name="trim" arity="1"/> - <name name="trim" arity="2"/> - <name name="trim" arity="3"/> + <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> @@ -594,7 +594,7 @@ ÖÄÅ</pre> or <c>both</c>, indicates from which direction characters are to be removed. </p> - <p> Default <c><anno>Characters</anno></c> are the set of + <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>. @@ -616,7 +616,7 @@ ÖÄÅ</pre> </func> <func> - <name name="uppercase" arity="1"/> + <name name="uppercase" arity="1" since="OTP 20.0"/> <fsummary>Convert a string to uppercase.</fsummary> <desc> <p> @@ -641,7 +641,7 @@ ÖÄÅ</pre> <note><p> The functions are kept for backward compatibility, but are not recommended. - They will be deprecated in Erlang/OTP 21. + They will be deprecated in a future release. </p> <p>Any undocumented functions in <c>string</c> are not to be used.</p> </note> @@ -649,8 +649,8 @@ ÖÄÅ</pre> <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 @@ -664,8 +664,8 @@ ÖÄÅ</pre> </func> <func> - <name name="chars" arity="2"/> - <name name="chars" arity="3"/> + <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 @@ -678,7 +678,7 @@ ÖÄÅ</pre> </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> @@ -692,7 +692,7 @@ ÖÄÅ</pre> </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 @@ -712,7 +712,7 @@ ÖÄÅ</pre> </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 @@ -724,7 +724,7 @@ ÖÄÅ</pre> </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 @@ -741,7 +741,7 @@ ÖÄÅ</pre> </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> @@ -757,8 +757,8 @@ ÖÄÅ</pre> </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 @@ -778,7 +778,7 @@ ÖÄÅ</pre> </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> @@ -789,7 +789,7 @@ ÖÄÅ</pre> </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> @@ -803,8 +803,8 @@ ÖÄÅ</pre> </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 @@ -823,7 +823,7 @@ ÖÄÅ</pre> </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 @@ -841,7 +841,7 @@ ÖÄÅ</pre> </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 @@ -858,7 +858,7 @@ ÖÄÅ</pre> </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 @@ -876,9 +876,9 @@ ÖÄÅ</pre> </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 or trailing, or both, blanks or a @@ -898,8 +898,8 @@ ÖÄÅ</pre> </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 @@ -916,8 +916,8 @@ 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 @@ -934,8 +934,8 @@ 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 @@ -952,10 +952,10 @@ sub_string("Hello World", 4, 8). </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"/> @@ -974,7 +974,7 @@ sub_string("Hello World", 4, 8). </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 @@ -994,8 +994,8 @@ sub_string("Hello World", 4, 8). </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 diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index 6d5065ca02..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>2017</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 @@ -208,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 @@ -310,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> @@ -321,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> @@ -358,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 @@ -379,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> @@ -392,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> @@ -428,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"/> @@ -495,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"/> @@ -576,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 @@ -613,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> @@ -658,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> 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 64d8789016..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> @@ -227,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> @@ -265,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 @@ -276,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 @@ -300,8 +302,8 @@ </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 @@ -313,8 +315,8 @@ </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 @@ -325,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> @@ -449,8 +451,8 @@ </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> @@ -458,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 @@ -469,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 @@ -480,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 @@ -492,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 @@ -516,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 @@ -527,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. @@ -539,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 @@ -554,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 @@ -592,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, @@ -603,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> @@ -626,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> @@ -642,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> @@ -659,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> @@ -679,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 350847bf7d..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="kernel: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 d822aca89c..b7696a4b7e 100644 --- a/lib/stdlib/doc/src/unicode.xml +++ b/lib/stdlib/doc/src/unicode.xml @@ -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 @@ -139,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"> @@ -156,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, @@ -165,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>, @@ -174,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"> @@ -211,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> @@ -220,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> @@ -367,7 +367,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfc_list" 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> @@ -386,7 +386,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfc_binary" arity="1"/> + <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> @@ -404,7 +404,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfd_list" arity="1"/> + <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> @@ -423,7 +423,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfd_binary" arity="1"/> + <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> @@ -441,7 +441,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfkc_list" arity="1"/> + <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> @@ -460,7 +460,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfkc_binary" arity="1"/> + <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> @@ -478,7 +478,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfkd_list" arity="1"/> + <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> @@ -497,7 +497,7 @@ decode_data(Data) -> </func> <func> - <name name="characters_to_nfkd_binary" arity="1"/> + <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> @@ -515,7 +515,7 @@ decode_data(Data) -> </func> <func> - <name name="encoding_to_bom" arity="1"/> + <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 26dc46719e..789e063c12 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -719,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> @@ -855,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 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/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 |