------ Original Message ------
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:
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:
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 onone 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.
