Range on Opensource internals

CPython's range Implementation in C: Lazy Sequences That Never Materialize

Jay Hubbert — Tue, 20 Oct 2026 09:00:00 +0000

TL;DR: range isn’t a list of integers. It’s four PyObject * fields — start, stop, step, and a cached length — and every value is computed on demand. len() is O(1), indexing is arithmetic, and x in range(...) is O(1) when x is an int.

Python’s range is not a list of integers. It’s a tiny immutable object that remembers only its start, stop, and step, then computes everything else on demand. range(0, 10**18) takes exactly the same memory as range(3).

In CPython that’s rangeobject in Objects/rangeobject.c, with a cached length and two iterator types. Let’s walk the representation and the hot paths through the 3.15 source.

The object struct

 c
 
 
// Objects/rangeobject.c
typedef struct {
 PyObject_HEAD
 PyObject *start;
 PyObject *stop;
 PyObject *step;
 PyObject *length;
} rangeobject;

Four PyObject * fields, all owned references. start, stop, and step are the user-supplied bounds, normalized to PyLong objects via PyNumber_Index in range_from_array. length is the precomputed number of items, also a PyLong.

There’s no array of integers anywhere. The sequence is fully lazy.

rangeobject is a fixed-size PyObject (sizeof(rangeobject)), so its allocation cost is constant no matter how many values the range would yield. Deallocation just decrements the four fields and returns the object to a small freelist (Py_ranges_MAXFREELIST == 6):

 c
 
 
// Objects/rangeobject.c
static void range_dealloc(PyObject *op) {
 rangeobject *r = (rangeobject*)op;
 Py_DECREF(r->start);
 Py_DECREF(r->stop);
 Py_DECREF(r->step);
 Py_DECREF(r->length);
 _Py_FREELIST_FREE(ranges, r, PyObject_Free);
}

Construction and the cached length

range_new / range_vectorcall funnel into range_from_array, which converts arguments and calls make_range_object:

 c
 
 
// Objects/rangeobject.c
static rangeobject *make_range_object(PyTypeObject *type, PyObject *start,
 PyObject *stop, PyObject *step) {
 PyObject *length = compute_range_length(start, stop, step);
 if (length == NULL) return NULL;
 rangeobject *obj = _Py_FREELIST_POP(rangeobject, ranges);
 if (obj == NULL) {
 obj = PyObject_New(rangeobject, type);
 ...
 }
 obj->start = start;
 obj->stop = stop;
 obj->step = step;
 obj->length = length;
 return obj;
}

compute_range_length first tries a fast path where all three values fit in a C long (compute_range_length_long), using the same formula as get_len_of_range:

 c
 
 
// Objects/rangeobject.c
static unsigned long get_len_of_range(long lo, long hi, long step) {
 assert(step != 0);
 if (step > 0 && lo < hi)
 return 1UL + (hi - 1UL - lo) / step;
 else if (step < 0 && lo > hi)
 return 1UL + (lo - 1UL - hi) / (0UL - step);
 else
 return 0UL;
}

If any value overflows long (or the result doesn’t fit), it falls back to PyObject arithmetic: take the positive-step case, compute (hi - lo - 1) // step + 1, clamping to zero when lo >= hi.

The result is stored once in r->length, so len(r) is just:

 c
 
 
// Objects/rangeobject.c
static Py_ssize_t range_length(PyObject *op) {
 rangeobject *r = (rangeobject*)op;
 return PyLong_AsSsize_t(r->length);
}

That’s why len(range(...)) is O(1) — and why a range whose length exceeds PY_SSIZE_T_MAX (possible on Win64 with huge ints) still works through the length field even though sq_length can’t represent it.

Indexing: computing, not looking up

range_item / range_subscript never touch a buffer. For an integer index, compute_range_item normalizes negative indices against length, bounds-checks, then computes the value:

 c
 
 
