Span

Unboxed span type for zero-allocation buffer references

The Span module provides an unboxed span type that references regions of buffers using offset and length. Spans use int16# internally since the maximum buffer size is 32KB, enabling zero-allocation buffer operations.

Type Definition

t · record

The span type representing an offset and length into a buffer.

off · int16#

Offset into the buffer (unboxed int16)

len · int16#

Length of the span (unboxed int16)

Construction

make

val make : off:int16# -> len:int16# -> t

Create a span from int16# offset and length.

off · int16# · required

The offset into the buffer

len · int16# · required

The length of the span

Example:

let span = Span.make ~off:(Span.of_int 10) ~len:(Span.of_int 5)

Conversion Functions

of_int

val of_int : int -> int16#

Convert int to int16# for use in span construction.

n · int · required

The integer value to convert

to_int

val to_int : int16# -> int

Convert int16# to int for regular operations.

n · int16# · required

The unboxed int16 value to convert

Accessors

off16

val off16 : t -> int16#

Get offset as int16# (unboxed).

span · t · required

The span to get the offset from

len16

val len16 : t -> int16#

Get length as int16# (unboxed).

span · t · required

The span to get the length from

off

val off : t -> int

Get offset as int (for array indexing).

span · t · required

The span to get the offset from

Example:

let offset = Span.off span in
let byte = Bigstringaf.get buffer offset

len

val len : t -> int

Get length as int (for comparisons with String.length etc).

span · t · required

The span to get the length from

Comparison Functions

equal

val equal : local_ Base_bigstring.t -> t -> string -> bool

Case-sensitive comparison of span contents with a string.

buf · local_ Base_bigstring.t · required

The buffer containing the span data

span · t · required

The span to compare

str · string · required

The string to compare against

Example:

if Span.equal buffer method_span "GET" then
  (* Handle GET request *)
  ...

equal_caseless

val equal_caseless : local_ Base_bigstring.t -> t -> string -> bool

Case-insensitive comparison of span contents with a string.

buf · local_ Base_bigstring.t · required

The buffer containing the span data

span · t · required

The span to compare

str · string · required

The string to compare against (case-insensitive)

Example:

if Span.equal_caseless buffer header_value "chunked" then
  (* Handle chunked encoding *)
  ...

Parsing Functions

parse_int64

val parse_int64 : local_ Base_bigstring.t -> t -> int64#

Parse decimal integer from span. Returns -1L on error.

This does NOT check for overflow. Use parse_int64_limited for security-critical parsing.

buf · local_ Base_bigstring.t · required

The buffer containing the span data

span · t · required

The span containing the decimal digits

Example:

let content_length = Span.parse_int64 buffer length_span in
if Int64.compare content_length (Int64.of_int (-1)) = 0 then
  (* Invalid number *)
  ...

parse_int64_limited

val parse_int64_limited : local_ Base_bigstring.t -> t -> max_value:int64# -> #(int64# * bool)

Parse decimal integer from span with overflow protection and maximum value limit.

Returns unboxed tuple #(value, overflow_flag) where:

• value: parsed value or -1L if empty/invalid
• overflow_flag: true if value exceeds max_value or has too many digits

buf · local_ Base_bigstring.t · required

The buffer containing the span data

span · t · required

The span containing the decimal digits

max_value · int64# · required

Maximum allowed value (returns overflow flag if exceeded)

Example:

let max_content_length = Int64.of_int 10_000_000 in
let #(length, overflow) = 
  Span.parse_int64_limited buffer length_span ~max_value:max_content_length in
if overflow then
  (* Content-Length too large *)
  raise (Error Content_length_overflow)

Conversion to Allocated Types

to_string

val to_string : local_ Base_bigstring.t -> t -> string

Copy span contents to a string. Allocates memory.

buf · local_ Base_bigstring.t · required

The buffer containing the span data

span · t · required

The span to copy

Example:

let path = Span.to_string buffer request.target_span in
printf "Request path: %s\n" path

to_bytes

val to_bytes : local_ Base_bigstring.t -> t -> bytes

Copy span contents to bytes. Allocates memory.

buf · local_ Base_bigstring.t · required

The buffer containing the span data

span · t · required

The span to copy

Pretty Printing

pp_with_buf

val pp_with_buf : local_ Base_bigstring.t -> Stdlib.Format.formatter -> t -> unit

Pretty-print span contents using buffer.

buf · local_ Base_bigstring.t · required

The buffer containing the span data

formatter · Stdlib.Format.formatter · required

The formatter to print to

span · t · required

The span to print

pp

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

Pretty-print span structure (offset and length).

formatter · Stdlib.Format.formatter · required

The formatter to print to

span · t · required

The span to print

Example:

Format.printf "Span: %a@." Span.pp span
(* Output: Span: {off=10; len=5} *)