rcolyer.net
RC Lib  Version 202403231100
Public Member Functions | Static Public Attributes | Friends | List of all members
RC::Data1D< T > Class Template Reference

A bounds-safe one-dimensional vector-like structure. More...

#include <Data1D.h>

Public Member Functions

 Data1D (size_t d_size)
 Constructor which sets the initial size to d_size. More...
 
 Data1D (const Data1D< T > &copy)
 Copy constructor that copies all elements. More...
 
 Data1D (const std::initializer_list< T > &new_data)
 Initializer list constructor, for initializing with bracketed data. More...
 
 Data1D (Data1D< T > &&other)
 Move constructor that reassigns all the data to this Data1D. More...
 
 Data1D (size_t d_size, T *new_data, bool auto_delete=false)
 Efficiently wraps in-place C-pointer data in a bounds-safe container. More...
 
void Delete ()
 Delete all the elements and free all allocated memory.
 
 ~Data1D ()
 Deletes all contents upon destruction. More...
 
bool IsEmpty () const
 Returns true if there are no elements / the size is 0.
 
template<class T2 >
size_t Find (const T2 &elem, size_t start_at=0) const
 Returns the first index at or after start_at for which the data equals elem. More...
 
template<class T2 >
bool Contains (const T2 &elem) const
 Returns true if at least one entry equals elem.
 
bool Check (const size_t x) const
 Check if index x is in bounds. More...
 
void Assert (const size_t x) const
 Throws an ErrorMsgBounds exception if x is out of bounds. More...
 
void Reserve (const size_t reserve_size)
 Reserve storage without resizing the array. More...
 
void Resize (const size_t resize_size)
 Resize the array, reallocating if necessary. More...
 
void SetOffset (const size_t new_offset)
 Set a new offset position for index 0. More...
 
void SetRange (const size_t new_offset, const size_t new_size)
 Set a new offset and data size, resizing if necessary. More...
 
T * Raw () const
 Access a raw unprotected C-pointer to the enclosed data. More...
 
size_t size () const
 Returns the current number of elements.
 
size_t TypeSize () const
 Returns the size of this Data1D's type.
 
size_t ByteSize () const
 Returns the current size in bytes.
 
size_t reserved () const
 Returns the number of elements for which space is reserved.
 
size_t ByteReserved () const
 Returns the current allocated storage in bytes.
 
size_t GetOffset () const
 Returns the current offset for index 0. More...
 
Data1D Copy (const size_t pos=0, const size_t amnt=npos) const
 Creates a duplicate copy of the contents, with up to amnt elements from pos.
 
template<class T2 >
Data1DCopyFrom (const Data1D< T2 > &other)
 Copy data from any type with a compatible assignment operator. More...
 
template<class T2 >
Data1DCopyFrom (const Data1D< T2 > &other, size_t pos, size_t num_elem=npos)
 assignment operator. More...
 
template<class T2 >
void CopyAt (const size_t pos, const Data1D< T2 > &other)
 Overwrite a range of data using all data from any compatible type, expanding if necessary. More...
 
template<class T2 >
void CopyAt (const size_t pos, const Data1D< T2 > &other, const size_t other_start, const size_t amnt=npos)
 Overwrite a range of data from any compatible type, expanding if necessary. More...
 
void CopyData (const size_t dest, const size_t source, const size_t amnt=npos)
 Copy data from any location in this Data1D to another location, handling overlap automatically. More...
 
Data1Doperator= (const Data1D &other)
 Assignment operator which copies all contents from other, respecting offsets. More...
 
Data1Doperator= (Data1D &&other)
 Assignment operator which copies all contents from other, respecting offsets. More...
 
template<class T2 >
Data1D< T2 > Cast ()
 Returns a new array with all the elements of this array assigned to type T2. More...
 
template<class Conv >
auto CastWith (Conv converter) -> Data1D< decltype(converter(*data))>
 Returns a new array with all the elements of this array converted to another type by converter.
 
template<class T2 >
Data1D< T2 > Reinterpret () const
 Returns a new array with the raw data of this Data1D reinterpreted as type T2. More...
 
RAIter< Data1D< T >, T > begin ()
 Copy data from any other object of a type with a compatible. More...
 
