# $Id: HDF.py,v 1.3 2005-07-14 01:36:41 gosselin_a Exp $
# $Log: not supported by cvs2svn $
# Revision 1.2  2004/08/02 15:36:04  gosselin
# pyhdf-0.7-1
#
# Revision 1.1  2004/08/02 15:22:59  gosselin
# Initial revision
#
# Author: Andre Gosselin
#         Maurice-Lamontagne Institute
#         gosselina@dfo-mpo.gc.ca

"""
Basic API (:mod:`pyhdf.HDF`)
============================

A module of the pyhdf package implementing the basic API of the
NCSA HDF4 library.

Introduction
------------
The role of the HDF module is to provide support to other modules of the
pyhdf package. It defines constants specifying file opening modes and
various data types, methods for accessing files, plus a few utility
functions to query library version and check if a file is an HDF one.

It should be noted that, among the modules of the pyhdf package, SD is
special in the sense that it is self-contained and does not need support
from the HDF module. For example, SD provides its own file opening and
closing methods, whereas VS uses methods of the HDF.HDF class for that.

Functions and classes summary
-----------------------------
The HDF module provides the following classes.

  HC
      The HC class holds constants defining opening modes and
      various data types.

  HDF
      The HDF class provides methods to open and close an HDF file,
      and return instances of the major HDF APIs (except SD).

      To instantiate an HDF class, call the HDF() constructor.

      methods:
        constructors:
          HDF()     open an HDF file, creating the file if necessary,
                    and return an HDF instance
          vstart()  initialize the VS (Vdata) API over the HDF file and
                    return a VS instance
          vgstart() initialize the V (Vgroup) interface over the HDF file
                    and return a V instance.


        closing file
          close()  close the HDF file

        inquiry
          getfileversion()  return info about the version of the  HDF file

The HDF module also offers the following functions.

  inquiry
    getlibversion()    return info about the version of the library
    ishdf()            determine whether a file is an HDF file


"""

import os, sys, types

from . import hdfext as _C
from .six.moves import xrange
from .HC import HC

# NOTE: The vstart() and vgstart() modules need to access the
#       VS and V modules, resp. We could simply import those
#       two modules, but then they would always be loaded and this
#       may not be what the user wants. Instead of forcing the
#       systematic import, we import the package `pyhdf',
#       and access the needed constructors by writing
#       'pyhdf.VS.VS()' and 'pyhdf.V.V()'. Until the VS or
#       V modules are imported, those statements will give an
#       error (undefined attribute). Once the user has imported
#       the modules, the error will disappear.

import pyhdf

from .error import HDF4Error, _checkErr

# List of names we want to be imported by an "from pyhdf.HDF import *"
# statement

__all__ = ['HDF', 'HDF4Error',
           'HC',
           'getlibversion', 'ishdf']

def getlibversion():
    """Get the library version info.

    Args:
      no argument
    Returns:
      4-element tuple with the following components:
        -major version number (int)
        -minor version number (int)
        -complete library version number (int)
        -additional information (string)

    C library equivalent : Hgetlibversion
                                                   """

    status, major_v, minor_v, release, info = _C.Hgetlibversion()
    _checkErr('getlibversion', status, "cannot get lib version")
    return major_v, minor_v, release, info

def ishdf(filename):
    """Determine whether a file is an HDF file.

    Args:
      filename  name of the file to check
    Returns:
      1 if the file is an HDF file, 0 otherwise

    C library equivalent : Hishdf
                                            """

    return _C.Hishdf(filename)


