ext/containers/array.bi

Summary
ext/containers/array.bi
LicenseCopyright © 2007-2011, FreeBASIC Extended Library Development Group
Macros
fbext_ArrayThis macro expands to the name of the fbext_Array type.
fbext_Array_DeclareThis macro expands to the definition of the fbext_Array class.
ext.fbext_Array(( T_)( Allocator_))A generic variable-length array.
Construction/Destruction/Assignment
default constructorConstructs an empty array (having zero elements).
copy constructorConstructs an array consisting of copies of the elements from another.
repeat constructorConstructs an array consisting of copies of the default value.
repeat constructorConstructs an array consisting of copies of an element value.
ranged constructorConstructs an array from a copy of a range of elements.
destructorDestroys the array.
copy operator letCopy assigns to the array from another.
Capacity
SizeGets the number of elements in the array.
CapacityGets the maximum number of elements the array can store without requiring additional memory.
EmptyDetermines if the array contains elements or not.
ReserveEnsures that the capacity of the array is at least n.
ResizeChanges the size of the array to newsize number of elements.
ResizeChanges the size of the array to newsize number of elements
Iterators
BeginGets an iterator to the element at the front of the array.
cBeginGets an iterator to the element at the front of the array; the element in immutable.
End_Gets an iterator to the element at the back of the array.
cEndGets an iterator to the element at the back of the array; the element is immutable.
Elements
FrontGets a pointer to the element at the front of the array.
cFrontGets a pointer to the element at the front of the array; the element is immutable.
BackGets a pointer to the element at the back of the array.
cBackGets a pointer to the element at the back of the array; the element is immutable.
IndexGets a pointer to the element at index n in the array.
cIndexGets a pointer to the element at index n in the array; the element is immutable.
Insertion/Erasure
PushBackInserts an element value at the back of the array.
PopBackErases the element at the back of the array.
InsertInserts an element before a certain position in the array.
InsertInserts a range of elements before a certain position in the array.
InsertInserts a number of copies of an element value before a certain position in the array.
EraseRemoves an element from the array.
EraseRemoves a range of elements from the array.
ClearRemoves all of the elements in the array.
Miscellaneous
Swap_Swaps the contents of the array with another in constant time.

License

Copyright © 2007-2011, FreeBASIC Extended Library Development Group

Distributed under the FreeBASIC Extended Library Group license.  See accompanying file LICENSE.txt or copy at http://code.google.com/p/fb-extended-lib/wiki/License

Macros

fbext_Array

# define fbext_Array(
   targs_
) fbext_TemplateID( Array, targs_, fbext_Array_DefaultTArgs() )

This macro expands to the name of the fbext_Array type.  It expects a single parameter which is a sequence of template arguments, which are described below.  Note that this is an unqualified name (no “ext.” prefix). elem 0: T_ - Element type stored in the array. elem 1: Allocator_ - Name of allocator template.  If not specified, fbext_Allocator is used.

fbext_Array_Declare

# macro fbext_Array_Declare(T_,
Allocator_)

This macro expands to the definition of the fbext_Array class.  It is not intented to be used directly, but through a call to fbext_TDeclare.

ext.fbext_Array(( T_)( Allocator_))

A generic variable-length array.

Summary
Construction/Destruction/Assignment
default constructorConstructs an empty array (having zero elements).
copy constructorConstructs an array consisting of copies of the elements from another.
repeat constructorConstructs an array consisting of copies of the default value.
repeat constructorConstructs an array consisting of copies of an element value.
ranged constructorConstructs an array from a copy of a range of elements.
destructorDestroys the array.
copy operator letCopy assigns to the array from another.
Capacity
SizeGets the number of elements in the array.
CapacityGets the maximum number of elements the array can store without requiring additional memory.
EmptyDetermines if the array contains elements or not.
ReserveEnsures that the capacity of the array is at least n.
ResizeChanges the size of the array to newsize number of elements.
ResizeChanges the size of the array to newsize number of elements
Iterators
BeginGets an iterator to the element at the front of the array.
cBeginGets an iterator to the element at the front of the array; the element in immutable.
End_Gets an iterator to the element at the back of the array.
cEndGets an iterator to the element at the back of the array; the element is immutable.
Elements
FrontGets a pointer to the element at the front of the array.
cFrontGets a pointer to the element at the front of the array; the element is immutable.
BackGets a pointer to the element at the back of the array.
cBackGets a pointer to the element at the back of the array; the element is immutable.
IndexGets a pointer to the element at index n in the array.
cIndexGets a pointer to the element at index n in the array; the element is immutable.
Insertion/Erasure
PushBackInserts an element value at the back of the array.
PopBackErases the element at the back of the array.
InsertInserts an element before a certain position in the array.
InsertInserts a range of elements before a certain position in the array.
InsertInserts a number of copies of an element value before a certain position in the array.
EraseRemoves an element from the array.
EraseRemoves a range of elements from the array.
ClearRemoves all of the elements in the array.
Miscellaneous
Swap_Swaps the contents of the array with another in constant time.

