SFXArray

Class which represents an array.

#include <SFXArray.h.hpp>

class SFXArray;

SFMTYPEDEFCLASS(SFXArray)

Inheritance diagram

Collaboration diagram

Description

SFXArray is the data structure to store all its elements into the consecutive memory area(internal buffer) and to access its element directly using the index.

SFXArray and SFXList

	SFXArray and SFXList
In the `SFXArray` class, an element can be directly accessed using the index. On the other hand, in the `SFXArray` class, accessing an element needs to be traversed via a two-way linked list. Therefore, accessing an element is faster than in the `SFXList` class. In the `SFXList` class, inserting or deleting an element is only to maintain the pointers of the element in question and the neighboring elements. On the other hand, in the `SFXArray` class, it is necessay to to move elements after the element in question in the internal buffer memory. Therefore, inserting or deleting an element is slower than in the `SFXList` class.

In the SFXArray class, an element can be directly accessed using the index. On the other hand, in the SFXArray class, accessing an element needs to be traversed via a two-way linked list. Therefore, accessing an element is faster than in the SFXList class.

In the SFXList class, inserting or deleting an element is only to maintain the pointers of the element in question and the neighboring elements. On the other hand, in the SFXArray class, it is necessay to to move elements after the element in question in the internal buffer memory. Therefore, inserting or deleting an element is slower than in the SFXList class.

In the default settings, when the first element is inserted, the internal buffer will be allocated by the size set with the SFXArray::SetThreshold function(default: size for 4 elements). Then, in case memory becomes insufficient while elements are inserted one by one, the internal buffer will be expanded by the cluster size set with the SFXArray::SetCluster function(default: size for 8 elements). Here, the size of one element is 4 byte.

Caution

	Caution
When the internal buffer is expanded, new consecutive memory area bigger than the current one by the cluster size will be allocated and all data of existing elements will be copied there. Therefore, if expansion is performed frequently, it may become the cause of performance deterioration If the number of the elements are known in advance, it is recommended to set the internal buffer size with the `SFXArray::SetThreshold` / `SFXArray::SetCluster` functions or to set the number of the elements with the `SFXArray::SetSize` function(). If the internal buffer is expanded with the `SFXArray::SetSize` function, each element in the expanded area will be set to 0.

When the internal buffer is expanded, new consecutive memory area bigger than the current one by the cluster size will be allocated and all data of existing elements will be copied there. Therefore, if expansion is performed frequently, it may become the cause of performance deterioration

If the number of the elements are known in advance, it is recommended to set the internal buffer size with the SFXArray::SetThreshold / SFXArray::SetCluster functions or to set the number of the elements with the SFXArray::SetSize function(*).

* If the internal buffer is expanded with the SFXArray::SetSize function, each element in the expanded area will be set to 0.

Each element size of SFXArray needs to be less than or equal 4 byte. In order to process data more than 4 byte ( such as UInt64 type, Float64 type, and so on ) or class instance as an element of the SFXArray instance ( array ), a pointer should be used.

// data more than 4 byte or class instance cannot be an element of the SFXArray instance ( array )

// SFXArray<SInt64> ar64;           NG
// SFXArray<SFXAnsiString> arstr;   NG

// but a pointer to the data more than 4 byte or class instance can be an element of the SFXArray instance ( array )

SFXArray<SInt64Ptr> ar64;        // OK
SFXArray<SFXAnsiStringPtr> arstr;// OK

Reference

SFXList | SFXStack | Array

Member

Constructor/Destructor
SFXArray( `Void` ) Constructor of the SFXArray class.
SFXArray( `UInt16` threshold , `UInt16` cluster ) Constructor of the SFXArray class.

