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

Last change on this file since 35192 was 35192, checked in by kon, 2 months ago

rel 1.4.0

File size: 8.8 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-duplicates
162
163<procedure>(alist-delete-duplicates KEY ALIST [TEST? [COUNT]]) -> alist</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 unlimited, & {{EQUALITY?}} defaults to {{eqv?}}.
178
179=== alist-delete-duplicates!
180
181<procedure>(alist-delete-duplicates! KEY ALIST [TEST? [COUNT]]) -> alist</procedure>
182
183Destructive version of {{alist-delete-with-count}}.
184
185{{alist-delete-first}} and {{alist-delete-first!}} are also available.
186
187=== unzip-alist
188
189<procedure>(unzip-alist ALIST)</procedure>
190
191Returns 2 values, a list of the keys & a list of the values from the {{ALIST}}.
192
193=== zip-alist
194
195<procedure>(zip-alist KEYS VALUES)</procedure>
196
197Returns an association list with elements from the corresponding items of
198{{KEYS}} and {{VALUES}}.
199
200=== plist->alist
201
202<procedure>(plist->alist PLIST) -> list</procedure>
203
204Returns the association-list form of {{PLIST}}.
205
206=== alist->plist
207
208<procedure>(alist->plist ALIST) -> list</procedure>
209
210Returns the property-list form of {{ALIST}}.
211
212=== shift!
213
214<procedure>(shift! LIST [DEFAULT]) -> *</procedure>
215
216Returns the first element of {{LIST}}, or {{DEFAULT}} when {{LIST}} is null.
217
218The {{car}} and {{cdr}} of the first {{pair}} of {{LIST}} are set to the
219corresponding element of the second {{pair}}.
220
221Like a stack-pop.
222
223=== unshift!
224
225<procedure>(unshift! OBJECT LIST) -> list</procedure>
226
227The {{car}} of the first {{pair}} of {{LIST}} is set to {{OBJECT}}. The
228{{cdr}} of the first {{pair}} of {{LIST}} is set to {{LIST}}.
229
230Like a stack-push.
231
232=== shift!/set
233
234<macro>(shift!/set VARIABLE [WHEN-EMPTY])</macro>
235
236Like {{shift!}} but assigns the {{VARIABLE}} {{'()}} after shifting from a list
237of length 1.
238
239{{WHEN-EMPTY}}, which defaults to {{#f}}, is returned when the list bound to
240{{VARIABLE}} is empty.
241
242=== andmap
243
244<procedure>(andmap FUNC LIST...) -> boolean</procedure>
245
246The arity of the function {{FUNC}} must be the length of {{LIST...}}.
247
248{{(and (FUNC (car LIST)...) (andmap FUNC (cdr LIST)...))}}.
249
250=== ormap
251
252<procedure>(ormap FUNC LIST...) -> boolean</procedure>
253
254The arity of the function {{FUNC}} must be the length of {{LIST...}}.
255
256{{(or (FUNC (car LIST)...) (ormap FUNC (cdr LIST)...))}}.
257
258=== pair-ref
259
260<procedure>(pair-ref LIST IDX) -> list</procedure>
261
262Returns the {{IDX}}th {{pair}} of {{LIST}}.
263
264=== list-set!
265
266<procedure>(list-set! LIST IDX OBJ) -> list</procedure>
267
268Replaces the {{car}} the {{(pair-ref LIST IDX)}} with {{OBJ}}.
269
270=== list-copy*
271
272<procedure>(list-copy* LIST START END FILL) -> list</procedure>
273
274Returns a copy of {{LIST}}, from {{START}} until {{END}}, where {{END}} maybe
275{{>}} {{(length LIST))}}. In which case {{FILL}} is used.
276
277== Usage
278
279<enscript language=scheme>
280(require-extension list-utils)
281</enscript>
282
283
284== Requirements
285
286[[check-errors]]
287
288
289== Bugs and Limitations
290
291
292== Author
293
294[[/users/kon-lovett|Kon Lovett]]
295
296
297== Version history
298
299; 1.4.0 : Add {{alist-delete-duplicates(!)}}, {{pair-ref}}, {{list-set!}}, {{list-copy*}}. Deperecate {{alist-delete-with/for-count(!)}}.
300; 1.3.0 : Add {{alist-delete-with-count}} & {{alist-delete-with-count!}}.
301; 1.2.0 : Add {{alist-delete-for-count}} & {{alist-delete-for-count!}}.
302; 1.1.2 : .
303; 1.1.1 : Fix for ticket #630
304; 1.1.0 : Added {{skip+}}, {{split-at+}}, and {{section}}.
305; 1.0.0 : Hello,
306
307
308== License
309
310Copyright (C) 2010-2017 Kon Lovett.  All rights reserved.
311
312Permission is hereby granted, free of charge, to any person obtaining a
313copy of this software and associated documentation files (the Software),
314to deal in the Software without restriction, including without limitation
315the rights to use, copy, modify, merge, publish, distribute, sublicense,
316and/or sell copies of the Software, and to permit persons to whom the
317Software is furnished to do so, subject to the following conditions:
318
319The above copyright notice and this permission notice shall be included
320in all copies or substantial portions of the Software.
321
322THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
323IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
324FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
325THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
326OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
327ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
328OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.