Front end API

typedef int32_t back_end_t;

#define TREXIO_HDF5             ( (back_end_t) 0 )
#define TREXIO_TEXT             ( (back_end_t) 1 )
/*#define TREXIO_JSON             ( (back_end_t) 2 )*/
#define TREXIO_INVALID_BACK_END ( (back_end_t) 2 )

#define TREXIO_DELIM            "\n"

  integer(trexio_backend), parameter :: TREXIO_HDF5 = 0
  integer(trexio_backend), parameter :: TREXIO_TEXT = 1
! integer(trexio_backend), parameter :: TREXIO_JSON = 2
  integer(trexio_backend), parameter :: TREXIO_INVALID_BACK_END = 2

# define TREXIO back ends
TREXIO_HDF5 = 0
TREXIO_TEXT = 1
#TREXIO_JSON = 2
TREXIO_INVALID_BACK_END = 2

class File:
    """TREXIO File object.

    General information about the TREXIO file.

    Parameters:

    filename: str
        Is a name of the full path to the TREXIO file.
    back_end: int
        One of the currently supported TREXIO back ends.
        For example, TREXIO_HDF5 (0) or TREXIO_TEXT (1).
    mode: str
        One of the currently supported TREXIO open modes.
        For example, 'r' or 'w'.
    isOpen: bool
        Flag indicating whether the current object is still open for I/O
    pytrexio_s:
        A PyObject corresponding to SWIG proxy of the trexio_s struct in C.
        This argument is in fact a TREXIO file handle, which is required for
        communicating with the C back end. 
    info: dict
        Dictionary of key-value pairs with additional information about the file.
    """


    def __init__(self, filename, mode='r', back_end=TREXIO_HDF5,
                 pytrexio_s=None, info=None):
        """This is a TREXIO File constructor."""

        self.filename = filename
        self.mode = mode
        self.back_end = back_end

        self.isOpen = False 
        if pytrexio_s is None:
            self.pytrexio_s = open(filename, mode, back_end)
            self.isOpen = True
        else:
            self.pytrexio_s = pytrexio_s
            self.isOpen = None

        self.info = info


    def close(self):
        """Close a TREXIO File."""

        if self.isOpen:
            close(self.pytrexio_s)
            self.isOpen = False
        else:
            raise Exception("TREXIO File object has not been opened.")


    def __del__(self):
        """This is a TREXIO File destructor."""

        if self.isOpen:
            close(self.pytrexio_s)
        elif self.isOpen is None:
            raise Exception("[WIP]: TREXIO file handle provided but what if the file is already closed?")
        else:
            pass 

