Struct CslStringList

pub struct CslStringList { /* private fields */ }

Wraps a gdal_sys::CSLConstList (a.k.a. char **papszStrList).

This data structure (a null-terminated array of null-terminated strings) is used throughout GDAL to pass KEY=VALUE-formatted options to various functions.

Example

There are a number of ways to populate a CslStringList:

use gdal::cpl::{CslStringList, CslStringListEntry};

let mut sl1 = CslStringList::new();
sl1.set_name_value("NUM_THREADS", "ALL_CPUS").unwrap();
sl1.set_name_value("COMPRESS", "LZW").unwrap();
sl1.add_string("MAGIC_FLAG").unwrap();

let sl2: CslStringList = "NUM_THREADS=ALL_CPUS COMPRESS=LZW MAGIC_FLAG".parse().unwrap();
let sl3 = CslStringList::from_iter(["NUM_THREADS=ALL_CPUS", "COMPRESS=LZW", "MAGIC_FLAG"]);
let sl4 = CslStringList::from_iter([
    CslStringListEntry::from(("NUM_THREADS", "ALL_CPUS")),
    CslStringListEntry::from(("COMPRESS", "LZW")),
    CslStringListEntry::from("MAGIC_FLAG")
]);

assert_eq!(sl1.to_string(), sl2.to_string());
assert_eq!(sl2.to_string(), sl3.to_string());
assert_eq!(sl3.to_string(), sl4.to_string());

One CslStringList can be combined with another:

use gdal::cpl::CslStringList;
let mut base: CslStringList = "NUM_THREADS=ALL_CPUS COMPRESS=LZW".parse().unwrap();
let debug: CslStringList = "CPL_CURL_VERBOSE=YES CPL_DEBUG=YES".parse().unwrap();
base.extend(&debug);

assert_eq!(base.fetch_name_value("CPL_DEBUG"), Some("YES".into()));

See the CSL* GDAL functions for more details.

Implementations

impl CslStringList

pub fn new() -> Self

Creates an empty GDAL string list.

pub fn add_name_value(&mut self, name: &str, value: &str) -> Result<()>

Assigns value to the key name without checking for a pre-existing assignments.

Returns Ok(()) on success, or Err(GdalError::BadArgument) if name has non-alphanumeric characters or value has newline characters.

See: CSLAddNameValue for details.

pub fn set_name_value(&mut self, name: &str, value: &str) -> Result<()>

Assigns value to the key name, overwriting any existing assignment to name.

Returns Ok(()) on success, or Err(GdalError::BadArgument) if name has non-alphanumeric characters or value has newline characters.

See: CSLSetNameValue for details.

pub fn add_string(&mut self, value: &str) -> Result<()>

Adds a copy of the string slice value to the list.

Returns Ok(()) on success, Err(GdalError::FfiNulError) if value cannot be converted to a C string, e.g. value contains a 0 byte, which is used as a string termination sentinel in C.

See: CSLAddString

pub fn add_entry(&mut self, entry: &CslStringListEntry) -> Result<()>

Adds the contents of a CslStringListEntry to self.

Returns Err(GdalError::BadArgument) if entry doesn’t not meet entry restrictions as described by CslStringListEntry.

pub fn fetch_name_value(&self, name: &str) -> Option<String>

Looks up the value corresponding to name.

See CSLFetchNameValue for details.

pub fn find_string(&self, value: &str) -> Option<usize>

Perform a case insensitive search for the given string

Returns Some(usize) of value index position, or None if not found.

See: CSLFindString for details.

pub fn find_string_case_sensitive(&self, value: &str) -> Option<usize>

Perform a case sensitive search for the given string

Returns Some(usize) of value index position, or None if not found.

See: CSLFindString for details.

pub fn partial_find_string(&self, fragment: &str) -> Option<usize>

Perform a case sensitive partial string search indicated by fragment.

Returns Some(usize) of value index position, or None if not found.

See: CSLPartialFindString for details.

pub fn get_field(&self, index: usize) -> Option<CslStringListEntry>

Fetch the CslStringListEntry for the entry at the given index.

Returns None if index is out of bounds, Some(entry) otherwise.

pub fn len(&self) -> usize

Determine the number of entries in the list.

See: CSLCount for details.

pub fn is_empty(&self) -> bool

Determine if the list has any values

pub fn iter(&self) -> CslStringListIterator<'_>

Get an iterator over the name=value elements of the list.

pub fn as_ptr(&self) -> CSLConstList

Get the raw pointer to the underlying data.

pub fn into_ptr(self) -> CSLConstList

Get the raw pointer to the underlying data, passing ownership (and responsibility for freeing) to the the caller.

Trait Implementations

impl Clone for CslStringList

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CslStringList

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CslStringList

fn default() -> Self

Returns the “default value” for a type.

impl Display for CslStringList

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for CslStringList

fn drop(&mut self)

Executes the destructor for this type.

impl Extend<CslStringListEntry> for CslStringList

fn extend<T: IntoIterator<Item = CslStringListEntry>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'a> FromIterator<&'a str> for CslStringList

fn from_iter<T: IntoIterator<Item = &'a str>>(iter: T) -> Self

Creates a value from an iterator.

impl FromIterator<CslStringListEntry> for CslStringList

fn from_iter<T: IntoIterator<Item = CslStringListEntry>>(iter: T) -> Self

Creates a value from an iterator.

impl FromIterator<String> for CslStringList

fn from_iter<T: IntoIterator<Item = String>>(iter: T) -> Self

Creates a value from an iterator.

impl FromStr for CslStringList

Parse a space-delimited string into a CslStringList.

See CSLTokenizeString for details

type Err = GdalError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<'a> IntoIterator for &'a CslStringList

type Item = CslStringListEntry

The type of the elements being iterated over.

type IntoIter = CslStringListIterator<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl TryFrom<RasterizeOptions> for CslStringList

type Error = GdalError

The type returned in the event of a conversion error.

fn try_from(value: RasterizeOptions) -> Result<CslStringList>

Performs the conversion.