readArray

Load an array from a file. More...

Functions
AFAPI array	readArray (const char *filename, const unsigned index)
AFAPI array	readArray (const char *filename, const char *key)
AFAPI int	readArrayCheck (const char *filename, const char *key)
	When reading by key, it may be a good idea to run this function first to check for the key and then call the readArray using the index. More...
AFAPI af_err	af_read_array_index (af_array *out, const char *filename, const unsigned index)
AFAPI af_err	af_read_array_key (af_array *out, const char *filename, const char *key)
AFAPI af_err	af_read_array_key_check (int *index, const char *filename, const char *key)
	When reading by key, it may be a good idea to run this function first to check for the key and then call the readArray using the index. More...

Detailed Description

Load an array from a file.

The readArray function lets users read arrays saved in files. Arrays can either be read using the index in the file (0-indexed), or using the key that was used along with the Array.

Note that if there are multiple arrays with the same key, only the first one will be read.

The format of the file (version 1) is as follows:

Header:

Description	Data Type	Size (Bytes)	Detailed Desc
Version	Char	1	ArrayFire File Format Version for future use. Currently set to 1
Array Count	Int	4	No. of Arrays stored in file

Per Array:

Description	Data Type	Size (Bytes)	Detailed Desc
Length of Key String	Int	4	No. of characters (excluding null ending) in the key string
Key	Char []	length	Key of the Array. Used when reading from file
Offset	Int64	8	No of bytes between offset and start of next array
Array Type	Char	1	Type corresponding to af_dtype enum
Dims (4 values)	Int64	4 * 8 = 32	Dimensions of the Array
Data	Type	sizeof(Type) * dims.elements()	Actual data of the array

The offset is equal to 1 byte (type) + 32 bytes (dims) + size of data.

An file with 2 arrays would look like (representative)

‍1
2
Array 1 Key Length
Array 1 Key
Array 1 Offset
Array 1 Type
Array 1 Dims
Array 1 Data
Array 2 Key Length
Array 2 Key
Array 2 Offset
Array 2 Type
Array 2 Dims
Array 2 Data

---

Function Documentation

af_read_array_index()

AFAPI af_err af_read_array_index	(	af_array *	out,
		const char *	filename,
		const unsigned	index
	)

Parameters

[out]	out	is the array read from index
[in]	filename	is the path to the location on disk
[in]	index	is the 0-based sequential location of the array to be read

Note

This function will throw an exception if the key is not found.

af_read_array_key()

AFAPI af_err af_read_array_key	(	af_array *	out,
		const char *	filename,
		const char *	key
	)

Parameters

[out]	out	is the array read from key
[in]	filename	is the path to the location on disk
[in]	key	is the tag/name of the array to be read. The key needs to have an exact match.

Note

This function will throw an exception if the key is not found.

af_read_array_key_check()

AFAPI af_err af_read_array_key_check	(	int *	index,
		const char *	filename,
		const char *	key
	)

When reading by key, it may be a good idea to run this function first to check for the key and then call the readArray using the index.

This will avoid exceptions in case of key not found.

Parameters

[out]	index	of the array in the file if the key is found. -1 if key is not found.
[in]	filename	is the path to the location on disk
[in]	key	is the tag/name of the array to be read. The key needs to have an exact match.

readArray() [1/2]

AFAPI array readArray	(	const char *	filename,
		const char *	key
	)

Parameters

[in]	filename	is the path to the location on disk
[in]	key	is the tag/name of the array to be read. The key needs to have an exact match.

Returns

array read by key

Note

This function will throw an exception if the key is not found.

readArray() [2/2]

AFAPI array readArray	(	const char *	filename,
		const unsigned	index
	)

Parameters

[in]	filename	is the path to the location on disk
[in]	index	is the 0-based sequential location of the array to be read

Returns

array read from the index location

Note

This function will throw an exception if the index is out of bounds

readArrayCheck()

AFAPI int readArrayCheck	(	const char *	filename,
		const char *	key
	)

When reading by key, it may be a good idea to run this function first to check for the key and then call the readArray using the index.

This will avoid exceptions in case of key not found.

Parameters

[in]	filename	is the path to the location on disk
[in]	key	is the tag/name of the array to be read. The key needs to have an exact match.

Returns

index of the array in the file if the key is found. -1 if key is not found.