#include <evo/ptrlist.h>

Detailed Description

template<class T, class TSize = SizeT>
class evo::PtrList< T, TSize >

Sequential list of managed pointers with random access.

Template Parameters

T	Type to use – an item type will be `T` (`Item`), a pointer to items type will be `T` (`Item`)
TSize	Size type to use for size/index values (must be unsigned integer) – default: SizeT

Features

This is similar to List but is specialized to hold an array of managed pointers, with PtrList:
- Sharing (without external references) is supported, but Slicing is not supported
- The size and capacity of the list are the same – no extra capacity is allocated for adding new items
- The size is the number of items allocated, any of which may be null
- Item pointers are automatically freed (if not NULL)
- Iterators skip null items and only return non-null items
Some methods have a read-only (const) version and mutable version with suffix "M" – example: item() and itemM()
operator[]() is read-only – use operator()() or get() for mutable access
Create items with get()
Supports Sharing – however immutable data will be copied

C++11:

Range-based for loop – see STL Compatibility
PtrList<int> list;
for (auto num : list.asconst()) {
}
Initialization lists
PtrList<int> list = {1, 2, 3};
Move semantics

Iterators

PtrList<>::Iter – Read-Only Iterator (IteratorRa)
PtrList<>::IterM – Mutable Iterator (IteratorRa)

Constructors

PtrList()
PtrList(const ThisType&)
PtrList(std::initializer_list<T>) [C++11]
PtrList(ThisType&&) [C++11]

Read Access

size()
- null(), empty()
- shared()
data()
- item()
- operator[]()
- first(), last(), iend()
compare()
- operator==()
- operator!=()
cbegin(), cend()
- begin() const, end() const
find()
- findr()

Modifiers

Classes
struct	Header
	List data header. More...

Public Types
typedef void	EvoContainerType

typedef T *	Item
	Item type (pointer to Value) More...

typedef IteratorRa< ThisType >::Const	Iter
	Iterator (const) - IteratorRa. More...

typedef IteratorRa< ThisType >	IterM
	Iterator (mutable) - IteratorRa. More...

typedef Size	Key
	Key type (item index) More...

typedef TSize	Size
	List size integer type More...

typedef PtrList< T, Size >	ThisType
	This list type. More...

typedef T	Value
	Value type (Item dereferenced, same as T) More...

Public Member Functions
	PtrList ()
	Default constructor sets as null. More...

	PtrList (const ThisType &data)
	Copy constructor. More...

	PtrList (std::initializer_list< T > init)
	Sequence constructor (C++11). More...

	PtrList (ThisType &&src)
	Move constructor (C++11). More...

	~PtrList ()
	Destructor. More...

const ThisType &	asconst () const
	Explicitly use a const reference to this. More...

IterM	begin ()
	Get iterator at first item (mutable). More...

Iter	begin () const
	Get iterator at first item (const). More...

Iter	cbegin () const
	Get iterator at first item (const). More...

Iter	cend () const
	Get iterator at end (const). More...

ThisType &	clear ()
	Clear by removing all items. More...

int	compare (const ThisType &data) const
	Comparison. More...

ThisType &	copy (const ThisType &data)
	Set as full (unshared) copy using data pointer (modifier). More...

const Item *	data () const
	Get data pointer for direct access (const). More...

Item *	dataM ()
	Get data pointer (mutable). More...

bool	empty () const
	Get whether empty. More...

IterM	end ()
	Get iterator at end. More...

Iter	end () const
	Get iterator at end (const). More...

Key	find (const Value &value, Key start=0, Key end=END) const
	Find first occurrence of item with forward search. More...

Key	findr (const T &value, Key start=0, Key end=END) const
	Find last occurrence of item with reverse search. More...

const Item	first () const
	Get first non-null item (const). More...

Value &	get (const Key &key, bool *created=NULL)
	Get item value for key, creating if needed (mutable). More...

Item	getitem (const Key &key, bool *created=NULL)
	Get item for key, creating if needed (mutable). More...

Key	iend (Size offset=0) const
	Get index for last item position using offset. More...

const Item	item (Key index) const
	Get item at position (const). More...

Item	itemM (Key index)
	Get item at position (mutable). More...

const Item	last () const
	Get last non-null item (const). More...

bool	null () const
	Get whether null. More...

bool	operator!= (const ThisType &data) const
	Inequality operator. More...

Item	operator() (Key index)
	Get item at position (mutable). More...

ThisType &	operator= (ThisType &&src)
	Move assignment operator (C++11). More...