trexio_t*
trexio_open(const char* file_name, const char mode,
            const back_end_t back_end)
{

  if (file_name == NULL) return NULL;
  if (file_name[0] == '\0') return NULL;
  /* Check overflow in file_name */

  if (back_end <  0) return NULL;
  if (back_end >= TREXIO_INVALID_BACK_END) return NULL;

  if (mode != 'r' && mode != 'w') return NULL;

  trexio_t* result = NULL;
  void* result_tmp = NULL;

  /* Allocate data structures */
  switch (back_end) {

  case TREXIO_TEXT:
    result_tmp = malloc(sizeof(trexio_text_t));
    break;

  case TREXIO_HDF5:
    result_tmp = malloc(sizeof(trexio_hdf5_t));
    break;
/*
  case TREXIO_JSON:
    result = (trexio_t*) malloc (sizeof(trexio_json_t));
    break;
*/
  }
  result = (trexio_t*) result_tmp;

  assert (result != NULL);    /* TODO: Error handling */


  /* Data for the parent type */

  strncpy(result->file_name, file_name, TREXIO_MAX_FILENAME_LENGTH);
  if (result->file_name[TREXIO_MAX_FILENAME_LENGTH-1] != '\0') {
    free(result);
    return NULL;
  }

  strncpy(result->version, PACKAGE_VERSION, 16);
  if (result->version[15] != '\0') {
    free(result);
    return NULL;
  }

  result->back_end    = back_end;
  result->mode        = mode;
  result->one_based   = false;  // Need to be flipped in Fortran interface
  int irc = pthread_mutex_init ( &(result->thread_lock), NULL);
  if (irc != 0) {
    free(result);
    return NULL;
  }
  assert (irc == 0);

  trexio_exit_code rc;

  /* Back end initialization */

  rc = TREXIO_OPEN_ERROR;

  switch (back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_init(result);
    break;

  case TREXIO_HDF5:
    rc = trexio_hdf5_init(result);
    break;
/*
  case TREXIO_JSON:
    rc = trexio_json_init(result);
    break;
*/
  }

  if (rc != TREXIO_SUCCESS) {
    free(result);
    return NULL;
  }

  rc = trexio_has_metadata_package_version(result);
  if (rc == TREXIO_FAILURE) {
    free(result);
    return NULL;
  }

  if (rc == TREXIO_HAS_NOT) {
    switch (back_end) {

    case TREXIO_TEXT:
      rc = trexio_text_write_metadata_package_version(result, PACKAGE_VERSION);
      break;

    case TREXIO_HDF5:
      rc = trexio_hdf5_write_metadata_package_version(result, PACKAGE_VERSION);
      break;
/*
    case TREXIO_JSON:
      rc = trexio_json_write_metadata_package_version(result, PACKAGE_VERSION);
      break;
*/
    }
  }

  if (rc != TREXIO_SUCCESS) {
    free(result);
    return NULL;
  }


  /* File locking */

  rc = TREXIO_LOCK_ERROR;

  switch (back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_lock(result);
    break;
  /* HDF5 v.>=1.10 has file locking activated by default */
  case TREXIO_HDF5:
    rc = TREXIO_SUCCESS;
    break;
/*
  case TREXIO_JSON:
    rc = trexio_json_lock(result);
    break;
*/
  }

  if (rc != TREXIO_SUCCESS) {
    free(result);
    return NULL;
  }

  return result;
}

interface
   integer(8) function trexio_open_c (filename, mode, backend) bind(C, name="trexio_open")
     use, intrinsic :: iso_c_binding
     import
     character(kind=c_char), dimension(*)       :: filename
     character, intent(in), value               :: mode
     integer(trexio_backend), intent(in), value :: backend
   end function trexio_open_c
end interface

def open(file_name: str, mode: str, back_end: int):
    """Create TREXIO file or open existing one.

    Parameters:

    file_name: str
        Name of the TREXIO file

    mode: str
        One of the currently supported ~open~ modes (e.g. 'w', 'r')

    back_end: int
        One of the currently supported TREXIO back ends (e.g. TREXIO_HDF5, TREXIO_TEXT)    

    Return: 
        SWIG object of type trexio_s.

    Examples:
    >>> from trexio import open as tr_open
    >>> trex_file = tr_open("example.h5", "w", TREXIO_HDF5)
    """

    try:
        trexio_file = pytr.trexio_open(file_name, mode, back_end)
        assert trexio_file is not None
    except AssertionError:
        raise Exception(f"Could not open TREXIO file {file_name} using trexio_open function. Please make sure that there are no typos in the file name.")

    return trexio_file

trexio_exit_code trexio_set_one_based(trexio_t* file)
{
  if (file == NULL)
    return TREXIO_FILE_ERROR;

  file->one_based = true;

  return TREXIO_SUCCESS;
}

