Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: docs and utils #21

Merged
merged 1 commit into from
May 27, 2023
Merged

feat: docs and utils #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
_build/
_checkouts/
_gen/
doc/
*.dump
*.crashdump
9 changes: 7 additions & 2 deletions rebar.config
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
]}.

{project_plugins, [
{erlfmt, {git, "[email protected]:WhatsApp/erlfmt.git", {branch, "main"}}}
{erlfmt, {git, "[email protected]:WhatsApp/erlfmt.git", {branch, "main"}}},
rebar3_ex_doc
]}.
{erlfmt, [write]}.

Expand All @@ -25,12 +26,16 @@
]},
{test, [
{ct, "--spec test/conf/test.spec --cover --readable true"}
]},
{doc, [
{ex_doc, "-f html"}
]}
]}.

{cover_opts, [verbose]}.
{cover_enabled, true}.

{xref_ignores, [
ncalendar
ncalendar,
{ncalendar_iso8601, format_timezone, 1}
]}.
2 changes: 1 addition & 1 deletion src/ncalendar.app.src
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{application, ncalendar, [
{description,
"An OTP library for the manipulation of a binary representation of dates and times"},
{vsn, "0.2.0"},
{vsn, "0.3.0"},
{registered, []},
{applications, [kernel, stdlib]},
{env, []}
Expand Down
106 changes: 89 additions & 17 deletions src/ncalendar.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,61 @@
]).

%%% TYPES
-type format() :: iso8601 | http_date | imf_fixdate.
-type gregorian_seconds() :: non_neg_integer().
-type opts() :: map().
-type timezone() ::
undefined
| -1200
| -1100
| -1000
| -0930
| -0900
| -0800
| -0700
| -0600
| -0500
| -0430
| -0400
| -0330
| -0300
| -0230
| -0200
| -0100
| +0000
| +0100
| +0200
| +0300
| +0330
| +0400
| +0430
| +0500
| +0530
| +0545
| +0600
| +0630
| +0700
| +0730
| +0800
| +0900
| +0930
| +1000
| +1030
| +1100
| +1130
| +1200
| +1245
| +1300
| +1345
| +1400.
-type timezone_alias() :: binary().
-type posix_time() :: non_neg_integer().
-type value() :: binary().