const RAIter< Data1D< T >, T > begin () const
 Const version of begin.
 
RAIter< Data1D< T >, T > end ()
 Return a bounds-checked random-access iterator starting just past the last element. More...
 
const RAIter< Data1D< T >, T > end () const
 Const version end.
 
T & operator[] (size_t x)
 Bounds-checked access of the element at index x from the offset (default 0). More...
 
T & operator() (size_t x)
 Identical to Data1D::operator[].
 
const T & operator[] (size_t x) const
 Const version of Data1D::operator[].
 
const T & operator() (size_t x) const
 Const version of Data1D::operator[].
 
T & At (size_t x)
 Identical to Data1D::operator[].
 
const T & At (size_t x) const
 Const version of Data1D::operator[].
 
T & Last ()
 Provides the last element. More...
 
const T & Last () const
 Const version of last()
 
void Zero ()
 Sets all elements equal to 0. More...
 
void ZeroRange (const size_t start, const size_t end=npos)
 Like Zero() but operating only between index start and end, inclusive. More...
 
void Sort ()
 Sorts the elements according to T::operator< in N*log2(N) time.
 
template<class Comparator >
void Sort (Comparator comp)
 Sorts the elements according to the binary comparitor comp. More...
 
void Shuffle ()
 Randomizes the order of all the elements. More...
 
void URandShuffle ()
 Randomizes the order of all the elements using /dev/urandom. More...
 
T * Extract ()
 Removes ownership of the contained data from the Data1D object. More...
 
void Crop ()
 Reduces memory consumption to only that necessary for size() elements. More...
 
void Clear ()
 Identical to Delete().
 
void Append (const T &newT)
 Add an element to the end, expanding if necessary. More...
 
template<class T2 >
void AppendFrom (const Data1D< T2 > &other)
 Append data from any type with a compatible assignment operator. More...
 
void Append (const Data1D &other)
 Appends all elements in other to the end, expanding if necessary. More...
 
void ExpandSet (size_t pos, const T &newT)
 Assign newT to index pos, expanding if necessary to reach that index. More...
 
void Insert (size_t pos, const T &newT)
 Inserts newT at position pos, shifting the other elements. More...
 
void Remove (size_t pos)
 Removes the element at pos from the array, shrinking the size. More...
 
Data1D< T > & operator+= (const T &newT)
 Add an element to the end, expanding if necessary. More...
 
Data1D< T > & operator+= (const Data1D &other)
 Appends all elements in other to the end, expanding if necessary. More...
 
Data1D< T > operator+ (const Data1D &other) const
 Create a new array from this Data1D concatenated with other after it.
 
void ToLilEndian ()
 Convert endianness of all elements if needed, for supported types.
 
void FromLilEndian ()
 Convert endianness of all elements if needed, for supported types.
 
void ToBigEndian ()
 Convert endianness of all elements if needed, for supported types.
 
void FromBigEndian ()
 Convert endianness of all elements if needed, for supported types.
 
template<class AnyValidType >
bool operator== (const Data1D< AnyValidType > &other) const
 Comparison operator for all elements. More...
 
template<class AnyValidType >
bool operator< (const Data1D< AnyValidType > &other) const
 Returns true if the first different element for this is less than for other. More...
 
template<class AnyValidType >
bool operator!= (const AnyValidType &other) const
 True if not equal.
 
template<class AnyValidType >
bool operator> (const AnyValidType &other) const
 True if other is less than this object.
 
template<class AnyValidType >
bool operator<= (const AnyValidType &other) const
 True if other is not less than this object.
 
template<class AnyValidType >
bool operator>= (const AnyValidType &other) const
 True if this object is not less than other.
 
template<class T2 >
void Get (T2 &store_at, size_t index_T) const
 Direct raw data extraction of type T2 at index. More...
 
template<class T2 >
T2 Get (size_t index_T=0) const
 Identical to the Get which receives store_at, but this returns the extracted value.
 
template<class T2 >
void Get (Data1D< T2 > &store_at, size_t index_T=0) const
 Fills the array store_at to its current size with raw assigned data of type T2 from this Data1D. More...
 
template<class T2 >
Data1D< T > & Put (const T2 &read_from, size_t index_T)
 Direct raw data insertion of type T2 at index. More...
 
