GeoJSON

https://docs.rs/geojson/latest
Admin
This crate provides Rust types and utilities for reading, writing, and parsing GeoJSON data...
Tokens:580,547
Snippets:3,358
Trust Score:9.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Rust Examples for JsonValue Variants

Source: https://docs.rs/geojson/latest/geojson/type.JsonValue

Illustrates the creation of different `JsonValue` variants using the `json!` macro. Each variant is shown with a simple example.

```rust
let v = json!(null);
```

```rust
let v = json!(true);
```

```rust
let v = json!(12.5);
```

```rust
let v = json!("a string");
```

```rust
let v = json!(["an", "array"]);
```

```rust
let v = json!({ "an": "object" });
```

--------------------------------

### Value Deserialization Example

Source: https://docs.rs/geojson/latest/geojson/type.JsonValue_search=std%3A%3Avec

This example demonstrates how to deserialize JSON data into a `Settings` struct using Serde, showcasing the default value handling for optional fields.

```APIDOC
## Value Deserialization Example

### Description
This example demonstrates how to deserialize JSON data into a `Settings` struct using Serde, showcasing the default value handling for optional fields.

### Method
N/A (Illustrative Code)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```rust
use serde_json::Value;

#[derive(Deserialize)]
struct Settings {
    level: i32,
    #[serde(default)]
    extras: Value,
}

let data = r#" { \"level\": 42 } "#;
let s: Settings = serde_json::from_str(data)?;

assert_eq!(s.level, 42);
assert_eq!(s.extras, Value::Null);
```

### Response
#### Success Response (200)
N/A (Illustrative Code)

#### Response Example
```json
{
  "level": 42,
  "extras": null
}
```
```

--------------------------------

### Example: Serializing a Struct to GeoJSON FeatureCollection

Source: https://docs.rs/geojson/latest/geojson/ser/index_search=std%3A%3Avec

This example demonstrates how to define a serializable struct and then convert a collection of these structs into a GeoJSON FeatureCollection string.

```APIDOC
## Example: Struct to GeoJSON FeatureCollection

### Description
This example shows how to define a Rust struct that can be serialized to GeoJSON and then convert a `Vec` of these structs into a GeoJSON FeatureCollection string.

### Method
`geojson::ser::to_feature_collection_string`

### Parameters

*   **`data`** (`&[T]` where `T: Serialize`) - A slice of serializable data structures.

### Request Example
```rust
use serde::Serialize;
use geojson::ser::serialize_geometry;

// Define a struct that can be serialized to GeoJSON
#[derive(Serialize)]
struct MyStruct {
    #[serde(serialize_with = "serialize_geometry")]
    geometry: geo_types::Point<f64>,
    name: String,
    population: u64
}

let my_structs = vec![
    MyStruct {
        geometry: geo_types::Point::new(11.1, 22.2),
        name: "Downtown".to_string(),
        population: 123
    },
    MyStruct {
        geometry: geo_types::Point::new(33.3, 44.4),
        name: "Uptown".to_string(),
        population: 456
    }
];

// Serialize the structs into a GeoJSON FeatureCollection string
let output_geojson = geojson::ser::to_feature_collection_string(&my_structs).unwrap();

println!("{}", output_geojson);
```

### Response Example (Success)
```json
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "coordinates": [11.1, 22.2],
                "type": "Point"
            },
            "properties": {
                "name": "Downtown",
                "population": 123
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "coordinates": [33.3, 44.4],
                "type": "Point"
            },
            "properties": {
                "name": "Uptown",
                "population": 456
            }
        }
    ]
}
```
```

--------------------------------

### Rust Vec<T> Examples: new, with_capacity, try_with_capacity, from_raw_parts

Source: https://docs.rs/geojson/latest/geojson/type.LineStringType_search=u32+-%3E+bool

These examples demonstrate various ways to create and manage `Vec<T>` (a dynamic array or vector) in Rust. `Vec::new()` creates an empty vector, `with_capacity` pre-allocates memory, `try_with_capacity` does the same but returns a Result for fallible allocations (experimental), and `from_raw_parts` reconstructs a vector from raw memory pointers (unsafe). These are fundamental operations for dynamic collections in Rust.

```rust
let mut vec: Vec<i32> = Vec::new();
```

```rust
let mut vec = Vec::with_capacity(10);

assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 10);

for i in 0..10 {
    vec.push(i);
}
assert_eq!(vec.len(), 10);
assert!(vec.capacity() >= 10);

vec.push(11);
assert_eq!(vec.len(), 11);
assert!(vec.capacity() >= 11);

let vec_units = Vec::<()>::with_capacity(10);
assert_eq!(vec_units.capacity(), usize::MAX);
```

```rust
pub unsafe fn from_raw_parts(
    ptr: *mut T,
    length: usize,
    capacity: usize,
) -> Vec<T>
```

--------------------------------

### Create Vec from External Allocation (Rust)

Source: https://docs.rs/geojson/latest/geojson/type.LineStringType_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a `Vec<T>` using memory allocated externally, rather than relying on Rust's default allocator for `Vec`. This example uses `std::alloc::alloc` to get raw memory, then constructs a `Vec` from it using `Vec::from_parts`. The caller must ensure the layout and pointer are valid.

