A dynamic buffer with multi-dimensional array style access. More...

#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <das2/value.h>
#include <das2/units.h>

Include dependency graph for array.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	DasAry
	Dynamic recursive ragged arrays. More...

Macros
#define	DASIDX_MAX 8
	The maximum number of array indices in das2.

#define	D2ARY_AS_SUBSEQ 0x00000001
	This array's elements aren't intended to be addressed to the last index, instead each run of the last index should be used as if it were a complete an individual entity. More...

#define	D2ARY_FILL_TERM 0x00000003
	A stronger condition then D2ARY_AS_SUBSEQ. More...

#define	D2ARY_AS_STRING 0x00000007
	A still stronger condition than D2ARY_FILL_TERM. More...

#define	DasAry_getPtrAt(pThis, pLoc) ((void*)(DasAry_getAt(pThis, vtUnknown, pLoc)))
	Wrapper around DasAry_get for vtUnknown pointers.

#define	DasAry_getIntsIn(T, ...) (const int32_t*) DasAry_getIn(T, vtInt, __VA_ARGS__)
	A wrapper around DasAry_getIn that casts the output and preforms type checking.

Functions
char *	das_shape_prnRng (ptrdiff_t pShape, int iFirstInternal, int nShapeLen, char sBuf, int nBufLen)
	Print shape information using symbols i,j,k etc for index positions. More...

char *	das_idx_prn (int nRank, ptrdiff_t pIdx, size_t uLen, char sBuf)
	print a generice set of ptrdiff_t values to a character array

int	das_rng2shape (int nRngRank, const ptrdiff_t pMin, const ptrdiff_t pMax, size_t *pShape)
	Calculate a strided array shape from a min/max range. More...

DAS_API bool	DasAry_init (DasAry pThis, const char id, das_val_type et, size_t sz_each, const ubyte fill, int rank, size_t shape, das_units units)
	Same as new_DasAry, but for initializing stack objects instead of making new heap objects. More...

DAS_API DasAry *	new_DasPtrAry (const char sType, int rank, size_t shape)
	A convenience wrapper for storing arrays of pointers. More...

DAS_API void	DasAry_deInit (DasAry *pThis)
	Similar to dec_dasAry, but for stack objects.

DAS_API size_t	DasAry_memUsed (const DasAry *pThis)
	Get number of bytes currently used for data values and associated indexes by this dynamic array. More...

DAS_API size_t	DasAry_memOwned (const DasAry *pThis)
	Get the number of bytes currently owned for use in storing data values and indexes. More...

DAS_API size_t	DasAry_memIndexed (const DasAry *pThis)
	Get the number of bytes needed to store these values and thier associated indexes. More...

DAS_API const ubyte *	DasAry_getFill (const DasAry *pThis)
	Return the fill value for this array. More...

DAS_API ubyte *	DasAry_getBuf (DasAry pThis, das_val_type et, int nDim, ptrdiff_t pLoc, size_t *pCount)
	This is the writable pointer version of DasAry_getIn. More...

DAS_API const ubyte *	DasAry_getAllVals (const DasAry pThis, size_t pElSize, size_t *pElements)
	Forget all the fancy indexing, just get a pointer to all the elements. More...

Variables
const ptrdiff_t	g_aShapeUnused [DASIDX_MAX]
	Global instance of unused array, suitable for memcpy.

Detailed Description

A dynamic buffer with multi-dimensional array style access.

Macro Definition Documentation

◆ D2ARY_AS_SUBSEQ

#define D2ARY_AS_SUBSEQ 0x00000001

This array's elements aren't intended to be addressed to the last index, instead each run of the last index should be used as if it were a complete an individual entity.

◆ D2ARY_FILL_TERM

#define D2ARY_FILL_TERM 0x00000003

A stronger condition then D2ARY_AS_SUBSEQ.

Not only should the last index be ignored when using this array, in addition for each run of the fastest moving index a FILL value is always inserted as the last element.

◆ D2ARY_AS_STRING

#define D2ARY_AS_STRING 0x00000007

A still stronger condition than D2ARY_FILL_TERM.

This flag indicates not only that the last index shouldn't be addressed and that each fast-index run is FILL terminated, the fill value is 0. This flag is useful for UTF-8 string data.

Function Documentation

◆ das_shape_prnRng()

char* das_shape_prnRng	(	ptrdiff_t *	pShape,
		int	iFirstInternal,
		int	nShapeLen,
		char *	sBuf,
		int	nBufLen
	)

Print shape information using symbols i,j,k etc for index positions.

Parameters

pShape	pointer to an array containing shape information
iFirstInternal	the index of the first internal index. The index notation changes at this point to use I,J,K instead of i,j,k and the index count reverts back to 0.
nShapeLen	An index 1 past the last unsed index in the shape array.
sBuf	a buffer to recieve the shape info
nBufLen	the length of the buffer. The function will not print past this value - 1 to insure null terminiation.

