aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc')
-rw-r--r--lib/stdlib/doc/src/notes.xml261
1 files changed, 261 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/notes.xml b/lib/stdlib/doc/src/notes.xml
index 87f5335723..76d49e37c2 100644
--- a/lib/stdlib/doc/src/notes.xml
+++ b/lib/stdlib/doc/src/notes.xml
@@ -31,6 +31,267 @@
</header>
<p>This document describes the changes made to the STDLIB application.</p>
+<section><title>STDLIB 3.0</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p> Fix a race bug affecting <c>dets:open_file/2</c>.
+ </p>
+ <p>
+ Own Id: OTP-13260 Aux Id: seq13002 </p>
+ </item>
+ <item>
+ <p>Don't search for non-existing Map keys twice</p>
+ <p>For <c>maps:get/2,3</c> and <c>maps:find/2</c>,
+ searching for an immediate key, e.g. an atom, in a small
+ map, the search was performed twice if the key did not
+ exist.</p>
+ <p>
+ Own Id: OTP-13459</p>
+ </item>
+ <item>
+ <p>
+ Avoid stray corner-case math errors on Solaris, e.g. an
+ error is thrown on undeflows in exp() and pow() when it
+ shouldn't be.</p>
+ <p>
+ Own Id: OTP-13531</p>
+ </item>
+ <item>
+ <p>Fix linting of map key variables</p>
+ <p>Map keys cannot be unbound and then used in parallel
+ matching.</p>
+ <p>Example: <c> #{ K := V } = #{ k := K } = M.</c> This
+ is illegal if <c>'K'</c> is not bound.</p>
+ <p>
+ Own Id: OTP-13534 Aux Id: ERL-135 </p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>The types of The Abstract Format in the
+ <c>erl_parse</c> module have been refined. </p>
+ <p>
+ Own Id: OTP-10292</p>
+ </item>
+ <item>
+ <p> Undocumented syntax for function specifications,
+ <c>-spec F/A :: Domain -&gt; Range</c>, has been removed
+ (without deprecation). </p> <p> Using the
+ <c>is_subtype(V, T)</c> syntax for constraints (in
+ function specifications) is no longer documented, and the
+ newer syntax <c>V :: T</c> should be used instead. The
+ Erlang Parser still recognizes the <c>is_subtype</c>
+ syntax, and will continue to do so for some time. </p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-11879</p>
+ </item>
+ <item>
+ <p>The '<c>random</c>' module has been deprecated. Use
+ the '<c>rand</c>' module instead.</p>
+ <p>
+ Own Id: OTP-12502 Aux Id: OTP-12501 </p>
+ </item>
+ <item>
+ <p>Background: In record fields with a type declaration
+ but without an initializer, the Erlang parser inserted
+ automatically the singleton type <c>'undefined'</c> to
+ the list of declared types, if that value was not present
+ there. That is, the record declaration:</p>
+ <p>
+ -record(rec, {f1 :: float(), f2 = 42 :: integer(), f3 ::
+ some_mod:some_typ()}).</p>
+ <p>was translated by the parser to:</p>
+ <p>
+ -record(rec, {f1 :: float() | 'undefined', f2 = 42 ::
+ integer(), f3 :: some_mod:some_typ() | 'undefined'}).</p>
+ <p>The rationale for this was that creation of a "dummy"
+ <c>#rec{}</c> record should not result in a warning from
+ dialyzer that, for example, the implicit initialization
+ of the <c>#rec.f1</c> field violates its type
+ declaration.</p>
+ <p>Problems: This seemingly innocent action has some
+ unforeseen consequences.</p>
+ <p>For starters, there is no way for programmers to
+ declare that e.g. only floats make sense for the
+ <c>f1</c> field of <c>#rec{}</c> records when there is no
+ "obvious" default initializer for this field. (This also
+ affects tools like PropEr that use these declarations
+ produced by the Erlang parser to generate random
+ instances of records for testing purposes.)</p>
+ <p>It also means that dialyzer does not warn if e.g. an
+ <c>is_atom/1</c> test or something more exotic like an
+ <c>atom_to_list/1</c> call is performed on the value of
+ the <c>f1</c> field.</p>
+ <p>Similarly, there is no way to extend dialyzer to warn
+ if it finds record constructions where <c>f1</c> is not
+ initialized to some float.</p>
+ <p>Last but not least, it is semantically problematic
+ when the type of the field is an opaque type: creating a
+ union of an opaque and a structured type is very
+ problematic for analysis because it fundamentally breaks
+ the opacity of the term at that point.</p>
+ <p>Change: To solve these problems the parser will not
+ automatically insert the <c>'undefined'</c> value
+ anymore; instead the user has the option to choose the
+ places where this value makes sense (for the field) and
+ where it does not and insert the <c>| 'undefined'</c>
+ there manually.</p>
+ <p>Consequences of this change: This change means that
+ dialyzer will issue a warning for all places where
+ records with uninitialized fields are created and those
+ fields have a declared type that is incompatible with
+ <c>'undefined'</c> (e.g. <c>float()</c>). This warning
+ can be suppressed easily by adding <c>| 'undefined'</c>
+ to the type of this field. This also adds documentation
+ that the user really intends to create records where this
+ field is uninitialized.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-12719</p>
+ </item>
+ <item>
+ <p> Remove deprecated functions in the modules
+ <c>erl_scan</c> and <c>erl_parse</c>. </p>
+ <p>
+ Own Id: OTP-12861</p>
+ </item>
+ <item>
+ <p>The pre-processor can now expand the ?FUNCTION_NAME
+ and ?FUNCTION_ARITY macros.</p>
+ <p>
+ Own Id: OTP-13059</p>
+ </item>
+ <item>
+ <p> A new behaviour <c>gen_statem</c> has been
+ implemented. It has been thoroughly reviewed, is stable
+ enough to be used by at least two heavy OTP applications,
+ and is here to stay. But depending on user feedback, we
+ do not expect but might find it necessary to make minor
+ not backwards compatible changes into OTP-20.0, so its
+ state can be designated as "not quite experimental"...
+ </p> <p> The <c>gen_statem</c> behaviour is intended to
+ replace <c>gen_fsm</c> for new code. It has the same
+ features and add some really useful: </p> <list
+ type="bulleted"> <item>State code is gathered</item>
+ <item>The state can be any term</item> <item>Events can
+ be postponed</item> <item>Events can be self
+ generated</item> <item>A reply can be sent from a later
+ state</item> <item>There can be multiple sys traceable
+ replies</item> </list> <p> The callback model(s) for
+ <c>gen_statem</c> differs from the one for
+ <c>gen_fsm</c>, but it is still fairly easy to rewrite
+ from <c>gen_fsm</c> to <c>gen_statem</c>. </p>
+ <p>
+ Own Id: OTP-13065 Aux Id: PR-960 </p>
+ </item>
+ <item>
+ <p>
+ Optimize binary:split/2 and binary:split/3 with native
+ BIF implementation.</p>
+ <p>
+ Own Id: OTP-13082</p>
+ </item>
+ <item>
+ <p>Background: The types of record fields have since R12B
+ been put in a separate form by <c>epp:parse_file()</c>,
+ leaving the record declaration form untyped. The separate
+ form, however, does not follow the syntax of type
+ declarations, and parse transforms inspecting
+ <c>-type()</c> attributes need to know about the special
+ syntax. Since the compiler stores the return value of
+ <c>epp:parse_file()</c> as debug information in the
+ abstract code chunk (<c>"Abst"</c> or
+ <c>abstract_code</c>), tools too need to know about the
+ special syntax, if they inspect <c>-type()</c> attributes
+ in abstract code.</p>
+ <p>Change: No separate type form is created by
+ <c>epp:parse_file()</c>, but the type information is kept
+ in the record fields. This means that all parse
+ transforms and all tools inspecting <c>-record()</c>
+ declarations need to recognize <c>{typed_record_field,
+ Field, Type}</c>.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-13148</p>
+ </item>
+ <item>
+ <p>
+ Unsized fields of the type <c>bytes</c> in binary
+ generators are now forbidden. (The other ways of writing
+ unsized fields, such as <c>binary</c>, are already
+ forbidden.)</p>
+ <p>
+ Own Id: OTP-13152</p>
+ </item>
+ <item>
+ <p> The type <c>map()</c> is built-in, and cannot be
+ redefined. </p>
+ <p>
+ Own Id: OTP-13153</p>
+ </item>
+ <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-13229 Aux Id: ERL-55 </p>
+ </item>
+ <item>
+ <p> Add <c>filename:basedir/2,3</c></p> <p>basedir
+ returns suitable path(s) for 'user_cache', 'user_config',
+ 'user_data', 'user_log', 'site_config' and 'site_data'.
+ On linux and linux like systems the paths will respect
+ the XDG environment variables.</p>
+ <p>
+ Own Id: OTP-13392</p>
+ </item>
+ <item>
+ <p>There are new preprocessor directives
+ <c>-error(Term)</c> and <c>-warning(Term)</c> to cause a
+ compilation error or a compilation warning,
+ respectively.</p>
+ <p>
+ Own Id: OTP-13476</p>
+ </item>
+ <item>
+ <p>
+ Optimize <c>'++'</c> operator and <c>lists:append/2</c>
+ by using a single pass to build a new list while checking
+ for properness.</p>
+ <p>
+ Own Id: OTP-13487</p>
+ </item>
+ <item>
+ <p>
+ Add <c>maps:update_with/3,4</c> and <c>maps:take/2</c></p>
+ <p>
+ Own Id: OTP-13522 Aux Id: PR-1025 </p>
+ </item>
+ <item>
+ <p><c>lists:join/2</c> has been added. Similar to
+ <c>string:join/2</c> but works with arbitrary lists.</p>
+ <p>
+ Own Id: OTP-13523</p>
+ </item>
+ <item>
+ <p>Obfuscate asserts to make Dialyzer shut up.</p>
+ <p>
+ Own Id: OTP-13524 Aux Id: PR-1002 </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>STDLIB 2.8</title>
<section><title>Fixed Bugs and Malfunctions</title>