This file is indexed.

/usr/share/doc/slsh/html/slshfun-8.html is in slsh 2.3.0-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.66">
 <TITLE> SLSH Library Reference (version 2.3.0): List Functions and List-based Data Structures</TITLE>
 <LINK HREF="slshfun-9.html" REL=next>
 <LINK HREF="slshfun-7.html" REL=previous>
 <LINK HREF="slshfun.html#toc8" REL=contents>
</HEAD>
<BODY>
<A HREF="slshfun-9.html">Next</A>
<A HREF="slshfun-7.html">Previous</A>
<A HREF="slshfun.html#toc8">Contents</A>
<HR>
<H2><A NAME="s8">8.</A> <A HREF="slshfun.html#toc8">List Functions and List-based Data Structures</A></H2>

<P>The file <CODE>arrayfuns.sl</CODE> includes functions for manipulating
lists.  It also includes some list-based data structures such as heaps.</P>
<H2><A NAME="list_sort"></A> <A NAME="ss8.1">8.1</A> <A HREF="slshfun.html#toc8.1"><B>list_sort</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD>
<P>Sort a list of item</P>
<DT><B> Usage </B><DD>
<P>
<BLOCKQUOTE><CODE>
<PRE>
   Int_Type indices = list_sort (List_Type list);        % Form 1
   list_sort (List_Type list; inplace);                  % Form 2
</PRE>
</CODE></BLOCKQUOTE>
</P>

<DT><B> Description </B><DD>
<P>The <CODE>list_sort</CODE> may be used to sort a list.  By default, it
returns a permutation index array for the desired sort.  If the
<CODE>inplace</CODE> qualifier is given, the sort will be in-place and no
index array will be returned.</P>
<DT><B> Qualifiers </B><DD>
<P>The following qualifiers may be used to modify the behavior of the
function:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
    dir=1
</PRE>
</CODE></BLOCKQUOTE>

If the value of the <CODE>dir</CODE> qualifier is non-negative, the sort will
take place in an increasing order.  If negative, the list will be
sorted in decreasing order.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
    cmp=&amp;cmpfunc
</PRE>
</CODE></BLOCKQUOTE>

The <CODE>cmp</CODE> qualifier specifies the function used to comparison
operation for two elements of an array.  Its value must be a
reference to a function that accepts two arguments representing the
objects to be compared.  It must return a positive integer, 0, or
a negative integer if the value of the first argument is greater
than, equal to, or less than the value of the second, respectively.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
    inplace[=1]
</PRE>
</CODE></BLOCKQUOTE>

The inplace qualifier may be used to indicate if the list is to be
sorted in place.  If the qualifier is present with no-value or a
non-zero value, the list will be sorted in place and no index array
will be returned.  If not present, or present with a value of 0, the
list will not be modified, and an index array will be returned.</P>
<DT><B> Example </B><DD>
<P>
<BLOCKQUOTE><CODE>
<PRE>
   list = {1, 9, 3, 7};
   i = list_sort (list);
   sorted_list = list[i];
</PRE>
</CODE></BLOCKQUOTE>

The above example creates a second list (<CODE>sorted_list</CODE>) by
using the permutation index array to rearrange the objects in the
unsorted list.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
   list = {1, 9, 3, 7};
   list_sort (list; inplace);
</PRE>
</CODE></BLOCKQUOTE>

In this example, the list is sorted in-place.</P>
<P>Consider a list of strings that are to be sorted in increasing
order of the number of bytes used by each string.  For this, a custom
sort function is required:
<BLOCKQUOTE><CODE>
<PRE>
    private define cmpfunc (a, b)
    {
       return strbytelen(a) - strbytelen(b);
    }
    list = {"Here", "is", "a", "list", "of", "strings"};
    list_sort (list; inplace);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<DT><B> Notes </B><DD>
<P>Keep in mind that a list can contain a heterogeneous collection of
object where there is no predefined comparison operation.  For
example, there may be no natural way to compare an integer to a
string.  For a heterogeneous list, a comparison function must be
provided.</P>
<DT><B> See Also </B><DD>
<P><CODE>array_sort, rearrange</CODE></P>
</DL>
</P>


