src/hope_list.erl

   1 -module(hope_list).
   2
   3 -export_type(
   4     [ t/1
   5     ]).
   6
   7 -export(
   8     [ unique_preserve_order/1
   9     , map/2
  10     , map/3  % Tunable recursion limit
  11     , map_rev/2
  12     , map_slow/2
  13     , map_result/2  % Not tail-recursive
  14     , first_match/2
  15     , divide/2
  16     ]).
  17
  18 -define(DEFAULT_RECURSION_LIMIT, 1000).
  19
  20 -type t(A) ::
  21     [A].
  22
  23 %% @doc Tail-recursive equivalent of lists:map/2
  24 %% @end
  25 -spec map([A], fun((A) -> (B))) ->
  26     [B].
  27 map(Xs, F) ->
  28     map(Xs, F, ?DEFAULT_RECURSION_LIMIT).
  29
  30 -spec map([A], fun((A) -> (B)), RecursionLimit :: non_neg_integer()) ->
  31     [B].
  32 map(Xs, F, RecursionLimit) ->
  33     map(Xs, F, RecursionLimit, 0).
  34
  35 map([], _, _, _) ->
  36     [];
  37 map([X1], F, _, _) ->
  38     Y1 = F(X1),
  39     [Y1];
  40 map([X1, X2], F, _, _) ->
  41     Y1 = F(X1),
  42     Y2 = F(X2),
  43     [Y1, Y2];
  44 map([X1, X2, X3], F, _, _) ->
  45     Y1 = F(X1),
  46     Y2 = F(X2),
  47     Y3 = F(X3),
  48     [Y1, Y2, Y3];
  49 map([X1, X2, X3, X4], F, _, _) ->
  50     Y1 = F(X1),
  51     Y2 = F(X2),
  52     Y3 = F(X3),
  53     Y4 = F(X4),
  54     [Y1, Y2, Y3, Y4];
  55 map([X1, X2, X3, X4, X5 | Xs], F, RecursionLimit, RecursionCount) ->
  56     Y1 = F(X1),
  57     Y2 = F(X2),
  58     Y3 = F(X3),
  59     Y4 = F(X4),
  60     Y5 = F(X5),
  61     Ys =
  62         case RecursionCount > RecursionLimit
  63         of  true  -> map_slow(Xs, F)
  64         ;   false -> map     (Xs, F, RecursionLimit, RecursionCount + 1)
  65         end,
  66     [Y1, Y2, Y3, Y4, Y5 | Ys].
  67
  68 %% @doc lists:reverse(map_rev(L, F))
  69 %% @end
  70 -spec map_slow([A], fun((A) -> (B))) ->
  71     [B].
  72 map_slow(Xs, F) ->
  73     lists:reverse(map_rev(Xs, F)).
  74
  75 %% @doc Tail-recursive alternative to lists:map/2, which accumulates and
  76 %% returns list in reverse order.
  77 %% @end
  78 -spec map_rev([A], fun((A) -> (B))) ->
  79     [B].
  80 map_rev(Xs, F) ->
  81     map_rev_acc(Xs, F, []).
  82
  83 -spec map_rev_acc([A], fun((A) -> (B)), [B]) ->
  84     [B].
  85 map_rev_acc([], _, Ys) ->
  86     Ys;
  87 map_rev_acc([X|Xs], F, Ys) ->
  88     Y = F(X),
  89     map_rev_acc(Xs, F, [Y|Ys]).
  90
  91 -spec map_result([A], fun((A) -> (hope_result:t(B, C)))) ->
  92     hope_result:t([B], C).
  93 map_result([], _) ->
  94     {ok, []};
  95 map_result([X | Xs], F) ->
  96     case F(X)
  97     of  {ok, Y} ->
  98             case map_result(Xs, F)
  99             of  {ok, Ys} ->
 100                     {ok, [Y | Ys]}
 101             ;   {error, _}=Error ->
 102                     Error
 103             end
 104     ;   {error, _}=Error ->
 105             Error
 106     end.
 107
 108 -spec unique_preserve_order(t(A)) ->
 109     t(A).
 110 unique_preserve_order(L) ->
 111     PrependIfNew =
 112         fun (X, Xs) ->
 113             case lists:member(X, Xs)
 114             of  true  ->      Xs
 115             ;   false -> [X | Xs]
 116             end
 117         end,
 118     lists:reverse(lists:foldl(PrependIfNew, [], L)).
 119
 120 -spec first_match([{Tag, fun((A) -> boolean())}], A) ->
 121     hope_option:t(Tag).
 122 first_match([], _) ->
 123     none;
 124 first_match([{Tag, F} | Tests], X) ->
 125     case F(X)
 126     of  true  -> {some, Tag}
 127     ;   false -> first_match(Tests, X)
 128     end.
 129
 130 %% @doc Divide list into sublists of up to a requested size + a remainder.
 131 %% Order unspecified. Size < 1 raises an error:
 132 %% `hope_list__divide__size_must_be_a_positive_integer'
 133 %% @end
 134 -spec divide([A], pos_integer()) ->
 135     [[A]].
 136 divide(_, Size) when Size < 1 orelse not is_integer(Size) ->
 137     % Q: Why?
 138     % A: For N < 0, what does it mean to have a negative-sized chunk?
 139     %    For N = 0, we can imagine that a single chunk is an empty list, but,
 140     %    how many such chunks should we produce?
 141     % This is pretty-much equivalnet to the problem of deviding something by 0.
 142     error(hope_list__divide__size_must_be_a_positive_integer);
 143 divide([], _) ->
 144     [];
 145 divide([X1 | Xs], MaxChunkSize) ->
 146     MoveIntoChunks =
 147         fun (X2, {Chunk, Chunks, ChunkSize}) when ChunkSize >= MaxChunkSize ->
 148                 {[X2], [Chunk | Chunks], 1}
 149         ;   (X2, {Chunk, Chunks, ChunkSize}) ->
 150                 {[X2 | Chunk], Chunks, ChunkSize + 1}
 151         end,
 152     {Chunk, Chunks, _} = lists:foldl(MoveIntoChunks, {[X1], [], 1}, Xs),
 153     [Chunk | Chunks].