Data.Grib.Raw.Index

The grib_index is the structure giving indexed access to messages in a file.

Most of the documentation herein was copied from the official documentation of grib_api.

The GRIB Index

newtype GribIndex

Index structure to access messages in a file.

Constructors

GribIndex (ForeignPtr GribIndex)

gribIndexNewFromFile

Arguments

:: GribContext

context

-> FilePath

name of the file of messages to be indexed

-> [Key]

a list of keys for the index. The type of the key can be explicitly declared appending :l for long, :d for double, :s for string to the key name. If the type is not declared explicitly, the native type is assumed

-> IO GribIndex

an IO action that will return the new index

Create a new index from a file.

The file is indexed with the keys in argument.

gribIndexNew

Arguments

:: GribContext

context

-> [Key]

a list of keys for the index. The type of the key can be explicitly declared appending :l for long, :d for double, :s for string to the key name. If the type is not declared explicitly, the native type is assumed

-> IO GribIndex

an IO action that will return the new index

Create a new index based on a set of keys.

gribIndexAddFile :: GribIndex -> FilePath -> IO ()

Indexes the file given in argument in the index given in argument.

gribIndexWrite :: GribIndex -> FilePath -> IO ()

Write the index and its messages to file.

gribIndexRead :: GribContext -> FilePath -> IO GribIndex

Read messages and their index from a file.

withGribIndex :: GribIndex -> (Ptr GribIndex -> IO b) -> IO b

Get values from the index

gribIndexGetSize :: GribIndex -> Key -> IO Int

Get the number of distinct values of the key in argument contained in the index.

The key must belong to the index.

gribIndexGetLong

Arguments

:: GribIndex

an index created from a file. The index must have been created with the key in argument.

-> Key

key for which the values are returned

-> Ptr CLong

array of values. The array must be allocated before entering this function and its size must be enough to contain all the values.

-> Int

size of the values array

-> IO [Int]

an IO action that will return the data in a list

Get the distinct values of the key in argument contained in the index.

This function is used when the type of the key was explicitly defined as long or when the native type of the key is long.

This function takes the address of an array that is used to retrieve the values. It could potentially be re-used between multiple calls.

gribIndexGetDouble

Arguments

:: GribIndex

an index created from a file. The index must have been created with the key in argument.

-> Key

key for which the values are returned

-> Ptr CDouble

array of values. The array must be allocated before entering this function and its size must be enough to contain all the values.

-> Int

size of the values array

-> IO [Double]

an IO action that will return the data in a list

Get the distinct values of the key in argument contained in the index.

This function is used when the type of the key was explicitly defined as double or when the native type of the key is double.

This function takes the address of an array that is used to retrieve the values. It could potentially be re-used between multiple calls.

gribIndexGetString

Arguments

:: GribIndex

an index created from a file. The index must have been created with the key in argument.

-> Key

key for which the values are returned

-> Ptr CString

array of values. The array must be allocated before entering this function and its size must be enough to contain all the values.

-> Int

size of the values array

-> IO [String]

an IO action that will return the data in a list

Get the distinct values of the key in argument contained in the index.

This function is used when the type of the key was explicitly defined as string or when the native type of the key is string.

This function takes the address of an array that is used to retrieve the values. It could potentially be re-used between multiple calls.

WARNING! This function seem to leak memory unless the returned strings in values are eventually freed with the grib context's free_mem function.

Select values from the index

gribIndexSelectLong :: GribIndex -> Key -> Int -> IO ()

Select the message subset with key==value.

The index must have been created with the key in argument. The value is a long. The key must have been created with long type or have long as native type if the type was not explicitly defined in the index creation.

gribIndexSelectDouble :: GribIndex -> Key -> Double -> IO ()

Select the message subset with key==value.

The index must have been created with the key in argument. The value is a double. The key must have been created with double type or have double as native type if the type was not explicitly defined in the index creation.

gribIndexSelectString :: GribIndex -> Key -> String -> IO ()

Select the message subset with key==value.

The index must have been created with the key in argument. The value is a string. The key must have been created with string type or have string as native type if the type was not explicitly defined in the index creation.

Other functions

gribHandleNewFromIndex :: GribIndex -> IO GribHandle

Create a new handle from an index after having selected the key values.

All the keys belonging to the index must be selected before calling this function. Successive calls to this function will return all the handles compatible with the constraints defined selecting the values of the index keys.

This operation may fail with:

• isGribException GribEndOfIndex when no more handles are available from the index.