```Rust
#![feature(box_vec_non_null)]

use std::alloc::{alloc, Layout};
use std::ptr::NonNull;

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let Some(mem) = NonNull::new(alloc(layout).cast::<u32>()) else {
            return;
        };

        mem.write(1_000_000);

        Vec::from_parts(mem, 1, 16)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}
```

--------------------------------

### GeoJson Parsing Example

Source: https://docs.rs/geojson/latest/geojson/geojson/enum.GeoJson

Demonstrates how to parse a GeoJSON string into a `GeoJson` enum using `from_str` and extract information.

```APIDOC
## GeoJson Parsing

### Description
This section shows an example of parsing a GeoJSON string into the `GeoJson` enum. It then demonstrates how to match on the `GeoJson` type to access its contents, such as a `FeatureCollection`.

### Method
`from_str` (implemented for `GeoJson`)

### Endpoint
N/A (This is a library function, not a network endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
N/A

### Request Example
```rust
 use geojson::GeoJson;
 use std::str::FromStr;

 let geojson_str = r#"{
   "type": "FeatureCollection",
   "features": [
     {
       "type": "Feature",
       "properties": {},
       "geometry": {
         "type": "Point",
         "coordinates": [
           -0.13583511114120483,
           51.5218870403801
         ]
       }
     }
   ]
 }"#;
 let geo_json = GeoJson::from_str(&geojson_str).unwrap();
 if let GeoJson::FeatureCollection(collection) = geo_json {
     assert_eq!(1, collection.features.len());
 } else {
     panic!("expected feature collection");
 }
```

### Response
#### Success Response (200)
N/A (This is a parsing operation, not an API response)

#### Response Example
N/A
```

--------------------------------

### Using Externally Allocated Memory for Vec (Rust)

Source: https://docs.rs/geojson/latest/geojson/type.LineStringType_search=std%3A%3Avec

This example shows how to create a Vec<T> using memory allocated manually via `std::alloc::alloc`. It highlights the importance of correctly determining the layout, allocating memory, and then using `Vec::from_raw_parts` to construct the Vec. Ensure the allocated memory is valid and meets the capacity requirements for the Vec. The example also demonstrates writing a value into the allocated memory before creating the Vec.

```rust
use std::alloc::{alloc, Layout};

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let mem = alloc(layout).cast::<u32>();
        if mem.is_null() {
            return;
        }

        mem.write(1_000_000);

        Vec::from_raw_parts(mem, 1, 16)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}

```

--------------------------------

### Full GeoJSON FeatureCollection Serialization Example (Rust)

Source: https://docs.rs/geojson/latest/geojson/ser/index

This example demonstrates how to define a struct with a geometry field and other properties, and then serialize a vector of these structs into a GeoJSON FeatureCollection string. It utilizes `serde::Serialize`, `geojson::ser::serialize_geometry`, and `geojson::ser::to_feature_collection_string`.

```rust
use serde::Serialize;
use geojson::ser::serialize_geometry;

#[derive(Serialize)]
struct MyStruct {
    // Serialize as geojson, rather than using the type's default serialization
    #[serde(serialize_with = "serialize_geometry")]
    geometry: geo_types::Point<f64>,
    name: String,
    population: u64
}

let my_structs = vec![
    MyStruct {
        geometry: geo_types::Point::new(11.1, 22.2),
        name: "Downtown".to_string(),
        population: 123
    },
    MyStruct {
        geometry: geo_types::Point::new(33.3, 44.4),
        name: "Uptown".to_string(),
        population: 456
    }
];

let output_geojson = geojson::ser::to_feature_collection_string(&my_structs).unwrap();

// The expected GeoJSON output can be asserted against
let expected_geojson = serde_json::json!(
    {
        "type":"FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": { "coordinates": [11.1,22.2], "type": "Point" },
                "properties": {
                    "name": "Downtown",
                    "population": 123
                }
            },
            {
                "type": "Feature",
                "geometry": { "coordinates": [33.3, 44.4], "type": "Point" },
                "properties": {
                    "name": "Uptown",
                    "population": 456
                }
            }
        ]
    }
);

```

--------------------------------

### GeoJson Parsing Example

Source: https://docs.rs/geojson/latest/geojson/enum.GeoJson

Demonstrates how to parse a GeoJSON string into a GeoJson object using the `from_str` method and extract FeatureCollections.

```APIDOC
## GeoJson Parsing Example

### Description
This example shows how to parse a GeoJSON string into a `GeoJson` object and handle `FeatureCollection`.

### Method
`GeoJson::from_str`

### Endpoint
N/A (This is a library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
 use geojson::GeoJson;
 use std::str::FromStr;

 let geojson_str = r#"{ "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": {}, "geometry": { "type": "Point", "coordinates": [ -0.13583511114120483, 51.5218870403801 ] } } ] }"#;
 let geo_json = GeoJson::from_str(&geojson_str).unwrap();
 if let GeoJson::FeatureCollection(collection) = geo_json {
     assert_eq!(1, collection.features.len());
 } else {
     panic!("expected feature collection");
 }
```

### Response
#### Success Response (200)
N/A (This is a library function, success is indicated by `Result::Ok`)

