Merge #251

251: Add functions to enumerate Drivers r=jdroenner,lnicola a=ttencate

- [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.
---



Co-authored-by: Thomas ten Cate <[email protected]>

Author: bors[bot]

CHANGES.md

@@ -10,6 +10,10 @@
 
   - https://github.com/georust/gdal/pull/267
 
+- **Breaking**: Rename `Driver::get` to `Driver::get_by_name`, add `Driver::get(usize)` and `Driver::count`
+
+  - <https://github.com/georust/gdal/pull/251>
+
 - Add `programs::raster::build_vrt`
 - Add `GeoTransformEx` extension trait with `apply` and `invert`
 
@@ -92,7 +96,7 @@
   - <https://github.com/georust/gdal/pull/193>
 
 ```rust
-let driver = Driver::get("GTiff").unwrap();
+let driver = Driver::get_by_name("GTiff").unwrap();
 let options = &[
     RasterCreationOption {
         key: "COMPRESS",

examples/metadata.rs

@@ -2,7 +2,7 @@ fn main() {
     use gdal::{Dataset, Metadata};
     use std::path::Path;
 
-    let driver = gdal::Driver::get("mem").unwrap();
+    let driver = gdal::Driver::get_by_name("mem").unwrap();
     println!("driver description: {:?}", driver.description());
 
     let path = Path::new("./fixtures/tinymarble.png");

examples/read_write_ogr.rs

@@ -17,7 +17,7 @@ fn run() -> Result<()> {
     // Create a new dataset:
     let path = std::env::temp_dir().join("abcde.shp");
     let _ = fs::remove_file(&path);
-    let drv = Driver::get("ESRI Shapefile")?;
+    let drv = Driver::get_by_name("ESRI Shapefile")?;
     let mut ds = drv.create_vector_only(path.to_str().unwrap())?;
     let lyr = ds.create_layer(Default::default())?;
 

examples/read_write_ogr_datetime.rs

@@ -15,7 +15,7 @@ fn run() -> gdal::errors::Result<()> {
     // Create a new dataset:
     let path = std::env::temp_dir().join("later.geojson");
     let _ = std::fs::remove_file(&path);
-    let drv = Driver::get("GeoJSON")?;
+    let drv = Driver::get_by_name("GeoJSON")?;
     let mut ds = drv.create_vector_only(path.to_str().unwrap())?;
     let lyr = ds.create_layer(Default::default())?;
 

examples/write_ogr.rs

@@ -7,7 +7,7 @@ use std::fs;
 fn example_1() -> Result<()> {
     let path = std::env::temp_dir().join("output1.geojson");
     let _ = fs::remove_file(&path);
-    let drv = Driver::get("GeoJSON")?;
+    let drv = Driver::get_by_name("GeoJSON")?;
     let mut ds = drv.create_vector_only(path.to_str().unwrap())?;
 
     let lyr = ds.create_layer(Default::default())?;
@@ -52,7 +52,7 @@ fn example_1() -> Result<()> {
 fn example_2() -> Result<()> {
     let path = std::env::temp_dir().join("output2.geojson");
     let _ = fs::remove_file(&path);
-    let driver = Driver::get("GeoJSON")?;
+    let driver = Driver::get_by_name("GeoJSON")?;
     let mut ds = driver.create_vector_only(path.to_str().unwrap())?;
     let mut layer = ds.create_layer(Default::default())?;
 

src/dataset.rs

@@ -552,7 +552,7 @@ impl Dataset {
     ///
     /// ```
     /// # use gdal::Driver;
-    /// # let driver = Driver::get("GPKG").unwrap();
+    /// # let driver = Driver::get_by_name("GPKG").unwrap();
     /// # let mut dataset = driver.create_vector_only("/vsimem/example.gpkg").unwrap();
     /// let blank_layer = dataset.create_layer(Default::default()).unwrap();
     /// ```
@@ -562,7 +562,7 @@ impl Dataset {
     /// ```
     /// # use gdal::{Driver, LayerOptions};
     /// # use gdal::spatial_ref::SpatialRef;
-    /// # let driver = Driver::get("GPKG").unwrap();
+    /// # let driver = Driver::get_by_name("GPKG").unwrap();
     /// # let mut dataset = driver.create_vector_only("/vsimem/example.gpkg").unwrap();
     /// let roads = dataset.create_layer(LayerOptions {
     ///     name: "roads",
@@ -720,7 +720,7 @@ impl Dataset {
     /// }
     /// #
     /// # fn main() -> gdal::errors::Result<()> {
-    /// #     let driver = gdal::Driver::get("SQLite")?;
+    /// #     let driver = gdal::Driver::get_by_name("SQLite")?;
     /// #     let mut dataset = driver.create_vector_only(":memory:")?;
     /// #     create_point_grid(&mut dataset)?;
     /// #     assert_eq!(dataset.layer(0)?.features().count(), 10000);

src/driver.rs

@@ -30,7 +30,8 @@ pub struct Driver {
 }
 
 impl Driver {
-    pub fn get(name: &str) -> Result<Driver> {
+    /// Returns the driver with the given short name.
+    pub fn get_by_name(name: &str) -> Result<Driver> {
         _register_drivers();
         let c_name = CString::new(name)?;
         let c_driver = unsafe { gdal_sys::GDALGetDriverByName(c_name.as_ptr()) };
@@ -40,6 +41,24 @@ impl Driver {
         Ok(Driver { c_driver })
     }
 
+    /// Returns the driver with the given index, which must be less than the value returned by
+    /// `Driver::count()`.
+    pub fn get(index: usize) -> Result<Driver> {
+        _register_drivers();
+        let c_driver = unsafe { gdal_sys::GDALGetDriver(index.try_into().unwrap()) };
+        if c_driver.is_null() {
+            return Err(_last_null_pointer_err("GDALGetDriver"));
+        }
+        Ok(Driver { c_driver })
+    }
+
+    /// Returns the number of registered drivers.
+    pub fn count() -> usize {
+        _register_drivers();
+        let count = unsafe { gdal_sys::GDALGetDriverCount() };
+        count.try_into().unwrap()
+    }
+
     /// Creates a new Driver object by wrapping a C pointer
     ///
     /// # Safety

src/raster/tests.rs

@@ -121,7 +121,7 @@ fn test_read_raster_with_average_resample() {
 
 #[test]
 fn test_write_raster() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver.create("", 20, 10, 1).unwrap();
 
     // create a 2x1 raster
@@ -153,7 +153,7 @@ fn test_rename_remove_raster() {
     let mem_file_path_a = Path::new("/vsimem/030bd1d1-8955-4604-8e37-177dade13863");
     let mem_file_path_b = Path::new("/vsimem/c7bfce32-2474-48fa-a907-2af95f83c824");
 
-    let driver = Driver::get("GTiff").unwrap();
+    let driver = Driver::get_by_name("GTiff").unwrap();
 
     dataset.create_copy(&driver, &mem_file_path_a, &[]).unwrap();
 
@@ -179,7 +179,7 @@ fn test_get_dataset_driver() {
 
 #[test]
 fn test_get_description() {
-    let driver = Driver::get("mem").unwrap();
+    let driver = Driver::get_by_name("mem").unwrap();
     assert_eq!(driver.description().unwrap(), "MEM".to_string());
 }
 
@@ -230,7 +230,7 @@ fn test_get_metadata_item() {
 
 #[test]
 fn test_set_metadata_item() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let mut dataset = driver.create("", 1, 1, 1).unwrap();
 
     let key = "Test_Key";
@@ -245,7 +245,7 @@ fn test_set_metadata_item() {
 
 #[test]
 fn test_set_description() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver.create("", 1, 1, 1).unwrap();
     let mut band = dataset.rasterband(1).unwrap();
 
@@ -258,7 +258,7 @@ fn test_set_description() {
 
 #[test]
 fn test_create() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver.create("", 10, 20, 3).unwrap();
     assert_eq!(dataset.raster_size(), (10, 20));
     assert_eq!(dataset.raster_count(), 3);
@@ -267,7 +267,7 @@ fn test_create() {
 
 #[test]
 fn test_create_with_band_type() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver
         .create_with_band_type::<f32, _>("", 10, 20, 3)
         .unwrap();
@@ -280,7 +280,7 @@ fn test_create_with_band_type() {
 
 #[test]
 fn test_create_with_band_type_with_options() {
-    let driver = Driver::get("GTiff").unwrap();
+    let driver = Driver::get_by_name("GTiff").unwrap();
     let options = [
         RasterCreationOption {
             key: "TILED",
@@ -327,7 +327,7 @@ fn test_create_with_band_type_with_options() {
 
 #[test]
 fn test_create_copy() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = Dataset::open(fixture!("tinymarble.png")).unwrap();
     let copy = dataset.create_copy(&driver, "", &[]).unwrap();
     assert_eq!(copy.raster_size(), (100, 50));
@@ -347,7 +347,7 @@ fn test_create_copy_with_options() {
 
     let copy = dataset
         .create_copy(
-            &Driver::get("GTiff").unwrap(),
+            &Driver::get_by_name("GTiff").unwrap(),
             mem_file_path,
             &[
                 RasterCreationOption {
@@ -376,7 +376,7 @@ fn test_create_copy_with_options() {
 #[test]
 #[allow(clippy::float_cmp)]
 fn test_geo_transform() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let mut dataset = driver.create("", 20, 10, 1).unwrap();
     let transform = [0., 1., 0., 0., 0., 1.];
     assert!(dataset.set_geo_transform(&transform).is_ok());
@@ -385,10 +385,10 @@ fn test_geo_transform() {
 
 #[test]
 fn test_get_driver_by_name() {
-    let missing_driver = Driver::get("wtf");
+    let missing_driver = Driver::get_by_name("wtf");
     assert!(missing_driver.is_err());
 
-    let ok_driver = Driver::get("GTiff");
+    let ok_driver = Driver::get_by_name("GTiff");
     assert!(ok_driver.is_ok());
     let driver = ok_driver.unwrap();
     assert_eq!(driver.short_name(), "GTiff");
@@ -486,15 +486,15 @@ fn test_read_block_data() {
 
 #[test]
 fn test_get_band_type() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver.create("", 20, 10, 1).unwrap();
     let rb = dataset.rasterband(1).unwrap();
     assert_eq!(rb.band_type(), GDALDataType::GDT_Byte);
 }
 
 #[test]
 fn test_get_rasterband() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver.create("", 20, 10, 1).unwrap();
     let rasterband = dataset.rasterband(1);
     assert!(rasterband.is_ok());
@@ -518,7 +518,7 @@ fn test_get_no_data_value() {
 #[test]
 #[allow(clippy::float_cmp)]
 fn test_set_no_data_value() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver.create("", 20, 10, 1).unwrap();
     let mut rasterband = dataset.rasterband(1).unwrap();
     assert_eq!(rasterband.no_data_value(), None);
@@ -648,7 +648,7 @@ fn test_get_rasterband_color_interp() {
 
 #[test]
 fn test_set_rasterband_color_interp() {
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let dataset = driver.create("", 1, 1, 1).unwrap();
     let mut rasterband = dataset.rasterband(1).unwrap();
     rasterband
@@ -678,7 +678,7 @@ fn test_rasterize() {
 
     let rows = 5;
     let cols = 5;
-    let driver = Driver::get("MEM").unwrap();
+    let driver = Driver::get_by_name("MEM").unwrap();
     let mut dataset = driver.create("", rows, cols, 1).unwrap();
 
     let bands = [1];

src/vector/vector_tests/mod.rs

@@ -672,7 +672,7 @@ mod tests {
         use std::fs;
 
         {
-            let driver = Driver::get("GeoJSON").unwrap();
+            let driver = Driver::get_by_name("GeoJSON").unwrap();
             let mut ds = driver
                 .create_vector_only(&fixture!("output.geojson"))
                 .unwrap();