interface
   integer function trexio_set_one_based(trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_set_one_based
end interface

trexio_exit_code
trexio_close (trexio_t* file)
{

  if (file == NULL) return TREXIO_FILE_ERROR;

  trexio_exit_code rc = TREXIO_FAILURE;

  assert(file->back_end < TREXIO_INVALID_BACK_END);

  /* Terminate the back end */
  switch (file->back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_deinit(file);
    break;

  case TREXIO_HDF5:
    rc = trexio_hdf5_deinit(file);
    break;
/*
  case TREXIO_JSON:
    rc = trexio_json_deinit(file);
    break;
*/
  }

  if (rc != TREXIO_SUCCESS) {
    FREE(file);
    return rc;
  }

  /* File unlocking */

  rc = TREXIO_UNLOCK_ERROR;

  switch (file->back_end) {

  case TREXIO_TEXT:
    rc = trexio_text_unlock(file);
    break;

  case TREXIO_HDF5:
    rc = TREXIO_SUCCESS;
    break;
/*
  case TREXIO_JSON:
    rc = trexio_json_unlock(file);
    break;
*/
  }

  /* Terminate front end */

  int irc = pthread_mutex_destroy( &(file->thread_lock) );

  free(file);

  if (irc != 0) return TREXIO_ERRNO;
  if (rc != TREXIO_SUCCESS) return rc;

  return TREXIO_SUCCESS;
}

interface
   integer function trexio_close (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_close
end interface

def close(trexio_file):
    """Close TREXIO file.

    Parameter is a ~trexio_file~ object that has been created by a call to ~open~ function.
    """

    try:
        rc = pytr.trexio_close(trexio_file)
        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise

interface
   integer function trexio_write_$group_num$_64 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_double$, intent(in), value :: num
   end function trexio_write_$group_num$_64
end interface

interface
   integer function trexio_read_$group_num$_64 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_double$, intent(out) :: num
   end function trexio_read_$group_num$_64
end interface

interface
   integer function trexio_write_$group_num$_32 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_single$, intent(in), value :: num
   end function trexio_write_$group_num$_32
end interface

interface
   integer function trexio_read_$group_num$_32 (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_single$, intent(out) :: num
   end function trexio_read_$group_num$_32
end interface

interface
   integer function trexio_write_$group_num$ (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_default$, intent(in), value :: num
   end function trexio_write_$group_num$
end interface

interface
   integer function trexio_read_$group_num$ (trex_file, num) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_num_f_dtype_default$, intent(out) :: num
   end function trexio_read_$group_num$
end interface

interface
   integer function trexio_has_$group_num$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_num$
end interface

def write_$group_num$(trexio_file, num_w: $group_num_py_dtype$) -> None: 
    """Write the $group_num$ variable in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    num_w: int
        Value of the $group_num$ variable to be written.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_write_$group_num$(trexio_file.pytrexio_s, num_w)
        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise    

def read_$group_num$(trexio_file) -> $group_num_py_dtype$: 
    """Read the $group_num$ variable from the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
        ~num_r~: int
        Integer value of $group_num$ variable read from ~trexio_file~.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc, num_r = pytr.trexio_read_$group_num$(trexio_file.pytrexio_s)
        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise    

    return num_r

def has_$group_num$(trexio_file) -> bool: 
    """Check that $group_num$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_num$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise    

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False

interface
   integer function trexio_write_$group_dset$_64 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_double$, intent(in) :: dset$group_dset_f_dims$
   end function trexio_write_$group_dset$_64
end interface

interface
   integer function trexio_read_$group_dset$_64 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_double$, intent(out) :: dset$group_dset_f_dims$
   end function trexio_read_$group_dset$_64
end interface

interface
   integer function trexio_write_$group_dset$_32 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_single$, intent(in) :: dset$group_dset_f_dims$
   end function trexio_write_$group_dset$_32
end interface

interface
   integer function trexio_read_$group_dset$_32 (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_single$, intent(out) :: dset$group_dset_f_dims$
   end function trexio_read_$group_dset$_32
end interface

interface
   integer function trexio_write_$group_dset$ (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_default$, intent(in) :: dset$group_dset_f_dims$
   end function trexio_write_$group_dset$
end interface

interface
   integer function trexio_read_$group_dset$ (trex_file, dset) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     $group_dset_f_dtype_default$, intent(out) :: dset$group_dset_f_dims$
   end function trexio_read_$group_dset$
end interface

interface
   integer function trexio_has_$group_dset$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_dset$
end interface

def write_$group_dset$(trexio_file, dset_w) -> None: 
    """Write the $group_dset$ array of numbers in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dset_w: list OR numpy.ndarray
        Array of $group_dset$ values to be written. If array data type does not correspond to int64 or float64, the conversion is performed.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        import numpy as np
    except ImportError:
        raise Exception("NumPy cannot be imported.")

    doConversion = False
    doFlatten = False
    if not isinstance(dset_w, (list, tuple)):
       # if input array is not a list or tuple then it is probably a numpy array
       if isinstance(dset_w, np.ndarray) and (not dset_w.dtype==np.int64 or not dset_w.dtype==np.float64):
           doConversion = True

       if len(dset_w.shape) > 1:
           doFlatten = True
           if doConversion:
               dset_64 = np.$group_dset_py_dtype$64(dset_w).flatten()
           else:
               dset_flat = np.array(dset_w, dtype=np.$group_dset_py_dtype$64).flatten()
       else:
           if doConversion:
               dset_64 = np.$group_dset_py_dtype$64(dset_w)

    else:
       # if input array is a multidimensional list or tuple, we have to convert it
       try:
           doFlatten = True
           ncol = len(dset_w[0])
           dset_flat = np.array(dset_w, dtype=np.$group_dset_py_dtype$64).flatten()
       except TypeError:
           doFlatten = False
           pass


    if doConversion:
        rc = pytr.trexio_write_safe_$group_dset$_64(trexio_file.pytrexio_s, dset_64)
    elif doFlatten:
        rc = pytr.trexio_write_safe_$group_dset$_64(trexio_file.pytrexio_s, dset_flat)
    else:
        rc = pytr.trexio_write_safe_$group_dset$_64(trexio_file.pytrexio_s, dset_w)

    if rc != TREXIO_SUCCESS:
        raise Error(rc)

def read_$group_dset$(trexio_file, dim = None, doReshape = None, dtype = None): 
    """Read the $group_dset$ array of numbers from the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dim (Optional): int
        Size of the block to be read from the file (i.e. how many items of $group_dset$ will be returned)
        If None, the function will read all necessary array dimensions from the file.

    dtype (Optional): type
        NumPy data type of the output (e.g. np.int32|int16 or np.float32|float16). If specified, the output array will be converted from the default double precision.

    doReshape (Optional): bool
        Flag to determine whether the output NumPy array has be reshaped or not. Be default, reshaping is performed
        based on the dimensions from the ~trex.json~ file. Otherwise, ~shape~ array (list or tuple) is used if provided by the user.

    Returns:
        ~dset_64~ if dtype is None or ~dset_converted~ otherwise: numpy.ndarray 
        1D NumPy array with ~dim~ elements corresponding to $group_dset$ values read from the TREXIO file.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
"""

    try:
        import numpy as np
    except ImportError:
        raise Exception("NumPy cannot be imported.")

    if doReshape is None:
        doReshape = True

    # if dim is not specified, read dimensions from the TREXIO file
    dims_list = None
    if dim is None or doReshape:
        $group_dset_dim$ = read_$group_dset_dim$(trexio_file) 

        dims_list = [$group_dset_dim_list$]
        dim = 1
        for i in range($group_dset_rank$):
            dim *= dims_list[i]


    shape = tuple(dims_list)
    if shape is None and doReshape:
        raise ValueError("Reshaping failure: shape is None.")

    try:
        rc, dset_64 = pytr.trexio_read_safe_$group_dset$_64(trexio_file.pytrexio_s, dim)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise


    isConverted = False
    dset_converted = None
    if dtype is not None:

        try:
            assert isinstance(dtype, type)
        except AssertionError:
            raise TypeError("dtype argument has to be an instance of the type class (e.g. np.float32).")


        if not dtype==np.int64 or not dtype==np.float64:
            try:
                dset_converted = np.array(dset_64, dtype=dtype)
            except:
                raise

            isConverted = True

    # additional assert can be added here to check that read_safe functions returns numpy array of proper dimension

    if doReshape:
        try:
            # in-place reshaping did not work so I have to make a copy
            if isConverted:    
                dset_reshaped = np.reshape(dset_converted, shape, order='C')
            else:
                dset_reshaped = np.reshape(dset_64, shape, order='C')
        except:
            raise

    if isConverted:    
        return dset_converted
    elif doReshape:
        return dset_reshaped
    else:
        return dset_64

def has_$group_dset$(trexio_file) -> bool: 
    """Check that $group_dset$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_dset$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise    

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False

interface
   integer function trexio_write_$group_dset$_low (trex_file, dset, max_str_len) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(in) :: dset(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_write_$group_dset$_low
end interface

interface
   integer function trexio_read_$group_dset$_low (trex_file, dset, max_str_len) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(out) :: dset(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_read_$group_dset$_low
end interface

interface
   integer function trexio_has_$group_dset$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_dset$
end interface

integer function trexio_read_$group_dset$ (trex_file, dset, max_str_len)
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character(len=*), intent(inout) :: dset(*)

  character, allocatable :: str_compiled(:)
  integer(8) :: $group_dset_dim$
  integer :: rc

  rc = trexio_read_$group_dset_dim$_64(trex_file, $group_dset_dim$)
  if (rc /= TREXIO_SUCCESS) trexio_read_$group_dset$ = rc

  allocate(str_compiled($group_dset_dim$*(max_str_len+1)+1))

  rc = trexio_read_$group_dset$_low(trex_file, str_compiled, max_str_len)
  if (rc /= TREXIO_SUCCESS) then 
    deallocate(str_compiled)
    trexio_read_$group_dset$ = rc
  else
    call trexio_str2strarray(str_compiled, $group_dset_dim$, max_str_len, dset)
    deallocate(str_compiled)
    trexio_read_$group_dset$ = TREXIO_SUCCESS
  endif

end function trexio_read_$group_dset$

integer function trexio_write_$group_dset$ (trex_file, dset, max_str_len)
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character(len=*), intent(in) :: dset(*)

  character(len=:), allocatable :: str_compiled
  integer(8) :: $group_dset_dim$
  integer :: rc

  rc = trexio_read_$group_dset_dim$_64(trex_file, $group_dset_dim$)
  if (rc /= TREXIO_SUCCESS) then
    trexio_write_$group_dset$ = rc
  else
    call trexio_strarray2str(dset, $group_dset_dim$, max_str_len, str_compiled)
    trexio_write_$group_dset$ = trexio_write_$group_dset$_low(trex_file, str_compiled, max_str_len)
  endif

end function trexio_write_$group_dset$

def write_$group_dset$(trexio_file, dset_w: list) -> None: 
    """Write the $group_dset$ array of strings in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dset_w: list
        Array of $group_dset$ strings to be written.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    max_str_length = len(max(dset_w, key=len)) + 1

    try:
        rc = pytr.trexio_write_$group_dset$(trexio_file.pytrexio_s, dset_w, max_str_length)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise    

def read_$group_dset$(trexio_file, dim = None) -> list: 
    """Read the $group_dset$ array of strings from the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    dim (Optional): int
        Size of the block to be read from the file (i.e. how many items of $group_dset$ will be returned)
        If None, the function will read all necessary array dimensions from the file.

    Returns:
        ~dset_r~: list
        1D list with ~dim~ elements corresponding to $group_dset$ strings read from the TREXIO file.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    # if dim is not specified, read dimensions from the TREXIO file
    if dim is None:
        $group_dset_dim$ = read_$group_dset_dim$(trexio_file) 

        dims_list = [$group_dset_dim_list$]
        dim = 1
        for i in range($group_dset_rank$):
            dim *= dims_list[i]


    try:
        rc, dset_1d_r = pytr.trexio_read_$group_dset$_low(trexio_file.pytrexio_s, PYTREXIO_MAX_STR_LENGTH)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise    


    try:
        dset_full = dset_1d_r.split(pytr.TREXIO_DELIM)
        dset_2d_r = [dset_full[i] for i in range(dim) if dset_full[i]]
        if not dset_2d_r:
            raise ValueError(f"Output of {read_$group_dset$.__name__} function cannot be an empty list.")
    except:
        raise

    return dset_2d_r

def has_$group_dset$(trexio_file) -> bool: 
    """Check that $group_dset$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_dset$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise    

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False

interface
   integer function trexio_write_$group_str$_c (trex_file, str, max_str_len) &
           bind(C, name="trexio_write_$group_str$")
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(in) :: str(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_write_$group_str$_c
end interface

interface
   integer function trexio_read_$group_str$_c (trex_file, str, max_str_len) &
           bind(C, name="trexio_read_$group_str$")
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
     character, intent(out) :: str(*)
     integer(4), intent(in), value :: max_str_len
   end function trexio_read_$group_str$_c
end interface

interface
   integer function trexio_has_$group_str$ (trex_file) bind(C)
     use, intrinsic :: iso_c_binding
     integer(8), intent(in), value :: trex_file
   end function trexio_has_$group_str$
end interface

integer function trexio_read_$group_str$ (trex_file, str, max_str_len)
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character, intent(out) :: str(*)

  trexio_read_$group_str$ = trexio_read_$group_str$_c(trex_file, str, max_str_len)

end function trexio_read_$group_str$

integer function trexio_write_$group_str$ (trex_file, str, max_str_len)
  use, intrinsic :: iso_c_binding, only : c_null_char
  implicit none
  integer(8), intent(in), value :: trex_file
  integer(4), intent(in), value :: max_str_len
  character(len=*), intent(in) :: str

  character(len=len_trim(str)+1) :: str_c

  str_c = trim(str) // c_null_char

  trexio_write_$group_str$ = trexio_write_$group_str$_c(trex_file, str_c, max_str_len)

end function trexio_write_$group_str$

def write_$group_str$(trexio_file, str_w: str) -> None: 
    """Write the $group_str$ variable in the TREXIO file.

    Parameters:

    trexio_file:
        TREXIO File object.

    str_w: str
        String corresponding to the $group_str$ variable to be written.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    max_str_length = len(str_w) + 1

    try:
        rc = pytr.trexio_write_$group_str$(trexio_file.pytrexio_s, str_w, max_str_length)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise    

def read_$group_str$(trexio_file) -> str: 
    """Read the $group_str$ variable from the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
        ~str_r~: str
        String corresponding to the $group_str$ variable read from ~trexio_file~.

    Raises:
        - Exception from AssertionError if TREXIO return code ~rc~ is different from TREXIO_SUCCESS and prints the error message using trexio_string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc, str_r = pytr.trexio_read_$group_str$(trexio_file.pytrexio_s, PYTREXIO_MAX_STR_LENGTH)

        if rc != TREXIO_SUCCESS:
            raise Error(rc)
    except:
        raise    

    return str_r

def has_$group_str$(trexio_file) -> bool: 
    """Check that $group_str$ variable exists in the TREXIO file.

    Parameter is a ~TREXIO File~ object that has been created by a call to ~open~ function.

    Returns:
          True if the variable exists, False otherwise

    Raises:
        - Exception from trexio.Error class if TREXIO return code ~rc~ is TREXIO_FAILURE and prints the error message using string_of_error.
        - Exception from some other error (e.g. RuntimeError).
    """

    try:
        rc = pytr.trexio_has_$group_str$(trexio_file.pytrexio_s)
        if rc == TREXIO_FAILURE:
            raise Error(rc)
    except:
        raise    

    if rc == TREXIO_SUCCESS:
        return True
    else:
        return False