gi-gio-2.0.19: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell | None
Language | Haskell2010

GI.Gio.Interfaces.Seekable

Contents

- Exported types
- Methods
  - canSeek
  - canTruncate
  - seek
  - tell
  - truncate

Description

`Seekable` is implemented by streams (implementations of `InputStream` or `OutputStream`) that support seeking.

Seekable streams largely fall into two categories: resizable and fixed-size.

`Seekable` on fixed-sized streams is approximately the same as POSIX `lseek()` on a block device (for example: attempting to seek past the end of the device is an error). Fixed streams typically cannot be truncated.

`Seekable` on resizable streams is approximately the same as POSIX `lseek()` on a normal file. Seeking past the end and writing data will usually cause the stream to resize by introducing zero bytes.

Synopsis

- newtype Seekable = Seekable (ManagedPtr Seekable)
- noSeekable :: Maybe Seekable
- class GObject o => IsSeekable o
- toSeekable :: (MonadIO m, IsSeekable o) => o -> m Seekable
- seekableCanSeek :: (HasCallStack, MonadIO m, IsSeekable a) => a -> m Bool
- seekableCanTruncate :: (HasCallStack, MonadIO m, IsSeekable a) => a -> m Bool
- seekableSeek :: (HasCallStack, MonadIO m, IsSeekable a, IsCancellable b) => a -> Int64 -> SeekType -> Maybe b -> m ()
- seekableTell :: (HasCallStack, MonadIO m, IsSeekable a) => a -> m Int64
- seekableTruncate :: (HasCallStack, MonadIO m, IsSeekable a, IsCancellable b) => a -> Int64 -> Maybe b -> m ()

# Exported types

newtype Seekable Source #

Memory-managed wrapper type.

Constructors

Seekable (ManagedPtr Seekable) |

Instances

GObject Seekable Source # |
Instance details Defined in GI.Gio.Interfaces.Seekable Methods gobjectType :: Seekable -> IO GType Source #
IsObject Seekable Source # |
Instance details Defined in GI.Gio.Interfaces.Seekable
IsSeekable Seekable Source # |
Instance details Defined in GI.Gio.Interfaces.Seekable

noSeekable :: Maybe Seekable Source #

A convenience alias for `Nothing` :: `Maybe` `Seekable`.

class GObject o => IsSeekable o Source #

Type class for types which can be safely cast to `Seekable`, for instance with `toSeekable`.

Instances

(GObject a, (UnknownAncestorError Seekable a :: Constraint)) => IsSeekable a Source # |
Instance details Defined in GI.Gio.Interfaces.Seekable
IsSeekable Seekable Source # |
Instance details Defined in GI.Gio.Interfaces.Seekable
IsSeekable BufferedInputStream Source # |
Instance details Defined in GI.Gio.Objects.BufferedInputStream
IsSeekable FileIOStream Source # |
Instance details Defined in GI.Gio.Objects.FileIOStream
IsSeekable FileInputStream Source # |
Instance details Defined in GI.Gio.Objects.FileInputStream
IsSeekable FileOutputStream Source # |
Instance details Defined in GI.Gio.Objects.FileOutputStream
IsSeekable MemoryInputStream Source # |
Instance details Defined in GI.Gio.Objects.MemoryInputStream
IsSeekable MemoryOutputStream Source # |
Instance details Defined in GI.Gio.Objects.MemoryOutputStream
IsSeekable DataOutputStream Source # |
Instance details Defined in GI.Gio.Objects.DataOutputStream
IsSeekable BufferedOutputStream Source # |
Instance details Defined in GI.Gio.Objects.BufferedOutputStream
IsSeekable DataInputStream Source # |
Instance details Defined in GI.Gio.Objects.DataInputStream

toSeekable :: (MonadIO m, IsSeekable o) => o -> m Seekable Source #

Cast to `Seekable`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

## canSeek

seekableCanSeek Source #

Arguments

:: (HasCallStack, MonadIO m, IsSeekable a) |
=> a | `seekable`: a `Seekable`.
-> m Bool | Returns: `True` if `seekable` can be seeked. `False` otherwise.

Tests if the stream supports the `SeekableIface`.

## canTruncate

seekableCanTruncate Source #

Arguments

:: (HasCallStack, MonadIO m, IsSeekable a) |
=> a | `seekable`: a `Seekable`.
-> m Bool | Returns: `True` if the stream can be truncated, `False` otherwise.

Tests if the length of the stream can be adjusted with `seekableTruncate`.

## seek

seekableSeek Source #

Arguments

:: (HasCallStack, MonadIO m, IsSeekable a, IsCancellable b) |
=> a | `seekable`: a `Seekable`.
-> Int64 | `offset`: a `goffset`.
-> SeekType | `type`: a `SeekType`.
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> m () | (Can throw `GError`)

Seeks in the stream by the given `offset`, modified by `type`.

Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If the stream is resizable then seeking past the end and then writing will result in zeros filling the empty space. Seeking past the end of a resizable stream and reading will result in EOF. Seeking past the end of a fixed-sized stream will fail.

Any operation that would result in a negative offset will fail.

If `cancellable` is not `Nothing`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnumCancelled` will be returned.

## tell

seekableTell Source #

Arguments

:: (HasCallStack, MonadIO m, IsSeekable a) |
=> a | `seekable`: a `Seekable`.
-> m Int64 | Returns: the offset from the beginning of the buffer.

Tells the current position within the stream.

## truncate

seekableTruncate Source #

Arguments

:: (HasCallStack, MonadIO m, IsSeekable a, IsCancellable b) |
=> a | `seekable`: a `Seekable`.
-> Int64 | `offset`: new length for `seekable`, in bytes.
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> m () | (Can throw `GError`)

Sets the length of the stream to `offset`. If the stream was previously larger than `offset`, the extra data is discarded. If the stream was previouly shorter than `offset`, it is extended with NUL ('\0') bytes.

If `cancellable` is not `Nothing`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnumCancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.