Thread: Suggestion for docs, section "4.2.3 Subscripts": bounds and base

The following documentation comment has been logged on the website:

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? 
Are slice boundaries inclusive or exclusive?

Suggestion: 
...
`expression[subscript]`
where by default the subscript is counted from 1. A contiguous slice of
array elements can be extracted by using the subscript of the first and last
element to be included in the slice:
`expression[first_included_subscript:last_included_subscript]`

Regards,
s.

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

On Mon, 2025-04-07 at 09:07 +0000, Stefan Schmiedl wrote:
> 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.

There is always room for improvement.

It would be great if you could put on both of your hats and come up with
a patch that implements the rather invasive change you are envisioning.
Then we can see if it feels better overall, and we have a concrete basis
for a discussion.

Yours,
Laurenz Albe

The following documentation comment has been logged on the website:

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?
Are slice boundaries inclusive or exclusive?