Merge pull request #733 from pguyot/w31/fix-types-and-more-documentat…

…ions

Fix some types and add missing nifs to erlang module

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

libs/estdlib/src/calendar.erl

@@ -45,6 +45,8 @@
     system_time_to_universal_time/2
 ]).
 
+-export_type([datetime/0]).
+
 %%-----------------------------------------------------------------------------
 %% @doc Year cannot be abbreviated.
 %%
@@ -65,7 +67,6 @@
 -type date() :: {year(), month(), day()}.
 -type time() :: {hour(), minute(), second()}.
 -type datetime() :: {date(), time()}.
--type time_unit() :: second | millisecond | microsecond.
 
 %%-----------------------------------------------------------------------------
 %% @equiv date_to_gregorian_days(Year, M, D)
@@ -161,7 +162,7 @@ day_of_the_week(Y, M, D) ->
 %% @doc     Convert an integer time value to a date and time in UTC.
 %% @end
 %%-----------------------------------------------------------------------------
--spec system_time_to_universal_time(Time :: integer(), TimeUnit :: time_unit()) ->
+-spec system_time_to_universal_time(Time :: integer(), TimeUnit :: erlang:time_unit()) ->
     datetime().
 system_time_to_universal_time(_Time, _TimeUnit) ->
     throw(nif_error).

libs/estdlib/src/erlang.erl

@@ -56,9 +56,12 @@
     atom_to_binary/2,
     atom_to_list/1,
     float_to_binary/1,
+    float_to_binary/2,
     float_to_list/1,
+    float_to_list/2,
     integer_to_binary/1,
     integer_to_list/1,
+    integer_to_list/2,
     fun_to_list/1,
     pid_to_list/1,
     ref_to_list/1,
@@ -79,6 +82,10 @@
     process_flag/2
 ]).
 
+-export_type([
+    time_unit/0
+]).
+
 %%
 %% TODO Correct the following bugs
 %% * cancel_timer should be renamed cancel, per the OTP documentation
@@ -541,6 +548,11 @@ atom_to_binary(_Atom, _Encoding) ->
 atom_to_list(_Atom) ->
     throw(nif_error).
 
+-type float_format_option() ::
+    {decimals, Decimals :: 0..57}
+    | {scientific, Decimals :: 0..57}
+    | compact.
+
 %%-----------------------------------------------------------------------------
 %% @param   Float   Float to convert
 %% @returns a binary with a text representation of the float
@@ -551,6 +563,17 @@ atom_to_list(_Atom) ->
 float_to_binary(_Float) ->
     throw(nif_error).
 
+%%-----------------------------------------------------------------------------
+%% @param   Float   Float to convert
+%% @param   Options Options for conversion
+%% @returns a binary with a text representation of the float
+%% @doc     Convert a float to a binary.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec float_to_binary(Float :: float(), Options :: [float_format_option()]) -> binary().
+float_to_binary(_Float, _Options) ->
+    throw(nif_error).
+
 %%-----------------------------------------------------------------------------
 %% @param   Float   Float to convert
 %% @returns a string with a text representation of the float
@@ -561,6 +584,17 @@ float_to_binary(_Float) ->
 float_to_list(_Float) ->
     throw(nif_error).
 
+%%-----------------------------------------------------------------------------
+%% @param   Float   Float to convert
+%% @param   Options Options for conversion
+%% @returns a string with a text representation of the float
+%% @doc     Convert a float to a string.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec float_to_list(Float :: float(), Options :: [float_format_option()]) -> string().
+float_to_list(_Float, _Options) ->
+    throw(nif_error).
+
 %%-----------------------------------------------------------------------------
 %% @param   Integer integer to convert to a binary
 %% @returns a binary with a text representation of the integer
@@ -581,6 +615,17 @@ integer_to_binary(_Integer) ->
 integer_to_list(_Integer) ->
     throw(nif_error).
 
+%%-----------------------------------------------------------------------------
+%% @param   Integer integer to convert to a string
+%% @param   Base    base for representation
+%% @returns a string representation of the integer
+%% @doc     Convert an integer to a string.
+%% @end
+%%-----------------------------------------------------------------------------
+-spec integer_to_list(Integer :: integer(), Base :: 2..36) -> string().
+integer_to_list(_Integer, _Base) ->
+    throw(nif_error).
+
 %%-----------------------------------------------------------------------------
 %% @param   Fun     function to convert to a string
 %% @returns a string representation of the function

libs/estdlib/src/gen_tcp.erl

@@ -46,6 +46,17 @@
 
 -type reason() :: term().
 
+-type option() ::
+    {active, boolean()}
+    | {buffer, pos_integer()}
+    | {timeout, pos_integer() | infinity}
+    | list
+    | binary.
+
+-type listen_option() :: option().
+-type connect_option() :: option().
+-type packet() :: string() | binary().
+
 -define(DEFAULT_PARAMS, [{active, true}, {buffer, 512}, {timeout, infinity}]).
 
 %%-----------------------------------------------------------------------------