ThisType &	operator= (const ThisType &data)
	Assignment operator. More...

bool	operator== (const ThisType &data) const
	Equality operator. More...

const Item	operator[] (Key index) const
	Get item at position (const). More...

ThisType &	remove (Key key)
	Remove item and set as null (modifier). More...

ThisType &	resize (Size newsize)
	Resize while preserving existing data (modifier). More...

ThisType &	resizemin (Size minsize)
	Resize to minimum size while preserving existing data (modifier). More...

ThisType &	set ()
	Set as null and empty. More...

ThisType &	set (const ThisType &data)
	Set from another list. More...

ThisType &	setempty ()
	Set as empty but not null. More...

bool	shared () const
	Get whether shared. More...

Size	size () const
	Get list size. More...

void	swap (ThisType &list)
	Swap with another list. More...

ThisType &	unshare ()
	Make sure data is not shared by allocating new buffer if needed (modifier). More...

Size	used () const
	Get list used size, number of non-null items. More...

Protected Attributes
Item *	data_
	Data pointer, NULL if null, can be 1 if empty (size_=0) More...

Header *	header_
	Data header pointer, NULL if no buffer allocated. More...

Size	size_
	Data size (same as header.size), 0 if empty. More...

Member Typedef Documentation

◆ EvoContainerType

typedef void EvoContainerType

◆ Item

typedef T* Item

Item type (pointer to Value)

◆ Iter

typedef IteratorRa<ThisType>::Const Iter

Iterator (const) - IteratorRa.

◆ IterM

typedef IteratorRa<ThisType> IterM

Iterator (mutable) - IteratorRa.

◆ Key

typedef Size Key

Key type (item index)

◆ Size

typedef TSize Size

List size integer type

◆ ThisType

typedef PtrList<T,Size> ThisType

This list type.

◆ Value

typedef T Value

Value type (Item dereferenced, same as T)

Constructor & Destructor Documentation

◆ PtrList() [1/4]

PtrList ( )

inline

Default constructor sets as null.

◆ PtrList() [2/4]

PtrList ( const ThisType & data )

inline

Copy constructor.

Makes shared copy if possible – see Sharing

Parameters

data	Data to copy

◆ ~PtrList()

~PtrList ( )

inline

Destructor.

◆ PtrList() [3/4]

PtrList ( std::initializer_list< T > init )

inline

Sequence constructor (C++11).

Parameters

init	Initializer list, passed as comma-separated values in braces `{ }`

◆ PtrList() [4/4]

PtrList ( ThisType && src )

inline

Move constructor (C++11).

Parameters

src	Source to move

Member Function Documentation

◆ asconst()

const ThisType& asconst ( ) const

inline

Explicitly use a const reference to this.

This is useful to force using this as const without casting

Returns: This

◆ begin() [1/2]

IterM begin ( )

inline

Get iterator at first item (mutable).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
cbegin() is more efficient, since this effectively calls unshare() to make items mutable

Returns: Iterator at first item, or at end position if empty

See also: IterM, end(), cbegin(), cend()

◆ begin() [2/2]

Iter begin ( ) const

inline