// Objects/rangeobject.c
static PyObject *compute_item(rangeobject *r, PyObject *i) {
 /* PyLong equivalent to: return r->start + (i * r->step) */
 if (r->step == _PyLong_GetOne()) {
 return PyNumber_Add(r->start, i);
 } else {
 PyObject *incr = PyNumber_Multiply(i, r->step);
 if (!incr) return NULL;
 PyObject *result = PyNumber_Add(r->start, incr);
 Py_DECREF(incr);
 return result;
 }
}

Notice the fast path when step == 1: it skips the multiply entirely. Negative indices are handled by adding length to the index first, exactly like standard sequence semantics. Out-of-range indices raise IndexError.

Slicing returns a new range, not a list. compute_slice uses _PySlice_GetLongIndices against r->length, then builds substart = compute_item(r, start), substop = compute_item(r, stop) and substep = r->step * step, and constructs a new range via make_range_object. So range(10)[2:8:2] is range(2, 8, 4) and costs O(1).

`contains` is O(1)

For an exact int (or bool), range_contains dispatches to range_contains_long, which avoids iteration entirely:

 c
 
 
// Objects/rangeobject.c
static int range_contains_long(rangeobject *r, PyObject *ob) {
 /* Check if the value can possibly be in the range. */
 cmp1 = PyObject_RichCompareBool(r->step, zero, Py_GT);
 if (cmp1 == 1) { /* positive steps: start <= ob < stop */
 cmp2 = PyObject_RichCompareBool(r->start, ob, Py_LE);
 cmp3 = PyObject_RichCompareBool(ob, r->stop, Py_LT);
 } else { /* negative steps: stop < ob <= start */
 cmp2 = PyObject_RichCompareBool(ob, r->start, Py_LE);
 cmp3 = PyObject_RichCompareBool(r->stop, ob, Py_LT);
 }
 if (cmp2 == 0 || cmp3 == 0) { /* ob outside of range */
 result = 0; goto end;
 }
 /* Check that the stride does not invalidate membership. */
 tmp1 = PyNumber_Subtract(ob, r->start);
 tmp2 = PyNumber_Remainder(tmp1, r->step);
 result = PyObject_RichCompareBool(tmp2, zero, Py_EQ);
end:
 ...
}

The algorithm is two steps: bound check (start <= ob < stop for a positive step, reversed for a negative one), then a divisibility check (ob - start) % step == 0. Both are O(1) big-int operations.

Gotcha: for any other object type, range_contains falls back to _PySequence_IterSearch — a linear scan. So x in range(...) is only guaranteed O(1) when x is an int.

range_index reuses the same membership test and then computes the index as (ob - start) // step (or just ob - start when step is 1).

Iteration: two tiers

range_iter picks between a fast C-long iterator and a generic PyObject-based one, depending on whether everything fits in a long:

 c
 
 
// Objects/rangeobject.c
static PyObject *range_iter(PyObject *seq) {
 rangeobject *r = (rangeobject *)seq;
 long lstart = PyLong_AsLong(r->start);
 if (lstart == -1 && PyErr_Occurred()) { PyErr_Clear(); goto long_range; }
 ... /* lstop, lstep similarly */
 ulen = get_len_of_range(lstart, lstop, lstep);
 if (ulen > (unsigned long)LONG_MAX) goto long_range;
 /* overflow check for lstart + ulen * lstep */
 ...
 return fast_range_iter(lstart, lstop, lstep, (long)ulen);
long_range:
 it = PyObject_New(longrangeiterobject, &PyLongRangeIter_Type);
 it->start = Py_NewRef(r->start);
 it->step = Py_NewRef(r->step);
 it->len = Py_NewRef(r->length);
 return (PyObject *)it;
}

The fast tier uses _PyRangeIterObject, whose entire state is three C longs:

 c
 
 
// Include/internal/pycore_range.h
typedef struct {
 PyObject_HEAD
 long start;
 long step;
 long len;
} _PyRangeIterObject;

Its tp_iternext is trivial, and allocation-free beyond the first PyLong_FromLong:

 c
 
 
