Documento de molib

Idiomas disponible : English français

CLASS

moArrayBase
moArray
moArrayUnique
moSortedArray
moSortedArrayUnique

NAME

Constructors - create an array

VERSION

Version: 1.2.0

SYNOPSIS

moArrayBase(unsigned long size, array_compare_function_t acf = 0);
moArrayBase(const moArrayBase& array, array_compare_function_t acf = 0);
moArray(unsigned long size, array_compare_function_t acf = 0);
moArray(const moArrayBase& array, array_compare_function_t acf = 0);
moArrayUnique(unsigned long size, array_compare_function_t acf = 0);
moArrayUnique(const moArrayBase& array, array_compare_function_t acf = 0);
moSortedArray(unsigned long size, array_compare_function_t acf);
moSortedArray(const moArrayBase& array, array_compare_function_t acf);
moSortedArrayUnique(unsigned long size, array_compare_function_t acf);
moSortedArrayUnique(const moArrayBase& array, array_compare_function_t acf);

PARAMETERS

size - size of one item in the array
acf - array compare function used to compare items together
array - an array to copy

DESCRIPTION

These objects are different types of arrays. They are all based on the ArrayBase object.

To simplify the management of these arrays, many functions are available. Items within an array can be compared between each others with the use of a user supplied function. For this reason it is possible to create sorted arrays. Note that objects can be compared between each others whatever their type. However it may not always give you a consistant result. It is important, if you are to sort objects, that the criteria to sort them remains the same throughout the life of the array. (for instance, if an object is given a name and the sort happens on that name, it isn't wise to enable the user to modify the name of the object - unless you also remove the object from the array and reinsert it so it finds its new place). Note also that objects pointers may vary when new objects are inserted into their corresponding array.

Arrays will be used anywhere you need a set of structures. (opposed to arrays which manage sets of C++ objects). These structures will most probably not have any functions associated with them, especially not virtual functions since no virtual table is available in this object.

The fact that an array is sorted or not is determined at creation time. It can't be changed later. However, it is really easy to sort an array only when required with the following code:

moSortedArray my_sorted_array(); my_sorted_array += my_other_array; // now 'my_other_array' has a sorted version of // its contents in 'my_sorted_array' // NOTE: it makes a copy of each item

You can't create an moArrayBase since it is a pure object.

Any non sorted array can be used without a compare function. In this case it won't be possible to search items in it. However, any other function will work as usual.

Using null (0) as the compare function will generate an moError() whenever one the Find() or FindNext() functions are called. These functions may be called by others such as the Insert() of a sorted array.

ERRORS

The array object can generate several different errors which are highlighted within the different functions. The main error which can happen is an out of memory error thrown with the MO_ERROR_MEMORY error number. Other errors will usually be reported with an moError() object.

Note: errors are there to prevent actions which would otherwise make the array unconsistant. If a major error makes the array unusable it will be specified (this is very unlikely).

SEE ALSO

Array management: SetArraySize, SetSize

Queries: Count, IsSorted, IsUnique, IsEmpty, Find, FindNext, Compare, Array, Exists

Objects insertion & modifications: Insert, operator +=, operator [], Append, Set, Delete, Empty

Reading objects: Get, GetCopy

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

Init - initialize an array whenever a constructor is called

VERSION

Version: 1.2.0

SYNOPSIS

private:
void Init(void);

DESCRIPTION

This function make an array variable members coherent to the system.

SEE ALSO

Constructors

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

SetArraySize - change the size of the array

VERSION

Version: 1.2.0

SYNOPSIS

void SetArraySize(unsigned long size);

PARAMETERS

size - the number of entries we want to have in this array

DESCRIPTION

This function changes the size of the array used to hold the object pointers inserted in the array. This function does not change what Count() returns unless the specified size is smaller than Count().

To change the number of items (i.e. Count()'s value) call the SetSize() function instead.

It is possible to set the array size to zero in which case the array will be freed.

ERRORS

When a memory error occurs, this function will throw a long error with MO_ERROR_MEMORY.

SEE ALSO

SetSize, Count

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase
moArray
moSortedArray

NAME

Find - search for an item in a array
FindNext - search for the next equal item

VERSION

Version: 1.2.0

SYNOPSIS

moArray, moSortedArray::
position_t Find(const moBase *object) const;

moArrayBase::
position_t FindNext(const moBase *object) const;

PARAMETERS

object - search the array for an object which is equal to this one

DESCRIPTION

This function searches an item within a array. In sorted arrays, a binary search will be used. In unsorted arrays, each items are compared to the object parameter until one is equal.

If more than one item in the array is equal to the object parameter only one of them is returned. In unsorted arrays, the first item found is returned. In sorted arrays, it is not possible to tell which one is returned.

In unordered arrays, it is possible to find the following items using the FindNext() function. In sorted arrays, one can use the Get() operator and compare the following object or use the FindNext() function call.

RETURN VALUE

This function returns the position of the found object. When
there are no item equal to the object parameter, then a value
of NO_POSITION is returned.

ERRORS

The comparisons may fail if an object has no comparison or invalid objects are compared between each others. Usually, the system throws a long(MO_ERROR_BAD_COMPARE) or when unordered objects at compared a long(MO_ERROR_UNORDERED). In the unlikely event a comparison error occurs, you may also receive a long(MO_ERROR_COMPARE).

SEE ALSO

Exists

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

InsertAt - low level insert function

VERSION

Version: 1.2.0

SYNOPSIS

protected:
void InsertAt(const moBase *object, position_t position);

PARAMETERS

object - the object to insert
position - position at which the item is inserted

DESCRIPTION

This function is an internal function used to insert an object in the array array. It should only be used by the internal Insert() functions which make sure the position is correct and insertion is possible (in unique arrays, items can be inserted only once).

ERRORS

This function calls the SetArraySize() which may generate memory errors.

SEE ALSO

Insert

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArray
moArrayUnique
moSortedArray
moSortedArrayUnique

NAME

Insert - insert an object in a array

VERSION

Version: 1.2.0

SYNOPSIS

moArray, moArrayUnique::
virtual bool Insert(const moBase *object, position_t position);

moArray, moArrayUnique, moSortedArray, moSortedArrayUnique::
virtual bool Insert(const moBase *object);

PARAMETERS

object - object to be inserted
position - position at which the item is inserted

DESCRIPTION

This function inserts the specified object in this array.

In sorted arrays, it's not possible to specify a position since the item will be placed at a very specific position determined by the order used to sort the array. The rule is to insert items in increasing order. If two items are equal, the newly inserted will be after all of the items already in the array and which are equal.

In other arrays, the item will be inserted at the end by default. When a position is given, it will be inserted at that position unless the given position is larger than the number of items in the array, in which case it is inserted at the end.

When the version without a position is used to insert an item in non-sorted array, a position of NO_POSITION is used (i.e. insert the item at the end of the array).

RETURN VALUE

These functions return true whenever the object was inserted.
This is really meaningful only when one of the Unique array
object is used (otherwise items are always inserted).

ERRORS

This function may call the Find() function to know where to insert the item or whether it is unique. See that function for comparison errors it can raise.

This function calls the SetArraySize() which may generate memory errors.

SEE ALSO

Append, Find, InsertAt

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase
moArray
moArrayUnique
moSortedArray
moSortedArrayUnique

NAME

Append - append a array to this array

VERSION

Version: 1.2.0

SYNOPSIS

moArray, moArrayUnique::
void Append(const moArrayBase *array, position_t position);

moArray, moArrayUnique, moArrayBase::
void Append(const moArrayBase *array);

PARAMETERS

array - the array to append
position - position at which the array items are inserted

DESCRIPTION

This function appends all the items of the specified array parameter to this array. Specific Append() functions are used for each type of array. The sorted and unique arrays use the Insert() function to insert each item of the array parameter to this array. The unsorted and non-unique array uses a very fast append function which inserts all the items in one block.

When a position larger than the number of items is specified then the items are all inserted at the end.

ERRORS

This function calls the Insert(), Find() and SetArraySize() functions which may generate different type of errors.

SEE ALSO

Find, Insert

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

Delete - delete an item in a array

VERSION

Version: 1.2.0

SYNOPSIS

void Delete(position_t position);

PARAMETERS

position - the position of the item to be deleted

DESCRIPTION

This function deletes the item at the specified position.

An invalid position will be silently ignored. This is because in the insertion functions, a position out of bounds is used to append items.

NOTES

The buffer holding the array of objects is never reduced by this function.

SEE ALSO

Empty, SetSize

BUGS

The item is removed from the array. However, the item itself remains in memory until the user calls the delete or any other appropriate function for deletion. It is fine to delete the item from memory before to delete it from the array as long as it is removed from the array right away.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

SetStep - set how fast the array should be enlarged

VERSION

Version: 1.2.0

SYNOPSIS

void SetStep(unsigned long step);

PARAMETERS

step - the new step value

DESCRIPTION

This function sets the step parameter of the array. At the start all arrays have a step of DEFAULT_STEP (256 at this time).

The step is used whenever the array needs to be enlarged to accept one or more items. The number of items added will include the requested size rounded up to the nearest multiple of this step value.

The step can't be set to a value smaller than 256 and should not be set to too large a value either.

SEE ALSO

Step, Size, SetSize, SetArraySize

BUGS

The size of the array isn't changed when this function is called. It will be only the next time it is necessary to enlarge the buffer to hold more entries.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

SetSize - set the number of items in a array

VERSION

Version: 1.2.0

SYNOPSIS

void SetSize(unsigned long size);

DESCRIPTION

This function will change the number of items present in a array. The Count() function will then return this value.

If necessary, the array will be enlarged in order to accept the request.

When a array is made larger, new entries are cleared (null pointers).

When a array is made smaller, the last items are lost. It is the user responsability to delete these items from memory before a call to this function, if required.

ERRORS

An moError() will be thrown when size is set larger than MAXIMUM_SIZE.

SEE ALSO

Insert

BUGS

Sorted arrays may not like to have entries which are zero pointers. It isn't wise to use this function on sorted arrays.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moSortedArray

NAME

SetCompare - define the offset of a compare function

VERSION

Version: 1.2.0

SYNOPSIS

void SetCompare(array_compare_function_t order_function);

PARAMETERS

order_function - a member function pointer

DESCRIPTION

Changes the default Compare() function call to this one. This order_function parameter is an offset to one of the compare functions of the given object.

This is primarily used to sort objects with different criteria in several different arrays.

ERRORS

A comparison function can only be set in an empty array. It is a major error to try to change the compare function of a non-empty array and for this reason this function will throw an MO_ERROR_COMPARE error if it ever happens.

SEE ALSO

IsSorted

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase
moSortedArray

NAME

IsSorted - test whether a array is sorted

VERSION

Version: 1.2.0

SYNOPSIS

virtual bool IsSorted(void) const;

DESCRIPTION

This function returns true if the given array was created with moSortedArray or moSortedArrayUnique.

It is not possible to change an array from unordered to sorted or vice versa. To do so, create another array and copy the original.

SEE ALSO

IsUnique

BUGS

If items change and these changes make them different toward their Compare() function, the array coherency will be lost and even though this function may return true, it won't be anymore.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase
moArrayUnique
moSortedArrayUnique

NAME

IsUnique - test whether a array accepts equal items

VERSION

Version: 1.2.0

SYNOPSIS

virtual bool IsUnique(void) const;

DESCRIPTION

This function returns true if the array will never have duplicated objects (i.e. was created with moArrayUnique or moSortedArrayUnique).

SEE ALSO

IsSorted

BUGS

If items change and these changes make them equal, the array coherency will be lost and even though this function may return true, it won't be anymore.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

IsEmpty - test whether a array if empty
Empty - makes the array empty

VERSION

Version: 1.2.0

SYNOPSIS

bool IsEmpty(void) const;
virtual void Empty(void);

DESCRIPTION

The IsEmpty() function returns true if the given array is empty. It is equivalent to testing whether the Count() is zero.

The Empty() function makes a array empty.

When emptying a array, the objects defined in the array are not deleted (since these are not duplicated when inserted in the array). It is the responsability of the user to delete these objects if required.

RETURN VALUE

IsEmpty() returns true when the array is empty; false otherwise

SEE ALSO

Count

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

Count - return the number of items present in this array
Size - return the size of an item
Step - return the number of items to add at once

VERSION

Version: 1.2.0

SYNOPSIS

unsigned long Count(void) const;
unsigned long Size(void) const;
unsigned long Step(void) const;

DESCRIPTION

The Count() function returns the number of items currently defined within this array.

The Size() function returns the size of one item in bytes. This is equivalent to the size defined at construction time. This size can't be changed.

The Step() function returns the number of items added at once whenever the array is too small. By default this is DEFAULT_STEP (256 at this time). You can change this value with the SetStep() function.

RETURN VALUE

Count():
the number of items in the array

Size():
the size of an item

Step();
the number of items added when the array needs to be grown

SEE ALSO

IsEmpty, Array

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

MaxCompare - return the maximum number of compares to be done to find an item in an array

VERSION

Version: 1.2.0

SYNOPSIS

unsigned long MaxCompare(void) const;

DESCRIPTION

This function returns the number of items which the system will compare before to return from a Find() function call.

This assumes the item being searched is unique. If not, then additional compares will occur to find the first instance of equal items.

List which aren't sorted require the Find() to search all the items sequentially. In this case, this function returns the same value as Count().

RETURN VALUE

the maximum number of compares which will occur in a Find()

SEE ALSO

Count, IsSorted

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

Array - returns the array pointer

VERSION

Version: 1.2.0

SYNOPSIS

const void *Array(void) const;

DESCRIPTION

This function returns a pointer to the internal array of structures.

It is unwise to try to modify the buffer. The number of items in the buffer is as returned by Count(). This buffer should only be used as a read-only buffer. This pointer will change if other functions are called.

RETURN VALUE

a pointer to the array of object;
the pointer can be zero (0) if the array is empty

SEE ALSO

Count

BUGS

This function should not exists, yet it simplifies the Append() function so it is possible to copy an array in another very quickly.

The pointer will be invalidated if other functions are called on this array (any function which may call the SetArraySize() to be precise).

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

Exists - checks whether a given object is present in a array

VERSION

Version: 1.2.0

SYNOPSIS

bool Exists(const void *data) const;

PARAMETERS

data - a structure of data to search

DESCRIPTION

The Exists() function searches for the data parameter and returns true if it finds it; false otherwise.

RETURN VALUE

true when the given object is present in the array

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase

NAME

+= operator - append an item or merge two arrays

VERSION

Version: 1.2.0

SYNOPSIS

moArrayBase& operator += (const void *data);
moArrayBase& operator += (const moArrayBase& array);

DESCRIPTION

In the first instance, the item data is appended in this array.

In the second instance, all of the items present in the array specified as a parameter are appended to this array. Note that the items are appended in the order they are found in the array parameter. That is significant only if the destination array is not sorted. It may be faster to call this function when the destination array is not sorted than to add items one by one.

This function uses the Insert() or Append() functions.

SEE ALSO

Insert, Append

BUGS

To insert a array as an item you need to cast the array into an moBase object to avoid calling the second instance of the function:

array1 += dynamic_cast<const moBase&>(array2);

It may also be wise to use the Insert() function in this case:

array1->Insert(array2);

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moArrayBase
moArray
moArrayUnique

NAME

Get - get a array item
GetCopy - get a copy of a array item
Set - sets an entries

VERSION

Version: 1.2.0

SYNOPSIS

moArrayBase:
void *Get(position_t position) const;
void GetCopy(position_t position, void *data);

moArray, moArrayUnique:
void Set(position_t position, const void *data);

PARAMETERS

position - zero based object position within the array
data - a source or destination data buffer

DESCRIPTION

The Get() function returns a pointer to one of the array objects. The position has to be between zero and Count() - 1.

The GetCopy() function makes a copy of one of the array items. The item is copied with a call to memcpy(). The position has to be between zero and Count() - 1.

The Set() function sets the array entry at position to the given object. If the position is larger or equal to Count() then the array is enlarged with the SetSize() function to the required size to include it. Note that this function is not available in sorted arrays.

In an moArrayUnique object the new object will be set only if it doesn't exist in the array so the coherency of the array (unicity) is kept. This means you can't be sure the Set() did set an entry in a unique array.

ERRORS

An moError() is thrown when position is out of bounds (Get) or larger than MAXIMUM_SIZE - the maximum size allowed (Set).

A long(MO_ERROR_MEMORY) is thrown when a memory error occurs.

SEE ALSO

Insert, operator +=

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox