Reference Manual: Arrays

All the arrays used by the library are similar. They can be used as vectors and as lists at the same time. The reason for this is just convenience. Sometimes we don't know in advance how many elements are we going to store (like, for instance, when reading data from a file) so it is convenient to add elements to a list using the Add method without having to worry about setting enough space to hold a maximum number of elements (Example: char line[2048]; to make "sure" we will have enough space to hold user input). On the other hand, it is easier, for internal structures, to use vectors of fixed size. This make consistency checks much easier and the library more robust in general. So, when going from reading data (using a list) to internally storing that data (using a vector), we have to "convert" a list into a vector. Using the fact that internally they are similar (a list is implemented as a dynamic array), we decided to use a "mixture" of them.

The method NumItems returns the number of items added to the list using Add. The method GetSize returns the actual number of slots allocated (can be bigger that NumItems).

All the list-like methods (Add, Delete, FindPosition, IsInList, etc) will consider only the first NumItems elements of the array. The rest of them (from NumItems to GetSize) can still be accessed with the operator[] but that will imply use as vector and the contents may not even be initialized (an object might be consistently used as an array or as a list and care must taken when switching from one mode of operation to the other). So a list can always be directly used as a vector. To convert from vector to list, the method UseAsList is provided. Imagine you have been using one vector, taking care of initializing all the elements and so on. Now you want to print/save the contents of that vector but your printing routines are expecting a list (i.e., it will only print the first NumItems elements). As you have been using the thing as a vector, NumItems will return 0 and nothing will be printed (it is just an empty list). So given that you know what you have done and are sure that all the elements of the vector are to be printed, a call to UseAsList will set the number of items to be equal to the size of the vector. This way, you can use the same structure (no copying needed) to call your printing routines. If you want to revert to the original vector state, use the Flush method. It will just set the number of items to 0 without actually deallocating the array.

Here is a description of the functions that can be applied to most of the arrays. To avoid excessive repetition, we list the declarations for DSL_intArray class but the same functions exist for the rest of types of arrays (i.e., int Add(int thisNumber) is listed but the DSL_doubleArray equivalent, int Add(double thisNumber), is not listed). When a specific function cannot be applied to a particular array is because it made no sense to us.

Methods - DSL_intArray

• int Add(int thisNumber)

Adds thisNumber at the end of the list. It will allocate more memory if necessary.

Error return values: DSL_OUT_OF_MEMORY, DSL_OBJECT_NOT_READY.

• int AddExclusive(int thisNumber)

The same as Add but only adds thisNumber if it's not already in the list.

Error return values: DSL_OUT_OF_RANGE (thisNumber is already in the list).

• int Delete(int index)

Deletes the item at the position indicated by index. This function preserves the order of the rest of the elements if the flag DSL_PRESERVE_ORDER is set. Otherwise, the order is not preserved.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (index is not a valid index).

• int DeleteByContent(int thisContent)

Deletes the first occurrence of thisContent in the array. Then works the same way as Delete.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (thisContent is not in the list).

• int DeleteDuplicates(void)

Deletes all those elements that appear more than once leaving just one copy of each. Works the same way as Delete.

Error return values: DSL_OBJECT_NOT_READY

• void Flush(void)

Empties the list without deallocating any memory (sets numitems to zero).

• int FillFrom(<another_array> &thisOne)

Without changing our size, we fill ourselves with as much information from thisOne as possible.

Error return values: DSL_OBJECT_NOT_READY

• int FindPosition(int ofThisNumber)

Returns the index of the first occurrence ofThisNumber in the list.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (ofThisNumber is not in the list).

• int GetSize(void)

Returns the total size of the list. This is the number of slots actually allocated.

• int IsInList(int aNumber)

Returns DSL_TRUE if aNumber is included in the list. Returns DSL_FALSE otherwise.

• int Insert(int here, int thisNumber)

Inserts thisNumber at the position indicated by here and shifts the contents of the array up starting from the old here element. It is allowed to insert right after the last element of the array. This way, thisNumber will be just added at the end of the array.

Error return values: DSL_OUT_OF_MEMORY, DSL_OUT_OF_RANGE (here is not a valid index), DSL_OBJECT_NOT_READY.

• int NumItems(void)

Returns the number of items contained in the list. This number must be, obviously, less than or equal to the one returned by GetSize.

• int RoomGuaranteed(int forThisPeople)

Guarantees that the array has room at least forThisPeople. After a call to this function, the actual contents of the array might be no longer valid (depending on whether there was reallocation or not). The number of items is set to zero (i.e., assumes use as vector).

Error return values: DSL_OUT_OF_MEMORY, DSL_OUT_OF_RANGE (forThisPeople is less than 0).

• int SetSize(int thisSize)

Sets the size of the array to be exactly thisSize. The old contents may be lost (if reallocation takes place). The number of items is set to zero (assumes use as vector).

Error return values: DSL_OUT_OF_MEMORY, DSL_OUT_OF_RANGE (thisSize is less than 0)

• void UseAsList(int nItems = -1)

Allows switching from use as vector to use as list. After a call to this function, the object will be transformed into a list with nItems elements. If nItems = -1 (default value), the list will contain as many elements as the total size of the array.

Array Types

DSL_intArray

This class represents an array of integers. See the section on arrays to find more information about this class.

DSL_doubleArray

This class represents an array of doubles. See the section on arrays to find more information about this class.

DSL_stringArray

This class represents an array of strings (char *). See the section on arrays to find more information about this class. The only difference with a normal array is that to modify an element of the array you should use SetString instead of the operator[]. This allows SMILE to deallocate "old" string.

DSL_idArray

This class represents an array of identifiers. It can only contain valid identifiers rather than normal strings. For an identifier to be valid, it must satisfy the following rules:

• It can only contain letters, numbers, and the '_' (underscore) character.

• It must start with a letter.

• It must have at least one character.

Also, identifiers included in an instance of DSL_idArray cannot be equal. This guarantees that there are no duplicates inside the same array.

• int Add(char *thisString)

This function rejects thisString if it doesn't follow the rules for identifiers. If it is ok, thisString gets added to the array.

Error return values: DSL_OUT_OF_RANGE (thisString is not a valid id or it is duplicated), DSL_OUT_OF_MEMORY, DSL_OBJECT_NOT_READY

• int CreateAndAddValidId(char *prefix = NULL, int serialNumber = 0)

Creates a valid id and adds it to the array. The created id will start with prefix and the serialNumber will be added at the end. If the id generated in this way is not valid, serialNumber will be increased and the whole thing tried again. For example, imagine that prefix is "Choice" and that serialNumber is 2. This function will generate the id "Choice2" and will try to add it to the array. If this is not possible (there may be a "Choice2" already, and there cannot be duplicates), "Choice3" will be generated and tried. This process will be repeated as many times as necessary until a valid id gets added to the array.

• int CreateAndInsertValidId(char *prefix = NULL, int serialNumber=0, int here=0)

The same as CreateAndAddValidId but inserting here.

• int CreateValidId(char *prefix, int serialNumber, char *buffer)

Creates a valid id following the process described above. It stores the resulting id in buffer. It is the responsibility of the caller to set up enough space for the result.

• int Insert(int here, char *thisString)

The same as Add, but inserting thisString here.

• int MakeConsistent(void)

Makes the whole array consistent (i.e., all the id's are valid and there are no duplicates). This function is provided to facilitate the translation from DSL_stringArray to DSL_idArray.