#### Response Example
N/A
```

--------------------------------

### Rust Tests: Serde JSON Example

Source: https://docs.rs/geojson/latest/src/geojson/feature_writer.rs_search=

Contains test code for `FeatureWriter`, including examples of using `serde_json::json!` macro to create JSON values for assertions.

```rust
    use super::*;
    use crate::JsonValue;

    use serde_json::json;

    // an example struct that we want to serialize
    #[derive(Serialize)]
```

--------------------------------

### Example: Interpret Feature as Custom Struct with geo-types (Rust)

Source: https://docs.rs/geojson/latest/src/geojson/de.rs_search=u32+-%3E+bool

Shows an example of interpreting a GeoJSON `Feature` into a custom struct `MyStruct` using the `from_feature` function. This example uses `geo_types::Point` for the geometry and demonstrates how to deserialize properties into struct fields. It also illustrates the usage of `#[serde(deserialize_with = "deserialize_geometry")]`.

```rust
use serde::Deserialize;
use geojson::Feature;
use geojson::de::{from_feature, deserialize_geometry, deserialize_single_feature};
use std::str::FromStr;

#[derive(Deserialize)]
struct MyStruct {
    // Deserialize `geometry` as GeoJSON, rather than using the type's default deserialization
    #[serde(deserialize_with = "deserialize_geometry")]
    geometry: geo_types::Point,
    name: String,
}

let geojson_str = r#"{ 
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [1.0, 2.0] },
    "properties": {
        "name": "My Name"
    }
}"#;
let feature  = Feature::from_str(geojson_str).unwrap();

let my_struct: MyStruct = from_feature(feature).unwrap();

assert_eq!("My Name", my_struct.name);
assert_eq!(geo_types::Point::new(1.0, 2.0), my_struct.geometry);

```

--------------------------------

### Example Test Struct for Serialization in Rust

Source: https://docs.rs/geojson/latest/src/geojson/feature_writer.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Defines a sample struct `#[derive(Serialize)]` within the `tests` module of the `geojson` crate in Rust. This struct serves as an example for testing serialization functionalities provided by the crate.

```rust
#[derive(Serialize)]
// an example struct that we want to serialize
struct ExampleStruct {}
```

--------------------------------

### GeoJson Parsing Example

Source: https://docs.rs/geojson/latest/geojson/enum.GeoJson_search=u32+-%3E+bool

Demonstrates how to parse a GeoJson string into a `GeoJson` enum and extract a `FeatureCollection`.

```APIDOC
## POST /websites/rs_geojson

### Description
This example shows how to parse a GeoJSON string into the `GeoJson` enum using `GeoJson::from_str`. It then demonstrates how to pattern match to extract a `FeatureCollection` and assert its contents.

### Method
POST

### Endpoint
/websites/rs_geojson

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
 use geojson::GeoJson;
 use std::str::FromStr;

 let geojson_str = r#"{
   "type": "FeatureCollection",
   "features": [
     {
       "type": "Feature",
       "properties": {},
       "geometry": {
         "type": "Point",
         "coordinates": [
           -0.13583511114120483,
           51.5218870403801
         ]
       }
     }
   ]
 }"
 #;
 let geo_json = GeoJson::from_str(&geojson_str).unwrap();
 if let GeoJson::FeatureCollection(collection) = geo_json {
     assert_eq!(1, collection.features.len());
 } else {
     panic!("expected feature collection");
 }
```

### Response
#### Success Response (200)
This endpoint does not return a response body, it's an example of code execution.

#### Response Example
None
```

--------------------------------

### Example: Deserialize GeoJSON FeatureCollection to Vec<MyStruct>

Source: https://docs.rs/geojson/latest/geojson/de/index

This example demonstrates a complete workflow for deserializing a GeoJSON FeatureCollection string into a vector of custom `MyStruct` instances. It includes the necessary `use` statements, struct definition with Serde annotations, and the invocation of `geojson::de::deserialize_feature_collection_str_to_vec`.

```rust
use serde::Deserialize;
use geojson::de::deserialize_geometry;

#[derive(Deserialize)]
struct MyStruct {
    // Deserialize from GeoJSON, rather than expecting the type's default serialization
    #[serde(deserialize_with = "deserialize_geometry")]
    geometry: geo_types::Point<f64>,
    name: String,
    population: u64
}

let input_geojson = serde_json::json!(
    {
        "type":"FeatureCollection",
        "features": [
            {
                "type": "Feature",
                "geometry": { "coordinates": [11.1,22.2], "type": "Point" },
                "properties": {
                    "name": "Downtown",
                    "population": 123
                }
            },
            {
                "type": "Feature",
                "geometry": { "coordinates": [33.3, 44.4], "type": "Point" },
                "properties": {
                    "name": "Uptown",
                    "population": 456
                }
            }
        ]
    }
).to_string();

let my_structs: Vec<MyStruct> = geojson::de::deserialize_feature_collection_str_to_vec(&input_geojson).unwrap();
assert_eq!("Downtown", my_structs[0].name);
assert_eq!(11.1, my_structs[0].geometry.x());

