Merge #318

318: Filling out `GDALDataType` metadata and utility support. r=metasim a=metasim

- [x] I agree to follow the project's [code of conduct](https://github.com/georust/gdal/blob/master/CODE_OF_CONDUCT.md).
- [x] I added an entry to `CHANGES.md` if knowledge of this change could be valuable to users.
---

Primarily adds `GdalTypeDescriptor` for enabling runtime inspection of `GDALDataType` properties.

**Note, potentially breaking change**: `GDALDataType` is no longer `pub use` in `gdal::raster`, 
  as `GdalType` and `GdalTypeDescriptor` sufficiently cover use cases in safe code. 
  Still accessible via `gdal_sys::GDALDataType`.

---

<img width="740" alt="image" src="https://user-images.githubusercontent.com/131013/197398449-e0c1f448-87ee-498f-b1c2-33625b08c653.png">


Co-authored-by: Simeon H.K. Fitch <fitch@astraea.io>

CHANGES.md

@@ -36,9 +36,16 @@
 
   - <https://github.com/georust/gdal/pull/324>
 
+- Added `GdalTypeDescriptor` to provide access to metadata and supporting routines around `GDALDataType` ordinals.
+- **Breaking**: `GDALDataType` is no longer `pub use` in `gdal::raster`, 
+  as `GdalType` and `GdalTypeDescriptor` sufficiently cover use cases in safe code. 
+  Still accessible via `gdal_sys::GDALDataType`.
+
+  - <https://github.com/georust/gdal/pull/318>
+
 ## 0.13
 
-- Add prebuild bindings for GDAL 3.5
+- Add prebuilt bindings for GDAL 3.5
 
   - <https://github.com/georust/gdal/pull/277>
 

src/driver.rs

