A high-performance general-purpose compute library

- Main Page
- Tutorials
- Release Notes
- Examples

Functions
readArray
ArrayFire Functions | ArrayFire Functions by Category » Input and Output functions » Reading and writing arrays

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.
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.

## 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.