Public Functions
`SFCError`	Append( `V` value ) [DEPRECATED] Append an element.
`SFCError`	Append( `SFXArray< V > const &` collection ) [DEPRECATED] Append an element.
`Void`	Clear( `Void` ) Clear this array.
`Bool`	Contains( `V` value ) Check whether or not this array contains the specified value.
static `SFXArray< V > const &`	EmptyInstance( `Void` ) Get an empty array.
`Bool`	Equals( `SFXArray< V > const &` collection ) Check whether or not this array equals the specified array.
`SInt32`	FirstIndexOf( `V` value , `SInt32` index = SINT32_MINIMUM ) Get the first index of the element that equals the specified value, searching from the head.
`V`	Get( `SInt32` index ) Get the element at the specified index.
`UInt16`	GetCluster( `Void` ) Get the cluster size of the internal buffer memory. [in bytes]
`Enumerator`	GetEnumerator( `SInt32` index ) Get the enumerator that points to the element at the specified index.
`V`	GetFirst( `Void` ) Get the element at the head.
`Enumerator`	GetFirstEnumerator( `Void` ) Get the enumerator that points to the first element.
`Iterator`	GetFirstIterator( `Void` ) Get the iterator that points to the first element.
`Iterator`	GetIterator( `SInt32` index ) Get the iterator that points to the element at the specified index.
`V`	GetLast( `Void` ) Get the element at the tail.
`Enumerator`	GetLastEnumerator( `Void` ) Get the enumerator that points to the last element.
`Iterator`	GetLastIterator( `Void` ) Get the iterator that points to the last element.
`SInt32`	GetSize( `Void` ) Get the size(the number of the elements).
`UInt16`	GetThreshold( `Void` ) Get the minimum size of the internal buffer memory. [in bytes]
`SFCError`	Insert( `SInt32` index , `SFXArray< V > const &` collection ) Insert the specified element or array before the specified index.
`SFCError`	Insert( `SInt32` index , `V` value ) Insert the specified element or array before the specified index.
`SFCError`	InsertFirst( `SFXArray< V > const &` collection ) Insert the specified element or list at the head.
`SFCError`	InsertFirst( `V` value ) Insert the specified element or list at the head.
`SFCError`	InsertLast( `SFXArray< V > const &` collection ) Insert the specified element or array at the tail.
`SFCError`	InsertLast( `V` value ) Insert the specified element or array at the tail.
`Bool`	IsEmpty( `Void` ) Check whether or not this array is empty.
`SInt32`	LastIndexOf( `V` value , `SInt32` index = SINT32_MAXIMUM ) Get the last index of the element that equals the specified value, searching from the tail.
`SFCError`	Move( `SInt32` destination , `SInt32` source ) Move the element at the specified index to the specified index.
`SFCError`	MoveFirst( `SInt32` source ) Move the element at the specified index to the head.
`SFCError`	MoveLast( `SInt32` source ) Move the element at the specified index to the tail.
`Void`	Remove( `SInt32` index ) Remove the elements at the specified index or range.
`Void`	Remove( `SInt32` begin , `SInt32` end ) Remove the elements at the specified index or range.
`Void`	RemoveFirst( `Void` ) Remove the element at the head.
`Void`	RemoveLast( `Void` ) Remove the element at the tail.
`SFCError`	Set( `SFXArray< V > const &` collection ) Set the element at the specified index of this array to the specified value. Or set this array to the specified array.
`SFCError`	Set( `SInt32` index , `V` value ) Set the element at the specified index of this array to the specified value. Or set this array to the specified array.
`Void`	SetCluster( `UInt16` size ) Set the cluster size of the internal buffer memory. [in bytes]
`SFCError`	SetFirst( `V` value ) Set the element at the head to the specified value.
`SFCError`	SetLast( `V` value ) Set the element at the tail to the specified value.
`SFCError`	SetSize( `SInt32` size ) Set the size of this array to the specified value.
`Void`	SetThreshold( `UInt16` size ) Set the minimum size of the internal buffer memory. [in bytes]
`SFCError`	Swap( `SInt32` destination , `SInt32` source ) Swap two elements at the specified indexes.
`SFCError`	SwapFirst( `SInt32` source ) Swap the element at the specified index for the element at the head.
`SFCError`	SwapLast( `SInt32` source ) Swap the element at the specified index for the element at the tail.
`V &`	operator[]( `SInt32` index ) Get the element by index.
`V const &`	operator[]( `SInt32` index ) Get the element by index.

Types
DefaultEnum Constants that represent the default values for the minimum size and the cluster size of the internal buffer memory. [in bytes]
Enumerator Class for managing the enumerator of this array.
Iterator Class for managing the iterator of this array.

SFXArray::SFXArray

Constructor of the SFXArray class.

[ public, explicit ]
SFXArray(Void);

[ public, explicit ]
SFXArray(
    UInt16 threshold   // minimum value of buffer size
    UInt16 cluster     // cluster size
);

Description

It is possible to improve performance by specifying the minimum size of the internal buffer memory and the cluster size optimized for your application in order to minimize the occurrence of memory reallocation.

	Tip
	The minimum size of the internal buffer memory or the cluster size can be set with the `SFXArray::SetThreshold` or `SFXArray::SetCluster` function.

Reference

SFXArray::Set | SFXArray::SetThreshold | SFXArray::SetCluster

SFXArray::Append

[DEPRECATED] Append an element.

[ public ]
SFCError Append(
    V value   // element to append
);