// Objects/rangeobject.c
static PyObject *rangeiter_next(PyObject *op) {
 _PyRangeIterObject *r = (_PyRangeIterObject*)op;
 if (r->len > 0) {
 long result = r->start;
 r->start = result + r->step;
 r->len--;
 return PyLong_FromLong(result);
 }
 return NULL;
}

The generic tier (longrangeiterobject) stores PyObject *start/step/len and does PyNumber_Add / PyNumber_Subtract per step, so it handles arbitrary-precision bounds at the cost of per-iteration allocation. Both iterators are recycled through freelists of size 6.

__reversed__ (range_reverse) re-expresses the reversed sequence as a new range range(start+(n-1)*step, start-step, -step) and again prefers the fast C-long iterator when all values fit.

Memory efficiency summary

A range is sizeof(rangeobject) (≈ 40 bytes on 64-bit) plus the four referenced PyLong objects — independent of its length.
The length is computed once at construction (O(1) for small ints, big-int arithmetic otherwise) and cached.
Indexing, slicing, containment, and len() are all O(1) for ints. Only non-int containment and iteration over huge values degrade.
Iteration has a zero-allocation-per-step fast path for the common case where bounds fit in a C long.

Key takeaways

range stores only start, stop, step, and a cached length. The sequence is never materialized.
Membership of an int is O(1) via a bounds check plus a modulo divisibility test; non-ints fall back to a linear search.
Indexing computes start + i * step; slicing produces another range.
There are two iterator tiers: a C-long fast path (_PyRangeIterObject) and a generic PyObject path for arbitrary precision.
Both range and its iterators are recycled through 6-deep freelists.

PostgreSQL's Multirange Type Implementation in C

Jay Hubbert — Mon, 31 Aug 2026 11:06:16 +0000

A multirange is what you get when you let a range type hold more than one range: int4multirange can be {[1,5),[10,20)}. The surprising thing is how little C there is to it. All six built-in multirange types — int4multirange, int8multirange, nummultirange, tsmultirange, tstzmultirange, datemultirange — are implemented by one set of functions in src/backend/utils/adt/multirangetypes.c. The only thing that varies is the element type, and even that is not compiled in; it is looked up at runtime.

This is a walk through the stored layout, based on reading the PostgreSQL source (version 20devel, commit e75fcc9867f).

The catalog

The six concrete multirange types live in src/include/catalog/pg_type.dat:

oid	type	element type	`typalign`	array oid
4451	`int4multirange`	`int4`	`i`	6150
4532	`nummultirange`	`numeric`	`i`	6151
4533	`tsmultirange`	`timestamp`	`d`	6152
4534	`tstzmultirange`	`timestamptz`	`d`	6153
4535	`datemultirange`	`date`	`i`	6155
4536	`int8multirange`	`int8`	`d`	6157

They are all typlen => -1 (varlena), typbyval => f, typtype => 'm', typcategory => 'R', and typstorage => 'x' (fully toastable). typalign is copied from the element type, which is why the integer and date multiranges are 4-byte aligned while the timestamp and bigint ones are 8-byte aligned. The element mapping is recorded in src/include/catalog/pg_range.dat as rngmultitypid, alongside the range constructor functions (rngmltconstruct0/1/2).

There is no seventh concrete type. The oid 4537 in the neighborhood is anymultirange, a typtype => 'p' pseudo-type used for polymorphic functions — not a value you can store.

The in-memory struct

MultirangeType is declared in src/include/utils/multirangetypes.h:

 c
 
 
typedef struct
{
	int32		vl_len_;		/* varlena header (do not touch directly!) */
	Oid			multirangetypid;	/* multirange type's own OID */
	uint32		rangeCount;		/* the number of ranges */

	/*
	 * Following the count are the range objects themselves, as ShortRangeType
	 * structs. Note that ranges are varlena too, depending on whether they
	 * have lower/upper bounds and because even their base types can be
	 * varlena. So we can't really index into this list.
	 */
} MultirangeType;

Twelve bytes. The “ShortRangeType structs” are not a real struct — they are just the bound values and a flags byte, appended after the header. Because the bounds can be variable length, you cannot index into the array directly; you have to walk it. That constraint shapes the entire format.