<H2><A NAME="heap_new"></A> <A NAME="ss8.2">8.2</A> <A HREF="slshfun.html#toc8.2"><B>heap_new</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD>
<P>Instantiate a heap data object</P>
<DT><B> Usage </B><DD>
<P><CODE>Struct_Type h = new_heap (List_Type list)</CODE></P>
<DT><B> Description </B><DD>
<P>The <CODE>new_heap</CODE> function takes a <CODE>List_Type</CODE> object and
rearranges its elements to form a heap.  A list rearranged to form a
heap has the property that <CODE>list[i] &gt;= list[2*i+j]</CODE>, where j=1 or 2,
and i is the list index (from 0).</P>
<P>Upon return, the elements of the list will be rearranged to have the
heap property and a new container object (the heap) will be
returned.  It may be manipulated using the method calls described
below.</P>
<DT><B> Qualifiers </B><DD>
<P>
<BLOCKQUOTE><CODE>
<PRE>
   dir=-1
</PRE>
</CODE></BLOCKQUOTE>

The <CODE>dir</CODE> qualifier may be used to specify the direction of the
heap.  The default (dir=-1) specifies a top-down ordering.  A
bottom-up ordering corresponds to dir=1.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
   cmp=&amp;cmpfunc
</PRE>
</CODE></BLOCKQUOTE>

The <CODE>cmp</CODE> may be used to specify the function to be used when
comparing elements of the list.  Its value must be a reference to a
function that takes two parameters and returns a positive integer if
the value of the first parameter is greater than the second, 0 if
they are equal, or a negative integer if the first is less than
the second.  For example, if the list consists of structures with
fields called <CODE>lastname</CODE> and <CODE>firstname</CODE> that are to be
used for ordering, then the desired function would look something
like:
<BLOCKQUOTE><CODE>
<PRE>
    define cmpfunc (a, b)
    {
       variable c = strcmp (a.lastname, b.lastname);
       if (c == 0) c = strcmp (a.firstname, b.firstname);
       return c;
    }
</PRE>
</CODE></BLOCKQUOTE>
</P>
<DT><B> Methods </B><DD>
<P><CODE></CODE></P>
<DT><B> length() </B><DD>
<P>Get the length to the heap</P>
<DT><B> add(obj) </B><DD>
<P>Add a new object to the heap</P>
<DT><B> remove() </B><DD>
<P>Remove the largest (for top-down) or smallest (for
bottom-up) item from the heap and return its value.</P>
<DT><B> peek() </B><DD>
<P>Get the largest (top-down) or smallest(bottom-up) item
from the heap, but do not remove it.</P>
<P>Note that attempting to peek at or remove an item from an empty list
will result in an <CODE>IndexError</CODE> exception.</P>
<DT><B> Example </B><DD>
<P>Suppose that merging two objects requires a time equal to the
combined length of the objects.  For example, if the length of first
is A and that of the second is B, then the time to merge the two
will be A + B.  What is the minimum amount of time it takes to merge
a list of N objects with lengths <CODE>{L_k}, k=0...N-1</CODE>?  The
answer to this is very simple if a bottom-up heap is used.  The idea
is to remove the two smallest objects from the heap, combine them
and then add the result back to the heap.  Repeat this process until
the heap is empty.  In the following, <CODE>list</CODE> is a list of the
lengths of the objects to be merged.
<BLOCKQUOTE><CODE>
<PRE>
     define compute_merge_time (list)
     {
        variable h = heap_new (list; dir=1);   % bottom-up heap
        variable a, b, c, t;
        a = h.remove (); t = 0;
        while (h.length())
          {
             b = h.remove ();
             c = a + b;
             t += c;
             h.add (c);
             a = h.remove ();
         }
       return t;
     }
</PRE>
</CODE></BLOCKQUOTE>
</P>
<DT><B> Notes </B><DD>
<P>Generally speaking, a list will require the specification of a
comparison function unless the list consists solely of elements that
may be compared using the <CODE>&gt;</CODE>, <CODE>&lt;</CODE>, and <CODE>==</CODE> operators.</P>
<DT><B> See Also </B><DD>
<P><CODE>list_sort, list_new</CODE></P>
</DL>
</P>


<HR>
<A HREF="slshfun-9.html">Next</A>
<A HREF="slshfun-7.html">Previous</A>
<A HREF="slshfun.html#toc8">Contents</A>
</BODY>
</HTML>