[ public ]
SFCError Append(
    SFXArray< V > const & collection   // array to append
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY
If failed: SFERR_FAILED

Description

Append an element at the end of array. This function is deprecated, use the SFXArray::InsertLast function.

Example

SFXArray<SInt16> array;
SInt16 i;

// append an element
if (array.Append(2) == SFERR_NO_ERROR) {
    // append an element
    if (array.Append(5) == SFERR_NO_ERROR) {
        // enumerate by index
        for (i = 0; i < array.GetSize(); ++i) {
            TRACE("%d", array[i]);  // 2 5 
        }
    }
}

Reference

SFXArray::Insert | SFXArray::InsertLast | SFXArray::Get | SFXArray::Remove | SFXArray::Set

SFXArray::Clear

Clear this array.

[ public ]
Void Clear(Void);

Description

This function clears this array. All the internal buffer allocated to this array will be released.

After this function is executed, the size of this array will become 0.

	Caution
If the type of the element is a pointer to a class instance or data bigger than 4 bytes, memory area that the pointer points to will not be released automatically. Before clearing this array, it is necessary to release that area explicitly using the delete statement. Otherwise, memory leakage will occur.

Caution

If the type of the element is a pointer to a class instance or data bigger than 4 bytes, memory area that the pointer points to will not be released automatically.

Before clearing this array, it is necessary to release that area explicitly using the delete statement. Otherwise, memory leakage will occur.

	Note
	This function will be called automatically when this array goes out of scope.

Example

SFXArray<SInt16> array;
    
...
     
array.Clear();    // clear the array

Reference

SFXArray::Remove | SFXArray::SetCluster | SFXArray::SetThreshold | SFXArray::GetSize

SFXArray::Contains

Check whether or not this array contains the specified value.

[ public, const ]
Bool Contains(
    V value   // value to check
);

Return value

If the specified value is contained: true
Otherwise: false

Description

This function checks whether or not this array contains the specified value.

	Note
	If the type of the element is a pointer to a class instance or data bigger than 4 bytes, their addresses will be compared with.

Example

SFXArray<SInt16> array;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {

        // check whether or not the stack contains the elements below
        TRACE("Contains(2) = %s", (array.Contains(2)) ? ("true") : ("false"));  // contains(2) = true
        TRACE("Contains(4) = %s", (array.Contains(4)) ? ("true") : ("false"));  // contains(4) = false
    }
}

Reference

SFXArray::FirstIndexOf

SFXArray::EmptyInstance

Get an empty array.

[ public, static ]
SFXArray< V > const & EmptyInstance(Void);

Description

Get an instance that represents an empty array.

SFXArray::Equals

Check whether or not this array equals the specified array.

[ public, const ]
Bool Equals(
    SFXArray< V > const & collection   // array to compare with 
);

Return value

If this array equals the specified array: true
Otherwise: false

Description

This function checks whether or not this array equals the specified array (whether or not the same elements are saved in the same order).

	Note
	If the type of the element is a pointer, its address will be compared.

SFXArray::FirstIndexOf

Get the first index of the element that equals the specified value, searching from the head.

[ public, const ]
SInt32 FirstIndexOf(
    V value                         // value to match
    SInt32 index = SINT32_MINIMUM   // index to search from
);

Return value

If succeeds: first index of the element that equals the specified value
If failed: -1

Description

This function gets the first index of the element of this array that equals the specified value, searching from the head to the tail.

By specifying the beginning index in the argument, you can search from any position other than the head. (The index of the head is 0.)

	Note
	If the type of the element is a pointer, its address will be compared.

Example

SFXArray<SInt16> array;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {

        // get the first index of the element that equals the specified value, searching from the beginning
        TRACE("FirstIndexOf(1) = %d", array.FirstIndexOf(1));  // firstIndexOf(1) = -1
        TRACE("FirstIndexOf(2) = %d", array.FirstIndexOf(2));  // firstIndexOf(2) = 0
        TRACE("FirstIndexOf(5) = %d", array.FirstIndexOf(5));  // firstIndexOf(5) = 1
    }
}

Reference

SFXArray::Contains | SFXArray::LastIndexOf

SFXArray::Get

Get the element at the specified index.

[ public, const ]
V Get(
    SInt32 index   // index of the element to get
);

Return value

Element at the index specified in the argument. 0 or null will be returned if no element exists at the specified index.

Return value

This function gets the element at the index specified in the argument.

	Caution
	In case no element exists at the specified index, no error will occur but this function will return 0 or null.

Reference

SFXArray::GetFirst | SFXArray::GetLast | SFXArray::Insert | SFXArray::Remove | SFXArray::Set

SFXArray::GetCluster

Get the cluster size of the internal buffer memory. [in bytes]

[ public, const ]
UInt16 GetCluster(Void);

Return value

Cluster size of the internal buffer memory [in bytes]

Description

This function gets the cluster size, by which the size of the internal buffer memory increases. [in bytes]