The stored format

The file’s header comment states the layout, and it is worth reading verbatim:

 text
 
 
12 bytes: MultirangeType struct including varlena header, multirange
 type's OID and the number of ranges in the multirange.
4 * (rangesCount - 1) bytes: 32-bit items pointing to the each range
 in the multirange starting from the second one.
1 * rangesCount bytes : 8-bit flags for each range in the multirange
The rest of the multirange are range bound values pointed by multirange items.

So after the 12-byte header comes an array of (rangeCount - 1) 32-bit items (the first range starts at offset zero and needs no item), then rangeCount one-byte flags, then the aligned bound values. The clever part is what goes in the items:

 c
 
 
#define MULTIRANGE_ITEM_OFF_BIT 0x80000000
#define MULTIRANGE_ITEM_GET_OFFLEN(item) ((item) & 0x7FFFFFFF)
#define MULTIRANGE_ITEM_HAS_OFF(item) ((item) & MULTIRANGE_ITEM_OFF_BIT)
#define MULTIRANGE_ITEM_OFFSET_STRIDE 4

Most items store a length, which makes them small and therefore compression-friendly. Every fourth item (i % 4 == 0) instead stores an absolute offset with the high bit set. That gives you a cheap “jump point” every four ranges while keeping the common case tiny. write_multirange_data() shows the encoding:

 c
 
 
items[i - 1] = ptr - begin;
if ((i % MULTIRANGE_ITEM_OFFSET_STRIDE) != 0)
	items[i - 1] -= prev_offset;	/* a length */
else
	items[i - 1] |= MULTIRANGE_ITEM_OFF_BIT;	/* an absolute offset */
prev_offset = ptr - begin;

Canonicalization: sort and merge on the way in

make_multirange() is the single entry point every constructor calls. Its first act is multirange_canonicalize(), which sorts the incoming ranges and merges any that touch:

 c
 
 
if (range_adjacent_internal(rangetyp, lastRange, currentRange))
{
	ranges[output_range_count - 1] = lastRange =
		range_union_internal(rangetyp, lastRange, currentRange, false);
}

The result is canonical: ranges are stored in order, non-overlapping, and never adjacent. That is why int4multirange(int4range(1,5), int4range(5,10)) and int4multirange(int4range(1,10)) are the same value — and why equality can be a straight range-by-range comparison. Note that empty ranges are dropped entirely; a multirange can never contain an empty range. It just stores zero ranges and reports MultirangeIsEmpty(mr) as mr->rangeCount == 0.

Reading a range back out

multirange_get_bounds() is the workhorse. It computes the offset by summing lengths until it hits an offset item:

 c
 
 
while (i > 0)
{
	offset += MULTIRANGE_ITEM_GET_OFFLEN(items[i - 1]);
	if (MULTIRANGE_ITEM_HAS_OFF(items[i - 1]))
		break;
	i--;
}

Then it walks the bound values using the element type’s typlen/typalign and returns a RangeBound for each side, reading the flags byte to fill in inclusive/infinite state. multirange_get_range() is the same walk but with the bound bytes copied into a freshly allocated RangeType. The fast path is deliberately cheaper: it avoids constructing a whole range when only the bounds are wanted.

The binary wire format is a different animal. multirange_send() writes an int32 range count, then for each range an int32 length followed by that range’s binary encoding; multirange_recv() mirrors it. It stores neither the multirange OID nor the compact item array.

Comparison and hashing

multirange_cmp() is the btree comparator. It walks the two multiranges range by range and compares lower then upper bounds; a shorter multirange is treated as if padded with empty ranges at the end, so it sorts first:

 c
 
 
if (i >= range_count_1)
{
	cmp = -1;
	break;
}

multirange_eq_internal() is a bound-by-bound loop, and equality of the OIDs is asserted up front. Hashing is hash_multirange(): each range’s flags and bounds are hashed through the element type’s hash function, then folded together:

 c
 
 