Construction/Destruction/Assignment

default constructor

Constructs an empty array (having zero elements).

copy constructor

Constructs an array consisting of copies of the elements from another.

Parameters

xan array containing the elements to copy.

repeat constructor

Constructs an array consisting of copies of the default value.

Parameters

nthe number of copies to make.

repeat constructor

Constructs an array consisting of copies of an element value.

Parameters

nthe number of copies to make.
valuethe value to copy.

ranged constructor

Constructs an array from a copy of a range of elements.

Parameters

firstan iterator to the first element in a range.
lastan iterator to one-passed the last element in a range.

destructor

declare destructor ( )

Destroys the array.

copy operator let

Copy assigns to the array from another.

Parameters

xThe array to copy.

Capacity

Size

declare const function Size ( ) as SizeType

Gets the number of elements in the array.

Returns

Returns the number of elements.

Capacity

declare const function Capacity ( ) as SizeType

Gets the maximum number of elements the array can store without requiring additional memory.

Returns

Returns the number of elements.

Empty

declare const function Empty ( ) as bool

Determines if the array contains elements or not.

Returns

Returns true if the array has zero elements, false otherwise.

Reserve

declare sub Reserve (byval n as SizeType)

Ensures that the capacity of the array is at least n.  If n is greater than Capacity, then the storage is reallocated.

Parameters

nthe requested minimum capacity.

Resize

declare sub Resize (byval newsize as SizeType)

Changes the size of the array to newsize number of elements.

Parameters

newsizethe requested new size.

Resize

declare sub Resize (byval newsize as SizeType,
byref value as const fbext_TypeName( T_))

Changes the size of the array to newsize number of elements

Parameters

newsizethe requested new size.
valueif newsize is greater than Size, the new elements are copied from this value.

Iterators

Begin

declare function Begin () as typeof(Iterator)

Gets an iterator to the element at the front of the array.

Returns

Returns an iterator to the element.

cBegin

declare const function cBegin () as typeof(IteratorToConst)

Gets an iterator to the element at the front of the array; the element in immutable.

Returns

Returns an iterator to the element.

End_

declare function End_ () as typeof(Iterator)

Gets an iterator to the element at the back of the array.

Returns

Returns an iterator to the element.

cEnd

declare const function cEnd () as typeof(IteratorToConst)

Gets an iterator to the element at the back of the array; the element is immutable.

Returns

Returns an iterator to the element.

Elements

Front

declare function Front () as fbext_TypeName( T_) ptr

Gets a pointer to the element at the front of the array.

Returns

Returns a pointer to the element.

cFront

declare const function cFront () as const fbext_TypeName( T_) ptr

Gets a pointer to the element at the front of the array; the element is immutable.

Returns

Returns a pointer to the element.

Back

declare function Back () as fbext_TypeName( T_) ptr

Gets a pointer to the element at the back of the array.

Returns

Returns a pointer to the element.

cBack

declare const function cBack () as const fbext_TypeName( T_) ptr

Gets a pointer to the element at the back of the array; the element is immutable.

Returns

Returns a pointer to the element.

Index

declare function Index (byval n as SizeType) as fbext_TypeName( T_) ptr

Gets a pointer to the element at index n in the array.

Parameters

nthe index of the elements to retrieve.

Returns

Returns a pointer to the element.  If n >= <Size>() then the behavior is undefined.

cIndex

declare const function cIndex (
   byval n as SizeType
) as const fbext_TypeName( T_) ptr

Gets a pointer to the element at index n in the array; the element is immutable.

Parameters

nthe index of the elements to retrieve.

Returns

Returns a pointer to the element.  If n >= <Size>() then the behavior is undefined.

Insertion/Erasure

PushBack

declare sub PushBack (byref value as const fbext_TypeName( T_))

Inserts an element value at the back of the array.

Parameters

valuethe value to insert.

PopBack

declare sub PopBack ( )

Erases the element at the back of the array.

Insert

