Expand data/list

Author: Shamrock-Frost

hackett-doc/scribblings/hackett/reference.scrbl

@@ -645,7 +645,17 @@ Returns @racket[Just] the first element of a list, or @racket[Nothing] if the li
   (head {1 :: 2 :: 3 :: Nil})
   (head (: Nil (t:List t:Integer))))}
 
-@defthing[tail (t:forall [a] {(t:List a) t:-> (t:Maybe (t:List a))})]{
+@defthing[last (forall [a] {(List a) -> (Maybe a)})]{
+
+Returns @racket[just] the last element of a list, or @racket[nothing] if the list is @racket[nil].
+This function is @tech[#:key "partial function"]{partial}, since it diverges on an infinitely long
+input, e.g. @racket[(letrec ([ones {1 :: ones}]) (last ones))].
+
+@(hackett-examples
+  (last {1 :: 2 :: 3 :: nil})
+  (last (: nil (List Integer))))}
+
+@defthing[tail (forall [a] {(List a) -> (Maybe (List a))})]{
 
 Returns @racket[Just] a list without its first element, or @racket[Nothing] if the list is
 @racket[Nil].
@@ -654,7 +664,17 @@ Returns @racket[Just] a list without its first element, or @racket[Nothing] if t
   (tail {1 :: 2 :: 3 :: Nil})
   (tail (: Nil (t:List t:Integer))))}
 
-@defthing[head! (t:forall [a] {(t:List a) t:-> a})]{
+@defthing[init (forall [a] {(List a) -> (Maybe a)})]{
+
+Returns @racket[just] a list without its the last element, or @racket[nothing] if the list is
+@racket[nil]. This function is @tech[#:key "partial function"]{partial}, since it diverges on an
+infinitely long input, e.g. @racket[(letrec ([ones {1 :: ones}]) (last ones))].
+
+@(hackett-examples
+  (init {1 :: 2 :: 3 :: nil})
+  (init (: nil (List Integer))))}
+
+@defthing[head! (forall [a] {(List a) -> a})]{
 
 A @tech[#:key "partial function"]{partial} version of @racket[head] that returns the first element of
 a list. If the list is empty, it raises an error.
@@ -663,7 +683,17 @@ a list. If the list is empty, it raises an error.
   (head! {1 :: 2 :: 3 :: Nil})
   (eval:error (head! (: Nil (t:List t:Integer)))))}
 
-@defthing[tail! (t:forall [a] {(t:List a) t:-> (t:List a)})]{
+@defthing[last! (forall [a] {(List a) -> a})]{
+
+A less-safe version of @racket[last] which tries to return the last element of any list. This function
+is @tech[#:key "partial function"]{partial}; if the given list is empty, @racket[last!] raises an
+error, and if the list is infinitely long, the function wil not return.
+
+@(hackett-examples
+  (last! {1 :: 2 :: 3 :: nil})
+  (eval:error (last! (: nil (List Integer)))))}
+
+@defthing[tail! (forall [a] {(List a) -> (List a)})]{
 
 A @tech[#:key "partial function"]{partial} version of @racket[tail] that returns a list without its
 first element. If the list is empty, it raises an error.
@@ -672,23 +702,70 @@ first element. If the list is empty, it raises an error.
   (tail! {1 :: 2 :: 3 :: Nil})
   (eval:error (tail! (: Nil (t:List t:Integer)))))}
 
-@defproc[(take [n t:Integer] [xs (t:List a)]) (t:List a)]{
+@defthing[init! (forall [a] {(List a) -> a})]{
+
+A less-safe version of @racket[init] which tries to return the last element of any list. This function
+is @tech[#:key "partial function"]{partial}; if the given list is empty, @racket[init!] raises an
+error, and if the list is infinitely long, the function wil not return.
+
+@(hackett-examples
+  (init! {1 :: 2 :: 3 :: nil})
+  (eval:error (init! (: nil (List Integer)))))}
+
+@defthing[uncons (forall [a] {(List a) -> (Maybe (Tuple a (List a)))})]{
+
+Returns @racket[nothing] if the list is @racket[nil], and @racket[just] a pair of the list's first
+element and the rest of it otherwise.
+
+@(hackett-examples
+  (uncons {1 :: 2 :: 3 :: nil})
+  (uncons (: nil (List Integer))))}
+
+@defthing[uncons! (forall [a] {(List a) -> (Tuple a (List a))})]{
+
+A @tech[#:key "partial function"]{partial} version of @racket[uncons] that returns a pair of the
+list's first element and the rest of it. If the list is empty, it raises an error.
+
+@(hackett-examples
+  (uncons! {1 :: 2 :: 3 :: nil})
+  (eval:error (uncons! (: nil (List Integer)))))}
+
+@defthing[null? (forall [a] {(List a) -> Bool})]{
+
+This predicate is @racket[true] when its argument is of the form @racket[nil], and is false otherwise.
+
+@(hackett-examples
+  (null? {1 :: 2 :: 3 :: nil})
+  (null? (: nil (List Integer))))}
+
+@defthing[length (forall [a] {(List a) -> Integer})]
+
+Returns the length of a finite list. Since the function will diverge on an infinitely long input,
+@racket[length] is @tech[#:key "partial function"]{partial}.
+
+@(hackett-examples
+  (length {1 :: 2 :: 3 :: nil})
+  (length (: nil (List Integer))))}
+
+@defproc[(take [n Integer] [xs (List a)]) (List a)]{
 
 Produces a list with the first @racket[n] elements of @racket[xs]. If @racket[xs] contains fewer than
 @racket[n] elements, @racket[xs] is returned unmodified.
 
 @(hackett-examples
-  (take 2 {1 :: 2 :: 3 :: Nil})
-  (take 2 {1 :: Nil}))}
+  (take 2 {1 :: 2 :: 3 :: nil})
+  (take 2 {1 :: nil})
+  (take 2 (: nil (List Integer))))}
 
 @defproc[(drop [n t:Integer] [xs (t:List a)]) (t:List a)]{
 
 Produces a list like @racket[xs] without its first @racket[n] elements. If @racket[xs] contains fewer
 then @racket[n] elements, the result is @racket[Nil].
 
 @(hackett-examples
-  (drop 2 {1 :: 2 :: 3 :: Nil})
-  (drop 2 {1 :: Nil}))}
+  (drop 2 {1 :: 2 :: 3 :: nil})
+  (drop 2 {1 :: nil})
+  (drop 2 (: nil (List Integer))))}
 
 @defproc[(filter [f {a t:-> t:Bool}] [xs (t:List a)]) (t:List a)]{
 
@@ -739,6 +816,14 @@ Adds the elements of @racket[xs] together and returns the sum. Equivalent to @ra
   (eval:check (sum {1 :: 2 :: 3 :: Nil}) 6)
   (eval:check (sum Nil) 0))}
 
+@defthing[intersperse (forall [a] {a -> (List a) -> (List a)})]{
+
+Given a separator and a list, intersperse intersperses the separator between each element of the list.
+
+@(hackett-examples
+ (intersperse 42 {1 :: 2 :: 3 :: nil})
+ (intersperse 42 nil))}
+
 @section[#:tag "reference-typeclasses"]{Typeclasses}
 
 @subsection[#:tag "reference-defining-typeclasses"]{Defining typeclasses and typeclass instances}

hackett-lib/hackett/data/list.rkt

@@ -3,23 +3,55 @@
 (require hackett/data/maybe
          hackett/private/prim)
 
-(provide (data List) head tail head! tail! take drop filter foldr foldl reverse zip-with sum
-         repeat cycle! or and any? all? elem? not-elem? delete delete-by)
+(provide (data List) head last tail init head! last! tail! init! uncons uncons! null? length take drop
+         filter foldr foldl reverse zip-with sum repeat cycle! or and any? all? elem? not-elem? delete
+         delete-by intersperse)
 
 (defn head : (∀ [a] {(List a) -> (Maybe a)})
   [[{x :: _}] (Just x)]
   [[Nil     ] Nothing])
 
+(defn last : (forall [a] {(List a) -> (Maybe a)})
+  [[{x :: nil}] (just x)]
+  [[{_ :: xs} ] (last xs)]
+  [[_         ] nothing])
+
 (defn tail : (∀ [a] {(List a) -> (Maybe (List a))})
   [[{_ :: xs}] (Just xs)]
   [[Nil      ] Nothing])
 
+(defn init : (forall [a] {(List a) -> (Maybe (List a))})
+  [[nil] nothing]
+  [[xs ] (just (init! xs))])
+
 (defn head! : (∀ [a] {(List a) -> a})
   [[xs] (from-maybe (error! "head!: empty list") (head xs))])
 
+(defn last! : (forall [a] {(List a) -> a})
+  [[xs] (from-maybe (error! "last!: empty list") (last xs))])
+
 (defn tail! : (∀ [a] {(List a) -> (List a)})
   [[xs] (from-maybe (error! "tail!: empty list") (tail xs))])
 
+(defn init! : (forall [a] {(List a) -> (List a)})
+  [[{_ :: nil}] nil]
+  [[{x :: xs} ] {x :: (init! xs)}]
+  [[nil       ] (error! "tail!: empty list")])
+
+(defn uncons : (forall [a] {(List a) -> (Maybe (Tuple a (List a)))})
+  [[{x :: xs}] (just (tuple x xs))]
+  [[nil      ] nothing])
+
+(defn uncons! : (forall [a] {(List a) -> (Tuple a (List a))})
+  [[xs] (from-maybe (error! "uncons!: empty list") (uncons xs))])
+
+(defn null? : (forall [a] {(List a) -> Bool})
+  [[nil] true]
+  [[_  ] false])
+
+(def length : (forall [a] {(List a) -> Integer})
+  (foldr (λ [_ acc] {acc + 1}) 0))
+
 (defn take : (∀ [a] {Integer -> (List a) -> (List a)})
   [[n {x :: xs}]
    (if {n == 0}
@@ -89,3 +121,10 @@
        {y :: (delete-by =? x ys)})]
   [[_ _ Nil]
    Nil])
+
+(defn intersperse : (forall [a] {a -> (List a) -> (List a)})
+  [[_  nil      ] nil]
+  [[in {x :: xs}] (letrec ([helper
+                            (λ* [[{y :: ys}] {in :: y :: (helper ys)}]
+                                [[nil      ] nil])])
+                          {x :: (helper xs)})])