template<class T2 >
Data1D< T > & Put (const Data1D< T2 > &read_from, size_t index_T=0)
 Like Get for a T2 type, but places sequential packed data. More...
 

Static Public Attributes

static const size_t npos = size_t(-1)
 The largest possible value of size_t.
 

Friends

template<class T2 >
void swap (Data1D< T2 > &a, Data1D< T2 > &b)
 Efficiently swap all the contents of a and b.
 

Detailed Description

template<class T>
class RC::Data1D< T >

A bounds-safe one-dimensional vector-like structure.

It provides efficient resizing and offsets, as well as convenience functions for assignments and comparisons. It also provides bounds-safe iterators. Note: Non-POD classes stored in Data1D containers must have a default constructor with default values or no arguments, which is necessary for efficient resizing. This requirement also permits safe use of offsets and temporary shrinking, because all allocated space contains defined data with properly constructed objects.

See also
Data2D
Data3D

Constructor & Destructor Documentation

◆ Data1D() [1/5]

template<class T >
RC::Data1D< T >::Data1D ( size_t  d_size)
inlineexplicit

Constructor which sets the initial size to d_size.

Parameters
d_sizeThe initial number of elements.

◆ Data1D() [2/5]

template<class T >
RC::Data1D< T >::Data1D ( const Data1D< T > &  copy)
inline

Copy constructor that copies all elements.

Parameters
copyA source Data1D from which elements should be copied.

◆ Data1D() [3/5]

template<class T >
RC::Data1D< T >::Data1D ( const std::initializer_list< T > &  new_data)
inline

Initializer list constructor, for initializing with bracketed data.

Parameters
new_dataAn initialization list of the form {elem1, elem2, ...}.

◆ Data1D() [4/5]

template<class T >
RC::Data1D< T >::Data1D ( Data1D< T > &&  other)
inline

Move constructor that reassigns all the data to this Data1D.

Parameters
otherA source Data1D from which elements should be moved.

◆ Data1D() [5/5]

template<class T >
RC::Data1D< T >::Data1D ( size_t  d_size,
T *  new_data,
bool  auto_delete = false 
)
inline

Efficiently wraps in-place C-pointer data in a bounds-safe container.

Note: If auto_delete=true, new_data must have been acquired with new[]. delete[] is used internally, so behavior may vary if it was acquired with new, malloc, or others.

Parameters
d_sizeThe initial number of elements.
new_dataC-pointer data to wrap.
auto_deleteShould the Data1D delete new_data upon destruction?

◆ ~Data1D()

template<class T >
RC::Data1D< T >::~Data1D ( )
inline

Deletes all contents upon destruction.

Note: For wrapped pointers, if auto_delete was false no deletion of the original data occurs.

Member Function Documentation

◆ Append() [1/2]

template<class T >
void RC::Data1D< T >::Append ( const Data1D< T > &  other)
inline

Appends all elements in other to the end, expanding if necessary.

Parameters
otherThe Data1D to append to the end.

◆ Append() [2/2]

template<class T >
void RC::Data1D< T >::Append ( const T &  newT)
inline

Add an element to the end, expanding if necessary.

Efficiency note: Expands by doubling for linear efficiency.

Parameters
newTThe new element to append to the end.
See also
Reserve

◆ AppendFrom()

template<class T >
template<class T2 >
void RC::Data1D< T >::AppendFrom ( const Data1D< T2 > &  other)
inline

Append data from any type with a compatible assignment operator.

Parameters
otherThe compatible Data1D from which data should be copied.

◆ Assert()

template<class T >
void RC::Data1D< T >::Assert ( const size_t  x) const
inline

Throws an ErrorMsgBounds exception if x is out of bounds.

Parameters
xThe index to check.

◆ begin()

template<class T >
RAIter<Data1D<T>,T> RC::Data1D< T >::begin ( )
inline

Copy data from any other object of a type with a compatible.

Return a bounds-checked random-access iterator starting at offset. Note that the iterator is revokable, meaning use of it will throw an exception if this Data1D is deleted.

Returns
A bounds-checked iterator.
See also
end()

◆ Cast()

template<class T >
template<class T2 >
Data1D<T2> RC::Data1D< T >::Cast ( )
inline