Get iterator at first item (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly

Returns: Iterator at first item, or at end position if empty

See also: end() const, cbegin()

◆ cbegin()

Iter cbegin ( ) const

inline

Get iterator at first item (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly

Returns: Iterator at first item, or at end position if empty

See also: Iter, cend(), begin(), end()

◆ cend()

Iter cend ( ) const

inline

Get iterator at end (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
This really just creates an empty iterator

Returns: Iterator at end position

See also: Iter, cbegin(), begin(), end()

◆ clear()

ThisType& clear ( )

inline

Clear by removing all items.

Does not set list as null – null status is unchanged
This does not change list size, only sets all items as null

Returns: This

◆ compare()

int compare ( const ThisType & data ) const

inline

Comparison.

Parameters

data	Data to compare to

Returns: Result (<0 if this is less, 0 if equal, >0 if this is greater)

◆ copy()

ThisType& copy ( const ThisType & data )

inline

Set as full (unshared) copy using data pointer (modifier).

Effectively calls unshare()

Parameters

data	Data to copy

Returns: This

◆ data()

const Item* data ( ) const

inline

Get data pointer for direct access (const).

Caution: Calling any modifier/mutable method like unshare() after this may (will) invalidate the returned pointer
Result is only valid if size() > 0, otherwise may be NULL or an invalid internal value

Returns: Data pointer as read-only, NULL/invalid if size() is 0 (const)

◆ dataM()

Item* dataM ( )

inline

Get data pointer (mutable).

Calls unshare()
Caution: Calling any modifier method like resize() after this may (will) invalidate the returned pointer
For best performance, reuse returned pointer for repeated access, or use data() instead for read-only access

Returns: Data pointer (mutable).

◆ empty()

bool empty ( ) const

inline

Get whether empty.

Empty when size() is 0 or all items are null

Returns: Whether empty

◆ end() [1/2]

IterM end ( )

inline

Get iterator at end.

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
This really just creates an empty iterator

Returns: Iterator at end position

See also: IterM, begin(), cbegin(), cend()

◆ end() [2/2]

Iter end ( ) const

inline

Get iterator at end (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
This really just creates an empty iterator

Returns: Iterator at end position

See also: begin() const, cend()

◆ find()

Key find	(	const Value &	value,
		Key	start = `0`,
		Key	end = `END`
	)		const

inline

Find first occurrence of item with forward search.

This searches non-null items for given value, using item operator==() for comparisons
Search stops before reaching end index or end of list

Parameters

value	Value to find
start	Starting index for search
end	End index for search, END for end of list

Returns: Found item index or NONE if not found

◆ findr()

Key findr	(	const T &	value,
		Key	start = `0`,
		Key	end = `END`
	)		const

inline

Find last occurrence of item with reverse search.

This searches non-null items for given value, using item operator==() for comparisons
Same as find() but does reverse search starting right before end index, or at last item if end of list
As with find(), item at end index is not checked

Parameters

value	Item to find
start	Starting index for search range – last item checked in reverse search
end	End index for search range (reverse search starting point), END for end of list

Returns: Found item index or NONE if not found

◆ first()

const Item first ( ) const

inline

Get first non-null item (const).

For best performance store result rather than calling repeatedly
Caution: Any operation that changes

Returns: First item pointer, NULL if empty or all items null

◆ get()

Value& get	(	const Key &	key,
		bool *	created = `NULL`
	)

inline

Get item value for key, creating if needed (mutable).

Calls unshare()
Item is created with default value if not found
This grows list as needed using resize() if item key is too small to fit

Parameters

key	Key (index) to use
created	Stores whether new item was created, if not NULL

Returns: Value reference for key

◆ getitem()

Item getitem	(	const Key &	key,
		bool *	created = `NULL`
	)

inline

Get item for key, creating if needed (mutable).

Calls unshare()
Item is created with default value if not found
This grows list as needed using resize() if item key is too small to fit

Parameters

key	Key (index) to use
created	Stores whether new item was created, if not NULL

Returns: Item pointer for key

◆ iend()

Key iend ( Size offset = 0 ) const

inline

Get index for last item position using offset.

This simplifies math when computing an index from last item position
This uses the formula: iend = size - 1 - offset

Parameters

offset Offset from end, 0 for last item, 1 for second-last, etc

Returns: Resulting index, END if offset out of bounds

◆ item()

const Item item ( Key index ) const

inline

Get item at position (const).

This is a pointer list so the given item can be null
Caution: Results are undefined if index is out of bounds

Parameters

index Item index

Returns: Given item as read-only pointer, NULL if item is null (const)

◆ itemM()

Item itemM ( Key index )

inline

Get item at position (mutable).

Calls unshare()
This is a pointer list so the given item can be null
This doesn't allow modifying the stored pointer, for that use get()
For best performance, use dataM() once for repeated item access, or item() for read-only access
Caution: Results are undefined if index is out of bounds – though index is checked with assert()

Parameters

index Item index

Returns: Given item pointer, NULL if item is null (mutable)

◆ last()

const Item last ( ) const

inline

Get last non-null item (const).

The last non-null item does not necessarilly mean the very last item in list
For best performance store result rather than calling repeatedly

Returns: Last item pointer, NULL if empty or all items null

◆ null()

bool null ( ) const

inline

Get whether null.

Always empty when null

Returns: Whether null

◆ operator!=()

bool operator!= ( const ThisType & data ) const

inline

Inequality operator.

Items are compared with operator==()

Parameters

data	Data to compare to

Returns: Whether inequal

◆ operator()()

Item operator() ( Key index )

inline

Get item at position (mutable).

Calls unshare()
This is a pointer list so the given item can be null
This doesn't allow modifying the stored pointer, for that use get()
For best performance, use dataM() once for repeated item access, or item() for read-only access
Caution: Results are undefined if index is out of bounds – though index is checked with assert()

Parameters

index Item index

Returns: Given item pointer, NULL if item is null (mutable)

◆ operator=() [1/2]

ThisType& operator= ( ThisType && src )

inline

Move assignment operator (C++11).

Parameters

src	Source to move

Returns: This

◆ operator=() [2/2]

ThisType& operator= ( const ThisType & data )

inline

Assignment operator.

Makes shared copy if possible – see Sharing

Parameters

data	Data to copy

Returns: This

◆ operator==()

bool operator== ( const ThisType & data ) const

inline

Equality operator.

Items are compared with operator==()

Parameters

data	Data to compare to

Returns: Whether equal

◆ operator[]()

const Item operator[] ( Key index ) const

inline

Get item at position (const).

This is a pointer list so the given item can be null
Caution: Results are undefined if index is out of bounds

Parameters

index Item index

Returns: Given item as read-only pointer, NULL if item is null (const)

◆ remove()

ThisType& remove ( Key key )

inline

Remove item and set as null (modifier).

Effectively calls unshare()
The removed item is set as null – no change to list size

Parameters

key	Item key (index) to remove

Returns: This

◆ resize()

ThisType& resize ( Size newsize )

inline

Resize while preserving existing data (modifier).

This adds/removes items as needed until given size is reached
Effectively calls unshare()
Advanced: See advBuffer() for getting writable pointer to buffer
Advanced: See advResize() for best performance in certain POD cases

Parameters

newsize New size as item count

Returns: This

◆ resizemin()

ThisType& resizemin ( Size minsize )

inline

Resize to minimum size while preserving existing data (modifier).

This calls resize() if current size is smaller than minimum

Parameters

minsize Minimum size as item count

Returns: This

◆ set() [1/2]

ThisType& set ( )

inline

Set as null and empty.

Returns: This

◆ set() [2/2]

ThisType& set ( const ThisType & data )

inline

Set from another list.

Makes shared copy if possible – see Sharing

Parameters

data	Data to set/copy

Returns: This

◆ setempty()

ThisType& setempty ( )

inline

Set as empty but not null.

Returns: This

◆ shared()

bool shared ( ) const

inline

Get whether shared.

List is shared when a buffer is allocated and shared (reference count > 1)

Returns: Whether shared

◆ size()

Size size ( ) const

inline

Get list size.

Returns: Size as item count

◆ swap()

void swap ( ThisType & list )

inline

Swap with another list.

This swaps internal state directly for best performance

Parameters

list	List to swap with

◆ unshare()

ThisType& unshare ( )

inline

Make sure data is not shared by allocating new buffer if needed (modifier).

Use to make buffer unique (not shared) and writable (when not empty)
This is called automatically by mutable/modifier methods
This does nothing if empty or not shared

Returns: This

◆ used()

Size used ( ) const

inline

Get list used size, number of non-null items.

Returns: Used size as item count

Member Data Documentation

◆ data_

Item* data_

protected

Data pointer, NULL if null, can be 1 if empty (size_=0)

◆ header_

Header* header_

protected

Data header pointer, NULL if no buffer allocated.

◆ size_

Size size_

protected

Data size (same as header.size), 0 if empty.

The documentation for this class was generated from the following file:

evo/ptrlist.h

Detailed Description

template<class T, class TSize = SizeT> class evo::PtrList< T, TSize >

Classes

Public Types

Public Member Functions

Protected Attributes

Member Typedef Documentation

◆ EvoContainerType

◆ Item

◆ Iter

◆ IterM

◆ Key

◆ Size

◆ ThisType

◆ Value

Constructor & Destructor Documentation

◆ PtrList() [1/4]

◆ PtrList() [2/4]

◆ ~PtrList()

◆ PtrList() [3/4]

◆ PtrList() [4/4]

Member Function Documentation

◆ asconst()

◆ begin() [1/2]

◆ begin() [2/2]

◆ cbegin()

◆ cend()

◆ clear()

◆ compare()

◆ copy()

◆ data()

◆ dataM()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ find()

◆ findr()

◆ first()

◆ get()

◆ getitem()

◆ iend()

◆ item()

◆ itemM()

◆ last()

◆ null()

◆ operator!=()

◆ operator()()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator[]()

◆ remove()

◆ resize()

◆ resizemin()

◆ set() [1/2]

◆ set() [2/2]

◆ setempty()

◆ shared()

◆ size()

◆ swap()

◆ unshare()

◆ used()

Member Data Documentation

◆ data_

◆ header_

◆ size_

template<class T, class TSize = SizeT>
class evo::PtrList< T, TSize >