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

-- | A rope data structure used by Yi
--   
--   A rope data structure used by Yi
@package yi-rope
@version 0.11

-- | This module defines a rope data structure for use in Yi. This
--   specific implementation uses a fingertree over Text.
--   
--   In contrast to our old implementation, we can now reap all the
--   benefits of Text: automatic unicode handling and blazing fast
--   implementation on underlying strings. This frees us from a lot of
--   book-keeping. We don't lose out on not using ByteString directly
--   because the old implementation encoded it into UTF8 anyway, making it
--   unsuitable for storing anything but text.
module Yi.Rope

-- | A YiString is a FingerTree with cached char and line
--   counts over chunks of Text.
data YiString

-- | See fromText.
fromString :: String -> YiString

-- | Converts a Text into a YiString using
--   defaultChunkSize-sized chunks for the underlying tree.
fromText :: Text -> YiString

-- | See fromText'.
fromString' :: Int -> String -> YiString

-- | This is like fromText but it allows the user to specify the
--   chunk size to be used. Uses defaultChunkSize if the given size
--   is <= 0.
fromText' :: Int -> Text -> YiString

-- | See toText.
toString :: YiString -> String

-- | See toReverseText.
--   
--   Note that it is actually ~4.5 times faster to use toReverseText
--   and unpack the result than to convert to String and use
--   reverse.
toReverseString :: YiString -> String

-- | Consider whether you really need to use this!
toText :: YiString -> Text

-- | Spits out the underlying string, reversed.
--   
--   Note that this is actually slightly faster than manually unrolling the
--   tree from the end, reverseing each chunk and concating,
--   at least with -O2 which you really need to be using with Text
--   anyway.
toReverseText :: YiString -> Text

-- | Checks if the given YiString is actually empty.
null :: YiString -> Bool

-- | Creates an empty YiString.
empty :: YiString

-- | Takes the first n given characters.
take :: Int -> YiString -> YiString

-- | Drops the first n characters.
drop :: Int -> YiString -> YiString

-- | Length of the whole underlying string.
--   
--   Amortized constant time.
length :: YiString -> Int

-- | Reverse the whole underlying string.
--   
--   This involves reversing the order of the chunks as well as content of
--   the chunks. We use a little optimisation here that re-uses the content
--   of each chunk but this exposes a potential problem: after many
--   transformations, our chunks size might become quite varied (but never
--   more than the default size), perhaps we should periodically rechunk
--   the tree to recover nice sizes?
reverse :: YiString -> YiString

-- | Count the number of newlines in the underlying string. This is
--   actually amortized constant time as we cache this information in the
--   underlying tree.
countNewLines :: YiString -> Int

-- | This is like lines' but it does *not* preserve newlines.
--   
--   Specifically, we just strip the newlines from the result of
--   lines'.
--   
--   This behaves slightly differently than the old split: the number of
--   resulting strings here is equal to the number of newline characters in
--   the underlying string. This is much more consistent than the old
--   behaviour which blindly used ByteStrings split and stitched
--   the result back together which was inconsistent with the rest of the
--   interface which worked with number of newlines.
lines :: YiString -> [YiString]

-- | Splits the YiString into a list of YiString each
--   containing a line.
--   
--   Note that in old implementation this allowed an arbitrary character to
--   split on. If you want to do that, manually convert toText and
--   use splitOn to suit your needs. This case is optimised for
--   newlines only which seems to have been the only use of the original
--   function.
--   
--   The newlines are preserved so this should hold:
--   
--   
--   'toText' . 'concat' . 'lines'' ≡ 'toText'
--   
--   
--   but the underlying structure might change: notably, chunks will most
--   likely change sizes.
lines' :: YiString -> [YiString]

-- | Joins up lines by a newline character. It does not leave a newline
--   after the last line. If you want a more classical unlines
--   behaviour, use map along with snoc.
unlines :: [YiString] -> YiString

