SYMMETRICA-MANUAL -- How to build a VECTORobject

How to build a VECTORobject

How to build a VECTORobject

Let us first look at an example for the construction of a VECTORobject:

#include "def.h"
#include "macro.h"
main()
{
OP\ v;
anfang();
v = callocobject();
m_il_v(8L,v);
println(v);
freeall(v);
ende();
}

The routine m_il_v() builds an VECTORobject with eight empty objects. The output will be

[#,#,#,#,#,#,#,#]

The complete description follows

NAME: m_il_v abbreviates make_integerlength_vectorobject.
SYNOPSIS: INT m_il_v(INT length; OP vectorobject)
DESCRIPTION: builds a vector of the given length. First there is a check whether vectorobject is an empty object, if this is not the case it is freed. Moreover, there is the allocation of the given number of objects, which are set to empty objects.
RETURN: the returnvalue is OK, ERROR if some error occured, e.g. if there is not enough memory for the objects.
MACRO: there is a macro M_IL_V, which does the same without any checking.

There is the routine/macro

b_il_v, B_IL_V

which is the same. There is also the routine, where you enter an INTEGERobject, and you will get a VECTORobject with this length. See the following example:

...
scan(INTEGER,a);
b_l_v(a,b);
println(b);
...

Here the INTEGERobject a becomes the length part of the VECTORobject b, and so, if you delete the VECTORobject using freeall(), or freeself(), you can no longer access the INTEGERobject a, because it was freed as part of the VECTORobject b. If you want to avoid this, you have to use the make-constructor, which does a copy:

...
scan(INTEGER,a);
m_l_v(a,b);
println(b);
...

Here you can free the VECTORobject b, and you have still an INTEGERobject a. This method is easier for you, but you need more memory for data. Now we are ready for the complete description of these two routines

NAME: m_l_v abbreviates make_length_vectorobject and b_l_v means build_length_vectorobject
SYNOPSIS:

INT m_l_v(OP length, vectorobject)

and

INT b_l_v(OP length, vectorobject)
DESCRIPTION: They build a vector of the given length. First there is a check whether vectorobject is an empty object, if not it is freed. Then there is a check whether length is an INTEGERobject. Then there is the allocation of the given number of objects, which are set to empty objects. Using b_l_v length will be the length part of the VECTORobject. Using m_l_v, a copy of the INTEGERobject length will be the length part of the VECTORobject.
RETURN: The returnvalue is OK, ERROR if some error occured, e.g. not enough memory for the objects.

There are the special cases, where you have one object and you want to build a vector, whose single component is this object:

NAME: m_o_v which abbreviates make_object_vector and, correspondingly, b_o_v which means build_object_vector
SYNOPSIS:

INT m_o_v(OP object,vector)

and

INT b_o_v(OP object,vector)
DESCRIPTION: They both build a vector of length one, whose entry is the object. The object is copied in m_o_v, but not by b_o_v. The vector is first freed to an empty object.
RETURN: the returnvalue is OK, ERROR if some error occured.

These are the routines for the construction of VECTORobjects, now we come to routines for the selection of parts.

harald.fripertinger "at" uni-graz.at, May 26, 2011

How to build a VECTORobject