assert_eq!("Uptown", my_structs[1].name);
assert_eq!(33.3, my_structs[1].geometry.x());
```

--------------------------------

### Extend Vec from a Range (Rust)

Source: https://docs.rs/geojson/latest/geojson/type.Bbox_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Illustrates `extend_from_within` which clones a slice specified by a range and appends it to the Vec. Examples cover extending from an open-ended range, a range starting from the beginning, and a closed range for Vec<char>, Vec<i32>, and Vec<String> respectively. This method panics if the range is invalid.

```rust
let mut characters = vec!['a', 'b', 'c', 'd', 'e'];
characters.extend_from_within(2..);
assert_eq!(characters, ['a', 'b', 'c', 'd', 'e', 'c', 'd', 'e']);

let mut numbers = vec![0, 1, 2, 3, 4];
numbers.extend_from_within(..2);
assert_eq!(numbers, [0, 1, 2, 3, 4, 0, 1]);

let mut strings = vec![String::from("hello"), String::from("world"), String::from("!")];
strings.extend_from_within(1..=2);
assert_eq!(strings, ["hello", "world", "!", "world", "!"]);
```

--------------------------------

### Rust: Create Vec with Capacity and Custom Allocator

Source: https://docs.rs/geojson/latest/geojson/type.Bbox_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates creating a `Vec` with a specific initial capacity using a custom allocator. It shows how elements can be added up to the capacity without reallocation and how further additions might trigger reallocation. Also illustrates behavior with zero-sized types.

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut vec = Vec::with_capacity_in(10, System);

// The vector contains no items, even though it has capacity for more
assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 10);

// These are all done without reallocating...
for i in 0..10 {
    vec.push(i);
}
assert_eq!(vec.len(), 10);
assert!(vec.capacity() >= 10);

// ...but this may make the vector reallocate
vec.push(11);
assert_eq!(vec.len(), 11);
assert!(vec.capacity() >= 11);

// A vector of a zero-sized type will always over-allocate, since no
// allocation is necessary
let vec_units = Vec::<(), System>::with_capacity_in(10, System);
assert_eq!(vec_units.capacity(), usize::MAX);

```

--------------------------------

### CloneToUninit Trait Implementation

Source: https://docs.rs/geojson/latest/geojson/struct.Geometry_search=std%3A%3Avec

Details the 'CloneToUninit' trait implementation, an experimental API for cloning into uninitialized memory.

```APIDOC
## impl<T> CloneToUninit for T

### Description
An experimental, nightly-only API for performing copy-assignment from `self` to an uninitialized memory location.

### Method
`unsafe fn clone_to_uninit(&self, dest: *mut u8)`

### Endpoint
N/A (this is a language feature, not an API endpoint)

### Parameters
- **dest** (*mut u8) - A raw pointer to the destination memory location.

### Request Body
None

### Response
This is an unsafe function and does not return a value directly; it performs an action.

### Response Example
N/A
```

--------------------------------

### Rust: Get TypeId

Source: https://docs.rs/geojson/latest/geojson/struct.Geometry_search=

This snippet demonstrates how to get the `TypeId` of a given type in Rust. The `type_id` method is part of the `Any` trait, which is a blanket implementation for types that are 'static and ?Sized.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Rust: Vec creation with specified capacity

Source: https://docs.rs/geojson/latest/geojson/type.Bbox_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to construct a new `Vec<T>` with a specified initial capacity using `Vec::with_capacity()`. This pre-allocates memory to hold at least `capacity` elements, potentially avoiding reallocations during initial insertions. It also includes examples for zero-sized types.

```rust
let mut vec = Vec::with_capacity(10);

// The vector contains no items, even though it has capacity for more
assert_eq!(vec.len(), 0);
assert!(vec.capacity() >= 10);

// These are all done without reallocating...
for i in 0..10 {
    vec.push(i);
}
assert_eq!(vec.len(), 10);
assert!(vec.capacity() >= 10);

// ...but this may make the vector reallocate
vec.push(11);
assert_eq!(vec.len(), 11);
assert!(vec.capacity() >= 11);

// A vector of a zero-sized type will always over-allocate, since no
// allocation is necessary
let vec_units = Vec::<()>::with_capacity(10);
assert_eq!(vec_units.capacity(), usize::MAX);
```

--------------------------------

### Get Map Length and Check if Empty - Rust

Source: https://docs.rs/geojson/latest/geojson/type.JsonObject_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides simple utility methods for `JsonObject` to get the number of elements currently stored in the map and to check if the map is empty.

```rust
pub fn len(&self) -> usize;

pub fn is_empty(&self) -> bool;
```

--------------------------------

### Value Conversions

Source: https://docs.rs/geojson/latest/geojson/type.JsonValue_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates conversions from various Rust types to Serde JSON `Value`.

```APIDOC
## Value Conversions

This section details how various Rust data types can be converted into the `serde_json::Value` enum.

### From `Map` to `Value::Object`

Converts a `serde_json::Map` into a `Value::Object`.

#### Example
```rust
use serde_json::{Map, Value};

let mut m = Map::new();
m.insert("Lorem".to_owned(), "ipsum".into());
let x: Value = m.into();
```

### From `Number` to `Value::Number`

Converts a `serde_json::Number` into a `Value::Number`.

#### Example
```rust
use serde_json::{Number, Value};

let n = Number::from(7);
let x: Value = n.into();
```

### From `Option<T>` to `Value`

Converts an `Option<T>` into a `Value`, where `T` can be converted into `Value`.

### From `String` to `Value::String`

Converts a `String` into a `Value::String`.

#### Example
```rust
use serde_json::Value;