Reference

SFXArray::SetCluster

SFXArray::GetEnumerator

Get the enumerator that points to the element at the specified index.

[ public, const ]
Enumerator GetEnumerator(
    SInt32 index   // index to start
);

Return value

Enumerator that points to the element at the specified index

Description

This function gets the enumerator of this array that points to the element at the specified index.

Note

	Note
If the specified index is less than or equals 0, this function is same as the `SFXArray::GetFirstEnumerator` function. If the specified index is more than or equals the size of this array, this function is same as the `SFXArray::GetLastEnumerator` function.

If the specified index is less than or equals 0, this function is same as the SFXArray::GetFirstEnumerator function.

If the specified index is more than or equals the size of this array, this function is same as the SFXArray::GetLastEnumerator function.

Reference

SFXArray::GetFirstEnumerator | SFXArray::GetLastEnumerator | SFXArray::GetIterator | SFXArray::Enumerator

SFXArray::GetFirst

Get the element at the head.

[ public, const ]
V GetFirst(Void);

Return value

Element at the head. 0 or null will be returned if no element exists in this array.

Description

This function gets the element at the head.

	Caution
	In case no element exists in this array, no error will occur but this function will return 0 or null.

Reference

SFXArray::Get | SFXArray::GetLast | SFXArray::RemoveFirst | SFXArray::InsertFirst

SFXArray::GetFirstEnumerator

Get the enumerator that points to the first element.

[ public, const ]
Enumerator GetFirstEnumerator(Void);

Return value

Enumerator that points to the first element

Description

This function gets the enumerator of this array that points to the first element.

Example

SFXArray<SInt16> array;
SFXArray<SInt16>::Enumerator en;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {
    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {
        
        // get the enumerator that points to the first element
        en = array.GetFirstEnumerator();
        
        // check whether the next element exists or not
        while(en.HasNext()) {
            TRACE("%d", en.GetNext());  // 2 5 
        }
    }
}

Reference

SFXArray::GetEnumerator | SFXArray::GetFirstIterator | SFXArray::Enumerator

SFXArray::GetFirstIterator

Get the iterator that points to the first element.

[ public ]
Iterator GetFirstIterator(Void);

Return value

Iterator that points to the first element

Description

This function gets the iterator of this array that points to the first element.

Example

SFXArray<SInt16> array;
SFXArray<SInt16>::Iterator it;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {
    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {
        
        // get the iterator that points to the first element
        it = array.GetFirstIterator();
        
        // check whether the next element exists or not
        while(it.HasNext()) {
            TRACE("%d", it.GetNext());  // 2 5 
        }
    }
}

Reference

SFXArray::GetIterator | SFXArray::GetFirstEnumerator | SFXArray::Iterator

SFXArray::GetIterator

Get the iterator that points to the element at the specified index.

[ public ]
Iterator GetIterator(
    SInt32 index   // index to start
);

Return value

Iterator that points to the element at the specified index

Description

This function gets the iterator of this array that points to the element at the specified index.

Note

	Note
If the specified index is less than or equals 0, this function is same as the `SFXArray::GetFirstIterator` function. If the specified index is more than or equals the size of this array, this function is same as the `SFXArray::GetLastIterator` function.

If the specified index is less than or equals 0, this function is same as the SFXArray::GetFirstIterator function.

If the specified index is more than or equals the size of this array, this function is same as the SFXArray::GetLastIterator function.

Reference

SFXArray::GetFirstIterator | SFXArray::GetLastIterator | SFXArray::GetIterator | SFXArray::Iterator

SFXArray::GetLast

Get the element at the tail.

[ public, const ]
V GetLast(Void);

Return value

Element at the tail. 0 or null will be returned if no element exists in this array.

Description

This function gets the element at the tail.

	Caution
	In case no element exists in this array, no error will occur but this function will return 0 or null.

Reference

SFXArray::Get | SFXArray::GetFirst | SFXArray::InsertLast | SFXArray::RemoveLast

SFXArray::GetLastEnumerator

Get the enumerator that points to the last element.

[ public, const ]
Enumerator GetLastEnumerator(Void);

Return value

Enumerator that points to the first element

Description

This function gets the enumerator of this array that points to the first element.

Reference

SFXArray::GetEnumerator | SFXArray::GetLastIterator | SFXArray::Enumerator

SFXArray::GetLastIterator

Get the iterator that points to the last element.

[ public ]
Iterator GetLastIterator(Void);

Return value

Iterator that points to the last element

Description

This function gets the iterator of this array that points to the last element.

Reference

SFXArray::GetIterator | SFXArray::GetLastEnumerator | SFXArray::Iterator

SFXArray::GetSize

