[bug-gawk] [Manual] Adding an example for asort() call with a comparison function

[Stéphane Goujet]

Hello,


  I could not find any example of calling asort() (or asorti()) with a 
comparison function in the manual.


> 9.1.3 String-Manipulation Functions
> ...
> asort(source [, dest [, how ] ]) #
> ...
> NOTE: The following description ignores the third argument, how, as it 
requires understanding features that we have not discussed yet. Thus, the 
discussion here is a deliberate simplification. (We do provide all the 
details later on; see Array Sorting Functions, for the full story.)

  OK, no example here, let's browse to "Array Sorting Functions":

> 12.2.2 Sorting Array Values and Indices with gawk

> So far, so good. Now it starts to get interesting. Both asort() and 
asorti() accept a third string argument to control comparison of array 
elements. When we introduced asort() and asorti() in String Functions, we 
ignored this third argument; however, now is the time to describe how this 
argument affects these two functions.

> Basically, the third argument specifies how the array is to be sorted. 
There are two possibilities. As with PROCINFO["sorted_in"], this argument 
may be one of the predefined names that gawk provides (see Controlling 
Scanning), or it may be the name of a user-defined function (see 
Controlling Array Traversal).

  All right, no example here, let's browse to "Controlling Array 
Traversal":

> 12.2.1 Controlling Array Traversal

  Here there are many examples of comparison functions. But there is not a 
single example of calling them with asort() or asorti().

  I guess it would be good to add at least a small example of either one 
of them, probably in 12.2.2., after the paragraphs I quoted.

  I can tell my own case : I missed or misunderstood the "asort() and 
asorti() accept a third *string* argument" and the "it may be the *name* 
of a user-defined function" and it took a while for me to realise the 
parameter should be a quoted string of the name of the function. I would 
have realised so much faster by seeing it in an example.
  Of course I cannot say everyone shares my level of blindness, but 
a small example would not hurt anyway. What is your opinion?



Faithfully yours,
  Stéphane Goujet.