let s: String = "lorem".to_owned();
let x: Value = s.into();
```

### From `Vec<T>` to `Value::Array`

Converts a `Vec<T>` into a `Value::Array`, where `T` can be converted into `Value`.

#### Example
```rust
use serde_json::Value;

let v = vec!["lorem", "ipsum", "dolor"];
let x: Value = v.into();
```

### From `bool` to `Value::Bool`

Converts a boolean into a `Value::Bool`.

#### Example
```rust
use serde_json::Value;

let b = false;
let x: Value = b.into();
```

### From `f32` to `Value::Number`

Converts a 32-bit floating-point number into `Value::Number`, or `Value::Null` if infinite or NaN.

#### Example
```rust
use serde_json::Value;

let f: f32 = 13.37;
let x: Value = f.into();
```

### From `f64` to `Value::Number`

Converts a 64-bit floating-point number into `Value::Number`, or `Value::Null` if infinite or NaN.

#### Example
```rust
use serde_json::Value;

let f: f64 = 13.37;
let x: Value = f.into();
```

### From various integer types (`i16`, `i32`, `i64`, `i8`, `isize`, `u16`, `u32`, `u64`, `u8`, `usize`) to `Value`

These integer types can be converted directly into `Value`.

### From `Iterator<(K, V)>` to `Value::Object`

Creates a `Value::Object` by collecting an iterator of key-value pairs, where keys are convertible to `String` and values to `Value`.

#### Example
```rust
use serde_json::Value;

let v: Vec<_> = vec![("lorem", 40), ("ipsum", 2)];
let x: Value = v.into_iter().collect();
```

### From `Iterator<T>` to `Value::Array`

Creates a `Value::Array` by collecting an iterator of elements, where each element is convertible to `Value`.

#### Examples
```rust
use serde_json::Value;

let v = std::iter::repeat(42).take(5);
let x: Value = v.collect();
```

```rust
use serde_json::Value;

let v: Vec<_> = vec!["lorem", "ipsum", "dolor"];
let x: Value = v.into_iter().collect();
```

```rust
use std::iter::FromIterator;
use serde_json::Value;

let x: Value = Value::from_iter(vec!["lorem", "ipsum", "dolor"]);
```
```

--------------------------------

### Creating Vec from External Allocation in Rust

Source: https://docs.rs/geojson/latest/geojson/type.Bbox_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This Rust example demonstrates creating a `Vec<u32>` from memory allocated using `std::alloc::alloc`. It shows how to allocate memory, write a value, and then construct a `Vec` with a specific length and capacity, emphasizing the `unsafe` block for memory operations.

```Rust
use std::alloc::{alloc, Layout};

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let mem = alloc(layout).cast::<u32>();
        if mem.is_null() {
            return;
        }

        mem.write(1_000_000);

        Vec::from_raw_parts(mem, 1, 16)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}
```

--------------------------------

### Rust Example: Converting geo_types Point to GeoJSON Value

Source: https://docs.rs/geojson/latest/src/geojson/geometry.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This example demonstrates how to convert a `geo_types::Point` into a `geojson::Value::Point` variant. It utilizes the `From` trait implementation, showcasing the interoperability between `geo_types` and `rs_geojson`.

```Rust
/// A `Value` can be created by using the `From` impl which is available for both `geo_types`
/// primitives AND `geo_types::Geometry` enum members:
///
/// ```rust
/// # #[cfg(feature = "geo-types")]
/// # fn test() {
/// let point = geo_types::Point::new(2., 9.);
/// let genum = geo_types::Geometry::from(point);
/// assert_eq!(
///     geojson::Value::from(&point),
///     geojson::Value::Point(vec![2., 9.]),
/// );
/// assert_eq!(
///     geojson::Value::from(&genum),
///     geojson::Value::Point(vec![2., 9.]),
/// );
/// # }
/// # #[cfg(not(feature = "geo-types"))]
/// # fn test() {}
/// # test()
/// ```
```

--------------------------------

### Rust: Constructing a Geometry Object

Source: https://docs.rs/geojson/latest/geojson/struct.Geometry

Demonstrates how to create a new Geometry object using the `Geometry::new` constructor with a `Value::Point`.

```rust
use geojson::{Geometry, Value};

let geometry = Geometry::new(Value::Point(vec![7.428959, 1.513394]));
```

--------------------------------

### Get Raw Pointer to Vec Buffer in Rust

Source: https://docs.rs/geojson/latest/geojson/type.LineStringType_search=std%3A%3Avec

Explains how to get a raw, immutable pointer to the vector's underlying buffer using `as_ptr`. The caller must ensure the vector outlives the pointer and that the memory is not mutated through this pointer or derived pointers.

```rust
let v = vec![10, 20, 30];
let ptr = v.as_ptr();
// Use ptr carefully, ensuring v is still valid and memory isn't mutated.
```

--------------------------------

### Rust: Create Vec with capacity and error handling (Nightly)

Source: https://docs.rs/geojson/latest/geojson/type.LineStringType_search=std%3A%3Avec

Shows how to construct a vector with a specified capacity using the experimental `Vec::try_with_capacity()` function. This returns a `Result` to handle potential allocation errors.

```Rust
#![feature(try_reserve)]
// This is a nightly-only experimental API.
// pub fn try_with_capacity(capacity: usize) -> Result<Vec<T>, TryReserveError>
```

--------------------------------

### Rust: Get Value from JSON Object or Array using Index

Source: https://docs.rs/geojson/latest/geojson/type.JsonValue_search=

This Rust code demonstrates retrieving a value from a JSON `Value` using the `get` method. It supports both string keys for objects and usize indices for arrays, returning `Option<&Value>`.

```Rust
let object = json!({ "A": 65, "B": 66, "C": 67 });
assert_eq!(*object.get("A").unwrap(), json!(65));