Get the size(the number of the elements).

[ public, const ]
SInt32 GetSize(Void);

Example

SFXArray<SInt16> array;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {
    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {
            // display the size(the number of the elements)
            TRACE("%d",array.GetSize());  // 2
    }
}

Reference

SFXArray::SetSize

SFXArray::GetThreshold

Get the minimum size of the internal buffer memory. [in bytes]

[ public, const ]
UInt16 GetThreshold(Void);

Return value

Minimum size of the internal buffer memory. [in bytes]

Description

This function gets the minimum size of the internal buffer memory. [in bytes]

Reference

SFXArray::SetThreshold

SFXArray::Insert

Insert the specified element or array before the specified index.

[ public ]
SFCError Insert(
    SInt32 index                       // index to insert
    SFXArray< V > const & collection   // array to insert
);

[ public ]
SFCError Insert(
    SInt32 index   // index to insert
    V value        // value of the element to insert
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

This function inserts the specified element or array before the specified index.

If the value of the specified index is less than or equals 0, the element will be inserted at the head.

If the value of the specified index is greater than or equals the number of the elements, the element will be inserted at the tail.

Example

SFXArray<SInt16> array;
SInt16 i;

// insert an element at the tail
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // insert an element at the tail
    if (array.InsertLast(5) == SFERR_NO_ERROR) {

        // insert an element at the head
        if (array.Insert(0, 3) == SFERR_NO_ERROR) {

            // insert an element before the specified index
            // if the value of the specified index is less than or equals 0, an element will be inserted at head
            // if the value of the specified index is greater than or equals the number of the elements, an element will be inserted at the tail
            if (array.Insert(10, 4) == SFERR_NO_ERROR) {

                // enumerate elements by index
                for (i = 0; i < array.GetSize(); ++i) {

                    TRACE("%d", array[i]);  // 3 2 5 4
               }
           }
       }
    }
}

Reference

SFXArray::InsertFirst | SFXArray::InsertLast | SFXArray::Set | SFXArray::Get | SFXArray::Remove

SFXArray::InsertFirst

Insert the specified element or list at the head.

[ public ]
SFCError InsertFirst(
    SFXArray< V > const & collection   // array to insert
);

[ public ]
SFCError InsertFirst(
    V value   // value of the element to insert
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

This function inserts the specified element or list at the head.

Reference

SFXArray::Insert | SFXArray::InsertLast | SFXArray::GetFirst | SFXArray::RemoveFirst

SFXArray::InsertLast

Insert the specified element or array at the tail.

[ public ]
SFCError InsertLast(
    SFXArray< V > const & collection   // array to insert
);

[ public ]
SFCError InsertLast(
    V value   // value of the element to insert
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

This function inserts the specified element or array at the tail.

Reference

SFXArray::Insert | SFXArray::InsertFirst | SFXArray::GetLast | SFXArray::RemoveLast

SFXArray::IsEmpty

Check whether or not this array is empty.

[ public, const ]
Bool IsEmpty(Void);

Return value

If empty: true
Otherwise: false

Description

This function checks whether or not this array is empty.

SFXArray::LastIndexOf

Get the last index of the element that equals the specified value, searching from the tail.

[ public, const ]
SInt32 LastIndexOf(
    V value                         // value to match
    SInt32 index = SINT32_MAXIMUM   // index to search from
);

Return value

If succeeds: last index of the element that equals the specified value
If failed: -1

Description

This function gets the last index of the element of this array that equals the specified value, searching from the tail to the head.

By specifying the beginning index in the argument, you can search from any position other than the tail. (The index of the head is 0.)

	Note
	If the type of the element is a pointer, its address will be compared.

Example

SFXArray<SInt16> array;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {

        // get the last index of the element that equals the specified value, searching from the end
        TRACE("LastIndexOf(1) = %d", array.LastIndexOf(1));  // lastIndexOf(1) = -1
        TRACE("LastIndexOf(2) = %d", array.LastIndexOf(2));  // lastIndexOf(2) = 0
        TRACE("LastIndexOf(5) = %d", array.LastIndexOf(5));  // lastIndexOf(5) = 1
    }
}

Reference

SFXArray::Contains | SFXArray::FirstIndexOf

SFXArray::Move

Move the element at the specified index to the specified index.

[ public ]
SFCError Move(
    SInt32 destination   // destination index of the element to move
    SInt32 source        // source index of the element to move
);

Return value

If succeeds: SFERR_NO_ERROR
If no element exists at the specified index: SFERR_INVALID_PARAM

Description

This function moves the element at the specified index to the specified index.

Reference

SFXArray::MoveFirst | SFXArray::MoveLast

SFXArray::MoveFirst

Move the element at the specified index to the head.

[ public ]
SFCError MoveFirst(
    SInt32 source   // source index
);

Return value

If succeeds: SFERR_NO_ERROR
If this array is empty: SFERR_INVALID_STATE
If no element exists at the specified index: SFERR_INVALID_PARAM

Description

This function moves the element at the specified index to the head.

Reference

SFXArray::Move | SFXArray::MoveLast

SFXArray::MoveLast

Move the element at the specified index to the tail.

[ public ]
SFCError MoveLast(
    SInt32 source   // source index
);

Return value

If succeeds: SFERR_NO_ERROR
If this array is empty: SFERR_INVALID_STATE
If no element exists at the specified index: SFERR_INVALID_PARAM

Description

This function moves the element at the specified index to the tail.

Reference

SFXArray::Move | SFXArray::MoveFirst

SFXArray::Remove

Remove the elements at the specified index or range.

[ public ]
Void Remove(
    SInt32 index   // index of the element to remove
);

[ public ]
Void Remove(
    SInt32 begin   // beginning index(this index is included)
    SInt32 end     // ending index(this index is not included)
);

Description

This function removes the element at the specified index or the elements in the specified index range.

If the specified index is less than 0 or greater than or equals the number of the elements, no element will be removed.

If the beginning index to remove is greater than or equals the number of the elements or the ending index to remove is less than or equals 0, no element will be removed.

If the beginning index to remove is less than or equals 0, it will be reset to 0.

If the ending index to remove is greater than the number of the elements, it will be reset to the number of the elements.

	Caution
	If no element exists at the specified index or range, no error will occur and nothing will happen.

Example

SFXArray<SInt16> array;
SInt16 i;

// insert an element at the tail
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // insert an element at the tail
    if (array.InsertLast(5) == SFERR_NO_ERROR) {

        // insert an element at the head
        if (array.Insert(0, 3) == SFERR_NO_ERROR) {

            // insert an element at the specified index
            // if the value of the specified index is less than or equals 0, an element will be inserted at head
            // if the value of the specified index is greater than or equals the number of the elements, an element will be inserted at the tail
            if (array.Insert(10, 4) == SFERR_NO_ERROR) {

                // remove from array[1] to array[2]
                array.Remove(1, 3);

                // enumerate elements by index
                for (i = 0; i < array.GetSize(); ++i) {

                    TRACE("%d", array[i]);  // 3 4
               }
           }
       }
    }
}