Returns a new array with all the elements of this array assigned to type T2.

See also
CopyFrom

◆ Check()

template<class T >
bool RC::Data1D< T >::Check ( const size_t  x) const
inline

Check if index x is in bounds.

Parameters
xThe index to check.
Returns
True if in bounds.

◆ CopyAt() [1/2]

template<class T >
template<class T2 >
void RC::Data1D< T >::CopyAt ( const size_t  pos,
const Data1D< T2 > &  other 
)
inline

Overwrite a range of data using all data from any compatible type, expanding if necessary.

Parameters
posThe offset in this Data1D to begin overwriting.
otherThe compatible Data1D to copy from.

◆ CopyAt() [2/2]

template<class T >
template<class T2 >
void RC::Data1D< T >::CopyAt ( const size_t  pos,
const Data1D< T2 > &  other,
const size_t  other_start,
const size_t  amnt = npos 
)
inline

Overwrite a range of data from any compatible type, expanding if necessary.

Parameters
posThe offset in this Data1D to begin overwriting.
otherThe compatible Data1D to copy from.
other_startThe offset in the other Data1D to begin copying from.
amntThe quantity of data to copy (automatically bounds-capped, defaults to all).

◆ CopyData()

template<class T >
void RC::Data1D< T >::CopyData ( const size_t  dest,
const size_t  source,
const size_t  amnt = npos 
)
inline

Copy data from any location in this Data1D to another location, handling overlap automatically.

Parameters
destThe offset in this Data1D to begin overwriting.
sourceThe offset in this Data1D to copy from.
amntThe quantity of data to copy (automatically bounds-capped, defaults to all).

◆ CopyFrom() [1/2]

template<class T >
template<class T2 >
Data1D& RC::Data1D< T >::CopyFrom ( const Data1D< T2 > &  other)
inline

Copy data from any type with a compatible assignment operator.

Parameters
otherThe compatible Data1D from which data should be copied.
Returns
A reference to this Data1D.

◆ CopyFrom() [2/2]

template<class T >
template<class T2 >
Data1D& RC::Data1D< T >::CopyFrom ( const Data1D< T2 > &  other,
size_t  pos,
size_t  num_elem = npos 
)
inline

assignment operator.

Note, to copy data around in the same Data1D, use CopyData.

Parameters
otherThe compatible Data1D from which data should be copied.
posThe offset in other to start copying from.
num_elemThe number of elements to copy.
Returns
A reference to this Data1D.

◆ Crop()

template<class T >
void RC::Data1D< T >::Crop ( )
inline

Reduces memory consumption to only that necessary for size() elements.

After calling, offset is 0 and points to the element indexed as 0 before calling. Efficiency note: This function may copy all elements if necessary for reallocating.

◆ end()

template<class T >
RAIter<Data1D<T>,T> RC::Data1D< T >::end ( )
inline

Return a bounds-checked random-access iterator starting just past the last element.

Note that the iterator is revokable, meaning use of it will throw an exception if this Data1D is deleted.

Returns
A bounds-checked iterator.
See also
begin()

◆ ExpandSet()

template<class T >
void RC::Data1D< T >::ExpandSet ( size_t  pos,
const T &  newT 
)
inline

Assign newT to index pos, expanding if necessary to reach that index.

Parameters
posThe index to which newT should be assigned.
newTThe new element to assign.

◆ Extract()

template<class T >
T* RC::Data1D< T >::Extract ( )
inline

Removes ownership of the contained data from the Data1D object.

Note, the array returned becomes the responsibility of the calling function, and should be delete[]'d externally! The pointer returned is as if the offset were set to 0 first. This Data1D is empty after calling this.

◆ Find()

template<class T >
template<class T2 >
size_t RC::Data1D< T >::Find ( const T2 &  elem,
size_t  start_at = 0 
) const
inline

Returns the first index at or after start_at for which the data equals elem.

Parameters
elemThe element to compare to each entry in this Data1D
start_atThe first index to begin comparing at.
Returns
The index of the item found, or npos if no matching data is found.

◆ Get() [1/2]

template<class T >
template<class T2 >
void RC::Data1D< T >::Get ( Data1D< T2 > &  store_at,
size_t  index_T = 0 
) const
inline