let array = json!([ "A", "B", "C" ]);
assert_eq!(*array.get(2).unwrap(), json!("C"));

assert_eq!(array.get("A"), None);
```

--------------------------------

### Example: Parse GeoJSON FeatureCollection from String in Rust

Source: https://docs.rs/geojson/latest/src/geojson/geojson.rs_search=

Demonstrates how to parse a GeoJSON FeatureCollection from a string literal using `GeoJson::from_str`. It then checks if the parsed object is indeed a FeatureCollection and asserts the number of features within it. This example highlights practical usage of the `FromStr` implementation.

```rust
use geojson::GeoJson;
use std::str::FromStr;

let geojson_str = r#"{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Point",
        "coordinates": [
          -0.13583511114120483,
          51.5218870403801
        ]
      }
    }
  ]
}"
#;
let geo_json = GeoJson::from_str(&geojson_str).unwrap();
if let GeoJson::FeatureCollection(collection) = geo_json {
    assert_eq!(1, collection.features.len());
} else {
    panic!("expected feature collection");
}
```

--------------------------------

### Create GeoJSON Feature with Point Geometry and Properties

Source: https://docs.rs/geojson/latest/src/geojson/lib.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to construct a GeoJSON Feature with a point geometry and associated properties. It utilizes the `geojson` crate and relies on `serde_json` for property management. The resulting Feature is then converted to a string.

```rust
use geojson::{Feature, GeoJson, Geometry, Value};

fn get_properties() -> ::geojson::JsonObject {
    let mut properties = ::geojson::JsonObject::new();
    properties.insert(
        String::from("name"),
        ::geojson::JsonValue::from("Firestone Grill"),
    );
    properties
}

fn main() {
    let geometry = Geometry::new(Value::Point(vec![-120.66029, 35.2812]));

    let geojson = GeoJson::Feature(Feature {
        bbox: None,
        geometry: Some(geometry),
        id: None,
        // See the next section about Feature properties
        properties: Some(get_properties()),
        foreign_members: None,
    });

    let geojson_string = geojson.to_string();
}
```

--------------------------------

### Create Vec from External Allocation with Global Allocator (Rust)

Source: https://docs.rs/geojson/latest/geojson/type.Bbox_search=std%3A%3Avec

Demonstrates creating a Vec from memory allocated by the global allocator. This example highlights the `unsafe` nature of `from_raw_parts_in` and the necessity of ensuring the memory meets the Vec's requirements.

```rust
#![feature(allocator_api)]

use std::alloc::{AllocError, Allocator, Global, Layout};

fn main() {
    let layout = Layout::array::<u32>(16).expect("overflow cannot happen");

    let vec = unsafe {
        let mem = match Global.allocate(layout) {
            Ok(mem) => mem.cast::<u32>().as_ptr(),
            Err(AllocError) => return,
        };

        mem.write(1_000_000);

        Vec::from_raw_parts_in(mem, 1, 16, Global)
    };

    assert_eq!(vec, &[1_000_000]);
    assert_eq!(vec.capacity(), 16);
}

```

--------------------------------

### Vec Push Methods

Source: https://docs.rs/geojson/latest/geojson/type.LineStringType

Documentation for various `push` methods on Rust's Vec type, used for appending elements.

```APIDOC
## `push` Method

### Description
Appends an element to the back of the vector.

### Method
`push`

### Parameters
- `value` (T) - The element to append.

### Panics
Panics if the new capacity exceeds `isize::MAX` bytes.

### Request Example
```rust
let mut vec = vec![1, 2];
vec.push(3);
assert_eq!(vec, [1, 2, 3]);
```

### Time complexity
Amortized O(1). O(capacity) when reallocation occurs.

## `push_within_capacity` Method

### Description
Appends an element if there is sufficient spare capacity; otherwise, an error is returned with the element. This method does not reallocate.

### Method
`push_within_capacity`

### Parameters
- `value` (T) - The element to append.

### Returns
- `Ok(())` if the element was successfully appended.
- `Err(T)` with the original element if there was insufficient capacity.

### Request Example
```rust
#![feature(vec_push_within_capacity)]
use std::collections::TryReserveError;
fn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {
    let mut vec = Vec::new();
    for value in iter {
        if let Err(value) = vec.push_within_capacity(value) {
            vec.try_reserve(1)?;
            let _ = vec.push_within_capacity(value);
        }
    }
    Ok(vec)
}
assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));
```

### Time complexity
O(1).

## `push_mut` Method

### Description
Appends an element to the back of the vector and returns a mutable reference to it.

### Method
`push_mut`