declare function Insert (
   byval position as typeof(Iterator),
   byref value as const fbext_TypeName( T_)
) as typeof(Iterator)

Inserts an element before a certain position in the array.

Parameters

positionan iterator to an element in the array; the new element will be added before this element.
valuethe value to add.

Returns

Returns an iterator to the newly inserted element.

Insert

declare sub Insert (byval position as typeof(Iterator),
byval first as typeof(IteratorToConst),
byval last as typeof(IteratorToConst))

Inserts a range of elements before a certain position in the array.

Parameters

positionan iterator to an element in the array; the new elements will be added before this element.
firstan iterator to the beginning of a range of elements to add.
lastan iterator to one-passed the last element of the range.

Insert

declare sub Insert (byval position as typeof(Iterator),
byval n as SizeType,
byref value as const fbext_TypeName( T_))

Inserts a number of copies of an element value before a certain position in the array.

Parameters

positionan iterator to an element in the array; the new elements will be added before this element.
nthe number of copies to insert.
xthe value to insert.

Erase

declare function Erase (byval position as typeof(Iterator)) as typeof(Iterator)

Removes an element from the array.

Parameters

positionan iterator to the element to be removed.

Returns

Returns an iterator to the next element in the array, or `this.End_()` if there are no such elements.

Erase

declare function Erase (byval first as typeof(Iterator),
byval last as typeof(Iterator)) as typeof(Iterator)

Removes a range of elements from the array.

Parameters

firstan iterator to the first element to be removed.
lastan iterator to one-passed the last element to be removed.

Returns

Returns an iterator to the next element in the array, or `this.End_()` if there are no such elements.

Clear

declare sub Clear ( )

Removes all of the elements in the array.

Miscellaneous

Swap_

declare sub Swap_ (byref x as typeof( fbext_Array(( T_)( Allocator_)) ))

Swaps the contents of the array with another in constant time.

Parameters

xthe array to swap.
# define fbext_Array(
   targs_
) fbext_TemplateID( Array, targs_, fbext_Array_DefaultTArgs() )
This macro expands to the name of the fbext_Array type.
# macro fbext_Array_Declare(T_,
Allocator_)
This macro expands to the definition of the fbext_Array class.
declare destructor ( )
Destroys the array.
declare const function Size ( ) as SizeType
Gets the number of elements in the array.
declare const function Capacity ( ) as SizeType
Gets the maximum number of elements the array can store without requiring additional memory.
declare const function Empty ( ) as bool
Determines if the array contains elements or not.
declare sub Reserve (byval n as SizeType)
Ensures that the capacity of the array is at least n.
declare sub Resize (byval newsize as SizeType)
Changes the size of the array to newsize number of elements.
declare function Begin () as typeof(Iterator)
Gets an iterator to the element at the front of the array.
declare const function cBegin () as typeof(IteratorToConst)
Gets an iterator to the element at the front of the array; the element in immutable.
declare function End_ () as typeof(Iterator)
Gets an iterator to the element at the back of the array.
declare const function cEnd () as typeof(IteratorToConst)
Gets an iterator to the element at the back of the array; the element is immutable.
declare function Front () as fbext_TypeName( T_) ptr
Gets a pointer to the element at the front of the array.
declare const function cFront () as const fbext_TypeName( T_) ptr
Gets a pointer to the element at the front of the array; the element is immutable.
declare function Back () as fbext_TypeName( T_) ptr
Gets a pointer to the element at the back of the array.
declare const function cBack () as const fbext_TypeName( T_) ptr
Gets a pointer to the element at the back of the array; the element is immutable.
declare function Index (byval n as SizeType) as fbext_TypeName( T_) ptr
Gets a pointer to the element at index n in the array.
declare const function cIndex (
   byval n as SizeType
) as const fbext_TypeName( T_) ptr
Gets a pointer to the element at index n in the array; the element is immutable.
declare sub PushBack (byref value as const fbext_TypeName( T_))
Inserts an element value at the back of the array.
declare sub PopBack ( )
Erases the element at the back of the array.
declare function Insert (
   byval position as typeof(Iterator),
   byref value as const fbext_TypeName( T_)
) as typeof(Iterator)
Inserts an element before a certain position in the array.
declare function Erase (byval position as typeof(Iterator)) as typeof(Iterator)
Removes an element from the array.
declare sub Clear ( )
Removes all of the elements in the array.
declare sub Swap_ (byref x as typeof( fbext_Array(( T_)( Allocator_)) ))
Swaps the contents of the array with another in constant time.