Fills the array store_at to its current size with raw assigned data of type T2 from this Data1D.

Usage example: Data1D<u64> x(1); Data1D<u8> y(8); x.Get(y,0); y.Get(x,0); If store_at has size 0, it resizes and grabs all available data.

◆ Get() [2/2]

template<class T >
template<class T2 >
void RC::Data1D< T >::Get ( T2 &  store_at,
size_t  index_T 
) const
inline

Direct raw data extraction of type T2 at index.

Bounds are checked. But if the raw data at the index is invalid for an assignment operation of type T2 (e.g., non-POD in ambiguous state), then behavior is undefined.

Parameters
store_atThe reference to which data is written.
index_TThe index from which the data is extracted.

◆ GetOffset()

template<class T >
size_t RC::Data1D< T >::GetOffset ( ) const
inline

Returns the current offset for index 0.

See also
SetOffset
SetRange

◆ Insert()

template<class T >
void RC::Data1D< T >::Insert ( size_t  pos,
const T &  newT 
)
inline

Inserts newT at position pos, shifting the other elements.

Efficiency note: For random positions, on average O(N).

Parameters
posThe index at which newT should be inserted.
newTThe new element to insert.

◆ Last()

template<class T >
T& RC::Data1D< T >::Last ( )
inline

Provides the last element.

Returns
A reference to the last element.

◆ operator+=() [1/2]

template<class T >
Data1D<T>& RC::Data1D< T >::operator+= ( const Data1D< T > &  other)
inline

Appends all elements in other to the end, expanding if necessary.

Parameters
otherThe Data1D to append to the end.
Returns
A reference to this Data1D.

◆ operator+=() [2/2]

template<class T >
Data1D<T>& RC::Data1D< T >::operator+= ( const T &  newT)
inline

Add an element to the end, expanding if necessary.

Efficiency note: Expands by doubling for linear efficiency.

Parameters
newTThe new element to append to the end.
Returns
A reference to this Data1D.
See also
Reserve

◆ operator<()

template<class T >
template<class AnyValidType >
bool RC::Data1D< T >::operator< ( const Data1D< AnyValidType > &  other) const
inline

Returns true if the first different element for this is less than for other.

If they are differently sized and identical through the common length, then the shorter one is considered less. Works for AnyValidType with defined operator< in both directions with T.

Parameters
otherThe Data1D to compare all elements with.
Returns
True if the first non-equal element for this is less than for other.

◆ operator=() [1/2]

template<class T >
Data1D& RC::Data1D< T >::operator= ( const Data1D< T > &  other)
inline

Assignment operator which copies all contents from other, respecting offsets.

Parameters
otherData1D to copy from, from offset (default 0) to size.
Returns
This object.

◆ operator=() [2/2]

template<class T >
Data1D& RC::Data1D< T >::operator= ( Data1D< T > &&  other)
inline

Assignment operator which copies all contents from other, respecting offsets.

Parameters
otherData1D to copy from, from offset (default 0) to size.
Returns
This object.

◆ operator==()

template<class T >
template<class AnyValidType >
bool RC::Data1D< T >::operator== ( const Data1D< AnyValidType > &  other) const
inline

Comparison operator for all elements.

Also returns false if they are differently sized. Works for AnyValidType with operator== defined with T.

Parameters
otherThe Data1D to compare all elements with.
Returns
True if all elements are equal.

◆ operator[]()

template<class T >
T& RC::Data1D< T >::operator[] ( size_t  x)
inline

Bounds-checked access of the element at index x from the offset (default 0).

Throws an ErrorMsgBounds exception if x is out of bounds.

Parameters
xIndex to access, where 0 is the element at offset.
Returns
Reference to the element at index x.

◆ Put() [1/2]

template<class T >
template<class T2 >
Data1D<T>& RC::Data1D< T >::Put ( const Data1D< T2 > &  read_from,
size_t  index_T = 0 
)
inline

Like Get for a T2 type, but places sequential packed data.

Copies the full array read_from with raw assigned data of type T2, to this Data1D starting at index, resizing as needed to include all of read_from. Usage example: Data1D<u64> x(1); Data1D<u8> y(8); x.Put(y,0); y.Put(x,0);