-- | Splits the string at given character position.
--   
--   If position <= 0 then the left string is empty and the
--   right string contains everything else.
--   
--   If position >= length of the string then the left string
--   contains everything and the right string is empty.
--   
--   Implementation note: the way this works is by splitting the underlying
--   finger at a closest chunk that goes *over* the given position (see
--   split). This either results in a perfect split at which point
--   we're done or more commonly, it leaves as few characters short and we
--   need to take few characters from the first chunk of the right side of
--   the split. We do precisely that.
--   
--   All together, this split is only as expensive as underlying
--   split, the cost of splitting a chunk into two, the cost of one
--   cons and one cons of a chunk and lastly the cost of splitAt of
--   the underlying Text. It turns out to be fairly fast all
--   together.
splitAt :: Int -> YiString -> (YiString, YiString)

-- | Splits the underlying string before the given line number.
--   Zero-indexed lines.
--   
--   Splitting at line <= 0 gives you an empty string. Splitting at
--   n > 0 gives you the first n lines.
--   
--   Also see splitAtLine'.
splitAtLine :: Int -> YiString -> (YiString, YiString)

-- | Add a Char in front of a YiString.
cons :: Char -> YiString -> YiString

-- | Add a Char in the back of a YiString.
snoc :: YiString -> Char -> YiString

-- | Single character YiString. Consider whether it's worth creating
--   this, maybe you can use cons or snoc instead?
singleton :: Char -> YiString

-- | Take the first character of the underlying string if possible.
head :: YiString -> Maybe Char

-- | Take the last character of the underlying string if possible.
last :: YiString -> Maybe Char

-- | Append two YiStrings.
--   
--   We take the extra time to optimise this append for many small
--   insertions. With naive append of the inner fingertree with
--   ><, it is often the case that we end up with a large
--   collection of tiny chunks. This function instead tries to join the
--   underlying trees at outermost chunks up to defaultChunkSize
--   which while slower, should improve memory usage.
--   
--   I suspect that this pays for itself as we'd spend more time computing
--   over all the little chunks than few large ones anyway.
append :: YiString -> YiString -> YiString

-- | Concat a list of YiStrings.
concat :: [YiString] -> YiString

-- | YiString specialised any.
--   
--   Implementation note: this currently just does any by doing ‘TX.Text’
--   conversions upon consecutive chunks. We should be able to speed it up
--   by running it in parallel over multiple chunks.
any :: (Char -> Bool) -> YiString -> Bool

-- | YiString specialised all.
--   
--   See the implementation note for any.
all :: (Char -> Bool) -> YiString -> Bool

-- | The usual dropWhile optimised for YiStrings.
dropWhile :: (Char -> Bool) -> YiString -> YiString

-- | The usual takeWhile optimised for YiStrings.
takeWhile :: (Char -> Bool) -> YiString -> YiString

-- | As dropWhile but drops from the end instead.
dropWhileEnd :: (Char -> Bool) -> YiString -> YiString

-- | Like takeWhile but takes from the end instead.
takeWhileEnd :: (Char -> Bool) -> YiString -> YiString

-- | Concatenates the list of YiStrings after inserting the
--   user-provided YiString between the elements.
--   
--   Empty YiStrings are not ignored and will end up as strings of
--   length 1. If you don't want this, it's up to you to pre-process the
--   list. Just as with intersperse, it is up to the user to
--   pre-process the list.
intercalate :: YiString -> [YiString] -> YiString

-- | Intersperses the given character between the YiStrings. This is
--   useful when you have a bunch of strings you just want to separate
--   something with, comma or a dash. Note that it only inserts the
--   character between the elements.
--   
--   What's more, the result is a single YiString. You can easily
--   achieve a version that blindly inserts elements to the back by mapping
--   over the list instead of using this function.
--   
--   You can think of it as a specialised version of intercalate.
--   Note that what this does not do is intersperse characters into
--   the underlying text, you should convert and use intersperse for
--   that instead.
intersperse :: Char -> [YiString] -> YiString

-- | Filters the characters from the underlying string.
--   
--   
--   >>> filter (/= 'a') "bac"
--   "bc"
--   
filter :: (Char -> Bool) -> YiString -> YiString

-- | Maps the characters over the underlying string.
map :: (Char -> Char) -> YiString -> YiString

-- | Splits the given YiString into a list of words, where spaces
--   are determined by isSpace. No empty strings are in the result
--   list.
words :: YiString -> [YiString]

-- | Join given YiStrings with a space. Empty lines will be filtered
--   out first.
unwords :: [YiString] -> YiString