@@ -73,7 +84,7 @@
 %%          in order to receive data on the socket.
 %% @end
 %%-----------------------------------------------------------------------------
--spec connect(Address :: inet:address(), Port :: inet:port(), Options :: inet:opts()) ->
+-spec connect(Address :: inet:address(), Port :: inet:port_number(), Options :: [connect_option()]) ->
     {ok, Socket :: inet:socket()} | {error, Reason :: reason()}.
 connect(Address, Port, Params0) ->
     Socket = open_port({spawn, "socket"}, []),
@@ -90,7 +101,7 @@ connect(Address, Port, Params0) ->
 %%          otherwise, an error with a reason.
 %% @end
 %%-----------------------------------------------------------------------------
--spec send(Socket :: inet:socket(), Packet :: inet:packet()) -> ok | {error, Reason :: reason()}.
+-spec send(Socket :: inet:socket(), Packet :: packet()) -> ok | {error, Reason :: reason()}.
 send(Socket, Packet) ->
     case call(Socket, {send, Packet}) of
         {ok, _Len} ->
@@ -105,7 +116,7 @@ send(Socket, Packet) ->
 %% @end
 %%-----------------------------------------------------------------------------
 -spec recv(Socket :: inet:socket(), Length :: non_neg_integer()) ->
-    {ok, inet:packet()} | {error, Reason :: reason()}.
+    {ok, packet()} | {error, Reason :: reason()}.
 recv(Socket, Length) ->
     recv(Socket, Length, infinity).
 
@@ -129,7 +140,7 @@ recv(Socket, Length) ->
 %% @end
 %%-----------------------------------------------------------------------------
 -spec recv(Socket :: inet:socket(), Length :: non_neg_integer(), Timeout :: non_neg_integer()) ->
-    {ok, inet:packet()} | {error, Reason :: reason()}.
+    {ok, packet()} | {error, Reason :: reason()}.
 recv(Socket, Length, Timeout) ->
     call(Socket, {recv, Length, Timeout}).
 
@@ -144,7 +155,7 @@ recv(Socket, Length, Timeout) ->
 %%          This function is currently unimplemented
 %% @end
 %%-----------------------------------------------------------------------------
--spec listen(Port :: inet:port(), Options :: inet:opts()) ->
+-spec listen(Port :: inet:port_number(), Options :: [listen_option()]) ->
     {ok, ListeningSocket :: inet:socket()} | {error, Reason :: reason()}.
 listen(Port, Options) ->
     Socket = open_port({spawn, "socket"}, []),

libs/estdlib/src/gen_udp.erl

@@ -56,7 +56,7 @@
 %%          send or receive UDP messages.
 %% @end
 %%-----------------------------------------------------------------------------
--spec open(PortNum :: inet:port()) -> {ok, inet:socket()} | {error, Reason :: reason()}.
+-spec open(PortNum :: inet:port_number()) -> {ok, inet:socket()} | {error, Reason :: reason()}.
 open(PortNum) ->
     open(PortNum, []).
 
@@ -76,7 +76,7 @@ open(PortNum) ->
 %%          <em><b>Note.</b>  The Params argument is currently ignored.</em>
 %% @end
 %%-----------------------------------------------------------------------------
--spec open(PortNum :: inet:port(), Options :: proplist()) ->
+-spec open(PortNum :: inet:port_number(), Options :: proplist()) ->
     {ok, inet:socket()} | {error, Reason :: reason()}.
 open(PortNum, Options) ->
     DriverPid = open_port({spawn, "socket"}, []),
@@ -97,7 +97,7 @@ open(PortNum, Options) ->
 -spec send(
     Socket :: inet:socket(),
     Address :: inet:address(),
-    PortNum :: inet:port(),
+    PortNum :: inet:port_number(),
     Packet :: packet()
 ) -> ok | {error, reason()}.
 send(Socket, Address, PortNum, Packet) ->
@@ -114,7 +114,7 @@ send(Socket, Address, PortNum, Packet) ->
 %% @end
 %%-----------------------------------------------------------------------------
 -spec recv(Socket :: inet:socket(), Length :: non_neg_integer()) ->
-    {ok, {inet:address(), inet:port(), packet()}} | {error, reason()}.
+    {ok, {inet:address(), inet:port_number(), packet()}} | {error, reason()}.
 recv(Socket, Length) ->
     recv(Socket, Length, infinity).
 
@@ -136,7 +136,7 @@ recv(Socket, Length) ->
 %% @end
 %%-----------------------------------------------------------------------------
 -spec recv(Socket :: inet:socket(), Length :: non_neg_integer(), Timeout :: non_neg_integer()) ->
-    {ok, {inet:address(), inet:port(), packet()}} | {error, reason()}.
+    {ok, {inet:address(), inet:port_number(), packet()}} | {error, reason()}.
 recv(Socket, Length, Timeout) ->
     call(Socket, {recvfrom, Length, Timeout}).