relude-1.2.2.0: Safe, performant, user-friendly and lightweight Haskell Standard Library

Copyright | (c) 2016 Stephen Diehl (c) 2016-2018 Serokell (c) 2018-2023 Kowainik
License | MIT
Maintainer | Kowainik <xrom.xkov@gmail.com>
Stability | Stable
Portability | Portable
Safe Haskell | Unsafe
Language | Haskell2010

Relude.Unsafe

Contents

- Unsafe list functions
- Unsafe `Maybe` functions
- Unsafe Text.Read functions

Description

⚠️ Warning ⚠️

This module contains unsafe partial functions. They are unavoidable sometimes, but we encourage you to use safer analogues:

Partial | Total
--- | ---
``head` :: [a] -> a` | ``head` :: NonEmpty a -> a`
``tail` :: [a] -> [a]` | ``tail` :: NonEmpty a -> [a]`
``read` :: Read a => String -> a` | ``readMaybe` :: Read a => String -> Maybe a`
``fromJust` :: Maybe a -> a` | ``fromMaybe` :: a -> Maybe a -> a`

This module is intended to be imported qualified and it is not included in default prelude exports.

    import qualified Relude.Unsafe as Unsafe

    foo :: [a] -> a
    foo = Unsafe.head

Synopsis

- head :: HasCallStack => [a] -> a
- tail :: HasCallStack => [a] -> [a]
- last :: HasCallStack => [a] -> a
- init :: HasCallStack => [a] -> [a]
- (!!) :: HasCallStack => [a] -> Int -> a
- at :: Int -> [a] -> a
- fromJust :: HasCallStack => Maybe a -> a
- read :: Read a => String -> a

# Unsafe list functions

head :: HasCallStack => [a] -> a #

\(\mathcal{O}(1)\). Extract the first element of a list, which must be non-empty.

To disable the warning about partiality put `{-# OPTIONS_GHC -Wno-x-partial -Wno-unrecognised-warning-flags #-}` at the top of the file. To disable it throughout a package put the same options into `ghc-options` section of Cabal file. To disable it in GHCi put `:set -Wno-x-partial -Wno-unrecognised-warning-flags` into `~/.ghci` config file. See also the migration guide.

##### Examples

Expand

    >>> head [1, 2, 3]
    1

    >>> head [1..]
    1

    >>> head []
    *** Exception: Prelude.head: empty list

tail :: HasCallStack => [a] -> [a] #

\(\mathcal{O}(1)\). Extract the elements after the head of a list, which must be non-empty.

To disable the warning about partiality put `{-# OPTIONS_GHC -Wno-x-partial -Wno-unrecognised-warning-flags #-}` at the top of the file. To disable it throughout a package put the same options into `ghc-options` section of Cabal file. To disable it in GHCi put `:set -Wno-x-partial -Wno-unrecognised-warning-flags` into `~/.ghci` config file. See also the migration guide.

#### Examples

Expand

    >>> tail [1, 2, 3]
    [2,3]

    >>> tail [1]
    []

    >>> tail []
    *** Exception: Prelude.tail: empty list

last :: HasCallStack => [a] -> a #

\(\mathcal{O}(n)\). Extract the last element of a list, which must be finite and non-empty.

WARNING: This function is partial. Consider using `unsnoc` instead.

#### Examples

Expand

    >>> last [1, 2, 3]
    3

    >>> last [1..]
    * Hangs forever *

    >>> last []
    *** Exception: Prelude.last: empty list

init :: HasCallStack => [a] -> [a] #

\(\mathcal{O}(n)\). Return all the elements of a list except the last one. The list must be non-empty.

WARNING: This function is partial. Consider using `unsnoc` instead.

#### Examples

Expand

    >>> init [1, 2, 3]
    [1,2]

    >>> init [1]
    []

    >>> init []
    *** Exception: Prelude.init: empty list

(!!) :: HasCallStack => [a] -> Int -> a infixl 9 #

List index (subscript) operator, starting from 0. It is an instance of the more general `genericIndex`, which takes an index of any integral type.

WARNING: This function is partial, and should only be used if you are sure that the indexing will not fail. Otherwise, use `!?`.

WARNING: This function takes linear time in the index.

#### Examples

Expand

    >>> ['a', 'b', 'c'] !! 0
    'a'

    >>> ['a', 'b', 'c'] !! 2
    'c'

    >>> ['a', 'b', 'c'] !! 3
    *** Exception: Prelude.!!: index too large

    >>> ['a', 'b', 'c'] !! (-1)
    *** Exception: Prelude.!!: negative index

at :: Int -> [a] -> a #

Similar to `!!` but with flipped arguments. get element from list using index value starting from `0`.

    >>> at 2 ["a", "b", "c"]
    "c"

it is also useful when used in a partially applied position like:

    >>> map (at 1) [["a","b","c"], ["a","b","c"], ["a","b","c"]]
    ["b","b","b"]

# Unsafe `Maybe` functions

fromJust :: HasCallStack => Maybe a -> a #

The `fromJust` function extracts the element out of a `Just` and throws an error if its argument is `Nothing`.

#### Examples

Expand

Basic usage:

    >>> fromJust (Just 1)
    1

    >>> 2 * (fromJust (Just 10))
    20

    >>> 2 * (fromJust Nothing)
    *** Exception: Maybe.fromJust: Nothing
    ...

WARNING: This function is partial. You can use case-matching instead.

# Unsafe Text.Read functions

read :: Read a => String -> a #

The `read` function reads input from a string, which must be completely consumed by the input process. `read` fails with an `error` if the parse is unsuccessful, and it is therefore discouraged from being used in real applications. Use `readMaybe` or `readEither` for safe alternatives.

    >>> read "123" :: Int
    123

    >>> read "hello" :: Int
    *** Exception: Prelude.read: no parse