Struct eccodes::codes_index::CodesIndex

pub struct CodesIndex { /* private fields */ }

Available on crate feature experimental_index only.

Structure representing an index of messages inside a GRIB file

⚠️ WARNING ⚠️ This feature might be unsafe to use, especially in concurrent environments. You should not this feature in any production-like environment (eg. scheduled cluster jobs, web servers). You can read about the issues in module-level documentation.

As GRIB files are binary dumps of message sections, index files encode the precalculated binary location of messages matching a set of keys. Some GRIB files contain thousands of messages, and to facilitate the fast reading of messages, index files are delivered with the files and used to query the binary location of a message and receive handles. Loading GRIB files by reading an index file is required for performance in certain situations.

Typical workflow for using CodesIndex involves:

• creating an index by reading file or constructing an empty one using new_from_keys or read_from_file
• adding GRIB files to the index using add_grib_file (not required if the index is read from file)
• selecting messages by key-value pairs using select
• reading the messages from the GRIB file by creating CodesHandle using CodesHandle::new_from_index

Example

let keys = vec!["shortName", "typeOfLevel"];
let grib_path = Path::new("./data/iceland.grib");
let index = CodesIndex::new_from_keys(&keys)?
    .add_grib_file(grib_path)?
    .select("shortName", "2t")?
    .select("typeOfLevel", "surface")?;

let handle = CodesHandle::new_from_index(index)?;

Implementations

impl CodesIndex

pub fn new_from_keys(keys: &[&str]) -> Result<CodesIndex, CodesError>

Constructs a new CodesIndex without an attached GRIB file.

The function takes as an argument a list of keys that will be (exclusively) used to select messages. To use the index, you need to add GRIB files using add_grib_file method.

Example

let keys = ["shortName", "typeOfLevel", "level", "stepType"];
let index = CodesIndex::new_from_keys(&keys)?;

Errors

This function will return CodesError::Internal if the index cannot be created.

pub fn read_from_file(index_file_path: &Path) -> Result<CodesIndex, CodesError>

Constructs a new CodesIndex by reading an index file at given path.

The path must point to a valid index file created by ecCodes library. GRIB file corresponding to the index file must be present in the same relative path as during the index file creation.

Example

let file_path = Path::new("./data/iceland-surface.grib.idx");
let index = CodesIndex::read_from_file(file_path)?;

Errors

This function will return CodesError::Internal if the index file is not valid or the GRIB file is not present in the same relative path as during the index file creation.

pub fn add_grib_file( self, index_file_path: &Path ) -> Result<CodesIndex, CodesError>

Attaches a GRIB file to the index.

Path must point to a valid GRIB file.

The function will index the file and add it to the index. There might be a performance overhead when adding a big file. Multiple files can be added to the index.

Example

let keys = vec!["shortName", "typeOfLevel", "level", "stepType"];
let index = CodesIndex::new_from_keys(&keys)?;
let grib_path = Path::new("./data/iceland.grib");
let index = index.add_grib_file(grib_path)?;

Errors

Returns CodesError::Internal if the file cannot be added to the index. The error might be also caused by incorrectly constructed index.

Trait Implementations

impl Debug for CodesIndex

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Select<&str> for CodesIndex

fn select(self, key: &str, value: &str) -> Result<CodesIndex, CodesError>

Selects messages from the index by key-value pair. Key must be a valid key present in the CodesIndex and value must be of the same type as the key.

impl Select<f64> for CodesIndex

fn select(self, key: &str, value: f64) -> Result<CodesIndex, CodesError>

Selects messages from the index by key-value pair. Key must be a valid key present in the CodesIndex and value must be of the same type as the key.

impl Select<i64> for CodesIndex

fn select(self, key: &str, value: i64) -> Result<CodesIndex, CodesError>

Selects messages from the index by key-value pair. Key must be a valid key present in the CodesIndex and value must be of the same type as the key.