### Parameters
- `value` (T) - The element to append.

### Returns
- `&mut T` - A mutable reference to the appended element.

### Panics
Panics if the new capacity exceeds `isize::MAX` bytes.

### Request Example
```rust
#![feature(push_mut)]
let mut vec = vec![1, 2];
let last = vec.push_mut(3);
assert_eq!(*last, 3);
assert_eq!(vec, [1, 2, 3]);
```

### Time complexity
Amortized O(1). O(capacity) when reallocation occurs.

## `push_mut_within_capacity` Method

### Description
Appends an element and returns a mutable reference to it if there is sufficient spare capacity; otherwise, an error is returned with the element. This method does not reallocate.

### Method
`push_mut_within_capacity`

### Parameters
- `value` (T) - The element to append.

### Returns
- `Ok(&mut T)` - A mutable reference to the appended element if successful.
- `Err(T)` - The original element if there was insufficient capacity.

### Request Example
```rust
// Example usage would be similar to push_within_capacity but returning a mutable reference on success.
```
```

--------------------------------

### Vec Creation (Nightly)

Source: https://docs.rs/geojson/latest/geojson/type.LineStringType_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

APIs for creating new Vec instances with specific allocators (nightly-only).

```APIDOC
## Vec Creation (Nightly)

### Description
This section covers nightly-only experimental APIs for creating `Vec<T, A>` instances with custom allocators.

### `new_in` API

#### Description
Constructs a new, empty `Vec<T, A>`. The vector will not allocate until elements are pushed onto it.

#### Method
`new_in`

#### Endpoint
N/A (Method within Vec<T, A>)

#### Parameters
*   `alloc`: The allocator to use for the vector.

#### Request Example
```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut vec: Vec<i32, _> = Vec::new_in(System);
```

### `with_capacity_in` API

#### Description
Constructs a new, empty `Vec<T, A>` with at least the specified capacity using the provided allocator. The vector will be able to hold at least `capacity` elements without reallocating. This method is allowed to allocate for more elements than `capacity`. If `capacity` is zero, the vector will not allocate.

It is important to note that although the returned vector has the minimum _capacity_ specified, the vector will have a zero _length_.

For `Vec<T, A>` where `T` is a zero-sized type, there will be no allocation and the capacity will always be `usize::MAX`.

#### Method
`with_capacity_in`

#### Endpoint
N/A (Method within Vec<T, A>)

#### Parameters
*   `capacity`: The minimum capacity for the new vector.
*   `alloc`: The allocator to use for the vector.

#### Request Example
```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut vec = Vec::with_capacity_in::<i32, _>(10, System);
```

##### §Panics
Panics if the new capacity exceeds `isize::MAX` _bytes_.
```

--------------------------------

### GET /vectors/is_empty

Source: https://docs.rs/geojson/latest/geojson/type.PolygonType

Checks if a vector is empty.

```APIDOC
## GET /vectors/is_empty

### Description
Returns `true` if the vector contains no elements, `false` otherwise.

### Method
GET

### Endpoint
/vectors/is_empty

### Parameters
#### Query Parameters
* **vec** (array) - The vector to check.

### Request Example
```json
{
  "vec": []
}
```

### Response
#### Success Response (200)
* **is_empty** (boolean) - `true` if the vector is empty, `false` otherwise.

#### Response Example
```json
{
  "is_empty": true
}
```
```

--------------------------------

### Rust: Get Raw Pointer to Vec Buffer with as_ptr

Source: https://docs.rs/geojson/latest/geojson/type.PolygonType_search=std%3A%3Avec

Explains how to get a raw pointer to the vector's buffer using `as_ptr`. This method is useful for low-level memory manipulation but requires careful handling to ensure pointer validity and prevent data races.

```rust
let v = vec![1, 2, 3];
let ptr = v.as_ptr();
```

--------------------------------

### Any Trait Implementation

Source: https://docs.rs/geojson/latest/geojson/struct.Geometry_search=std%3A%3Avec

Details the 'Any' trait implementation in Rust, which provides runtime type information.

```APIDOC
## impl<T> Any for T

### Description
Provides runtime type information for any statically sized type.

### Method
`type_id(&self) -> TypeId`

### Endpoint
N/A (this is a language feature, not an API endpoint)

### Parameters
None

### Request Body
None

### Response
#### Success Response (N/A)
- **TypeId** (TypeId) - A unique identifier for the type of the object.

#### Response Example
N/A
```

--------------------------------

### Rust: Mutably Get Value from JSON Object or Array

Source: https://docs.rs/geojson/latest/geojson/type.JsonValue_search=

This Rust code demonstrates how to get a mutable reference to a value within a JSON `Value` using `get_mut`. It supports string keys for objects and usize indices for arrays, returning `Option<&mut Value>`.

```Rust
let mut object = json!({ "A": 65, "B": 66, "C": 67 });
*object.get_mut("A").unwrap() = json!(69);

let mut array = json!([ "A", "B", "C" ]);
*array.get_mut(2).unwrap() = json!("D");
```

--------------------------------

### Borrow and BorrowMut Trait Implementations

Source: https://docs.rs/geojson/latest/geojson/struct.Geometry_search=std%3A%3Avec

Explains the 'Borrow' and 'BorrowMut' trait implementations for immutable and mutable borrowing.

```APIDOC
## impl<T> Borrow<T> for T

