source: project/wiki/eggref/4/list-utils @ 34654

Last change on this file since 34654 was 34654, checked in by kon, 12 months ago

rel 1.3

File size: 9.2 KB
Line 
1[[tags: egg]]
2
3== list-utils
4
5Miscellaneous list oriented routines.
6
7[[toc:]]
8
9
10== Documentation
11
12=== skip+
13
14<procedure>(skip+ LIST COUNT) => (list integer)</procedure>
15
16Returns 2 values, the {{COUNT}} {{pair}} from {{LIST}}, and the remaining
17count. The remaining count will be zero when end-of-list reached.
18
19{{COUNT}} is a {{natural fixnum}}.
20
21<enscript language=scheme>
22(skip+ '(1 2) 3) ;=> '() 1
23(skip+ '(1 2 3) 3) ;=> '() 0
24(skip+ '(1 2 3 4) 3) ;=> '(4) 0
25</enscript>
26
27=== split-at+
28
29<procedure>(split-at+ LIST COUNT [PADS]) => (list list)</procedure>
30
31Returns 2 values, the leading {{COUNT}} elements from {{LIST}} as a new
32{{list}}, and the remaining elements from {{LIST}}. Should there be fewer than
33{{COUNT}} elements available padding is attempted.
34
35Padding is performed by trying to complete the remaining elements from the {{list}}
36{{PADS}}.
37
38{{COUNT}} is a {{natural fixnum}}.
39{{PADS}} is a {{list}} or {{#f}}. Default is {{'()}}.
40
41A negative {{COUNT}} is treated as {{0}}.
42
43When {{PADS}} is {{#f}} then an incomplete leading sublist is treated as
44{{'()}}. The very odd treatment of {{PADS}} = {{#f}} can safely be ignored
45since this is not the default behavior.
46
47<enscript language=scheme>
48(split-at+ '(1 2 3) 3) ;=> '(1 2 3) '()
49(split-at+ '(1 2 3) 2) ;=> '(1 2) '(3)
50(split-at+ '(1 2 3) 4) ;=> '(1 2 3) '()
51(split-at+ '(1 2 3) 4 #f) ;=> '() '()
52</enscript>
53
54=== section
55
56<procedure>(section LIST SIZE [[STEP] PADS]) => list</procedure>
57
58Returns a {{list}} of {{list}}, built by taking {{SIZE}} elements from
59{{LIST}} every {{STEP}} elements. When too few elements remain to complete a
60''section'' padding is performed.
61
62{{SIZE}} is a {{positive fixnum}}.
63{{STEP}} is a {{positive fixnum}}. Default is {{SIZE}}.
64{{PADS}} is a {{list}} or {{#f}}. Default is {{'()}}.
65
66When {{PADS}} is {{#f}} then any incomplete trailing section is dropped. The
67very odd treatment of {{PADS}} = {{#f}} can safely be ignored since this is not
68the default behavior.
69
70<enscript language=scheme>
71(section '(1 2) 3 3 '(3 4 5)) ;=> ((1 2 3))
72(section '(1 2 3) 2 1 '(3 4 5)) ;=> ((1 2) (2 3))
73(section '(1 2 3) 2 2 '(4 5)) ;=> ((1 2) (3 4))
74(section '(1 2 3) 2 2) ;=> ((1 2) (3))
75</enscript>
76
77=== length=0?
78
79<macro>(length=0? LIST) => boolean</macro>
80
81List of length zero? (Just {{null?}}.)
82
83=== length=1?
84
85<macro>(length=1? LIST) => boolean</macro>
86
87List of length one?
88
89=== length>1?
90
91<macro>(length>1? LIST) => boolean</macro>
92
93List of length greater than one?
94
95=== length=2?
96
97<macro>(length=2? LIST) => boolean</macro>
98
99List of length two?
100
101=== ensure-list
102
103<macro>(ensure-list OBJECT) => list</macro>
104
105Returns a list, either the list {{OBJECT}} or {{(list OBJECT)}}.
106
107=== not-null?
108
109<macro>(not-null? LIST) => (or list boolean)</macro>
110
111Returns {{#f}} if the given {{LIST}} is empty, and {{LIST}} otherwise.
112
113=== alist-delete-first
114
115<macro>(alist-delete-first KEY ALIST [TEST?])</macro>
116
117Returns {{(alist-delete-with-count KEY ALIST [TEST?] 1)}}.
118
119=== alist-delete-first!
120
121<macro>(alist-delete-first! KEY ALIST [TEST?])</macro>
122
123Destructive version of {{alist-delete-first}}.
124
125=== assoc-def
126
127<macro>(assoc-def KEY ALIST [TEST] [NOT-FOUND])</macro>
128
129The assoc procedure with an optional test and default value.
130
131Error signaling version of {{assoc}}. When the {{KEY}} is not found and
132a {{NOT-FOUND}} value is not supplied an {{error}} is invoked.
133
134=== assv-def
135
136<macro>(assv-def KEY ALIST [NOT-FOUND])</macro>
137
138The assv procedure with a default value.
139
140Error signaling version of {{assv}}. When the {{KEY}} is not found and
141a {{NOT-FOUND}} value is not supplied an {{error}} is invoked.
142
143=== assq-def
144
145<macro>(assq-def KEY ALIST [NOT-FOUND])</macro>
146
147The assq procedure with a default value.
148
149Error signaling version of {{assq}}. When the {{KEY}} is not found and
150a {{NOT-FOUND}} value is not supplied an {{error}} is invoked.
151
152=== alist-inverse-ref
153
154<procedure>(alist-inverse-ref VALUE ALIST [TEST? [NOT-FOUND]])</procedure>
155
156Returns the first key associated with {{VALUE}} in the {{ALIST}} using the
157{{TEST?}} predicate, else {{NOT-FOUND}}.
158
159{{TEST?}} is {{eqv?}} and {{NOT-FOUND}} is {{#f}}.
160
161=== alist-delete-for-count
162
163<procedure>(alist-delete-for-count KEY ALIST [TEST? [COUNT]])</procedure>
164
165Deletes the first {{COUNT}} associations from alist {{ALIST}} with the given
166key {{KEY}}, using key-comparison procedure {{TEST?}}. The dynamic order in
167which the various applications of equality are made is from the alist head to
168the tail.
169
170Returns a new alist. The alist is not disordered - elements that appear in the
171result alist occur in the same order as they occur in the argument alist.
172
173The equality procedure is used to compare the element keys, {{key[i: 0 <= i <
174(length ALIST)}}', of the alist's entries to the key parameter in this way:
175{{(TEST? KEY key[i])}}.
176
177{{COUNT}} defaults to essentially, infinity, and {{EQUALITY?}} defaults to
178{{eqv?}}.
179
180=== alist-delete-for-count!
181
182<procedure>(alist-delete-for-count! KEY ALIST [TEST? [COUNT]])</procedure>
183
184Destructive version of {{alist-delete-with-count}}.
185
186{{alist-delete-first}} and {{alist-delete-first!}} are also available as
187procedures.
188
189=== alist-delete-with-count
190
191<procedure>(alist-delete-with-count KEY ALIST [[COUNT] TEST?])</procedure>
192
193Deletes the first {{COUNT}} associations from alist {{ALIST}} with the given
194key {{KEY}}, using key-comparison procedure {{TEST?}}. The dynamic order in
195which the various applications of equality are made is from the alist head to
196the tail.
197
198Returns a new alist. The alist is not disordered - elements that appear in the
199result alist occur in the same order as they occur in the argument alist.
200
201The equality procedure is used to compare the element keys, {{key[i: 0 <= i <
202(length ALIST)}}', of the alist's entries to the key parameter in this way:
203{{(TEST? KEY key[i])}}.
204
205{{COUNT}} defaults to essentially, infinity, and {{EQUALITY?}} defaults to
206{{eqv?}}.
207
208=== alist-delete-with-count!
209
210<procedure>(alist-delete-with-count! KEY ALIST [[COUNT] TEST?])</procedure>
211
212Destructive version of {{alist-delete-with-count}}.
213
214{{alist-delete-first}} and {{alist-delete-first!}} are also available as
215procedures.
216
217=== unzip-alist
218
219<procedure>(unzip-alist ALIST)</procedure>
220
221Returns 2 values, a list of the keys & a list of the values from the {{ALIST}}.
222
223=== zip-alist
224
225<procedure>(zip-alist KEYS VALUES)</procedure>
226
227Returns an association list with elements from the corresponding items of
228{{KEYS}} and {{VALUES}}.
229
230=== plist->alist
231
232<procedure>(plist->alist PLIST) => list</procedure>
233
234Returns the association-list form of {{PLIST}}.
235
236=== alist->plist
237
238<procedure>(alist->plist ALIST) => list</procedure>
239
240Returns the property-list form of {{ALIST}}.
241
242=== shift!
243
244<procedure>(shift! LIST [DEFAULT]) => *</procedure>
245
246Returns the first element of {{LIST}}, or {{DEFAULT}} when {{LIST}} is null.
247
248The {{car}} and {{cdr}} of the first {{pair}} of {{LIST}} are set to the
249corresponding element of the second {{pair}}.
250
251Like a stack-pop.
252
253=== unshift!
254
255<procedure>(unshift! OBJECT LIST) => list</procedure>
256
257The {{car}} of the first {{pair}} of {{LIST}} is set to {{OBJECT}}. The
258{{cdr}} of the first {{pair}} of {{LIST}} is set to {{LIST}}.
259
260Like a stack-push.
261
262=== shift!/set
263
264<macro>(shift!/set VARIABLE [WHEN-EMPTY])</macro>
265
266Like {{shift!}} but assigns the {{VARIABLE}} {{'()}} after shifting from a list
267of length 1.
268
269{{WHEN-EMPTY}}, which defaults to {{#f}}, is returned when the list bound to
270{{VARIABLE}} is empty.
271
272=== andmap
273
274<procedure>(andmap FUNC LIST...) => boolean</procedure>
275
276The arity of the function {{FUNC}} must be the length of {{LIST...}}.
277
278{{(and (FUNC (car LIST)...) (andmap FUNC (cdr LIST)...))}}.
279
280=== ormap
281
282<procedure>(ormap FUNC LIST...) => boolean</procedure>
283
284The arity of the function {{FUNC}} must be the length of {{LIST...}}.
285
286{{(or (FUNC (car LIST)...) (ormap FUNC (cdr LIST)...))}}.
287
288
289== Usage
290
291<enscript language=scheme>
292(require-extension list-utils)
293</enscript>
294
295
296== Requirements
297
298[[check-errors]]
299
300
301== Bugs and Limitations
302
303
304== Author
305
306[[/users/kon-lovett|Kon Lovett]]
307
308
309== Version history
310
311; 1.3.0 : Add {{alist-delete-with-count}} & {{alist-delete-with-count!}}.
312; 1.2.0 : Add {{alist-delete-for-count}} & {{alist-delete-for-count!}}.
313; 1.1.2 : .
314; 1.1.1 : Fix for ticket #630
315; 1.1.0 : Added {{skip+}}, {{split-at+}}, and {{section}}.
316; 1.0.0 : Hello,
317
318
319== License
320
321Copyright (C) 2010-2017 Kon Lovett.  All rights reserved.
322
323Permission is hereby granted, free of charge, to any person obtaining a
324copy of this software and associated documentation files (the Software),
325to deal in the Software without restriction, including without limitation
326the rights to use, copy, modify, merge, publish, distribute, sublicense,
327and/or sell copies of the Software, and to permit persons to whom the
328Software is furnished to do so, subject to the following conditions:
329
330The above copyright notice and this permission notice shall be included
331in all copies or substantial portions of the Software.
332
333THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
334IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
335FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
336THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
337OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
338ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
339OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.