Reference

SFXArray::RemoveFirst | SFXArray::RemoveLast | SFXArray::Insert | SFXArray::Get | SFXArray::Set

SFXArray::RemoveFirst

Remove the element at the head.

[ public ]
Void RemoveFirst(Void);

Description

This function removes the element at the head.

	Caution
	If no element exists in this array, no error will occur and nothing will happen.

Reference

SFXArray::Remove | SFXArray::RemoveLast | SFXArray::GetFirst | SFXArray::InsertFirst

SFXArray::RemoveLast

Remove the element at the tail.

[ public ]
Void RemoveLast(Void);

Description

This function removes the element at the tail.

	Caution
	If no element exists in this array, no error will occur and nothing will happen.

Reference

SFXArray::Remove | SFXArray::RemoveFirst | SFXArray::GetLast | SFXArray::InsertLast

SFXArray::Set

Set the element at the specified index of this array to the specified value. Or set this array to the specified array.

[ public ]
SFCError Set(
    SFXArray< V > const & collection   // array to set
);

[ public ]
SFCError Set(
    SInt32 index   // index to set
    V value        // value to set
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY
If no element exists at the specified index: SFERR_INVALID_PARAM

Description

This function sets the element at the specified index of this array to the specified value, or sets this array to the specified array.

* In case an error occurs during processing, this array will be restored.

Example

SFXArray<SInt16> array;
SInt16 i;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {

        // set a value to the element of array 
        if (array.Set(1, 10) == SFERR_NO_ERROR) {

            // enumerate elements by index
            for (i = 0; i < array.GetSize(); ++i) {

                TRACE("%d", array[i]);  // 2 10
           }
       }
    }
}

Reference

SFXArray::Get | SFXArray::Insert | SFXArray::Remove

SFXArray::SetCluster

Set the cluster size of the internal buffer memory. [in bytes]

[ public ]
Void SetCluster(
    UInt16 size   // cluster size to set
);

Description

This function sets the minimum unit to allocate the internal buffer memory(SFXClusterHeap). [in bytes]

Default: SFXArray::DEFAULT_CLUSTER bytes

For the value of SFXArray::DEFAULT_CLUSTER, refer to SFXArray::DefaultEnum.

	Tip
	Since the size of one element is 4 byte, a multiple of four should be specified in the size argument.

