(ns lists
  "Erlang :lists module — list processing functions.

   In CljElixir: (lists/reverse lst), (lists/sort lst), etc.
   Lower-level than Enum; operates directly on Erlang lists.")

(defn reverse
  "Reverses a list.
   (lists/reverse [3 1 2]) ;=> [2 1 3]"
  ([list])
  ([list tail]))

(defn sort
  "Sorts a list using Erlang term ordering.
   (lists/sort [3 1 2]) ;=> [1 2 3]
   (lists/sort (fn [a b] (> a b)) [3 1 2]) ;=> [3 2 1]"
  ([list])
  ([fun list]))

(defn usort
  "Sorts and removes duplicates.
   (lists/usort [3 1 2 1]) ;=> [1 2 3]"
  ([list])
  ([fun list]))

(defn keysort
  "Sorts list of tuples by element at `n`-th position (1-based).
   (lists/keysort 1 [{:b 2} {:a 1}]) ;=> [{:a 1} {:b 2}]"
  [n tuple-list])

(defn keyfind
  "Finds first tuple where element at `n` matches `key`. Returns tuple or false.
   (lists/keyfind :a 1 [{:a 1} {:b 2}]) ;=> {:a 1}"
  [key n tuple-list])

(defn keystore
  "Replaces or appends tuple in list based on key at position `n`."
  [key n tuple-list new-tuple])

(defn keydelete
  "Deletes first tuple with matching key at position `n`."
  [key n tuple-list])

(defn keymember
  "Returns true if any tuple has `key` at position `n`."
  [key n tuple-list])

(defn keyreplace
  "Replaces first tuple with matching key at position `n`."
  [key n tuple-list new-tuple])

(defn keytake
  "Takes first tuple with matching key. Returns {value rest} or false."
  [key n tuple-list])

(defn map
  "Applies `fun` to each element, returns new list.
   (lists/map (fn [x] (* x 2)) [1 2 3]) ;=> [2 4 6]"
  [fun list])

(defn flatmap
  "Maps and flattens one level.
   (lists/flatmap (fn [x] [x x]) [1 2 3]) ;=> [1 1 2 2 3 3]"
  [fun list])

(defn filter
  "Returns elements for which `pred` returns true.
   (lists/filter (fn [x] (> x 2)) [1 2 3 4]) ;=> [3 4]"
  [pred list])

(defn filtermap
  "Filters and maps in one pass. `fun` returns true/false/{true, value}.
   (lists/filtermap (fn [x] (if (> x 2) {:true (* x 10)} false)) [1 2 3 4]) ;=> [30 40]"
  [fun list])

(defn foldl
  "Left fold.
   (lists/foldl (fn [elem acc] (+ acc elem)) 0 [1 2 3]) ;=> 6"
  [fun acc list])

(defn foldr
  "Right fold.
   (lists/foldr (fn [elem acc] (+ acc elem)) 0 [1 2 3]) ;=> 6"
  [fun acc list])

(defn foreach
  "Calls `fun` on each element for side effects. Returns :ok.
   (lists/foreach (fn [x] (IO/puts x)) [1 2 3])"
  [fun list])

(defn flatten
  "Flattens nested lists.
   (lists/flatten [[1 [2]] [3]]) ;=> [1 2 3]"
  ([list])
  ([list tail]))

(defn append
  "Appends lists.
   (lists/append [1 2] [3 4]) ;=> [1 2 3 4]
   (lists/append [[1] [2] [3]]) ;=> [1 2 3]"
  ([list-of-lists])
  ([list1 list2]))

(defn concat
  "Concatenates a list of things to a flat list."
  [list])

(defn merge
  "Merges sorted lists.
   (lists/merge [1 3 5] [2 4 6]) ;=> [1 2 3 4 5 6]"
  ([list1 list2])
  ([fun list1 list2])
  ([list-of-lists]))

(defn zip
  "Zips two lists into a list of tuples.
   (lists/zip [1 2 3] [:a :b :c]) ;=> [{1 :a} {2 :b} {3 :c}]"
  [list1 list2])

(defn unzip
  "Unzips a list of tuples into two lists.
   (lists/unzip [{1 :a} {2 :b}]) ;=> {[1 2] [:a :b]}"
  [tuple-list])

(defn zipwith
  "Zips with a combining function.
   (lists/zipwith (fn [a b] (+ a b)) [1 2 3] [4 5 6]) ;=> [5 7 9]"
  [fun list1 list2])

(defn member
  "Returns true if `elem` is in `list`.
   (lists/member 2 [1 2 3]) ;=> true"
  [elem list])

(defn nth
  "Returns the `n`-th element (1-based).
   (lists/nth 2 [10 20 30]) ;=> 20"
  [n list])

(defn nthtail
  "Returns the tail starting at position `n` (1-based).
   (lists/nthtail 2 [10 20 30]) ;=> [30]"
  [n list])

(defn last
  "Returns the last element.
   (lists/last [1 2 3]) ;=> 3"
  [list])

(defn delete
  "Deletes first occurrence of `elem`.
   (lists/delete 2 [1 2 3 2]) ;=> [1 3 2]"
  [elem list])

(defn subtract
  "Subtracts elements of `list2` from `list1`.
   (lists/subtract [1 2 3 2] [2]) ;=> [1 3 2]"
  [list1 list2])

(defn duplicate
  "Creates a list with `elem` repeated `n` times.
   (lists/duplicate 3 :ok) ;=> [:ok :ok :ok]"
  [n elem])

(defn seq
  "Generates a sequence from `from` to `to`.
   (lists/seq 1 5) ;=> [1 2 3 4 5]
   (lists/seq 1 10 2) ;=> [1 3 5 7 9]"
  ([from to])
  ([from to step]))

(defn sum
  "Returns the sum of all elements."
  [list])

(defn max
  "Returns the maximum element."
  [list])

(defn min
  "Returns the minimum element."
  [list])

(defn prefix
  "Returns true if `list1` is a prefix of `list2`."
  [list1 list2])

(defn suffix
  "Returns true if `list1` is a suffix of `list2`."
  [list1 list2])

(defn splitwith
  "Splits list into two at the point where `pred` first returns false."
  [pred list])

(defn partition
  "Partitions list into two: elements satisfying `pred` and those that don't."
  [pred list])

(defn takewhile
  "Takes elements while `pred` returns true."
  [pred list])

(defn dropwhile
  "Drops elements while `pred` returns true."
  [pred list])

(defn droplast
  "Drops the last element of a list.
   (lists/droplast [1 2 3]) ;=> [1 2]"
  [list])

(defn sublist
  "Returns a sublist.
   (lists/sublist [1 2 3 4 5] 3) ;=> [1 2 3]
   (lists/sublist [1 2 3 4 5] 2 3) ;=> [2 3 4]"
  ([list len])
  ([list start len]))

(defn search
  "Searches for an element matching `pred`. Returns {:value elem} or false."
  [pred list])

(defn enumerate
  "Returns a list of {index, element} tuples.
   (lists/enumerate [\"a\" \"b\" \"c\"]) ;=> [{1 \"a\"} {2 \"b\"} {3 \"c\"}]"
  ([list])
  ([index list])
  ([index step list]))

(defn all
  "Returns true if `pred` returns true for all elements."
  [pred list])

(defn any
  "Returns true if `pred` returns true for any element."
  [pred list])

(defn join
  "Joins list elements into a string (Elixir extension)."
  [list separator])

(defn map-foldl
  "Combined map and foldl."
  [fun acc list])

(defn map-foldr
  "Combined map and foldr."
  [fun acc list])