%%% EXPORT TYPES
-export_type([
datetime/0,
format/0,
gregorian_seconds/0,
opts/0,
timestamp/0,
timezone/0,
timezone_alias/0,
value/0
Expand All @@ -70,6 +119,7 @@
To :: format(),
Value :: value(),
Result :: value().
%% @equiv convert(From, To, Value, #{})
convert(From, To, Value) ->
convert(From, To, Value, #{}).

Expand All @@ -79,23 +129,26 @@ convert(From, To, Value) ->
Value :: value(),
Opts :: opts(),
Result :: value().
%% @doc Converts a binary representation of a datetime from one format to another.
convert(From, To, Value, Opts) ->
ModFrom = mod(From),
ModTo = mod(To),
ModTo:from_datetimezone(ModFrom:to_datetimezone(Value), Opts).

-spec from_datetime(Format, Datetime) -> Result when
Format :: format(),
Datetime :: datetime(),
Datetime :: calendar:datetime(),
Result :: value().
%% @equiv from_datetime(Format, Datetime, #{})
from_datetime(Format, Datetime) ->
from_datetime(Format, Datetime, #{}).

-spec from_datetime(Format, Datetime, Opts) -> Result when
Format :: format(),
Datetime :: datetime(),
Datetime :: calendar:datetime(),
Opts :: opts(),
Result :: value().
%% @doc Converts a <code>calendar:datetime()</code> value to a binary representation in the specified format.
from_datetime(Format, Datetime, Opts) ->
Datetimezone = {Datetime, {millisecond, 0}, +0000},
Mod = mod(Format),
Expand All @@ -105,6 +158,7 @@ from_datetime(Format, Datetime, Opts) ->
Format :: format(),
GregorianSeconds :: gregorian_seconds(),
Result :: value().
%% @equiv from_gregorian_seconds(Format, GregorianSeconds, #{})
from_gregorian_seconds(Format, GregorianSeconds) ->
from_gregorian_seconds(Format, GregorianSeconds, #{}).

Expand All @@ -113,40 +167,45 @@ from_gregorian_seconds(Format, GregorianSeconds) ->
GregorianSeconds :: gregorian_seconds(),
Opts :: opts(),
Result :: value().
%% @doc Converts the given amout of gregorian seconds to a binary representation in the specified format.
from_gregorian_seconds(Format, GregorianSeconds, Opts) ->
Datetime = calendar:gregorian_seconds_to_datetime(GregorianSeconds),
Datetimezone = {Datetime, {millisecond, 0}, +0000},
Mod = mod(Format),
Mod:from_datetimezone(Datetimezone, Opts).

-spec from_posix_time(Format, UnixTime) -> Result when
-spec from_posix_time(Format, PosixTime) -> Result when
Format :: format(),
UnixTime :: posix_time(),
PosixTime :: posix_time(),
Result :: value().
from_posix_time(Format, UnixTime) ->
from_posix_time(Format, UnixTime, #{}).
%% @equiv from_posix_time(Format, PosixTime, #{})
from_posix_time(Format, PosixTime) ->
from_posix_time(Format, PosixTime, #{}).

-spec from_posix_time(Format, UnixTime, Opts) -> Result when
-spec from_posix_time(Format, PosixTime, Opts) -> Result when
Format :: format(),
UnixTime :: posix_time(),
PosixTime :: posix_time(),
Opts :: opts(),
Result :: value().
from_posix_time(Format, UnixTime, Opts) ->
GregorianSeconds = UnixTime + ?EPOCH_DELTA,
%% @doc Converts the given POSIX time (in seconds) to a binary representation in the specified format.
from_posix_time(Format, PosixTime, Opts) ->
GregorianSeconds = PosixTime + ?EPOCH_DELTA,
from_gregorian_seconds(Format, GregorianSeconds, Opts).

-spec from_timestamp(Format, Timestamp) -> Result when
Format :: format(),
Timestamp :: timestamp(),
Timestamp :: erlang:timestamp(),
Result :: value().
%% @equiv from_timestamp(Format, Timestamp, #{})
from_timestamp(Format, Timestamp) ->
from_timestamp(Format, Timestamp, #{}).

-spec from_timestamp(Format, Timestamp, Opts) -> Result when
Format :: format(),
Timestamp :: timestamp(),
Timestamp :: erlang:timestamp(),
Opts :: opts(),
Result :: value().
%% @doc Converts the given <code>erlang:timestamp</code> value to a binary representation in the specified format.
from_timestamp(Format, Timestamp, Opts) ->
Milliseconds = ncalendar_util:timestamp_to_milliseconds(Timestamp),
Datetimezone = ncalendar_util:milliseconds_to_datetimezone(Milliseconds, +0000),
Expand All @@ -157,6 +216,7 @@ from_timestamp(Format, Timestamp, Opts) ->
Format :: format(),
Value :: value(),
Result :: boolean().
%% @equiv is_valid(Format, Value, #{})
is_valid(Format, Value) ->
is_valid(Format, Value, #{}).

Expand All @@ -165,20 +225,23 @@ is_valid(Format, Value) ->
Value :: value(),
Opts :: opts(),
Result :: boolean().
%% @doc Checks if the given binary representation of a datetime is valid for the specified format.
is_valid(Format, Value, Opts) ->
Mod = mod(Format),
Mod:is_valid(Value, Opts).

-spec now(Format) -> Result when
Format :: format(),
Result :: value().
%% @equiv now(Format, +0000)
now(Format) ->
now(Format, +0000).

-spec now(Format, Timezone) -> Result when
Format :: format(),
Timezone :: timezone(),
Result :: value().
%% @equiv now(Format, Timezone, #{})
now(Format, Timezone) ->
now(Format, Timezone, #{}).

Expand All @@ -187,6 +250,7 @@ now(Format, Timezone) ->
Timezone :: timezone(),
Opts :: opts(),
Result :: value().
%% @doc Returns the current datetime in the specified format.
now(Format, Timezone, Opts) ->
Datetimezone = ncalendar_util:milliseconds_to_datetimezone(
erlang:system_time(millisecond) + (?EPOCH_DELTA * 1000),
Expand All @@ -199,6 +263,7 @@ now(Format, Timezone, Opts) ->
Format :: format(),
Value :: value(),
Result :: timezone().
%% @doc Returns the timezone of the given binary representation of a datetime.
timezone(Format, Value) ->
Mod = mod(Format),
{_Date, _Time, Timezone} = Mod:to_datetimezone(Value),
Expand All @@ -207,7 +272,8 @@ timezone(Format, Value) ->
-spec to_datetime(Format, Value) -> Result when
Format :: format(),
Value :: value(),
Result :: datetime().
Result :: calendar:datetime().
%% @doc Converts the given binary representation of a datetime to a <code>calendar:datetime()</code> value.
to_datetime(Format, Value) ->
Mod = mod(Format),
Datetimezone = Mod:to_datetimezone(Value),
Expand All @@ -217,6 +283,7 @@ to_datetime(Format, Value) ->
Format :: format(),
Value :: value(),
Result :: gregorian_seconds().
%% @doc Converts the given binary representation of a datetime to gregorian seconds.
to_gregorian_seconds(Format, Value) ->
Mod = mod(Format),
Datetimezone = Mod:to_datetimezone(Value),
Expand All @@ -226,14 +293,16 @@ to_gregorian_seconds(Format, Value) ->
Format :: format(),
Value :: value(),
Result :: posix_time().
%% @doc Converts the given binary representation of a datetime to POSIX time (in seconds).
to_posix_time(Format, Value) ->
GregorianSeconds = to_gregorian_seconds(Format, Value),
GregorianSeconds - ?EPOCH_DELTA.

-spec to_timestamp(Format, Value) -> Result when
Format :: format(),
Value :: value(),
Result :: timestamp().
Result :: erlang:timestamp().
%% @doc Converts the given binary representation of a datetime to a <code>erlang:timestamp()</code> value.
to_timestamp(Format, Value) ->
Mod = mod(Format),
Datetimezone = Mod:to_datetimezone(Value),
Expand All @@ -244,6 +313,7 @@ to_timestamp(Format, Value) ->
%%%-----------------------------------------------------------------------------
-spec timezones() -> Result when
Result :: [timezone()].
%% @doc Returns a list of all supported timezones.
timezones() ->
?TIMEZONES.

Expand All @@ -252,6 +322,7 @@ timezones() ->
Value :: value(),
Timezone :: timezone(),
Result :: value().
%% @equiv shift_timezone(Format, Value, Timezone, #{})
shift_timezone(Format, Value, Timezone) ->
shift_timezone(Format, Value, Timezone, #{}).

Expand All @@ -261,6 +332,7 @@ shift_timezone(Format, Value, Timezone) ->
Timezone :: timezone(),
Opts :: opts(),
Result :: value().
%% @doc Shifts the timezone of the given binary representation of a datetime to the specified timezone.
shift_timezone(Format, Value, Timezone, Opts) ->
case timezone(Format, Value) of
undefined ->
Expand Down
61 changes: 0 additions & 61 deletions src/ncalendar.hrl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,67 +14,6 @@
-ifndef(ncalendar).
-define(ncalendar, true).

%%% TYPES
-type date() :: calendar:date().
-type datetime() :: calendar:datetime().
% Datetime is: UTC time | local time (if no timezone is specified).
-type datetimezone() :: {datetime(), sub_seconds(), timezone() | timezone_alias()}.
-type format() :: iso8601.
-type gregorian_seconds() :: non_neg_integer().
-type milliseconds() :: non_neg_integer().
-type opts() :: map().
-type sub_seconds() :: {millisecond, milliseconds()}.
-type time() :: calendar:time().
-type timestamp() :: erlang:timestamp().
-type timezone() ::
undefined
| -1200
| -1100
| -1000
| -0930
| -0900
| -0800
| -0700
| -0600
| -0500
| -0430
| -0400
| -0330
| -0300
| -0230
| -0200
| -0100
| +0000
| +0100
| +0200
| +0300
| +0330
| +0400
| +0430
| +0500
| +0530
| +0545
| +0600
| +0630
| +0700
| +0730
| +0800
| +0900
| +0930
| +1000
| +1030
| +1100
| +1130
| +1200
| +1245
| +1300
| +1345
| +1400.
%% <<"Z">>
-type timezone_alias() :: binary().
-type posix_time() :: non_neg_integer().
-type value() :: binary().

%%% MACROS
-define(TIMEZONES, [
-1200,
Expand Down
Loading