caqti 1.5.0 · OCaml Package

Type descriptors for fields and tuples.

Primitive Field Types

The following is normally only needed for drivers and to define new field types. Everything needed for common usage is covered in Row Types.

type 'a field = ..

An extensible type describing primitive SQL types and types which can be converted to and from such types. When adding a new constructor, register the coding with Field.define_coding if possible. Otherwise, the type will only work with drivers which handle it themselves. The shipped drivers only handle the constructors listed here.

type field +=

| Bool : bool field
| Int : int field
| Int16 : int field
| Int32 : int32 field
| Int64 : int64 field
| Float : float field
| String : string field
| Octets : string field
| Pdate : Ptime.t field
| Ptime : Ptime.t field
| Ptime_span : Ptime.span field
| Enum : string -> string field

Primitive field types handled by the shipped drivers.

module Field : sig ... end

Facilities for extending and using primitive field types.

Row Types

type _ t = private

| Unit : unit t
| Field : 'a field -> 'a t
| Option : 'a t -> 'a option t
| Tup2 : 'a t * 'b t -> ('a * 'b) t
| Tup3 : 'a t * 'b t * 'c t -> ('a * 'b * 'c) t
| Tup4 : 'a t * 'b t * 'c t * 'd t -> ('a * 'b * 'c * 'd) t
| Custom : {
1. rep : 'b t;
2. encode : 'a -> ('b, string) Stdlib.result;
3. decode : 'b -> ('a, string) Stdlib.result;
} -> 'a t

Type descriptor for row types.

Note. The concrete representation of this type should be considered private, including pattern-matching usage; use the below functions for compatibility with future versions.

type any =

| Any : 'a t -> any

t with existentially wrapped static type.

val length : 'a t -> int

length t is the number of fields used to represent t.

val pp : Stdlib.Format.formatter -> 'a t -> unit

pp ppf t prints a human presentation of t on ppf.

val pp_any : Stdlib.Format.formatter -> any -> unit

pp_any ppf t prints a human presentation of t on ppf.

val pp_value : Stdlib.Format.formatter -> ('a t * 'a) -> unit

pp_value ppf (t, v) prints a human representation of v given the type descriptor t. This function is meant for debugging; the output is neither guaranteed to be consistent across releases nor to contain a complete record of the data.

val show : 'a t -> string

show t is a human presentation of t.

val field : 'a field -> 'a t

field ft is a row of a single field of type ft. This function can be used when adding new field types; use the below functions otherwise.

module Std : Caqti_type_sig.Std with type 'a t := 'a t

Standard type descriptors provided as a submodule for easy inclusion.

include Caqti_type_sig.Std with type 'a t := 'a t

Composite

The following provides constructors for narrow tuple types; to describe wider tuple types, use nested application.

val option : 'a t -> 'a option t

val unit : unit t

A type holding no fields. This is used to pass no parameters and as the result for queries which does not return any rows. It can also be nested in tuples, in which case it will not contribute to the total number of fields.

val tup2 : 'a t -> 'b t -> ('a * 'b) t

Creates a pair type.

val tup3 : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t

Creates a 3-tuple type.

val tup4 : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t

Creates a 4-tuple type.

val custom : 
  encode:('a -> ('b, string) Stdlib.result) ->
  decode:('b -> ('a, string) Stdlib.result) ->
  'b t ->
  'a t

custom ~encode ~decode rep creates a custom type represented by rep, where encode is used to encode parameters into rep and decode is used to decode result rows from rep.

Note. This should be considered experimental and may be revised or removed in a future version.

Singular

val bool : bool t

A bool mapped to boolean on the SQL side if supported, otherwise mapped to an integer.

val int : int t

An int mapped to a sufficiently wide integer on the SQL side.

val int16 : int t

An int mapped to a smallint (16 bits) on the SQL side.

val int32 : int32 t

An int32 mapped to an integer (32 bits) on the SQL side.

val int64 : int64 t

An int64 mapped to a bigint (64 bits) on the SQL side.

val float : float t

A float mapped to double precision or (best alternative) on the SQL side. Serialization may be lossy (e.g. base 10 may be used), so even if both sides support IEEE 754 double precision numbers, there may be discrepancies in the last digits of the binary representaton.

val string : string t

An UTF-8 string. The database should accept UTF-8 if non-ASCII characters are present.

val octets : string t

A string mapped to whichever type is used to represent binary data on the SQL side.

val pdate : Ptime.t t

A time truncated to a date and mapped to the SQL date type.

val ptime : Ptime.t t

An absolute time with driver-dependent precision. This corresponds to an SQL timestamp type with UTC time zone.

val ptime_span : Ptime.span t

A period of time. If the database lacks a dedicated representation, the integer number of seconds is used.

val enum : 
  encode:('a -> string) ->
  decode:(string -> ('a, string) Stdlib.result) ->
  string ->
  'a t

enum ~encode ~decode name creates an enum type which on the SQL side is named name, with cases which are converted with encode and decode functions. This is implemented in terms of the Caqti_type.Enum field type.

package caqti

Primitive Field Types

Row Types

Composite

Singular