-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Easily and clearly create lists with only one element in them. -- -- The list-singleton package allows you to easily and clearly -- create lists with only one element in them, which are typically called -- "singleton lists" or simply "singletons". (Not to be confused with the -- @singletons@ package!) -- -- With any luck this library will be included in future versions of the -- @base@ package. See this mailing list thread for an extended -- discussion: -- https://mail.haskell.org/pipermail/libraries/2019-August/029801.html. @package list-singleton @version 1.0.0.0 -- | This module is meant to augment the Data.List.NonEmpty module. -- You may want to import both modules using the same alias. For example: -- --

--   import qualified Data.List.NonEmpty as NonEmpty
--   import qualified Data.List.NonEmpty.Singleton as NonEmpty
--

module Data.List.NonEmpty.Singleton -- | O(1) Create a non-empty list with a single element in it. -- --

--   >>> singleton "pepperoni"
--   "pepperoni" :| []
--

-- -- If you want to create a regular list with a single element in it, -- consider using singleton from Data.List.Singleton. singleton :: a -> NonEmpty a -- | This module is meant to augment the Data.List module. You may -- want to import both modules using the same alias. For example: -- --

--   import qualified Data.List as List
--   import qualified Data.List.Singleton as List
--

module Data.List.Singleton -- | O(1) Create a list with a single element in it. -- --

--   >>> singleton "pepperoni"
--   ["pepperoni"]
--

-- -- There are many other ways to construct lists, so why might you prefer -- to use singleton? Here's a comparison with a few popular -- methods: -- --

If you already have the element as a named value like x, -- you can wrap it up in a list literal: [x]. You should prefer -- doing that to calling singleton.
```
-- Instead of this:
--   singleton x -- Consider this instead: [x] 
```
If you don't already have the element named, you can introduce a -- name by using a lambda: (\ x -> [x]). This is perhaps the -- most common way to create a singleton list, but it focuses more on -- mechanics than intent. Also it can be get little noisy, especially -- with identifiers longer than single letters like x.
```
--
--   Instead of this: g . (\ x -> [x]) . f -- Consider this instead: g .
--   singleton . f 
```
If you don't want to introduce a name at all, you can use an -- operator section: (: []). This is more advanced because it -- requires familiarity with operator sections, list constructors, and -- how lists are desugared. (If you're not familiar with those concepts, -- the expression (: []) is the same as (\ x -> x : -- []), which is the same as (\ x -> [x]).) While those -- concepts are perhaps fundamental to understanding Haskell, you can get -- surprisingly far without them.
```
-- Instead of this: g . (: []) . f
--   -- Consider this instead: g . singleton . f 
```
If you want to avoid lambdas, lists, and operators completely, you -- can use the pure method from the Applicative type class. -- This has a lot of upsides: it's short, it's in the Prelude, and -- it's easy to search for. Unfortunately it has one downside: it's -- polymorphic. That means it can return any type that has an -- Applicative instance, like Maybe or IO. By -- comparison singleton is monomorphic and can only produce a -- list. Usually the fact that pure is polymorphic isn't a -- problem, but sometimes it can produce confusing errors. Using -- singleton can be a good way to force polymorphic code to use a -- list.
```
>>> import Data.Char (chr) >>> print (pure
--   (chr 72)) ... <interactive>:2:8: error: * Ambiguous type
--   variable `f0' arising from a use of `pure' prevents the constraint
--   `(Applicative f0)' from being solved. Probable fix: use a type
--   annotation to specify what `f0' should be. ... >>> print
--   (singleton (chr 72)) "H" 
```
```
-- Instead of this: g .
--   pure . f -- Consider this instead: g . singleton . f
--   
```

-- -- The name "singleton" was chosen to mirror similar functions provided -- by other libraries. For example: -- --

Data.Binary.Builder.singleton
Data.ByteString.singleton
Data.Sequence.singleton
Data.Text.singleton

-- -- Note that singleton is lazy in its argument. -- --

--   >>> length (singleton undefined)
--   1
--

-- -- If you want to create a NonEmpty list with a single element in -- it, consider using singleton from -- Data.List.NonEmpty.Singleton. singleton :: a -> [a]