range_hash = hash_bytes_uint32((uint32) flags);
range_hash ^= lower_hash;
range_hash = pg_rotate_left32(range_hash, 1);
range_hash ^= upper_hash;
result = (result << 5) - result + range_hash;

That (result << 5) - result trick is the same one hash_array uses to combine elements. There is also a hash_multirange_extended() for 64-bit, seeded hashing.

Look at it yourself

The sizes follow directly from the layout. An empty int4multirange is just the 12-byte header; adding a range adds one flags byte plus the aligned bounds:

 sql
 
 
SELECT octet_length('{}'::int4multirange); -- 12
SELECT octet_length('{[1,5)}'::int4multirange); -- 24
SELECT octet_length('{[1,5),[10,20)}'::int4multirange); -- 36

Canonicalization and unnest are visible too:

 sql
 
 
SELECT '{[1,5),[5,10)}'::int4multirange; -- {[1,10)}
SELECT unnest('{[1,5),[10,20)}'::int4multirange);
-- int4range
-- ----------
-- [1,5)
-- [10,20)

The multirange family is supported by btree/multirange_ops, hash/multirange_ops, and gist/multirange_ops (see pg_amproc.dat), so you can put a multirange in an index or a hash join.

What it all means

A multirange is a varlena with a 12-byte header, a compact item array, a flags array, and aligned bound values.
The items store lengths by default and absolute offsets every fourth entry, which is what makes the format cheap to compress and cheap to seek into.
make_multirange() canonicalizes: sort, drop empties, merge touching ranges. The stored form is canonical, which is why equality is a simple comparison.
All six types share one implementation; only the element type, and therefore the alignment and the element hash/compare functions, differs.
The wire format is not the storage format — send/recv use a flat length-prefixed list of range encodings.

PostgreSQL's Range Type Implementation in C

Jay Hubbert — Thu, 13 Aug 2026 21:37:21 +0000

A range type is one of PostgreSQL’s stranger storage formats. It is a variable-length value, but its first four bytes are not a payload — they are the length of the whole thing, then four more bytes holding the range type’s own OID, then up to two bound values stored inline, and finally a single flags byte at the very end. There is no length prefix per bound, no padding before the lower bound, and no separate “empty” representation. The whole format is documented in a comment at the top of rangetypes.c, and it is worth reading before you ever hex-dump one.

This is a walk through the layout and the canonicalization, based on reading the PostgreSQL source (commit e75fcc9867f).

The catalog and the subtype table

The six built-in range types live in src/include/catalog/pg_type.dat:

oid	type	subtype	`typalign`	array oid
3904	`int4range`	`int4`	`i`	3905
3906	`numrange`	`numeric`	`i`	3907
3908	`tsrange`	`timestamp`	`d`	3909
3910	`tstzrange`	`timestamptz`	`d`	3911
3912	`daterange`	`date`	`i`	3913
3926	`int8range`	`int8`	`d`	3927

They are all typlen => -1, typbyval => f, typtype => 'r', typcategory => 'R', and typstorage => 'x'. typalign is copied from the subtype — that is why int4range and numrange are 4-byte aligned while tsrange and int8range are 8-byte aligned.

The relationship between a range and its element type is not inferred; it is recorded in src/include/catalog/pg_range.dat:

 c
 
 
{ rngtypid => 'int4range', rngsubtype => 'int4',
 rngmultitypid => 'int4multirange', rngsubopc => 'btree/int4_ops',
 rngconstruct2 => 'int4range(int4,int4)',
 rngconstruct3 => 'int4range(int4,int4,text)',
 ...
 rngcanonical => 'int4range_canonical', rngsubdiff => 'int4range_subdiff' },

That last pair of fields is the heart of the type. rngcanonical points at a per-type canonicalization function, and only three of the six have one: int4range, int8range, and daterange. The continuous types — numrange, tsrange, tstzrange — have rngcanonical => '-'. That single difference is why int4range(1,5,'(]') comes back as [2,6) while numrange(1,5,'(]') stays (1,5].

