Photon C++ Client API  4.1.15.3
Classes | Public Member Functions | List of all members
JVector< Etype > Class Template Reference
Inheritance diagram for JVector< Etype >:
Inheritance graph
[legend]
Collaboration diagram for JVector< Etype >:
Collaboration graph
[legend]

Public Member Functions

 JVector (unsigned int initialCapacity=0, unsigned int capacityIncrement=1)
 
 JVector (const Etype *carray, unsigned int elementCount, unsigned int initialCapacity=0, unsigned int capacityIncrement=1)
 
virtual ~JVector (void)
 
 JVector (const JVector< Etype > &rhv)
 
JVectoroperator= (const JVector< Etype > &rhv)
 
bool operator== (const JVector< Etype > &toCompare) const
 
bool operator!= (const JVector< Etype > &toCompare) const
 
const Etype & operator[] (unsigned int index) const
 
Etype & operator[] (unsigned int index)
 
unsigned int getCapacity (void) const
 
bool contains (const Etype &elem) const
 
const Etype & getFirstElement (void) const
 
int getIndexOf (const Etype &elem) const
 
bool getIsEmpty (void) const
 
const Etype & getLastElement (void) const
 
int getLastIndexOf (const Etype &elem) const
 
unsigned int getSize (void) const
 
const Etype * getCArray (void) const
 
void copyInto (Etype *array) const
 
void addElement (const Etype &obj)
 
void addElements (const JVector< Etype > &vector)
 
void addElements (const Etype *carray, unsigned int elementCount)
 
void ensureCapacity (unsigned int minCapacity)
 
void removeAllElements (void)
 
bool removeElement (const Etype &obj)
 
void trimToSize (void)
 
const Etype & getElementAt (unsigned int index) const
 
void insertElementAt (const Etype &obj, unsigned int index)
 
void removeElementAt (unsigned int index)
 
void setElementAt (const Etype &obj, unsigned int index)
 
JStringtoString (JString &retStr, bool withTypes=false) const
 
- Public Member Functions inherited from Base
virtual ~Base (void)
 
- Public Member Functions inherited from ToString
virtual ~ToString (void)
 
virtual JString typeToString (void) const
 
JString toString (bool withTypes=false) const
 

Additional Inherited Members

- Static Public Member Functions inherited from Base
static void setListener (const BaseListener *baseListener)
 
static int getDebugOutputLevel (void)
 
static bool setDebugOutputLevel (int debugLevel)
 
static const LogFormatOptionsgetLogFormatOptions (void)
 
static void setLogFormatOptions (const LogFormatOptions &options)
 

Detailed Description

template<typename Etype>
class ExitGames::Common::JVector< Etype >

This is a C++ implementation of the Vector Container class from Sun Java.

This class is based on the Java Vector class and as such contains all the public member functions of its Java equivalent. Unlike Java, typecasts are not necessary since C++ allows template instantiation of types at compile time. In addition to the Java public member functions, some operators were also added in order to take advantage of the operator overloading feature available in C++.

Constructor & Destructor Documentation

§ JVector() [1/3]

JVector ( unsigned int  initialCapacity = 0,
unsigned int  capacityIncrement = 1 
)

Constructor.

Creates an empty JVector of elements of the type of the template parameter.