### Description
Provides immutable borrowing capabilities.

### Method
`borrow(&self) -> &T`

### Endpoint
N/A (this is a language feature, not an API endpoint)

### Parameters
None

### Request Body
None

### Response
#### Success Response (N/A)
- **&T** (&T) - An immutable reference to the borrowed value.

#### Response Example
N/A

## impl<T> BorrowMut<T> for T

### Description
Provides mutable borrowing capabilities.

### Method
`borrow_mut(&mut self) -> &mut T`

### Endpoint
N/A (this is a language feature, not an API endpoint)

### Parameters
None

### Request Body
None

### Response
#### Success Response (N/A)
- **&mut T** (&mut T) - A mutable reference to the borrowed value.

#### Response Example
N/A
```

--------------------------------

### Deserialize GeoJSON FeatureCollection with Custom Structs - Rust

Source: https://docs.rs/geojson/latest/src/geojson/de.rs_search=

This example shows how to deserialize a GeoJSON FeatureCollection string into a vector of custom structs using `geojson::de::deserialize_geometry` for the geometry field. It handles cases where the `geo-types` feature might not be enabled, using `cfg_attr` for conditional compilation of documentation examples.

```rust
#[derive(Deserialize)]
struct MyStruct {
    #[serde(deserialize_with = "deserialize_geometry")]
    geometry: geo_types::Point<f64>,
    name: String,
}

let feature_collection_str = r#"{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": { "type": "Point", "coordinates": [11.1, 22.2] },
            "properties": { "name": "Downtown" }
        },
        {
            "type": "Feature",
            "geometry": { "type": "Point", "coordinates": [33.3, 44.4] },
            "properties": { "name": "Uptown" }
        }
    ]
}"#;
let reader = feature_collection_str.as_bytes();

// enumerate over the features in the feature collection
```

--------------------------------

### Get Raw Pointer to Vec Buffer in Rust

Source: https://docs.rs/geojson/latest/geojson/type.Bbox_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Explains how to get a raw pointer (`*const T`) to the beginning of the Vec's buffer using `as_ptr`. This method is for advanced use cases and requires careful handling to avoid undefined behavior, especially regarding aliasing rules and pointer validity.

```rust
let v = vec![1, 2, 3];
let ptr = v.as_ptr();
// Use ptr carefully...
```

--------------------------------

### Construct GeoJSON Geometry in Rust

Source: https://docs.rs/geojson/latest/geojson/struct.Geometry_search=std%3A%3Avec

Demonstrates how to construct a `Geometry` object in Rust, primarily by initializing it with a `Value` (e.g., `Value::Point`). Geometries can also be created directly from `Value`s using the `into()` method.

```rust
use geojson::{Geometry, Value};

let geometry = Geometry::new(Value::Point(vec![7.428959, 1.513394]));
```

```rust
let geometry1: Geometry = Value::Point(vec![7.428959, 1.513394]).into();
```

--------------------------------

### Rust GeoJSON Feature Serialization Example

Source: https://docs.rs/geojson/latest/src/geojson/de.rs

This Rust code snippet demonstrates the serialization of GeoJSON data, specifically focusing on Feature objects with Point geometries and associated properties. It includes assertions to verify the generated JSON output against an expected structure. This example is useful for validating GeoJSON output in Rust applications.

```rust
#[cfg(test)]
mod tests {
    use super::*; // Assuming GeoJsonFeature and related structs are defined in the parent module
    use serde_json::json;

    #[test]
    fn test_geojson_serialization() {
        // Define the expected GeoJSON output as a Serde JSON value
        let expected_output_json = json!([
            {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [126.6, 10.1]
                },
                "properties": {
                    "name": "Dinagat Islands",
                    "age": 124
                }
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [3.3, 4.5]
                },
                "properties": {
                    "name": "Neverland",
                    "age": 457
                }
            }
        ]);

        // Assume 'actual_output_json' is a Serde JSON value generated from your GeoJSON data structure
        // For demonstration purposes, let's create a placeholder for actual_output_json
        // In a real scenario, this would come from serializing your Rust GeoJSON objects.
        let actual_output_json = json!([
            {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [126.6, 10.1]
                },
                "properties": {
                    "name": "Dinagat Islands",
                    "age": 124
                }
            },
            {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [3.3, 4.5]
                },
                "properties": {
                    "name": "Neverland",
                    "age": 457
                }
            }
        ]);

        assert_eq!(actual_output_json, expected_output_json);
    }
}

```

--------------------------------

### Rust Trait Implementations: CloneToUninit, From, Into

Source: https://docs.rs/geojson/latest/geojson/struct.Geometry_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This snippet includes blanket implementations for `CloneToUninit`, `From`, and `Into` traits. `CloneToUninit` (experimental) allows cloning to uninitialized memory. `From` provides a conversion into a type, and `Into` provides a conversion from a type.

```rust
impl<T: Clone> CloneToUninit for T {
    unsafe fn clone_to_uninit(&self, dest: *mut u8);
}

impl<T> From<T> for T {
    fn from(t: T) -> T;
}

impl<T, U> Into<U> for T where U: From<T> {
    fn into(self) -> U;
}
```
Tokens:
Raw