------ Original Message ------
From "Laurenz Albe" <laurenz.a...@cybertec.at>
To s...@xss.de; pgsql-docs@lists.postgresql.org
Date 07.04.2025 10:03:47
Subject Re: Suggestion for docs, section "4.2.3 Subscripts": bounds and
base
On Thu, 2025-04-03 at 18:22 +0000, PG Doc comments form wrote:
Page: https://www.postgresql.org/docs/17/sql-expressions.html
Description:
I skimmed over section 4.2 while waiting for a meeting to start and found no
mention of the following two questions that immediately pop up in my mind
when subscripts are mentionned:
Are subscripts 0-based or 1-based?
This question is answered in the documentation of the array data types:
https://www.postgresql.org/docs/current/arrays.html
The array subscript numbers are written within square brackets. By default
PostgreSQL uses a one-based numbering convention for arrays, that is, an
array of n elements starts with array[1] and ends with array[n].
Are slice boundaries inclusive or exclusive?
That becomes clear on the same page:
We can also access arbitrary rectangular slices of an array, or subarrays.
An array slice is denoted by writing lower-bound:upper-bound for one or
more array dimensions. For example, this query retrieves the first item
on Bill's schedule for the first two days of the week:
SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';
schedule
------------------------
{{meeting},{training}}
(1 row)
Admittedly, there is no exact definition, but the example makes clear that
the boundaries are inclusive.
I don't think that we need to repeat that information.
Yours,
Laurenz Albe
Wearing my documentation writer's hat, I agree that the information
given on
one page need not be repeated on another one, especially if it's already
cross-referenced.
However, with my documentation reader's glasses on, I would have liked
to see
that data there, as it would have allowed me to file subscripts under
"brackets, mostly 1-based, slices [a:b] are closed intervals" and move
on.
As it is, I needed to follow the link to the array page, then to the
section
"Accessing", where I encounter "Now, we can run some queries on the
table",
which implies that I need to at least scan content somewhere above the
current
point to learn about the table structure. Only then I reach the bit
about the
first index.
Pages in part I and II (at least, I have not really gone into III and
IV) feel like
they're meant to be read completely from top to bottom, not topical like
a lookup
in the excellent Reference where I usually can find answers to my
questions by
reading a few lines in the description of the option I'm unsure about.
As such, I'd have appreciated the additional information as it would
have kept
me in the flow of the page, a flow that its author has worked hard to
set up for me.
Kind regards,
s.