Parameters
initialCapacitythe amount of elements, the JVector can take without need for resize. If you choose this too small, the JVector needs expensive resizes later (it's most likely, that the complete memory has to be copied to a new location on resize), if you choose it too big, you will waste much memory. The default is 40.
capacityIncrementEvery time, when one adds an element to the Vector and it has no capacity left anymore, it's capacity will grow with this amount of elements on automatic resize. If you pass a too small value here, expensive resize will be needed more often, if you choose a too big one, possibly memory is wasted. The default is 10.

§ JVector() [2/3]

JVector ( const Etype *  carray,
unsigned int  elementCount,
unsigned int  initialCapacity = 0,
unsigned int  capacityIncrement = 1 
)

Constructor.

Creates a JVector, initialized with the passed carray the template parameter.

Parameters
carrayall elements of this array up to elementCount will get copied into the constructed instance
elementCountshall not be greater than the actual element count of carray or undefined behavior will occur
initialCapacitythe amount of elements, the JVector can take without need for resize. Defaults to the value that gets passed for elementCount. If you choose this too small, the JVector needs expensive resizes later (it's most likely, that the complete memory has to be copied to a new location on resize), if you choose it too big, you will waste much memory.
capacityIncrementEvery time, when one adds an element to the Vector and it has no capacity left anymore, it's capacity will grow with this amount of elements on automatic resize. If you pass a too small value here, expensive resize will be needed more often, if you choose a too big one, possibly memory is wasted. The default is 10.

§ ~JVector()

~JVector ( void  )
virtual

Destructor.

§ JVector() [3/3]

JVector ( const JVector< Etype > &  toCopy)

Copy-Constructor.

Creates an object out of a deep copy of its parameter.

The parameter has to be of the same template overload as the object, you want to create.

Parameters
toCopyThe object to copy.

Member Function Documentation

§ operator=()

JVector< Etype > & operator= ( const JVector< Etype > &  toCopy)

operator=.

Makes a deep copy of its right operand into its left operand. Both operands have to be of the same template overload.

This overwrites old data in the left operand.

§ operator==()

bool operator== ( const JVector< Etype > &  toCompare) const

operator==.

Returns
true, if both operands are equal, false otherwise. Two instances are treated as equal, if they both contain the the same amount of elements and every element of one instance equals the other instance's element at the same index. If the element type is a pointer type, then the pointers are checked for equality, not the values, to which they point to.

§ operator!=()

bool operator!= ( const JVector< Etype > &  toCompare) const

operator!=.

Returns
false, if operator==() would return true, true otherwise.

§ operator[]() [1/2]

const Etype & operator[] ( unsigned int  index) const

operator[]. Wraps the function getElementAt(), so you have the same syntax like for arrays.

§ operator[]() [2/2]

Etype & operator[] ( unsigned int  index)

operator[]. Wraps the function getElementAt(), so you have the same syntax like for arrays.

§ getCapacity()

unsigned int getCapacity ( void  ) const

Returns the current capacity of the JVector.

Returns
the current capacity.

§ contains()

bool contains ( const Etype &  elem) const

Checks, if the JVector contains the passed data as an element.

Parameters
elema reference to the data, you want to check. Needs to be either a primitive type or an object of a class with an overloaded == operator.
Returns
true, if the element was found, false otherwise.

§ getFirstElement()

const Etype & getFirstElement ( void  ) const

Returns the first element of the JVector. Shows undefined behavior for empty vectors.

Returns
the first element.

§ getIndexOf()

int getIndexOf ( const Etype &  elem) const

Searches the JVector from the first element in forward direction for the passed element and returns the first index, where it was found.

Parameters
elemthe element, to search for.
Returns
the index of the first found of the passed element or -1, if the element could not be found at all.

§ getIsEmpty()

bool getIsEmpty ( void  ) const

Checks, if the JVector is empty.

Returns
true, if the JVector is empty, or false, if it contains at least one element.

§ getLastElement()

const Etype & getLastElement ( void  ) const

Returns the last element of the JVector. Shows undefined behavior for empty vectors.

Returns
the last element.

§ getLastIndexOf()

int getLastIndexOf ( const Etype &  elem) const

Searches the JVector from the last element in backward direction for the passed element and returns the first index, where it was found.

Parameters
elemthe element, to search for.
Returns
the index of the first found of the passed element or -1, if the element could not be found at all.

§ getSize()

unsigned int getSize ( void  ) const

Returns the size of the JVector.

Returns
the size.

§ getCArray()

const Etype * getCArray ( void  ) const
Remarks
For a deep-copy copyInto() should be used. Use getSize() to find out the element count of the returned array.
Returns
a read-only pointer copy of the Etype*, that is internally used to store the elements.

§ copyInto()

void copyInto ( Etype *  array) const

Copies all elements of the JVector into the passed array. The caller has to make sure, that the array is big enough to take all elements of the vector, otherwise calling this function produces a buffer overflow.

Parameters
arrayan array of variables of the type of the template overload.
Returns
nothing.

§ addElement()

void addElement ( const Etype &  elem)

Adds an element to the JVector. This automatically resizes the JVectors capacity to it's old size + the capacityIncrement, that you passed, when creating the vector (if you passed no value for capacityIncrement, then it was set to it's default value (see constructor doc)), if the size of the JVector has already reached it's capacity. When resizing occurs, then most likely the whole vector has to be copied to new memory. So this can be an expensive operation for huge vectors.

Note
When this function needs to increase the capacity, then all references/pointers to elements, that have been acquired before this function has been called, become invalid!
Parameters
elemthe element to add.
Returns
nothing.

§ addElements() [1/2]

void addElements ( const JVector< Etype > &  vector)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calls the above function with vector.getCArray() and vector.getSize() as parameters

Parameters
vectorthe vector from which to copy the elements

§ addElements() [2/2]

void addElements ( const Etype *  carray,
unsigned int  elementCount 
)

Adds the first 'elementCount' elements of the provided array to the JVector. This automatically resizes the JVectors capacity to it's old size + 'elementCount', if the new size of the JVector is bigger than it's old capacity. When resizing occurs, then most likely the whole vector has to be copied to new memory. So this can be an expensive operation for huge vectors.

Note
When this function needs to increase the capacity, then all references/pointers to elements, that have been acquired before this function has been called, become invalid!
Parameters
carraythe elements to add.
elementCountthe number of elements to add - must not be greater than the size of carray.
Returns
nothing.

§ ensureCapacity()

void ensureCapacity ( unsigned int  minCapacity)

Resizes the JVector to the passed capacity, if it's old capacity has been smaller. If resizing is needed, then the whole JVector has to be copied into new memory, so in that case this is an expensive operation for huge JVectors. Call this function, before you add a lot of elements to the vector, to avoid multiple expensive resizes through adding.

Note
When this function needs to increase the capacity, then all references/pointers to elements, that have been acquired before this function has been called, will get invalid!
Parameters
minCapacitythe new capacity for the JVector.
Returns
nothing.

§ removeAllElements()

void removeAllElements ( void  )

Clears the JVector.

Returns
nothing.

§ removeElement()

bool removeElement ( const Etype &  obj)

Removes the passed element from the JVector.

Parameters
objthe element, to remove.
Returns
true, if the element has been removed, false, if it could not be found.

§ trimToSize()

void trimToSize ( void  )

Trims the capacity of the JVector to the size, it currently uses. Call this function for a JVector with huge unused capacity, if you do not want to add further elements to it and if you are short on memory. This function copies the whole vector to new memory, so it is expensive for huge vectors. If you only add one element to the JVector later, it's copied again.

Note
Trimming a JVector instance (that isn't already optimally trimmed) will make all references/pointers to elements, that have been acquired before this function has been called, invalid!

§ getElementAt()

const Etype & getElementAt ( unsigned int  index) const

Returns the element of the JVector at the passed index. This does not check for valid indexes and shows undefined behavior for invalid indexes!

Parameters
indexthe index of the element, that should be returned. Must not be bigger than the current size of the vector!
Returns
the element at the passed index.

§ insertElementAt()

void insertElementAt ( const Etype &  obj,
unsigned int  index 
)

Inserts parameter one into the JVector at the index, passed as parameter two. Because all elements above or at the passed index have to be moved one position up, it is expensive, to insert an element at an low index into a huge JVector.

Parameters
objthe element, to insert.
indexthe position in the JVector, the element is inserted at.
Returns
nothing.

§ removeElementAt()

void removeElementAt ( unsigned int  index)

Removes the element at the passed index from the JVector. Shows undefined behavior for invalid indexes.

Parameters
indexthe index of the element to remove.
Returns
nothing.

§ setElementAt()

void setElementAt ( const Etype &  obj,
unsigned int  index 
)

Sets the element at the passed index of the JVector to the passed new value. Shows undefined behavior for invalid indexes.

Parameters
objthe new value.
indexthe index of the element, which is set to the new value.
Returns
nothing.

§ toString()

JString & toString ( JString retStr,
bool  withTypes = false 
) const
virtual
Remarks
The cost of this function depends a lot on implementation details of the implementing subclasses, but for container classes this function can become quite expensive, if the instance contains huge amounts of data, as its cost for many container class implementations increases disproportionately high to the size of the payload.
Parameters
retStrreference to a string, to store the return-value in; the information, which is generated by this function, will be attached at the end of any eventually existing previous content of the string
withTypesset to true, to include type information in the generated string
Returns
a JString representation of the instance and its contents for debugging purposes.

Implements ToString.