hs-bindgen-runtime
Safe HaskellSafe-Inferred
LanguageGHC2021

HsBindgen.Runtime.PtrConst

Description

Read-only pointers

This module is intended to be imported qualified.

import HsBindgen.Runtime.Prelude
import HsBindgne.Runtime.PtrConst qualified as PtrConst
Synopsis

Documentation

type PtrConst a = ConstPtr a Source #

A read-only pointer.

A PtrConst a is a pointer to a type a with a C const qualifier. For instance, the Haskell type PtrConst CInt is equivalent to the C type const int*. const-qualified contents of a pointer should not be modified, but reading the contents is okay.

peek :: Storable a => PtrConst a -> IO a Source #

Like peek

unsafeToPtr :: PtrConst a -> Ptr a Source #

Unsafe: convert a PtrConst to a Ptr.

NOTE: use the output pointer only with read access.

unsafeFromPtr :: Ptr a -> PtrConst a Source #

Unsafe: convert a Ptr to a PtrConst.

NOTE: use the input pointer only with read access.

Relationship with ConstPtr

PtrConst is a pointer-to-const-data, but ConstPtr is too. They are mostly equivalent, so why a new type? For two main reasons:

  1. ConstPtr is actually a misnomer: it is a pointer-to-const-data, not a const-pointer-to-data.
  2. ConstPtr can be freely converted to a Ptr, even though its contents should be considered to be read-only.

PtrConst is arguably a better name, and it goes further in ensuring that the pointer only has read access.

On base-4.18 and up, PtrConst is a type synonym around ConstPtr, while on earlier base versions it is a custom, opaque datatype. If you care about compatibility with all base versions that hs-bindgen-runtime support, then you should treat PtrConst as its own type distinct from ConstPtr using only the functions in the HsBindgen.Runtime.PtrConst module rather than the Foreign.C.ConstPtr module.