Internal buffer memory

	Internal buffer memory
In the `SFXArray` class, an element will be stored into the internal buffer memory when appended. Initially, the size set with the `SFXArray::SetThreshold` function will be allocated as the internal buffer memory. If an element cannot be stored into the internal buffer memory when tried to be appended, the size added by the cluster size set with the `SFXArray::SetCluster` function will be re-allocated as the internal buffer memory. To minimize the re-allocation of the the internal buffer memory, it is recommended to optimize the size set with the `SFXArray::SetThreshold` / `SFXArray::SetCluster` function depending on the application characteristics.

In the SFXArray class, an element will be stored into the internal buffer memory when appended.

Initially, the size set with the SFXArray::SetThreshold function will be allocated as the internal buffer memory.

If an element cannot be stored into the internal buffer memory when tried to be appended, the size added by the cluster size set with the SFXArray::SetCluster function will be re-allocated as the internal buffer memory.

To minimize the re-allocation of the the internal buffer memory, it is recommended to optimize the size set with the SFXArray::SetThreshold / SFXArray::SetCluster function depending on the application characteristics.

Reference

SFXArray::GetCluster | SFXArray::SetThreshold | SFXArray::DefaultEnum | SFXClusterHeap::SetCluster | SFXClusterHeap

SFXArray::SetFirst

Set the element at the head to the specified value.

[ public ]
SFCError SetFirst(
    V value   // value to set
);

Return value

If succeeds: SFERR_NO_ERROR
If this array is empty: SFERR_INVALID_STATE

Description

This function sets the element at the head to the specified value.

Reference

SFXArray::GetFirst | SFXArray::Set | SFXArray::SetLast

SFXArray::SetLast

Set the element at the tail to the specified value.

[ public ]
SFCError SetLast(
    V value   // value to set
);

Return value

If succeeds: SFERR_NO_ERROR
If this array is empty: SFERR_INVALID_STATE

Description

This function sets the element at the tail to the specified value.

Reference

SFXArray::GetLast | SFXArray::Set | SFXArray::SetFirst

SFXArray::SetSize

Set the size of this array to the specified value.

[ public ]
SFCError SetSize(
    SInt32 size   // size to set
);

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

This function sets the size of this array to the specified value.

	Note
	If the specified size is smaller than the current size of this array, elements after the specified size will be removed. On the contrary, if it is bigger than the current size of this array, each of the expanded elements will be set to 0.

Reference

SFXArray::GetSize

SFXArray::SetThreshold

Set the minimum size of the internal buffer memory. [in bytes]

[ public ]
Void SetThreshold(
    UInt16 size   // minimum size of the internal buffer memory to set
);

Description

This function sets the minimum memory of the internal buffer memory(SFXClusterHeap). [in bytes]

Default: SFXArray::DEFAULT_THRESHOLD bytes

For the value of SFXArray::DEFAULT_THRESHOLD, refer to SFXArray::DefaultEnum.

	Tip
	Since the size of one element is 4 byte, a multiple of four should be specified in the size argument.

Internal buffer memory

	Internal buffer memory
In the `SFXArray` class, an element will be stored into the internal buffer memory when appended. Initially, the size set with the `SFXArray::SetThreshold` function will be allocated as the internal buffer memory. If an element cannot be stored into the internal buffer memory when tried to be appended, the size added by the cluster size set with the `SFXArray::SetCluster` function will be re-allocated as the internal buffer memory. To minimize the re-allocation of the the internal buffer memory, it is recommended to optimize the size set with the `SFXArray::SetThreshold` / `SFXArray::SetCluster` function depending on the application characteristics.

In the SFXArray class, an element will be stored into the internal buffer memory when appended.

Initially, the size set with the SFXArray::SetThreshold function will be allocated as the internal buffer memory.

Reference

SFXArray::GetThreshold | SFXArray::SetCluster | SFXArray::DefaultEnum | SFXClusterHeap::SetThreshold | SFXClusterHeap

SFXArray::Swap

Swap two elements at the specified indexes.

[ public ]
SFCError Swap(
    SInt32 destination   // destination index
    SInt32 source        // source index
);

Return value

If succeeds: SFERR_NO_ERROR
If no element exists at the specified index: SFERR_INVALID_PARAM

Description

This function swaps two elements at the specified indexes.

Reference

SFXArray::SwapFirst | SFXArray::SwapLast

SFXArray::SwapFirst

Swap the element at the specified index for the element at the head.

[ public ]
SFCError SwapFirst(
    SInt32 source   // source index
);

Return value

If succeeds: SFERR_NO_ERROR
If this array is empty: SFERR_INVALID_STATE
If no element exists at the specified index: SFERR_INVALID_PARAM

