User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:vector-push [2019/09/14 05:00]
cl:functions:vector-push [2019/09/20 16:00] (current)
Line 1: Line 1:
 +====== Function VECTOR-PUSH,​ VECTOR-PUSH-EXTEND ======
 +
 +====Syntax====
 +  * **vector-push** //​new-element vector// → //​new-index-p//​
 +  * **vector-push-extend** //​new-element vector ''&​optional''​ extension// → //​new-index//​
 +
 +====Arguments and Values====
 +  * //​new-element//​ - an //​[[CL:​Glossary:​object]]//​.
 +  * //vector// - a //​[[CL:​Glossary:​vector]]//​ with a //​[[CL:​Glossary:​fill pointer]]//​.
 +  * //​extension//​ - a positive //​[[CL:​Glossary:​integer]]//​. The default is //​[[CL:​Glossary:​implementation-dependent]]//​.
 +  * //​new-index-p//​ - a //​[[CL:​Glossary:​valid array index]]// for //vector//, or **[[CL:​Constant Variables:​nil]]**.
 +  * //​new-index//​ - a //​[[CL:​Glossary:​valid array index]]// for //vector//.
 +
 +====Description====
 +**vector-push** and **vector-push-extend** store //​new-element//​ in //vector//. **vector-push** attempts to store //​new-element//​ in the element of //vector// designated by the //​[[CL:​Glossary:​fill pointer]]//,​ and to increase the //​[[CL:​Glossary:​fill pointer]]// by one. If the ''​([[CL:​Functions:​greater-or-equal|>​=]] ([[CL:​Functions:​fill-pointer]] //vector//) ([[CL:​Functions:​array-dimension]] //vector// 0))'',​ neither //vector// nor its //​[[CL:​Glossary:​fill pointer]]// are affected. Otherwise, the store and increment take place and **vector-push** returns the former value of the //​[[CL:​Glossary:​fill pointer]]// which is one less than the one it leaves in //vector//.
 +
 +**vector-push-extend** is just like **vector-push** except that if the //​[[CL:​Glossary:​fill pointer]]// gets too large, //vector// is extended using **[[CL:​Functions:​adjust-array]]** so that it can contain more elements. //​extension//​ is the minimum number of elements to be added to //vector// if it must be extended.
 +
 +**vector-push** and **vector-push-extend** return the index of //​new-element//​ in //vector//. If ''​([[CL:​Functions:​greater-or-equal|>​=]] ([[CL:​Functions:​fill-pointer]] //vector//) ([[CL:​Functions:​array-dimension]] //vector// 0))'',​ **vector-push** returns **[[CL:​Constant Variables:​nil]]**.
 +
 +====Examples====
 +<​blockquote>​
 +([[CL:​Macros:​defparameter]] *fable* ([[CL:​Functions:​list]] '​fable))
 +<​r>​*FABLE*</​r>​
 +([[CL:​Macros:​defparameter]] *fa* 
 +  ([[CL:​Functions:​make-array]] 8 :​fill-pointer 2 
 +                :​initial-element '​first-one))
 +<​r>​*FA*</​r>​
 +([[CL:​Functions:​vector-push]] *fable* *fa*) <​r>​2</​r> ​
 +([[CL:​Functions:​fill-pointer]] fa) <​r>​3</​r>​
 +([[CL:​Functions:​eq]] ([[CL:​Functions:​aref]] fa 2) fable) <​r>//​[[CL:​Glossary:​true]]//​ </r>
 +
 +([[CL:​Macros:​defparameter]] *array* ​
 +  ([[CL:​Functions:​make-array]] 5 :​element-type '​[[CL:​Types:​character]] ​
 +                :adjustable [[CL:​Constant Variables:​t]]
 +                :​fill-pointer 3))
 +<​r>​*ARRAY*</​r>​
 +(vector-push-extend #\X *array*) <​r>​3</​r> ​
 +([[CL:​Functions:​fill-pointer]] *array*) <​r>​4</​r> ​
 +(vector-push-extend #\Y *array* 4) <r>4 </r>
 +([[CL:​Functions:​array-total-size]] *array*) <​r>​→ 5 ;(or more)</​r>​
 +(vector-push-extend #\Z *array* 4) <r>5 </r>
 +([[CL:​Functions:​array-total-size]] *array*) <​r>​→ 9 ;(or more)</​r>​
 +</​blockquote>​
 +
 +====Affected By==== ​
 +The value of the //​[[CL:​Glossary:​fill pointer]]//​.
 +
 +How //vector// was created.
 +
 +====Exceptional Situations====
 +An error of type **[[CL:​Types:​error]]** is signaled by **vector-push-extend** if it tries to extend //vector// and //vector// is not //​[[CL:​Glossary:​actually adjustable]]//​.
 +
 +An error of type **[[CL:​Types:​error]]** is signaled if //vector// does not have a //​[[CL:​Glossary:​fill pointer]]//​.
 +
 +====See Also====
 +**[[CL:​Functions:​adjustable-array-p|Function ADJUSTABLE-ARRAY-P]]**,​ **[[CL:​Functions:​fill-pointer|Function FILL-POINTER]]**,​ **[[CL:​Functions:​vector-pop|Function VECTOR-POP]]**
 +
 +====Notes====
 +None.