+ cons and uncons

Author: gusty

src/FSharpPlus/Data/NonEmptyList.fs

@@ -148,19 +148,39 @@ module NonEmptyList =
     let zipShortest (list1: NonEmptyList<'T>) (list2: NonEmptyList<'U>) =
         { Head = (list1.Head, list2.Head); Tail = List.zipShortest list1.Tail list2.Tail }
 
-    /// Returns a new NonEmptyList with the element added to the beginning.
-    let cons e {Head = x; Tail = xs} = {Head = e ; Tail = x::xs}
+    /// <summary>Adds an element to the beginning of the given list</summary>
+    /// <param name="value">The element to add</param>
+    /// <param name="list">The list to add to</param>
+    /// <returns>A new list with the element added to the beginning.</returns>
+    let cons e { Head = x; Tail = xs } = { Head = e ; Tail = x::xs }
+
+    /// <summary>Splits the list in head and tail.</summary>
+    /// <param name="list">The input list.</param>
+    /// <returns>A tuple with the head and the tail of the original list.</returns>
+    /// <exception cref="T:System.ArgumentException">Thrown when the input list tail is empty.</exception>
+    let uncons ({ Head = x; Tail = xs } as list) =
+        match xs with
+        | [] -> invalidArg (nameof(list)) "The input sequence has an empty tail"
+        | _  -> x, ofList xs
+
+    /// <summary>Splits the list in head and tail.</summary>
+    /// <param name="list">The input list.</param>
+    /// <returns>A tuple with the head and the tail of the original list.</returns>
+    let unconsAsList ({ Head = x; Tail = xs } as list) = x, xs
 
     /// Returns the first element of a new non empty list. You can also use property nel.Head.
     let head {Head = x; Tail = _ } = x
 
     /// <summary>Returns a new NonEmptyList of the elements trailing the first element.</summary>
     /// <exception cref="System.ArgumentException">Thrown when the tail is empty.</exception>
     /// <remarks>Throws exception for empty tail</remarks>
-    let tail {Head = _; Tail = xs } = ofList xs
+    let tail ({ Head = _; Tail = xs } as list) =
+        match xs with
+        | [] -> invalidArg (nameof(list)) "The input sequence has an empty tail"
+        | _  -> ofList xs
 
     /// <summary>Returns a new NonEmptyList of the elements trailing the first element or None.</summary>
-    let tryTail {Head = _; Tail = xs } = tryOfList xs
+    let tryTail { Head = _; Tail = xs } = tryOfList xs
     let rec tails s =
         let {Tail = xs} = s
         match xs with

src/FSharpPlus/Extensions/Array.fs

@@ -1,5 +1,7 @@
 namespace FSharpPlus
 
+#nowarn "1204" // Suppress warning about using FSharp Compiler's error strings.
+
 /// Additional operations on Array
 [<RequireQualifiedAccess>]
 module Array =
@@ -8,6 +10,23 @@ module Array =
     open FSharp.Core.CompilerServices
     open FSharpPlus.Internals.Errors
 
+    /// <summary>Adds an element to the beginning of the given array</summary>
+    /// <param name="value">The element to add</param>
+    /// <param name="array">The array to add to</param>
+    /// <returns>A new array with the element added to the beginning.</returns>
+    let cons value array =
+        raiseIfNull (nameof(array)) array
+        Array.insertAt 0 value array
+
+    /// <summary>Splits the array in head and tail.</summary>
+    /// <param name="array">The input array.</param>
+    /// <returns>A tuple with the head and the tail of the original array.</returns>
+    /// <exception cref="T:System.ArgumentException">Thrown when the input array is empty.</exception>
+    let uncons array =
+        raiseIfNull (nameof(array)) array
+        if Array.isEmpty array then invalidArg (nameof(array)) LanguagePrimitives.ErrorStrings.InputSequenceEmptyString
+        else array[0], array[1..]
+
     /// <summary>Applies an array of functions to an array of values and concatenates them.</summary>
     /// <param name="f">The array of functions.</param>
     /// <param name="x">The array of values.</param>

src/FSharpPlus/Extensions/List.fs

@@ -1,5 +1,7 @@
 namespace FSharpPlus
 
+#nowarn "1204" // Suppress warning about using FSharp Compiler's error strings.
+
 /// Additional operations on List
 [<RequireQualifiedAccess>]
 module List =
@@ -28,12 +30,21 @@ module List =
     /// <summary>Adds an element to the beginning of the given list</summary>
     /// <param name="value">The element to add</param>
     /// <param name="list">The list to add to</param>
-    /// <returns>A concatenated list of the result lists of applying each function to each value</returns>
+    /// <returns>A new list with the element added to the beginning.</returns>
     /// <remarks>
     /// Same as <c>List.Cons</c> but with curried parameters.
     /// </remarks>
     let cons value list = value :: list : list<'T>
 
+    /// <summary>Splits the list in head and tail.</summary>
+    /// <param name="list">The input list.</param>
+    /// <returns>A tuple with the head and the tail of the original list.</returns>
+    /// <exception cref="T:System.ArgumentException">Thrown when the input list is empty.</exception>
+    let uncons list =
+        match list with
+        | []    -> invalidArg (nameof(list)) LanguagePrimitives.ErrorStrings.InputSequenceEmptyString
+        | x::xs -> x, xs
+
     /// <summary>Applies a list of functions to a list of values and concatenates them</summary>
     /// <param name="f">The list of functions.</param>
     /// <param name="x">The list of values.</param>

src/FSharpPlus/Extensions/Seq.fs

@@ -5,6 +5,12 @@ namespace FSharpPlus
 module Seq =
     open System
 
+    /// <summary>Adds an element to the beginning of the given sequence</summary>
+    /// <param name="value">The element to add</param>
+    /// <param name="source">The sequence to add to</param>
+    /// <returns>A new sequence with the element added to the beginning.</returns>
+    let cons value source = seq { yield value; yield! source } : seq<'T>
+
     /// <summary>Applies the given function to each element of the sequence and concatenates the results.</summary>
     ///
     /// <remarks>Remember sequence is lazy, effects are delayed until it is enumerated.</remarks>