source: project/wiki/eggref/4/dyn-vector @ 33363

Last change on this file since 33363 was 33363, checked in by Ivan Raikov, 5 years ago

dyn-vector doc: updated version history and added procedure dynvector

File size: 7.8 KB
Line 
1[[tags:egg]]
2
3== dyn-vector
4
5Dynamic (dense) vectors based on SRFI-43.
6
7[[toc:]]
8
9== Usage
10
11(require-extension dyn-vector)
12
13== Documentation
14
15
16The dyn-vector library is an implementation of a dynamically-growing
17vector, based on [[http://srfi.schemers.org/srfi-43/|SRFI-43]].  An
18attempt to set the {{i}}'th element of a dynvector of underlying size
19n causes the dynvector to grow to size {{2n}}, {{i+1}}, or {{16}},
20whichever is greatest. The semantics of this library follow SRFI-43
21closely, with the exception of the following procedures:
22
23<procedure>dynvector-ref vect i</procedure>
24
25If the index {{i}} is greater than the current size of the vector,
26this procedure returns the default value specified when the dynamic
27vector was created.
28
29<procedure>dynvector-set! vect i e</procedure>
30
31If the index {{i}} is greater than the current size of the vector, the
32vector size is increased to {{max(2*N,i+1)}} and the new element is
33then inserted in the vector.
34
35<procedure>dynvector-clear! vect n</procedure>
36
37This procedure removes all elements from the dynamic vector, and sets
38the size of the vector to {{n}}.
39
40<procedure>dynvector-extend! vect n</procedure>
41
42This procedure explicitly resizes the dynamic vector to the specified
43size.
44
45<procedure>dynvector-tabulate f len [dflt]</procedure>
46
47If the optional argument {{dflt}} is specified, it is used as default
48value, otherwise the first element in the vector is used as default
49value.
50
51<procedure>list->dynvector lst [dflt] -> dynvector</procedure>
52
53If the optional argument {{dflt}} is specified, it is used as default
54value, otherwise the first element in the list is used as default
55value.
56
57
58=== Procedures
59
60
61<procedure>dynvector? x -> boolean</procedure>
62
63Returns {{#t}} if {{x}} is a dynamic vector, {{#f}} otherwise.
64
65
66<procedure>dynvector-tabulate f len [dflt]</procedure>
67
68Creates a new dynamic vector of length {{len}} and iterates across
69each index, applying f at each iteration to the current index; if the
70optional argument {{dflt}} is specified, it is used as default value,
71otherwise the first element in the vector is used as default value.
72
73<procedure>list->dynvector lst [dflt] -> dynvector</procedure>
74
75Creates a dynamic vector with the elements of the given list; if the
76optional argument {{dflt}} is specified, it is used as default value,
77otherwise the first element in the vector is used as default value.
78
79<procedure>dynvector elem ... -> dynvector</procedure>
80
81Creates a dynamic vector with the given elements; the default value is {{#f}}.
82
83<procedure>make-dynvector n default -> dynvector</procedure>
84
85Creates a dynamic vector of length {{n}} and fills it with value {{default}}.
86
87<procedure>dynvector-clear! x n -> unspecified</procedure>
88
89Removes all elements from the given dynamic vector, and sets the size of the vector to {{n}}.
90
91<procedure>dynvector-length x -> integer</procedure>
92
93Returns the length of the given dynamic vector.
94
95<procedure>dynvector-ref x i -> value</procedure>
96
97Returns the element at index {{i}}of the given dynamic vector{{x}}.
98
99<procedure>dynvector-set! x i e -> unspecified</procedure>
100
101Updates the element at index {{i}}of the given dynamic vector{{x}}; if
102the index {{i}} is greater than the current size of the vector, the
103vector size is increased to {{max(2*N,i+1)}} and the new element is
104then inserted in the vector.
105
106<procedure>dynvector-expand! x n -> unspecified</procedure>
107
108Expands the size of the dynamic vector to the given size {{n}}.
109
110<procedure>dynvector-for-each f x1 ... -> unspecified</procedure>
111
112Dynamic vector iterator: applies {{f}}to each index in the range {{[0,
113k)}}, where {{k}} is the length of the smallest dynamic vector
114argument passed, and the respective list of parallel elements from
115{{x1}} ...  at that index.
116
117<procedure>dynvector-map f x1 ... -> dynvector</procedure>
118
119Constructs a new dynamic vector of the shortest size of the given
120dynamic vector; each element at index {{i}} of the new dynamic vector
121is mapped from the old vectors by {{f i (dynvector-ref x1 i) ...}}.
122
123<procedure>dynvector-copy x -> dynvector</procedure>
124
125Creates a copy of the given dynamic vector.
126
127<procedure>dynvector-fold f initial x1 ... -> state</procedure>
128
129Left-to-right dynamic vector iterator with state. {{f}} is iterated
130over each index in all of the vectors, stopping at the end of the
131shortest; {{f}} is applied as {{(f i state (dynvector-ref x1 i) ...)}}
132where state is the current state value, which begins with {{initial}}
133and becomes whatever {{f}}returns at the respective iteration; {{i}}
134is the current index.
135
136<procedure>dynvector-fold-right f initial x1 ... -> state</procedure>
137
138Right-to-left dynamic vector iterator with state. {{f}} is iterated
139over each index in all of the vectors, stopping at the end of the
140shortest; {{f}} is applied as {{(f i state (dynvector-ref x1 i) ...)}}
141where state is the current state value, which begins with {{initial}}
142and becomes whatever {{f}}returns at the respective iteration; {{i}}
143is the current index.
144
145<procedure>dynvector-index pred? x1 ... -> integer or #f</procedure>
146
147Finds and returns the index of the first elements in {{x1 ...}} that
148satisfy {{pred?}}; if no matching element is found by the end of the
149shortest vector, {{#f}} is returned.
150
151<procedure>dynvector-any pred? x1 ... -> value or #f</procedure>
152
153Finds the first set of elements in {{x1 ... }}for which {{pred?}}
154returns a true value. If such a parallel set of elements exists, this
155procedure returns the value that {{pred?}}returned for that set of
156elements.
157
158<procedure>dynvector-every pred? x1 ... -> value or #f</procedure>
159
160If, for every index {{i}} between 0 and the length of the shortest
161vector argument, the set of elements {{(dynvector-ref x1 i) ...}}
162satisfies {{pred?}}, this procedure returns the value that
163{{pred?}}returned for the last set of elements.
164
165<procedure>dynvector->list x1 -> list</procedure>
166
167Returns a list containing all the elements in the given dynamic vector.
168
169== Examples
170
171
172 csi> (require-extension dyn-vector)
173 
174 csi> (define dv (make-dynvector 1 0))
175 csi> (dynvector-ref dv 6)
176 0
177 csi> (dynvector-set! dv 6 18)
178 csi> (dynvector-ref dv 6)
179 18
180 csi> (define dv2 (list->dynvector '(1 2 3)))
181 csi> dv2
182 #(dynvector 1 2 3)
183 csi> (dynvector-ref dv2 4)
184 1
185 csi> (dynvector-clear! dv2 5)
186 csi> (dynvector-for-each (lambda (i x) (print i " = " x)) dv2)
187 0 = 1
188 1 = 1
189 2 = 1
190 3 = 1
191 4 = 1
192 csi> (dynvector-map (lambda (i x) (+ x i)) dv2)
193 #(dynvector 1 2 3 4 5)
194 csi> (dynvector-fold (lambda (i state v) (+ state v)) 0 dv2)
195 5
196
197== About this egg
198
199
200=== Author
201
202[[/users/ivan-raikov|Ivan Raikov]]
203
204=== Version history
205
206; 1.13 : Bug fixes for zero-sized vectors; added procedure dynvector [thanks to Lewis Campbell]
207; 1.12 : License change to LGPL-3
208; 1.11 : Converted documentation to wiki format
209; 1.9 : Ported to Chicken 4
210; 1.8 : Build script updated for better cross-platform compatibility
211; 1.7 : eggdoc documentation fix
212; 1.6 : License upgrade to GPL v3
213; 1.5 : Minor updates to the setup script
214; 1.4 : Bug fix in the setup script
215; 1.3 : Added a clarification of how the vector grows [thanks to John Cowan]
216; 1.2 : Bug fix to handle zero-length initial base vector
217; 1.1 : Added optional dflt argument to list->dynvector and dynvector->tabulate
218; 1.0 : Initial release
219
220=== License
221
222 Parts of this documentation are taken from SRFI-43.
223 The rest was created by Ivan Raikov.
224 
225 This program is free software: you can redistribute it and/or modify
226 it under the terms of the GNU Lesser General Public License as
227 published by the Free Software Foundation, either version 3 of the
228 License, or (at your option) any later version.
229 
230 This program is distributed in the hope that it will be useful, but
231 WITHOUT ANY WARRANTY; without even the implied warranty of
232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
233 General Public License for more details.
234 
235 A full copy of the Lesser GPL license can be found at
236 <http://www.gnu.org/licenses/>.
237
Note: See TracBrowser for help on using the repository browser.