Module `Dtype.Ptr`

type t

Pointer dtype: a base Val.t plus address space, buffer element count (size), pointer vector width (v), and optional image metadata.

Invariant: v >= 1. size = -1 indicates an unbounded buffer. Image pointers additionally have base Val.float32, address space Global, size equal to the product of their image shape, and priority 100. Construct image pointers with Image.imageh or Image.imagef.

Accessors

val scalar : t -> scalar

scalar p is the scalar identity of the base value dtype.

val count : t -> int

count p is the vector width of the base value dtype.

val addrspace : t -> addr_space

addrspace p is the memory address space of p.

val v : t -> int

v p is the pointer vector width of p (number of independent pointer lanes packed together). Always >= 1.

val size : t -> int

size p is the number of elements in the pointed-to buffer, or -1 for unbounded.

val base : t -> Val.t

base p is the pointed-to value dtype (scalar and base count).

val value : t -> Val.t

value p is the dtype produced by reading through p. It preserves the pointer vector width: reading through float.ptr(...).vec(4) produces float.vec(4).

val image_kind : t -> image_kind option

image_kind p is Some kind if p is an image pointer dtype and None otherwise.

val image_shape : t -> int list option

image_shape p is Some shape if p is an image pointer dtype and None otherwise.

val is_image : t -> bool

is_image p is true iff p carries image metadata.

Constructors

val create : Val.t -> addrspace:addr_space -> size:int -> t

create base ~addrspace ~size is a pointer to base in addrspace with size elements (-1 for unbounded). Pointer vector width defaults to 1.

val create_v : Val.t -> addrspace:addr_space -> size:int -> v:int -> t

create_v base ~addrspace ~size ~v is like create with explicit pointer vector width v.

Raises Invalid_argument if v < 1.

Transformers

val scalarize : t -> t

scalarize p is p with pointer vector width 1 and base count = 1. The address space and size are preserved.

val vec : int -> t -> t

vec n p is p with pointer vector width set to n.

Raises Invalid_argument if n < 1 or if p is already vectorized.

val with_base : Val.t -> t -> t

with_base dt p is p with base value dtype replaced by dt. The address space, v, and size are preserved. Image metadata is removed because image dtypes have a fixed Val.float32 base.

val with_size : int -> t -> t

with_size n p is p with buffer element count set to n. Image metadata is removed if n differs from the current image size, because image dtype size is derived from shape.

Properties

val bitsize : t -> int

bitsize p is the base storage width in bits. For ordinary pointers it is the base scalar width times base count. For image pointers it is 16 for Imageh and 32 for Imagef.

val itemsize : t -> int

itemsize p is bitsize rounded up to whole bytes.

val nbytes : t -> int

nbytes p is size p * itemsize p.

Raises Invalid_argument if size p = -1.

val priority : t -> int

priority p is the promotion priority. Image pointers have priority 100, matching tinygrad image dtypes.

Comparison

val equal : t -> t -> bool

equal a b is true iff all fields of a and b are structurally equal (base scalar, base count, addrspace, v, size).

Note. IR validators may use partial field comparisons (e.g., index validation ignores size); those checks are intentionally distinct from this structural equality.

val compare : t -> t -> int

compare a b is a total order over pointer types. Orders by priority, base scalar priority, base count, addrspace, v, size, and image metadata.

Formatting

val to_string : t -> string

to_string p is a human-readable representation of p in the form {base}*[.vec(v)] [addrspace] (e.g., "f32* [global]", "i32*.vec(4) [local]").

val repr : t -> string

repr p is the tinygrad-style pointer or image dtype representation, such as "dtypes.float.ptr(-1)", "dtypes.int.ptr(4, AddrSpace.LOCAL).vec(2)", or "dtypes.imageh((8, 16, 4))".

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

pp formats a pointer dtype using to_string.