Description

This function swaps the element at the specified index for the element at the head.

Reference

SFXArray::Swap | SFXArray::SwapLast

SFXArray::SwapLast

Swap the element at the specified index for the element at the tail.

[ public ]
SFCError SwapLast(
    SInt32 source   // source index
);

Return value

If succeeds: SFERR_NO_ERROR
If this array is empty: SFERR_INVALID_STATE
If no element exists at the specified index: SFERR_INVALID_PARAM

Description

This function swaps the element at the specified index for the element at the tail.

Reference

SFXArray::Swap | SFXArray::SwapFirst

SFXArray::operator[]

Get the element by index.

[ public ]
V & operator[](
    SInt32 index   // index of the element to get
);

[ public, const ]
V const & operator[](
    SInt32 index   // index of the element to get
);

Reference

SFXArray::Get | SFXArray::Set

SFXArray::DefaultEnum

Constants that represent the default values for the minimum size and the cluster size of the internal buffer memory. [in bytes]

enum DefaultEnum {
    DEFAULT_THRESHOLD = 4 * sizeof(VoidPtr),      // default minimum size of the internal buffer memory [in bytes]
    DEFAULT_CLUSTER   = 8 * sizeof(VoidPtr)       // default cluster size to allocate the internal buffer memory [in bytes]
};

Description

DEFAULT_THRESHOLD and DEFAULT_CLUSTER are the constants that represent the default values for the minimum size and the cluster size of the internal buffer memory(SFXClusterHeap). [in bytes]

Reference

SFXArray::SetCluster | SFXArray::SetThreshold | SFXClusterHeap

SFXArray::Enumerator

Class for managing the enumerator of this array.

[ public ]

SFMTYPEDEFCLASS(Enumerator)
friend class Enumerator;
class Enumerator  {
    public:
        explicit            Enumerator          (Void) : Enumeratoa();
                            Enumerator          (IteratorConstRef iterator) : Enumeratoa(iterator);
        EnumeratorRef       operator=           (IteratorConstRef iterator);
        V                   GetNext             (Void);
        V                   GetPrevious         (Void);
        Bool                HasNext             (Void) const;
        Bool                HasPrevious         (Void) const;
        Bool                IsValid             (Void) const;
};

Description

This class is for managing the enumerator of this array.

This class has the following member functions.

GetNext	Get the next element. If no next element exists, null or 0 will be returned.
GetPrevious	Get the previous element. If no previous element exists, null or 0 will be returned.
HasNext	Check whether or not the next element exists.
HasPrevious	Check whether or not the previous element exists.
IsValid	Check whether or not the enumerator is valid.

Example

SFXArray<SInt16> array;
SFXArray<SInt16>::Enumerator en;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {
        
        // get the enumerator that points to the first element
        en = array.GetFirstEnumerator();
        
        // check whether the next element exists or not
        while(en.HasNext()) {

            TRACE("%d", en.GetNext());  // 2 5 
        }
    }

Reference

SFXArray::Iterator

SFXArray::Iterator

Class for managing the iterator of this array.

[ public ]

SFMTYPEDEFCLASS(Iterator)
friend class Iterator;
class Iterator  {
    public:
        explicit            Iterator            (Void) : Iteratoa();
 SFCError     Set                 (V value);
        V                   GetNext             (Void);
        V                   GetPrevious         (Void);
        Bool                HasNext             (Void) const;
        Bool                HasPrevious         (Void) const;
        Bool                IsValid             (Void) const;
 SFCError            Insert              (V value);
        Vold                Remove              (Void);

    friend      class               Enumerator;
};

Description

This class is for managing the iterator of this array.

This class has the following member functions.

Set	Set the element of current iterator to the specified value.
GetNext	Get the next element. If no next element exists, null or 0 will be returned.
GetPrevious	Get the previous element. If no previous element exists, null or 0 will be returned.
HasNext	Check whether or not the next element exists.
HasPrevious	Check whether or not the previous element exists.
IsValid	Check whether or not the iterator is valid.
Insert	Insert an element after the element of current iterator.
Remove	Remove the element of current iterator.

Example

SFXArray<SInt16> array;
SFXArray<SInt16>::Iterator it;

// append an element
if (array.InsertLast(2) == SFERR_NO_ERROR) {

    // append an element
    if (array.InsertLast(5) == SFERR_NO_ERROR) {
        
        // get the iterator that points to the first element
        it = array.GetFirstIterator();
        
        // check whether the next element exists or not
        while(it.HasNext()) {

            TRACE("%d", it.GetNext());  // 2 5 
        }
    }
}

Reference

SFXArray::Enumerator