@@ -98,7 +98,7 @@ impl Driver {
     /// let ds = d.create("in-memory", 64, 64, 3)?;
     /// assert_eq!(ds.raster_count(), 3);
     /// assert_eq!(ds.raster_size(), (64, 64));
-    /// assert_eq!(ds.rasterband(1)?.band_type(), u8::gdal_type());
+    /// assert_eq!(ds.rasterband(1)?.band_type(), u8::gdal_ordinal());
     /// # Ok(())
     /// # }
     /// ```
@@ -127,7 +127,7 @@ impl Driver {
     /// let ds = d.create_with_band_type::<f64, _>("in-memory", 64, 64, 3)?;
     /// assert_eq!(ds.raster_count(), 3);
     /// assert_eq!(ds.raster_size(), (64, 64));
-    /// assert_eq!(ds.rasterband(1)?.band_type(), f64::gdal_type());
+    /// assert_eq!(ds.rasterband(1)?.band_type(), f64::gdal_ordinal());
     /// # Ok(())
     /// # }
     /// ```
@@ -168,7 +168,7 @@ impl Driver {
     /// ds.set_spatial_ref(&SpatialRef::from_epsg(4326)?)?;
     /// assert_eq!(ds.raster_count(), 1);
     /// assert_eq!(ds.raster_size(), (64, 64));
-    /// assert_eq!(ds.rasterband(1)?.band_type(), u8::gdal_type());
+    /// assert_eq!(ds.rasterband(1)?.band_type(), u8::gdal_ordinal());
     /// assert_eq!(ds.spatial_ref()?.auth_code()?, 4326);
     /// # Ok(())
     /// # }
@@ -212,7 +212,7 @@ impl Driver {
                 size_x as c_int,
                 size_y as c_int,
                 bands as c_int,
-                T::gdal_type(),
+                T::gdal_ordinal(),
                 options_c.as_ptr(),
             )
         };

src/raster/mdarray.rs

@@ -164,7 +164,7 @@ impl<'a> MDArray<'a> {
         let n_dst_buffer_alloc_size = 0;
 
         let rv = unsafe {
-            let data_type = GDALExtendedDataTypeCreate(T::gdal_type());
+            let data_type = GDALExtendedDataTypeCreate(T::gdal_ordinal());
 
             if !self.datatype().class().is_numeric() {
                 return Err(GdalError::UnsupportedMdDataType {

src/raster/mod.rs

@@ -91,7 +91,7 @@ pub use rasterband::{
     StatisticsMinMax,
 };
 pub use rasterize::{rasterize, BurnSource, MergeAlgorithm, OptimizeMode, RasterizeOptions};
-pub use types::{GDALDataType, GdalType};
+pub use types::{AdjustedValue, GdalDataType, GdalType};
 pub use warp::reproject;
 
 /// Key/value pair for passing driver-specific creation options to

src/raster/rasterband.rs

@@ -1,13 +1,14 @@
 use crate::dataset::Dataset;
 use crate::gdal_major_object::MajorObject;
 use crate::metadata::Metadata;
-use crate::raster::{GDALDataType, GdalType};
+use crate::raster::GdalType;
 use crate::utils::{_last_cpl_err, _last_null_pointer_err, _string};
 use gdal_sys::{
     self, CPLErr, GDALColorEntry, GDALColorInterp, GDALColorTableH, GDALComputeRasterMinMax,
-    GDALCreateColorRamp, GDALCreateColorTable, GDALDestroyColorTable, GDALGetPaletteInterpretation,
-    GDALGetRasterStatistics, GDALMajorObjectH, GDALPaletteInterp, GDALRIOResampleAlg, GDALRWFlag,
-    GDALRasterBandH, GDALRasterIOExtraArg, GDALSetColorEntry, GDALSetRasterColorTable,
+    GDALCreateColorRamp, GDALCreateColorTable, GDALDataType, GDALDestroyColorTable,
+    GDALGetPaletteInterpretation, GDALGetRasterStatistics, GDALMajorObjectH, GDALPaletteInterp,
+    GDALRIOResampleAlg, GDALRWFlag, GDALRasterBandH, GDALRasterIOExtraArg, GDALSetColorEntry,
+    GDALSetRasterColorTable,
 };
 use libc::c_int;
 use std::ffi::CString;
@@ -232,7 +233,7 @@ impl<'a> RasterBand<'a> {
     /// use gdal::raster::{GdalType, ResampleAlg};
     /// let dataset = Dataset::open("fixtures/m_3607824_se_17_1_20160620_sub.tif")?;
     /// let band1 = dataset.rasterband(1)?;
-    /// assert_eq!(band1.band_type(), u8::gdal_type());
+    /// assert_eq!(band1.band_type(), u8::gdal_ordinal());
     /// let size = 4;
     /// let mut buf = vec![0; size*size];
     /// band1.read_into_slice::<u8>((0, 0), band1.size(), (size, size), buf.as_mut_slice(), Some(ResampleAlg::Bilinear))?;
@@ -272,7 +273,7 @@ impl<'a> RasterBand<'a> {
                 buffer.as_mut_ptr() as GDALRasterBandH,
                 size.0 as c_int,
                 size.1 as c_int,
-                T::gdal_type(),
+                T::gdal_ordinal(),
                 0,
                 0,
                 options_ptr,
@@ -302,7 +303,7 @@ impl<'a> RasterBand<'a> {
     /// use gdal::raster::{GdalType, ResampleAlg};
     /// let dataset = Dataset::open("fixtures/m_3607824_se_17_1_20160620_sub.tif")?;
     /// let band1 = dataset.rasterband(1)?;
-    /// assert_eq!(band1.band_type(), u8::gdal_type());
+    /// assert_eq!(band1.band_type(), u8::gdal_ordinal());
     /// let size = 4;
     /// let buf = band1.read_as::<u8>((0, 0), band1.size(), (size, size), Some(ResampleAlg::Bilinear))?;
     /// assert_eq!(buf.size, (size, size));
@@ -346,7 +347,7 @@ impl<'a> RasterBand<'a> {
                 data.as_mut_ptr() as GDALRasterBandH,
                 size.0 as c_int,
                 size.1 as c_int,
-                T::gdal_type(),
+                T::gdal_ordinal(),
                 0,
                 0,
                 options_ptr,
@@ -463,7 +464,7 @@ impl<'a> RasterBand<'a> {
                 buffer.data.as_ptr() as GDALRasterBandH,
                 buffer.size.0 as c_int,
                 buffer.size.1 as c_int,
-                T::gdal_type(),
+                T::gdal_ordinal(),
                 0,
                 0,
             )