Returns: The a pointer to the position in the buffer sBuf after all text was written.

◆ DasAry_init()

DAS_API bool DasAry_init	(	DasAry *	pThis,
		const char *	id,
		das_val_type	et,
		size_t	sz_each,
		const ubyte *	fill,
		int	rank,
		size_t *	shape,
		das_units	units
	)

Same as new_DasAry, but for initializing stack objects instead of making new heap objects.

Returns: True if the object could be successfully initialized

◆ new_DasPtrAry()

DAS_API DasAry* new_DasPtrAry	(	const char *	sType,
		int	rank,
		size_t *	shape
	)

A convenience wrapper for storing arrays of pointers.

This function is the equivalent of the code: void* p = NULL; new_DasAry("MyType", vtUnknown, sizeof(void*), &p, rank, shape, NULL);

Parameters

sType	A string identification of the data type.
rank	The number of dimensions in the array. This sets the number of arguments needed in the get() function call. To make your code easier to read, the defines RANK_1, RANK_2, ... RANK_8 are provided.
shape	The initial shape of the array. One integer is needed here for each dimension in the array. Use the value 0 to set a dimension to be unbounded.

Returns: A new array buffer allocated on the heap.

See also: new_DasAry

◆ DasAry_memUsed()

DAS_API size_t DasAry_memUsed ( const DasAry * pThis )

Get number of bytes currently used for data values and associated indexes by this dynamic array.

This is not the number of bytes allocated for dynamic storage. It represents how much of the allocated memory is currently in use. Memory is used for the actual data values themselves, as well as the index arrays that point to index roll-over points.

This is the number of bytes of dynamic storage used. For sub-arrays the value is zero, since they don't use any dynamic memory.

Parameters

pThis a DasAry structure

Returns: The sum of heap bytes currently holding data values and array indexes by this array.

See also: DasAry_memOwned() for the number of bytes allocated; DasAry_memIndexed() for the number of bytes indexed, even if it's owned by some other array.

◆ DasAry_memOwned()

DAS_API size_t DasAry_memOwned ( const DasAry * pThis )

Get the number of bytes currently owned for use in storing data values and indexes.

This is the number of bytes allocated for dynamic storage. For sub-arrays the value is zero, since they don't own thier own memory.

Note: Arrays allocated more memory then is needed during append opperations to avoid frequent (and time expensive) malloc calls. Calling DasAry_clear() does not actually free memory, it only marks it available for reuse.

Parameters

pThis a DasAry structure

Returns: The sum of heap bytes currently allocated for data values and array indexes, even if those bytes are not currently in use.

◆ DasAry_memIndexed()

DAS_API size_t DasAry_memIndexed ( const DasAry * pThis )

Get the number of bytes needed to store these values and thier associated indexes.

Even if the array doesn't own it's own memory, this function will not return unless there are no values accessable by this array.

Parameters

pThis a DasAry structure

Returns: The sum of heap bytes currently holding data values and array indexes accessible from this DasAry structure, even if the memory is owned by some other array.

◆ DasAry_getFill()

DAS_API const ubyte* DasAry_getFill ( const DasAry * pThis )

Return the fill value for this array.

The caller is responsible for casting to the proper type

◆ DasAry_getBuf()

DAS_API ubyte* DasAry_getBuf	(	DasAry *	pThis,
		das_val_type	et,
		int	nDim,
		ptrdiff_t *	pLoc,
		size_t *	pCount
	)

This is the writable pointer version of DasAry_getIn.

See the argument list form DasAry_getIn()

Returns: A raw byte pointer suitable for direct value insertion. Not that the amount of space for writing is *pCount times the element size from DasAry_valSize().

◆ DasAry_getAllVals()

DAS_API const ubyte* DasAry_getAllVals	(	const DasAry *	pThis,
		size_t *	pElSize,
		size_t *	pElements
	)

Forget all the fancy indexing, just get a pointer to all the elements.

This can be handy for just writing array data to disk, be warned that it is not sufficent. In addition the stride coefficents will need to be saved if the array is a qubic. If not, all the indexes will also need to be saved.

See also: DasAry_getAllIdx for a raw return of the associated index buffers.

Parameters

pThis	A pointer to an array structure
pElSize	A pointer to a location to receive the element size
pElements	A pointer to a location to receive the number of valid elements

Returns: A pointer to the first valid element, or NULL if no elements are valid. Note that DasAry storage is always dense. There is no reason to believe that the returned pointer can be strided.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ D2ARY_AS_SUBSEQ

◆ D2ARY_FILL_TERM

◆ D2ARY_AS_STRING

Function Documentation

◆ das_shape_prnRng()

◆ DasAry_init()

◆ new_DasPtrAry()

◆ DasAry_memUsed()

◆ DasAry_memOwned()

◆ DasAry_memIndexed()

◆ DasAry_getFill()

◆ DasAry_getBuf()

◆ DasAry_getAllVals()