At runtime all of this is cached in a TypeCacheEntry (src/include/utils/typcache.h) with the fields rngelemtype, rng_collation, rng_cmp_proc_finfo, rng_canonical_finfo, and rng_subdiff_finfo. The I/O functions cache theirs in fn_extra as a RangeIOData.

The on-disk struct

RangeType is declared in src/include/utils/rangetypes.h:

 c
 
 
typedef struct
{
	int32		vl_len_;		/* varlena header (do not touch directly!) */
	Oid			rangetypid;		/* range type's own OID */
	/* Following the OID are zero to two bound values, then a flags byte */
} RangeType;

Eight bytes. The bounds are not named fields — they are variable-length trailing data whose position is computed from the flags. The flags byte is the last byte of the object:

 c
 
 
#define RANGE_EMPTY			0x01	/* range is empty */
#define RANGE_LB_INC		0x02	/* lower bound is inclusive */
#define RANGE_UB_INC		0x04	/* upper bound is inclusive */
#define RANGE_LB_INF		0x08	/* lower bound is -infinity */
#define RANGE_UB_INF		0x10	/* upper bound is +infinity */
#define RANGE_LB_NULL		0x20	/* lower bound is null (NOT USED) */
#define RANGE_UB_NULL		0x40	/* upper bound is null (NOT USED) */
#define RANGE_CONTAIN_EMPTY 0x80	/* marks a GiST internal-page entry whose
									 * subtree contains some empty ranges */

The two RANGE_*_NULL bits are defined but never used; a NULL bound is instead represented as an infinity, which is why int4range(NULL,5) and '(,5]'::int4range are the same value. RANGE_CONTAIN_EMPTY is a GiST-only optimization bit, not part of a user value.

Serialization: bounds inline, flags last

range_serialize() is the function that turns two RangeBound structs into bytes. It first validates, then measures, then writes. The header comment on the file states the layout and the alignment trick:

4 bytes: varlena header 4 bytes: range type’s OID Lower boundary value, if any, aligned according to subtype’s typalign Upper boundary value, if any, aligned according to subtype’s typalign 1 byte for flags

This representation is chosen to avoid needing any padding before the lower boundary value, even when it requires double alignment. We can expect that the varlena header is presented to us on a suitably aligned boundary (possibly after detoasting), and then the lower boundary is too.

The code asserts exactly that — sizeof(RangeType) is 8 and MAXALIGN(sizeof(RangeType)) is 8:

 c
 
 
/* Count space for varlena header and range type's OID */
msize = sizeof(RangeType);
Assert(msize == MAXALIGN(msize));

/* Count space for bounds */
if (RANGE_HAS_LBOUND(flags))
{
	if (typlen == -1)
		lower->val = PointerGetDatum(PG_DETOAST_DATUM_PACKED(lower->val));
	msize = datum_compute_size(msize, lower->val, typbyval, typalign,
							 typlen, typstorage);
}
...
/* Add space for flag byte */
msize += sizeof(char);

/* Note: zero-fill is required here, just as in heap tuples */
range = (RangeType *) palloc0(msize);
SET_VARSIZE(range, msize);
range->rangetypid = typcache->type_id;

ptr = (char *) (range + 1);
... /* write lower, then upper */
*((char *) ptr) = flags;

datum_compute_size() and datum_write() are deliberately modeled on heap_compute_data_size() and heap_fill_tuple() from heaptuple.c, and they implement the same alignment and short-varlena rules. Two details are worth pulling out:

A range can never contain a TOAST pointer. datum_write() throws cannot store a toast pointer inside a range if it sees VARATT_IS_EXTERNAL. The caller detoasts first, so compression is applied to the whole range object rather than to individual bounds.
Short varlenas are packed. If the subtype is packable (TYPE_IS_PACKABLE(typlen, typstorage)) and the bound fits, the bound is written with a 1-byte header and no alignment padding, exactly as a text column would be. numeric’s typstorage is 'm', so numrange bounds qualify.

Deserialization: flags first, then bounds

