finish readme

Author: Quba1

README.md

@@ -60,58 +60,72 @@ export LD_LIBRARY_PATH=<your_eccodes_path>/lib
 
 ### Working with GRIB files
 
-To access a GRIB file you need to create `CodesHandle` with one of provided constructors.
+To access a GRIB file you need to create `CodesFile` with one of the provided constructors.
 
-GRIB files consist of messages which represent data fields at specific time and level.
-Messages are represented by the `KeyedMessage` structure.
+ecCodes represents GRIB files as a set of separate messages, each containing data fields at specific time and level.
+Messages are represented here by a generic `CodesMessage` structure, but you shouldn't use it directly.
+Instead use `RefMessage`, `ArcMessage` or `BufMessage` to operations - check the docs for more information when to use each.
 
-`CodesHandle` implements `FallibleStreamingIterator`
-which allows you to iterate over messages in the file. The iterator returns `&KeyedMessage` which valid until next iteration.
-`KeyedMessage` implements several methods to access the data as needed, most of those can be called directly on `&KeyedMessage`.
-You can also use `try_clone()` to clone the message and prolong its lifetime.
+To obtain `CodesMessage` from `CodesFile` you need to create an instance of `RefMessageIter` or `ArcMessageIter` using
+`CodesFile::ref_message_iter()` or `CodesFile::arc_message_iter()`.
+Those structures implement `FallibleIterator`, please check its documentation if you are not familiar with it.
 
-Data defining and contained by `KeyedMessage` is represented by `Key`s.
-You can read them directly with `read_key()`, use `KeysIterator`
-to iterate over them or use `CodesNearest` to get the values of four nearest gridpoints for given coordinates.
+`CodesMessage` implements several methods to access the data as needed, most of those can be called directly.
+Almost all methods can be called on any `CodesMessage`, except for `KeyWrite` operations, which can be called only on `BufMessage`
+to avoid confusion if written keys are save to file or not.
 
-You can also modify the message with `write_key()` and write it to a new file with `write_to_file()`.
+Data contained by `CodesMessage` is represented as *keys* (like in dictionary).
+Keys can be read with static types using `read_key()` or with dynamic types
+using `read_key_dynamic()`.
+To discover what keys are present in a message use `KeysIterator`.
 
-#### Example
+With `ndarray` feature (enabled by default) you can also read `CodesMessage` into `ndarray` using `to_ndarray()`
+and `to_lons_lats_values()`.
 
-```rust
-// We are reading the mean sea level pressure for 4 gridpoints
-// nearest to Reykjavik (64.13N, -21.89E) for 1st June 2021 00:00 UTC
-// from ERA5 Climate Reanalysis
+You can use `CodesNearest` to get the data values of four nearest gridpoints for given coordinates.
+
+To modify keys within the message use `write_key_unchecked()`.
+To save that modified message use `write_to_file()`.
 
-use eccodes::{ProductKind, CodesHandle, KeyType};
-use eccodes::FallibleStreamingIterator;
+#### Example 1 - Reading GRIB file
 
-// Open the GRIB file and create the CodesHandle
-let file_path = Path::new("./data/iceland.grib");
-let product_kind = ProductKind::GRIB;
-let mut handle = CodesHandle::new_from_file(file_path, product_kind)?;
+In this example we are reading mean sea level pressure for 4 gridpoints nearest to
+Reykjavik (64.13N, -21.89E) for 1st June 2021 00:00 UTC from ERA5 Climate Reanalysis.
+
+```rust
+use eccodes::{CodesFile, FallibleIterator, KeyRead, ProductKind};
 
+// Open the GRIB file and create the CodesFile
+let mut handle = CodesFile::new_from_file("./data/iceland.grib", ProductKind::GRIB)?;
 // Use iterator to find a message with shortName "msl" and typeOfLevel "surface"
 // We can use while let or for_each() to iterate over the messages
-while let Some(msg) = handle.next()? {
-    if msg.read_key("shortName")?.value == KeyType::Str("msl".to_string())
-        && msg.read_key("typeOfLevel")?.value == KeyType::Str("surface".to_string()) {
-       
+while let Some(msg) = handle.ref_message_iter().next()? {
+    // We need to specify the type of key we read
+    let short_name: String = msg.read_key("shortName")?;
+    let type_of_level: String = msg.read_key("typeOfLevel")?;
+    if short_name == "msl" && type_of_level == "surface" {
         // Create CodesNearest for given message
-        let nearest_gridpoints = msg.codes_nearest()?
+        let nearest_gridpoints = msg
+            .codes_nearest()?
             // Find the nearest gridpoints to Reykjavik
             .find_nearest(64.13, -21.89)?;
         // Print value and distance of the nearest gridpoint
-        println!("value: {}, distance: {}",
-            nearest_gridpoints[3].value,
-            nearest_gridpoints[3].distance);
+        println!(
+            "value: {}, distance: {}",
+            nearest_gridpoints[3].value, nearest_gridpoints[3].distance
+        );
     }
 }
 ```
 
+### Multithreading
+
+Since v0.14 messages inside a file can be read as `ArcMessage` which
+allows to move and share the message across threads.
+
 ### Writing GRIB files
 
-The crate provides a basic support for setting `KeyedMessage` keys
+The crate provides a basic support for setting `CodesMessage` keys
 and writing GRIB files. The easiest (and safest) way to create a
 new custom message is to copy existing one from other GRIB file,
 modify the keys and write to new file.
@@ -125,11 +139,11 @@ This crate aims to return error whenever possible, even if the error is caused b
 As ecCodes is often used in scientific applications with long and extensive jobs,
 this allows the user to handle the error in the way that suits them best and not risk crashes.
 
-All error descriptions are provided in the `errors` module.
-Destructors, which cannot panic, report errors through the `log` crate.
+All error descriptions are provided in the [`errors`] module.
+Destructors, which cannot panic, report errors through `tracing` and `log` crate.
 
 None of the functions in this crate explicitly panics.
-However, users should not that dependencies might panic in some edge cases.
+However, users should be aware that dependencies (eg. `ndarray`) might panic in some edge cases.
 
 ## Safety
 
@@ -139,19 +153,17 @@ Moreover, pointers are always checked for null before being dereferenced.
 That said, neither main developer nor contributors have expertise in unsafe Rust and bugs might have
 slipped through. We are also not responsible for bugs in the ecCodes library.
 
-If you find a bug or have a suggestion, feel free to discuss it on Github.
+**For critical applications always perform extensive testing before using this crate in production.**
 
-## Features
+If you find a bug or have a suggestion, feel free to discuss it on Github.
 
-- `ndarray` - enables support for converting `KeyedMessage` to `ndarray::Array`.
-This feature is enabled by default. It is currently tested only with simple lat-lon grids.
+## Feature Flags
 
-- `experimental_index` - enables support for creating and using index files for GRIB files.
-This feature experimental and disabled by default. If you want to use it, please read
-the information provided in `codes_index` documentation.
+- `ndarray` - enables support for converting [`CodesMessage`](codes_message::CodesMessage) to [`ndarray::Array`].
+   This feature is enabled by default. It is currently tested only with simple lat-lon grids.
 
 - `docs` - builds the crate without linking ecCodes, particularly useful when building the documentation
-on [docs.rs](https://docs.rs/). For more details check documentation of [eccodes-sys](https://crates.io/crates/eccodes-sys).
+   on [docs.rs](https://docs.rs/). For more details check documentation of [eccodes-sys](https://crates.io/crates/eccodes-sys).
 
 To build your own crate with this crate as dependency on docs.rs without linking ecCodes add following lines to your `Cargo.toml`