Struct eccodes::codes_handle::CodesHandle [−][src]
pub struct CodesHandle { /* fields omitted */ }
Expand description
Main structure used to operate on the GRIB file. It takes a full ownership of the accessed file. It can be constructed either using a file or a memory buffer.
Implementations
The constructor that takes a path
to an existing file and
a requested ProductKind
and returns the CodesHandle
object.
Example
let file_path = Path::new("./data/iceland.grib");
let product_kind = ProductKind::GRIB;
let handle = CodesHandle::new_from_file(file_path, product_kind).unwrap();
The function opens the file as File
and then utilises
fdopen()
function
to associate io::RawFd
from File
with a stream represented by libc::FILE
pointer.
The constructor takes a path
as an argument instead of File
to ensure that fdopen()
uses the same mode as File
.
The file descriptor does not take the ownership of a file, therefore the
File
is safely closed when it is dropped.
Errors
Returns CodesError::FileHandlingInterrupted
with io::Error
when the file cannot be opened.
Returns CodesError::LibcNonZero
with errno
information
when the stream cannot be created from the file descriptor.
Returns CodesError::Internal
with error code
when internal codes_handle
cannot be created.
Returns CodesError::NoMessages
when there is no message of requested type
in the provided file.
pub fn new_from_memory(
file_data: Bytes,
product_kind: ProductKind
) -> Result<Self, CodesError>
pub fn new_from_memory(
file_data: Bytes,
product_kind: ProductKind
) -> Result<Self, CodesError>
The constructor that takes data of file present in memory in Bytes
format and
a requested ProductKind
and returns the CodesHandle
object.
Example
let product_kind = ProductKind::GRIB;
let file_data =
reqwest::get("https://github.com/ScaleWeather/eccodes/blob/main/data/iceland.grib?raw=true")
.await
.unwrap()
.bytes()
.await
.unwrap();
let handle = CodesHandle::new_from_memory(file_data, product_kind).unwrap();
The function associates the data in memory with a stream
represented by libc::FILE
pointer
using fmemopen()
function.
The constructor takes a full ownership of the data inside Bytes
,
which is safely dropped during the CodesHandle
drop.
Errors
Returns CodesError::LibcNonZero
with errno
information
when the file stream cannot be created.
Returns CodesError::Internal
with error code
when internal codes_handle
cannot be created.
Returns CodesError::NoMessages
when there is no message of requested type
in the provided file.
Trait Implementations
Executes the destructor for this type.
This method calls fclose()
from libc for graceful cleanup.
Currently it is assumed that under normal circumstances this destructor never fails. However in some edge cases fclose can return non-zero code. In such case all pointers and file descriptors are safely deleted. However memory leaks can still occur.
If any function called in the destructor returns an error warning will appear in log.
If bugs occurs during CodesHandle
drop please enable log output and post issue on Github.
FallibleIterator
implementation for CodesHandle
to access GRIB messages inside file.
To access GRIB messages the ecCodes library uses a method similar to a C-style iterator.
It digests the FILE *
multiple times each time returning the codes_handle
raw pointer
to a message inside the file. This method would be unsafe to expose directly.
Therefore this crate utilizes the Iterator
to provide the access to GRIB messages in
a safe and convienient way.
FallibleIterator
is used instead of classic Iterator
because internal ecCodes functions can return error codes when the GRIB file
is corrupted and for some other reasons. The usage of FallibleIterator
is sligthly different
than usage of Iterator
, check its documentation for more details.
For a true memory safety and to provide a ful Rust Iterator functionality, this iterator clones each message to a new buffer.Although internal ecCodes message copy implementation makes this operation quite cheap, using this iterator (and in effect this crate) comes with memory overhead, but is a necessity for memory safety.
Using the FallibleIterator
is the only way to read KeyedMessage
s from the file.
Its basic usage is simply with while let statement (similar to for loop for classic Iterator
):
let file_path = Path::new("./data/iceland-surface.grib");
let product_kind = ProductKind::GRIB;
let mut handle = CodesHandle::new_from_file(file_path, product_kind).unwrap();
while let Some(message) = handle.next().unwrap() {
let key = message.read_key("name").unwrap();
if let KeyType::Str(name) = key.value {
println!("{:?}", name);
}
}
The FallibleIterator
can be collected to convert the handle into a
Vector
of KeyedMessage
s.
For example:
let file_path = Path::new("./data/iceland-surface.grib");
let product_kind = ProductKind::GRIB;
let handle = CodesHandle::new_from_file(file_path, product_kind).unwrap();
let handle_collected: Vec<KeyedMessage> = handle.collect().unwrap();
Use of filter()
, map()
and other methods provided with Iterator
allow for
more advanced extracting of GRIB messages from the file.
Errors
The next()
method will return CodesInternal
when internal ecCodes function returns non-zero code.
type Item = KeyedMessage
type Item = KeyedMessage
The type being iterated over.
type Error = CodesError
type Error = CodesError
The error type.
Advances the iterator and returns the next value. Read more
Returns bounds on the remaining length of the iterator. Read more
Consumes the iterator, returning the number of remaining items.
Returns the last element of the iterator.
Returns the n
th element of the iterator.
Returns an iterator starting at the same point, but stepping by the given amount at each iteration. Read more
Returns an iterator which yields the elements of this iterator followed by another. Read more
fn zip<I>(
self,
o: I
) -> Zip<Self, <I as IntoFallibleIterator>::IntoFallibleIter> where
I: IntoFallibleIterator<Error = Self::Error>,
fn zip<I>(
self,
o: I
) -> Zip<Self, <I as IntoFallibleIterator>::IntoFallibleIter> where
I: IntoFallibleIterator<Error = Self::Error>,
Returns an iterator that yields pairs of this iterator’s and another iterator’s values. Read more
Returns an iterator which applies a fallible transform to the elements of the underlying iterator. Read more
Calls a fallible closure on each element of an iterator.
Returns an iterator which uses a predicate to determine which values should be yielded. The predicate may fail; such failures are passed to the caller. Read more
Returns an iterator which both filters and maps. The closure may fail; such failures are passed along to the consumer. Read more
Returns an iterator which yields the current iteration count as well as the value. Read more
Returns an iterator that can peek at the next element without consuming it. Read more
Returns an iterator that skips elements based on a predicate.
Returns an iterator that yields elements based on a predicate.
Returns an iterator which skips the first n
values of this iterator.
Returns an iterator that yields only the first n
values of this
iterator. Read more
Returns an iterator which applies a stateful map to values of this iterator. Read more
Returns an iterator which maps this iterator’s elements to iterators, yielding those iterators’ values.
fn flatten(self) -> Flatten<Self> where
Self::Item: IntoFallibleIterator,
<Self::Item as IntoFallibleIterator>::Error == Self::Error,
fn flatten(self) -> Flatten<Self> where
Self::Item: IntoFallibleIterator,
<Self::Item as IntoFallibleIterator>::Error == Self::Error,
Returns an iterator which flattens an iterator of iterators, yielding those iterators’ values.
Returns an iterator which yields this iterator’s elements and ends after
the first Ok(None)
. Read more
Returns an iterator which passes each element to a closure before returning it.
Transforms the iterator into a collection. Read more
Transforms the iterator into two collections, partitioning elements by a closure.
Applies a function over the elements of the iterator, producing a single final value. Read more
Applies a function over the elements of the iterator, producing a single final value. Read more
Determines if all elements of this iterator match a predicate.
Determines if any element of this iterator matches a predicate.
Returns the first element of the iterator that matches a predicate.
Applies a function to the elements of the iterator, returning the first non-None
result.
Returns the position of the first element of this iterator that matches a predicate. The predicate may fail; such failures are returned to the caller. Read more
Returns the maximal element of the iterator.
Returns the element of the iterator which gives the maximum value from the function. Read more
Returns the element that gives the maximum value with respect to the function.
Returns the minimal element of the iterator.
Returns the element of the iterator which gives the minimum value from the function. Read more
Returns the element that gives the minimum value with respect to the function.
Returns an iterator that yields this iterator’s items in the opposite order. Read more
Converts an iterator of pairs into a pair of containers.
Returns an iterator which clones all of its elements.
Returns an iterator which repeas this iterator endlessly.
Lexicographically compares the elements of this iterator to that of another. Read more
fn partial_cmp<I>(self, other: I) -> Result<Option<Ordering>, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
fn partial_cmp<I>(self, other: I) -> Result<Option<Ordering>, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
Lexicographically compares the elements of this iterator to that of another. Read more
Determines if the elements of this iterator are equal to those of another. Read more
Determines if the elements of this iterator are not equal to those of another. Read more
fn lt<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
fn lt<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
Determines if the elements of this iterator are lexicographically less than those of another. Read more
fn le<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
fn le<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
Determines if the elements of this iterator are lexicographically less than or equal to those of another. Read more
fn gt<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
fn gt<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
Determines if the elements of this iterator are lexicographically greater than those of another. Read more
fn ge<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
fn ge<I>(self, other: I) -> Result<bool, Self::Error> where
I: IntoFallibleIterator<Error = Self::Error>,
Self::Item: PartialOrd<<I as IntoFallibleIterator>::Item>,
Determines if the elements of this iterator are lexicographically greater than or equal to those of another. Read more
Returns a normal (non-fallible) iterator over Result<Item, Error>
.
Auto Trait Implementations
impl RefUnwindSafe for CodesHandle
impl !Send for CodesHandle
impl !Sync for CodesHandle
impl Unpin for CodesHandle
impl UnwindSafe for CodesHandle
Blanket Implementations
Mutably borrows from an owned value. Read more
type Item = <I as FallibleIterator>::Item
type Item = <I as FallibleIterator>::Item
The elements of the iterator.
type Error = <I as FallibleIterator>::Error
type Error = <I as FallibleIterator>::Error
The error value of the iterator.
type IntoFallibleIter = I
type IntoFallibleIter = I
The iterator.
Creates a fallible iterator from a value.