class HDF(object):
    """The HDF class encapsulates the basic HDF functions.
    Its main use is to open and close an HDF file, and return
    instances of the major HDF APIs (except for SD).
    To instantiate an HDF class, call the HDF() constructor. """

    def __init__(self, path, mode=HC.READ, nblocks=0):
        """HDF constructor: open an HDF file, creating the file if
        necessary.

        Args:
          path    name of the HDF file to open
          mode    file opening mode; this mode is a set of binary flags
                  which can be ored together

                      HC.CREATE   combined with HC.WRITE to create file
                                  if it does not exist
                      HC.READ     open file in read-only access (default)
                      HC.TRUNC    if combined with HC.WRITE, overwrite
                                  file if it already exists
                      HC.WRITE    open file in read-write mode; if file
                                  exists it is updated, unless HC.TRUNC is
                                  set, in which case it is erased and
                                  recreated; if file does not exist, an
                                  error is raised unless HC.CREATE is set,
                                  in which case the file is created

                   Note an important difference in the way CREATE is
                   handled by the HDF C library and the pyhdf package.
                   In the C library, CREATE indicates that a new file should
                   always be created, overwriting an existing one if
                   any. For pyhdf, CREATE indicates a new file should be
                   created only if it does not exist, and the overwriting
                   of an already existing file must be explicitly asked
                   for by setting the TRUNC flag.

                   Those differences were introduced so as to harmonize
                   the way files are opened in the pycdf and pyhdf
                   packages. Also, this solves a limitation in the
                   hdf (and netCDF) library, where there is no easy way
                   to implement the frequent requirement that an existent
                   file be opened in read-write mode, or created
                   if it does not exist.

          nblocks  number of data descriptor blocks in a block with which
                   to create the file; the parameter is ignored if the file
                   is not created; 0 asks to use the default

        Returns:
          an HDF instance

        C library equivalent : Hopen
                                                     """
        # Private attributes:
        #  _id:       file id (NOTE: not compatile with the SD file id)

        # See if file exists.
        exists = os.path.exists(path)

        if HC.WRITE & mode:
            if exists:
                if HC.TRUNC & mode:
                    try:
                        os.remove(path)
                    except Exception as msg:
                        raise HDF4Error(msg)
                    mode = HC.CREATE
                else:
                    mode = HC.WRITE
            else:
                if HC.CREATE & mode:
                    mode = HC.CREATE
                else:
                    raise HDF4Error("HDF: no such file")
        else:
            if exists:
                if mode & HC.READ:
                    mode = HC.READ     # clean mode
                else:
                    raise HDF4Error("HDF: invalid mode")
            else:
                raise HDF4Error("HDF: no such file")

        id = _C.Hopen(path, mode, nblocks)
        _checkErr('HDF', id, "cannot open %s" % path)
        self._id = id


    def __del__(self):
        """Delete the instance, first calling the end() method
        if not already done.          """

        try:
            if self._id:
                self.close()
        except:
            pass

    def close(self):
        """Close the HDF file.

        Args:
          no argument
        Returns:
          None

        C library equivalent : Hclose
                                                """

        _checkErr('close', _C.Hclose(self._id), "cannot close file")
        self._id = None

    def getfileversion(self):
        """Get file version info.

        Args:
          no argument
        Returns:
          4-element tuple with the following components:
            -major version number (int)
            -minor version number (int)
            -complete library version number (int)
            -additional information (string)

        C library equivalent : Hgetlibversion
                                                   """

        status, major_v, minor_v, release, info = _C.Hgetfileversion(self._id)
        _checkErr('getfileversion', status, "cannot get file version")
        return major_v, minor_v, release, info

    def vstart(self):
        """Initialize the VS API over the file and return a VS instance.

        Args:
          no argument
        Returns:
          VS instance

        C library equivalent : Vstart (in fact: Vinitialize)
                                                              """
        # See note at top of file.
        return pyhdf.VS.VS(self)

    def vgstart(self):
        """Initialize the V API over the file and return a V instance.

        Args:
          no argument
        Returns:
          V instance

        C library equivalent : Vstart (in fact: Vinitialize)
                                                              """
        # See note at top of file.
        return pyhdf.V.V(self)



###########################
# Support functions
###########################


def _array_to_ret(buf, nValues):

    # Convert array 'buf' to a scalar or a list.

    if nValues == 1:
        ret = buf[0]
    else:
        ret = []
        for i in xrange(nValues):
            ret.append(buf[i])
    return ret

def _array_to_str(buf, nValues):

    # Convert array of bytes 'buf' to a string.

    # Return empty string if there is no value.
    if nValues == 0:
        return ""
    # When there is just one value, _array_to_ret returns a scalar
    # over which we cannot iterate.
    if nValues == 1:
        chrs = [chr(buf[0])]
    else:
        chrs = [chr(b) for b in _array_to_ret(buf, nValues)]
    # Strip NULL at end
    if chrs[-1] == '\0':
        del chrs[-1]
    return ''.join(chrs)