-- | Splits the YiString on characters matching the predicate, like
--   split.
--   
--   For splitting on newlines use lines or lines' instead.
--   
--   Implementation note: GHC actually makes this naive implementation
--   about as fast and in cases with lots of splits, faster, as a
--   hand-rolled version on chunks with appends which is quite amazing in
--   itself.
split :: (Char -> Bool) -> YiString -> [YiString]

-- | Takes every character but the last one: returns Nothing on empty
--   string.
init :: YiString -> Maybe YiString

-- | Takes the tail of the underlying string. If the string is empty to
--   begin with, returns Nothing.
tail :: YiString -> Maybe YiString

-- | Returns a pair whose first element is the longest prefix (possibly
--   empty) of t of elements that satisfy p, and whose second is the
--   remainder of the string. See also span.
--   
--   This implementation uses splitAt which actually is just as fast
--   as hand-unrolling the tree. GHC sure is great!
span :: (Char -> Bool) -> YiString -> (YiString, YiString)

-- | Just like span but with the predicate negated.
break :: (Char -> Bool) -> YiString -> (YiString, YiString)

-- | Left fold.
--   
--   Benchmarks show that folding is actually Pretty Damn Slow™: consider
--   whether folding is really the best thing to use in your scenario.
foldl' :: (a -> Char -> a) -> a -> YiString -> a

-- | Replicate the given YiString set number of times, concatenating the
--   results. Also see replicateChar.
replicate :: Int -> YiString -> YiString

-- | Replicate the given character set number of times and pack the result
--   into a YiString.
--   
--   
--   >>> replicateChar 4 ' '
--   "    "
--   
replicateChar :: Int -> Char -> YiString

-- | Reads file into the rope, also returning the ConverterName
--   that was used for decoding. You should resupply this to
--   writeFile if you're aiming to preserve the original encoding.
--   
--   If we fail to guess the encoding used, error message is given instead.
--   
--   It is up to the user to handle exceptions not directly related to
--   character decoding.
readFile :: FilePath -> IO (Either Text YiString)

-- | Write a YiString into the given file.
--   
--   It's up to the user to handle exceptions.
writeFile :: FilePath -> YiString -> IO ()
fromRope :: YiString -> FingerTree Size YiChunk

-- | Helper function doing conversions of to and from underlying
--   Text. You should aim to implement everything in terms of
--   YiString instead.
--   
--   Please note that this maps over each chunk so this can only be
--   used with layout-agnostic functions. For example
--   
--   
--   >>> let t = 'fromString' "abc" <> 'fromString' "def"
--   
--   >>> 'toString' $ 'withText' 'TX.reverse' t
--   "cbafed"
--   
--   
--   Probably doesn't do what you wanted, but toUpper would.
--   Specifically, for any f : Text → Text,
--   withText will only do the ‘expected’ thing iff
--   
--   
--   f x <> f y ≡ f (x <> y)
--   
--   
--   which should look very familiar.
withText :: (Text -> Text) -> YiString -> YiString

-- | Maps over each chunk which means this function is UNSAFE! If
--   you use this with functions which don't preserve Size, that is
--   the chunk length and number of newlines, things will break really,
--   really badly. You should not need to use this.
--   
--   Also see unsafeFmap
unsafeWithText :: (Text -> Text) -> YiString -> YiString
instance GHC.Show.Show Yi.Rope.YiString
instance GHC.Classes.Eq Yi.Rope.YiChunk
instance GHC.Show.Show Yi.Rope.YiChunk
instance GHC.Show.Show Yi.Rope.Size
instance GHC.Classes.Eq Yi.Rope.Size
instance GHC.Classes.Eq Yi.Rope.YiString
instance Control.DeepSeq.NFData Yi.Rope.YiString
instance Data.String.IsString Yi.Rope.YiString
instance GHC.Base.Semigroup Yi.Rope.YiString
instance GHC.Base.Monoid Yi.Rope.YiString
instance GHC.Classes.Ord Yi.Rope.YiString
instance Data.Binary.Class.Binary Yi.Rope.YiString
instance Data.FingerTree.Measured Yi.Rope.Size Yi.Rope.YiChunk
instance Control.DeepSeq.NFData Yi.Rope.YiChunk
instance GHC.Base.Semigroup Yi.Rope.Size
instance GHC.Base.Monoid Yi.Rope.Size
instance Control.DeepSeq.NFData Yi.Rope.Size
