Struct eccodes::codes_index::CodesIndex
source · pub struct CodesIndex { /* private fields */ }
experimental_index
only.Expand description
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
orread_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
usingCodesHandle::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§
source§impl CodesIndex
impl CodesIndex
sourcepub fn new_from_keys(keys: &[&str]) -> Result<CodesIndex, CodesError>
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.
sourcepub fn read_from_file(index_file_path: &Path) -> Result<CodesIndex, CodesError>
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.
sourcepub fn add_grib_file(
self,
index_file_path: &Path
) -> Result<CodesIndex, CodesError>
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§
source§impl Debug for CodesIndex
impl Debug for CodesIndex
source§impl Select<&str> for CodesIndex
impl Select<&str> for CodesIndex
source§fn select(self, key: &str, value: &str) -> Result<CodesIndex, CodesError>
fn select(self, key: &str, value: &str) -> Result<CodesIndex, CodesError>
CodesIndex
and value must be of the same type as the key. Read moresource§impl Select<f64> for CodesIndex
impl Select<f64> for CodesIndex
source§fn select(self, key: &str, value: f64) -> Result<CodesIndex, CodesError>
fn select(self, key: &str, value: f64) -> Result<CodesIndex, CodesError>
CodesIndex
and value must be of the same type as the key. Read moresource§impl Select<i64> for CodesIndex
impl Select<i64> for CodesIndex
source§fn select(self, key: &str, value: i64) -> Result<CodesIndex, CodesError>
fn select(self, key: &str, value: i64) -> Result<CodesIndex, CodesError>
CodesIndex
and value must be of the same type as the key. Read more