range_deserialize() is the mirror image. It reads the flags byte from the last byte, because that is cheaper than trying to know the bounds’ size first:

 c
 
 
/* fetch the flag byte from datum's last byte */
flags = *((const char *) range + VARSIZE(range) - 1);

/* initialize data pointer just after the range OID */
ptr = (const char *) (range + 1);

/* fetch lower bound, if any */
if (RANGE_HAS_LBOUND(flags))
{
	lbound = fetch_att(ptr, typbyval, typlen);
	ptr = att_addlength_pointer(ptr, typlen, ptr);
}

/* fetch upper bound, if any */
if (RANGE_HAS_UBOUND(flags))
{
	ptr = (char *) att_align_pointer(ptr, typalign, typlen, ptr);
	ubound = fetch_att(ptr, typbyval, typlen);
}

For by-reference element types the Datums returned are pointers into the range object — the header warns about this explicitly. range_get_flags() is a one-liner used by the GiST code that only needs the flags.

Input, output, and canonicalization

Text input goes through range_parse() and range_parse_bound(). It accepts the literal empty (case-insensitive), [ / ( for the lower bound, ] / ) for the upper, and per-bound quoting and backslash escaping. An empty bound string becomes an infinity; a quoted empty string is the literal empty value. Output is the inverse in range_deparse() / range_bound_escape().

range_in() then hands each bound string to the subtype’s input function via InputFunctionCallSafe, builds two RangeBounds, and calls make_range(). make_range() is the public entry point: it calls range_serialize() and then, if the type has a canonicalization function, invokes it:

 c
 
 
range = range_serialize(typcache, lower, upper, empty, escontext);
...
if (OidIsValid(typcache->rng_canonical_finfo.fn_oid) &&
	!RangeIsEmpty(range))
{
	...
	result = FunctionCallInvoke(fcinfo);
	...
	range = DatumGetRangeTypeP(result);
}

For the discrete types the canonical function shifts an exclusive bound to the adjacent inclusive integer. int4range_canonical():

 c
 
 
if (!lower.infinite && !lower.inclusive)
{
	int32		bnd = DatumGetInt32(lower.val);

	if (unlikely(bnd == PG_INT32_MAX))
		ereturn(escontext, (Datum) 0,
				(errcode(ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE),
				 errmsg("integer out of range")));
	lower.val = Int32GetDatum(bnd + 1);
	lower.inclusive = true;
}

if (!upper.infinite && upper.inclusive)
{
	int32		bnd = DatumGetInt32(upper.val);

	if (unlikely(bnd == PG_INT32_MAX))
		ereturn(escontext, (Datum) 0,
				(errcode(ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE),
				 errmsg("integer out of range")));
	upper.val = Int32GetDatum(bnd + 1);
	upper.inclusive = false;
}

So [1,5] becomes [1,6), (1,5) becomes [2,5), and (1,5)’s left-neighbour int4range(1,5,'(]') becomes [2,6). daterange_canonical() does the same with a DateADT increment and a validity check. The continuous types have no such function, which is exactly why their bounds are not rewritten.

Comparison is range_cmp_bounds(). It handles infinities without calling the subtype’s comparison function, and when two finite bounds compare equal it refines the answer using the inclusive/exclusive flags. range_compare() is the qsort comparator used for sorting range values.

The binary format is a different animal

The text and storage layouts above are for range_send() and the heap. The wire format used by range_send() / range_recv() is simpler and does not store the range OID or the bounds inline: it writes the flags byte first, then each bound as a 4-byte length followed by the subtype’s binary encoding:

 c
 
 
pq_sendbyte(&buf, flags);

if (RANGE_HAS_LBOUND(flags))
{
	bytea	 *bound = SendFunctionCall(&cache->typioproc, lower.val);
	uint32		bound_len = VARSIZE(bound) - VARHDRSZ;

	pq_sendint32(&buf, bound_len);
	pq_sendbytes(&buf, bound_data, bound_len);
}

This is the same convention used by record types. Note also the defensive mask in range_recv() that strips the unused RANGE_*_NULL bits before decoding.

