src/hz_format.erl

@@ -1,8 +1,30 @@
 %%% @doc
-%%% GajuDesk Helper Functions
+%%% Formatting and reading functions for Gaju and Puck quantities
+%%%
+%%% The numbers involved in dealing with blockchain amounts are enormous
+%%% by comparison to legacy forms of currency. It isn't so much that
+%%% thousands of Gajus is hard to reason about, but rather that quadrillions
+%%% of Pucks is quite hard to even lock on to visually.
+%%%
+%%% A normal commas and underscores method of decimal formatting is provided, as
+%%% `us' formatting along with two additional approaches:
+%%% - Japanese traditional myriad structure (`jp' style)
+%%% - An internationalized variant inspired by the Japanese technique over periods
+%%%   (`metric' for SI prefixes, and `legacy' for Anglicized prefixes)
+%%%
+%%% These are all accessible via the `amount/N' functions.
+%%%
+%%% The `read/1' function can accept any of the output variants as a string and
+%%% will return the number of pucks indicated by the provided string, allowing for
+%%% simple copy/paste functionality as well as direct input using any of the
+%%% supported notations.
 %%% @end
 
 -module(hz_format).
+-vsn("0.7.0").
+-author("Craig Everett <ceverett@tsuriai.jp>").
+-copyright("Craig Everett <ceverett@tsuriai.jp>").
+-license("GPL-3.0-or-later").
 
 -export([amount/1, amount/2, amount/3, amount/4,
          read/1,
@@ -211,10 +233,13 @@ bestern2(gaju, Ranks, Span, 0, Pucks) ->
     end;
 bestern2(gaju, Ranks, Span, all, Pucks) ->
     P = lists:flatten(string:pad(integer_to_list(Pucks rem one_gaju()), 18, leading, $0)),
+    Zilch = lists:all(fun(C) -> C =:= $0 end, P),
     {H, T} =
-        case Span of
+        case {Span, Zilch} of
-            3 -> {bestern2(gaju, Ranks, 3, 0, Pucks), period(" P", Ranks, lists:reverse(P))};
+            {3, false} -> {bestern2(gaju, Ranks, 3, 0, Pucks), period(" P", Ranks, lists:reverse(P))};
-            4 -> {jp(gaju, 0, Pucks),                 myriad(puck_mark(), Ranks, lists:reverse(P))}
+            {4, false} -> {jp(gaju, 0, Pucks),                 myriad(puck_mark(), Ranks, lists:reverse(P))};
+            {3, true}  -> {bestern2(gaju, Ranks, 3, 0, Pucks), ""};
+            {4, true}  -> {jp(gaju, 0, Pucks),                 ""}
         end,
     lists:flatten([H, " ",  T]);
 bestern2(gaju, Ranks, Span, Precision, Pucks) ->
@@ -230,15 +255,15 @@ bestern2(gaju, Ranks, Span, Precision, Pucks) ->
             false ->
                 ReverseP = lists:reverse(lists:sublist(P, Digits)),
                 PuckingString = lists:flatten(string:pad(ReverseP, 18, leading, $0)),
-                    case lists:all(fun(C) -> C =:= $0 end, PuckingString) of
+                case lists:all(fun(C) -> C =:= $0 end, PuckingString) of
-                        false ->
+                    false ->
-                            case Span of
+                        case Span of
-                                3 -> period(" P", Ranks, PuckingString);
+                            3 -> period(" P", Ranks, PuckingString);
-                                4 -> myriad(puck_mark(), Ranks, PuckingString)
+                            4 -> myriad(puck_mark(), Ranks, PuckingString)
-                            end;
+                        end;
-                        true ->
+                    true ->
-                            ""
+                        ""
-                    end;
+                end;
             true ->
                 []
         end,