Returns
*this

◆ Put() [2/2]

template<class T >
template<class T2 >
Data1D<T>& RC::Data1D< T >::Put ( const T2 &  read_from,
size_t  index_T 
)
inline

Direct raw data insertion of type T2 at index.

Bounds are checked. But if the raw data at the index is invalid for an assignment operation of type T2 (e.g., not-POD in ambiguous state), then behavior is undefined.

Parameters
read_fromThe reference from which data is read.
index_TThe index at which data is placed.
Returns
*this

◆ Raw()

template<class T >
T* RC::Data1D< T >::Raw ( ) const
inline

Access a raw unprotected C-pointer to the enclosed data.

Warning: This convenience function bypasses the bounds protections provided by this class. The returned pointer is likely to become invalid after any of the operations on this object which change the size.

Returns
C-style pointer to the contents at the offset (0 by default).

◆ Reinterpret()

template<class T >
template<class T2 >
Data1D<T2> RC::Data1D< T >::Reinterpret ( ) const
inline

Returns a new array with the raw data of this Data1D reinterpreted as type T2.

Warning, this carries the same risks and caveats as C-type casting the raw data before assignment, and has undefined behavior for non-POD types in an ambiguous state. If the data sizes do not fit to an integral size of the returned type then there will be extra undefined bytes at the end of the returned data.

See also
Put
Get

◆ Remove()

template<class T >
void RC::Data1D< T >::Remove ( size_t  pos)
inline

Removes the element at pos from the array, shrinking the size.

Efficiency note: For random positions, on average O(N).

Parameters
posThe index at which an element should be removed.

◆ Reserve()

template<class T >
void RC::Data1D< T >::Reserve ( const size_t  reserve_size)
inline

Reserve storage without resizing the array.

Parameters
reserve_sizeThe number of elements worth of storage to reserve.

◆ Resize()

template<class T >
void RC::Data1D< T >::Resize ( const size_t  resize_size)
inline

Resize the array, reallocating if necessary.

This may trigger a copy operation upon expansion. For efficiency it never reallocates or copies while shrinking or expanding within a previous size range. Use Crop if necessary to shrink storage to the current size.

Parameters
resize_sizeThe new number of elements.

◆ SetOffset()

template<class T >
void RC::Data1D< T >::SetOffset ( const size_t  new_offset)
inline

Set a new offset position for index 0.

This also adjusts the size to reach the same last element.

Parameters
new_offsetThe new absolute offset from the 0th allocated element.
See also
SetRange

◆ SetRange()

template<class T >
void RC::Data1D< T >::SetRange ( const size_t  new_offset,
const size_t  new_size 
)
inline

Set a new offset and data size, resizing if necessary.

Parameters
new_offsetThe new absolute offset from the 0th allocated element.
new_sizeThe new number of elements.
See also
SetOffset
Resize

◆ Shuffle()

template<class T >
void RC::Data1D< T >::Shuffle ( )
inline

Randomizes the order of all the elements.

Performs a Mersenne Twister random shuffle of the elements, microsecond time-seeded on the first call.

◆ Sort()

template<class T >
template<class Comparator >
void RC::Data1D< T >::Sort ( Comparator  comp)
inline

Sorts the elements according to the binary comparitor comp.

comp should return true if less, and should not modify the elements passed.

◆ URandShuffle()

template<class T >
void RC::Data1D< T >::URandShuffle ( )
inline

Randomizes the order of all the elements using /dev/urandom.

Uses /dev/urandom, available on many unix implementations, to perform a shuffle which is reseeded with environmental randomness.

◆ Zero()

template<class T >
void RC::Data1D< T >::Zero ( )
inline

Sets all elements equal to 0.

Note: Types for Data1D do not need to have a defined assignment operator which can receive a 0 unless this function is called for that Data1D instance.

◆ ZeroRange()

template<class T >
void RC::Data1D< T >::ZeroRange ( const size_t  start,
const size_t  end = npos 
)
inline

Like Zero() but operating only between index start and end, inclusive.

If end is unspecified, defaults to the end of the data. If either is out of bounds, ErrorMsgBounds is thrown.


The documentation for this class was generated from the following file:
email address
— (c) 2015