Statistics: a histogram of bounds

Because a range has two bounds, ANALYZE cannot use the ordinary scalar histogram. range_typanalyze() (in src/backend/utils/adt/rangetypes_typanalyze.c) builds a combined histogram whose entries are ranges formed from the sorted lower bounds and the sorted upper bounds, plus a separate empty-range fraction. The selectivity code in rangetypes_selfuncs.c reads that empty fraction first and merges it with the histogram estimate; for operators like @> it knows an empty range is contained by everything, while for < it matches nothing.

Look at it yourself

The sizes are observable with pg_column_size, which works on any type (octet_length accepts only string types), and they reveal the layout. For a 17-byte int4range the flags byte is the last byte:

 sql
 
 
SELECT pg_column_size(int4range(1,5)); -- 17
SELECT pg_column_size(int8range(1,5)); -- 25
SELECT pg_column_size(daterange('2020-01-01','2020-12-31')); -- 17
SELECT pg_column_size(tsrange('2020-01-01','2020-12-31')); -- 25
SELECT pg_column_size('empty'::int4range); -- 9

That is sizeof(RangeType) (8) + the two bounds + one flags byte. Canonicalization is visible directly:

 sql
 
 
SELECT int4range(1,5,'(]'); -- [2,6)
SELECT int4range(1,5,'[]'); -- [1,6)
SELECT numrange(1,5,'(]'); -- (1,5] -- no canonicalization
SELECT daterange('2020-01-01','2020-12-31','[]'); -- [2020-01-01,2021-01-01)

The empty range is not NULL and not a zero-length value; it is a real 9-byte object whose flags byte has RANGE_EMPTY set and whose two bounds are absent.

What it all means

A range is a varlena: 4-byte length, 4-byte type OID, up to two inline bounds, one trailing flags byte.
The bounds are stored using the subtype’s typalign and the same short-varlena rules as heap columns; a range can never hold a TOAST pointer.
The flags byte is read from the last byte, which is why the format puts it last and why there is no per-bound length.
Discrete types (int4, int8, date) canonicalize exclusive bounds to adjacent integers; the continuous types do not. That one catalog field, rngcanonical, is the whole difference.
Comparison refines equal finite bounds by their inclusive/exclusive flags.
ANALYZE builds a bounds histogram plus an empty fraction, and the selectivity functions special-case empty ranges.

Range on Opensource internals

CPython's range Implementation in C: Lazy Sequences That Never Materialize

The object struct

Construction and the cached length

Indexing: computing, not looking up

`contains` is O(1)

Iteration: two tiers

Memory efficiency summary

Key takeaways

Further reading

PostgreSQL's Multirange Type Implementation in C

The catalog

The in-memory struct

The stored format

Canonicalization: sort and merge on the way in

Reading a range back out

Comparison and hashing

Look at it yourself

What it all means

Further reading

PostgreSQL's Range Type Implementation in C

The catalog and the subtype table

The on-disk struct

Serialization: bounds inline, flags last

Deserialization: flags first, then bounds

Input, output, and canonicalization

The binary format is a different animal

Statistics: a histogram of bounds

Look at it yourself

What it all means

Further reading

Range on Opensource internals

CPython's range Implementation in C: Lazy Sequences That Never Materialize

The object struct

Construction and the cached length

Indexing: computing, not looking up

__contains__ is O(1)

Iteration: two tiers

Memory efficiency summary

Key takeaways

Further reading

PostgreSQL's Multirange Type Implementation in C

The catalog

The in-memory struct

The stored format

Canonicalization: sort and merge on the way in

Reading a range back out

Comparison and hashing

Look at it yourself

What it all means

Further reading

PostgreSQL's Range Type Implementation in C

The catalog and the subtype table

The on-disk struct

Serialization: bounds inline, flags last

Deserialization: flags first, then bounds

Input, output, and canonicalization

The binary format is a different animal

Statistics: a histogram of bounds

Look at it yourself

What it all means

Further reading

`contains` is O(1)