-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A package that aims to provide a uniform interface to string-like types.
--   
--   The package defines a typeclass that can be implemented to provide a
--   uniform interface for <tt>String</tt>-like objects.
--   
--   The typeclass itself has default implementations that convert the
--   <tt>StringLike</tt> item first to a lazy <tt>Text</tt>, then performs
--   the operation, and converts results back to its <tt>StringLike</tt>
--   object. This is usually <i>not</i> as efficient as an operation for
--   that specific type. Therefore it is advisable to implement the other
--   functions as well. One can however decide to only implement
--   <tt>fromText</tt> and <tt>toText</tt>; or <tt>toString</tt>.
@package string-like
@version 0.1.0.0


-- | The module defines a typeclass that can be implemented to provide a
--   uniform interface for <a>String</a>-like objects (like <a>String</a>,
--   <a>Text</a>, etc.).
--   
--   The typeclass itself has default implementations that convert the
--   <a>StringLike</a> item first to a lazy <a>Text</a>, then performs the
--   operation, and converts results back to its <a>StringLike</a> object.
--   This is usually <i>not</i> as efficient as an operation for that
--   specific type. Therefore it is advisable to implement the other
--   functions as well. One can however decide to only implement
--   <a>fromText</a> and <a>toText</a>; or <a>toString</a>.
--   
--   The module contains instances for <a>String</a>, <a>Text</a>,
--   <a>Text</a>, <a>ByteString</a> and <a>ByteString</a>.
module Data.String.Like

-- | A typeclass that provides a uniform interface for string-like objects.
class IsString a => StringLike a

-- | Return an empty string-like object.
empty :: StringLike a => a

-- | Create a stringlike object by prepending a <a>Char</a> to an already
--   existing string-like object.
cons :: StringLike a => Char -> a -> a

-- | Create a stringlike object by appending a <a>Char</a> at the end of an
--   already existing string-like object.
snoc :: StringLike a => a -> Char -> a

-- | Unpack a stringlike object by obtaining the first character, and the
--   rest of the string, given the string is non-empty. <a>Nothing</a>
--   otherwise.
uncons :: StringLike a => a -> Maybe (Char, a)

-- | Unpack a string-like object by obtaining te last character, and the
--   string without the last character, given the string is non-empty.
--   <a>Nothing</a> otherwise.
unsnoc :: StringLike a => a -> Maybe (a, Char)

-- | Obtain the length of the string-like object.
length :: StringLike a => a -> Int

-- | Compare the length of the string with the given length. Returns
--   <a>EQ</a> if the string has the same length, <a>LT</a> if the string
--   is shorter, and <a>GT</a> if the string is longer. If the length is
--   not explicitly stored, this function can stop from the moment the
--   string-like object is exhausted, or the threshold has been reached.
compareLength :: StringLike a => a -> Int -> Ordering

-- | Convert the given string-like object to a <a>String</a>. If not
--   specified, it will use <a>toText</a>, and then unpack the <a>Text</a>
--   object in a <a>String</a>.
toString :: StringLike a => a -> String

-- | Convert a given <a>Char</a> to a string-like object containing the
--   single character.
fromChar :: StringLike a => Char -> a

-- | Concatenate the list of string-like objects to a string-like object.
strConcat :: StringLike a => [a] -> a

-- | Create a string-like object by mapping each character to another
--   string-like object, and concatenate these.
strConcatMap :: StringLike a => (Char -> a) -> a -> a

-- | Check if any of the <a>Char</a>s in the string-like object satisfy a
--   given condition.
strAny :: StringLike a => (Char -> Bool) -> a -> Bool

-- | Check if all of the <a>Char</a>s of the string-like object satisfy a
--   given condition.
strAll :: StringLike a => (Char -> Bool) -> a -> Bool

-- | Check if the given string is empty.
strNull :: StringLike a => a -> Bool

-- | Append two string-like objects to a new string-like object.
append :: StringLike a => a -> a -> a

-- | Map all the characters of a string-like object to a new string-like
--   object.
strMap :: StringLike a => (Char -> Char) -> a -> a

-- | Inserts the given string-like object in between the string-like
--   objects in the list. For example to make a comma-separated string.
intercalate :: StringLike a => a -> [a] -> a

-- | Inserts the given character in between the string-like objects in the
--   list. For example to make a string of words.
intersperse :: StringLike a => Char -> a -> a

-- | Transposes the rows and columns of the list of string-like objects.
transpose :: StringLike a => [a] -> [a]

-- | Calculate the reverse string of the given string.
reverse :: StringLike a => a -> a

-- | Convert the given string-like object to its lowercase equivalent.
toLower :: StringLike a => a -> a

-- | Convert the given string-like object to its uppercase equivalent.
toUpper :: StringLike a => a -> a

-- | Convert the given string-like object to its title-case equivalent.
toTitle :: StringLike a => a -> a

-- | Convert a <a>Text</a> object to the string-like object.
fromText :: StringLike a => Text -> a

-- | Convert the string-like object to an <a>Text</a> object.
toText :: StringLike a => a -> Text

-- | Class for string-like datastructures; used by the overloaded string
--   extension (-XOverloadedStrings in GHC).
class IsString a
fromString :: IsString a => String -> a

-- | Convert from one <a>StringLike</a> type to another <a>StringLike</a>
--   type. This is done through a lazy <a>Text</a>.
convertStringLike :: (StringLike a, StringLike b) => a -> b
instance Data.String.Like.StringLike [GHC.Types.Char]
instance Data.String.Like.StringLike Data.Text.Internal.Text
instance Data.String.Like.StringLike Data.Text.Internal.Lazy.Text
instance Data.String.Like.StringLike Data.ByteString.Internal.ByteString
instance Data.String.Like.StringLike Data.ByteString.Lazy.Internal.ByteString