# Misleading documentation of sort/4

**URL:** <https://swi-prolog.discourse.group/t/misleading-documentation-of-sort-4/8716>\
**Category:** PlDoc\
**Created:** [January 4, 2025, 9:39pm UTC](https://swi-prolog.discourse.group/t/misleading-documentation-of-sort-4/8716 "2025-01-04T21:39:17Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![mike.elston](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/mike.elston/32/3691_2.png) [@mike.elston](https://swi-prolog.discourse.group/u/mike.elston)\
**Post date:** [January 4, 2025, 9:39pm UTC](https://swi-prolog.discourse.group/t/misleading-documentation-of-sort-4/8716/1 "2025-01-04T21:39:17Z")

</div>

Hi

The documention of sort/4 [sort/4](https://eu.swi-prolog.org/pldoc/doc_for?object=sort/4)

says:

The following example sorts a list of rows, for example resulting from [csv\_read\_file/2](https://eu.swi-prolog.org/pldoc/man?predicate=csv_read_file/2)) ascending on the 3th column and descending on the 4th column:

```
sort(4, @>=, Rows0, Rows1), sort(3, @=<, Rows1, Sorted).

```

But that is wrong isn’t it? The first sort will sort on column 4 then the second sort will sort on column 3 i.e. only the second sort will have any effect.

The following illustrates:

```
test :-
    X1 = [row(3, a), row(1, b), row(2, c), row(1, c), row(1, a)],
    sort(1, @=<, X1, X2),
    sort(2, @=<, X2, X3),
    write(X3).

:- test.
[row(1,a),row(3,a),row(1,b),row(1,c),row(2,c)]
true.

```

---

<div class="post-metadata">

**Author:** ![Olopierpa](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/olopierpa/32/6855_2.png) [@Olopierpa](https://swi-prolog.discourse.group/u/Olopierpa)\
**Post date:** [January 4, 2025, 10:21pm UTC](https://swi-prolog.discourse.group/t/misleading-documentation-of-sort-4/8716/2 "2025-01-04T22:21:36Z")

</div>

> > ![](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/mike.elston/45/3691_2.png "mike.elston") | [mike.elston](https://swi-prolog.discourse.group/u/mike.elston)  
> > January 4 |
> > 
> > - | - |
> 
> Hi
> 
> The documention of sort/4 [sort/4](https://eu.swi-prolog.org/pldoc/doc_for?object=sort/4)
> 
> says:
> 
> The following example sorts a list of rows, for example resulting from [csv\_read\_file/2](https://eu.swi-prolog.org/pldoc/man?predicate=csv_read_file/2)) ascending on the 3th column and descending on the 4th column:
> 
> ```prolog
> sort(4, @>=, Rows0, Rows1), sort(3, @=<, Rows1, Sorted).
> 
> ```
> 
> But that is wrong isn’t it? The first sort will sort on column 4 then the second sort will sort on column 3 i.e. only the second sort will have any effect.

Must read as: “ascending on the 3th column and descending on the 4th column (when 3rd column is equal)”  
That is, the exampe wants to show that the sort is actually stable.

[https://stackoverflow.com/questions/1517793/what-is-stability-in-sorting-algorithms-and-why-is-it-important](https://stackoverflow.com/questions/1517793/what-is-stability-in-sorting-algorithms-and-why-is-it-important):

Now, the bug is that it must have said 3rd, not 3th 🙂

Cheers

---

<div class="post-metadata">

**Author:** ![jan](https://yyz2.discourse-cdn.com/free1/user_avatar/swi-prolog.discourse.group/jan/32/4_2.png) [@jan](https://swi-prolog.discourse.group/u/jan)\
**Post date:** [January 5, 2025, 11:12am UTC](https://swi-prolog.discourse.group/t/misleading-documentation-of-sort-4/8716/3 "2025-01-05T11:12:46Z")

</div>

> [@Olopierpa](#):
>
> Must read as: “ascending on the 3th column and descending on the 4th column (when 3rd column is equal)”

Thanks. Pushed [DOC: sort/4 stable sort example. · SWI-Prolog/swipl-devel@54fdcbe · GitHub](https://github.com/SWI-Prolog/swipl-devel/commit/54fdcbe9e159a0480d6748e9b91a6848cd37bb11)
