### Example: Flush and Write to MmapRaw

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapRaw

Demonstrates creating a memory map using MmapRaw, writing data to it via a mutable slice, and flushing the changes to disk. This example utilizes `std::fs::OpenOptions`, `std::io::Write`, and `std::slice`.

```rust
use std::fs::OpenOptions;
use std::io::Write;
use std::path::PathBuf;
use std::slice;

use memmap2::MmapRaw;

let tempdir = tempfile::tempdir()?;
let path: PathBuf = /* path to file */
let file = OpenOptions::new().read(true).write(true).create(true).truncate(true).open(&path)?;
file.set_len(128)?;

let mut mmap = unsafe { MmapRaw::map_raw(&file)? };

let mut memory = unsafe { slice::from_raw_parts_mut(mmap.as_mut_ptr(), 128) };
memory.write_all(b"Hello, world!")?;
mmap.flush()?;
```

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

### Create Read-Only Memory Map from File (Rust Example)

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Demonstrates how to create a read-only memory map from a file using `MmapOptions`. This example opens a file, creates an `Mmap` instance, and then asserts that the initial bytes match the expected header. The `unsafe` block is required due to the nature of memory mapping.

```Rust
use memmap2::MmapOptions;
use std::io::Write;
use std::fs::File;

# fn main() -> std::io::Result<()> {
let file = File::open("README.md")?;
let mmap = unsafe { MmapOptions::new().map(&file)? };
assert_eq!(b"# memmap2", &mmap[0..9]);
# Ok(())
# }

```

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

### Create MmapOptions Builder - Rust

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Initializes a new builder for configuring memory map options. This is the starting point for creating memory maps with custom settings. Dependencies include the `memmap2` crate.

```rust
/// Creates a new set of options for configuring and creating a memory map.
///
/// # Example
///
/// ```
/// use memmap2::{MmapMut, MmapOptions};
/// # use std::io::Result;
///
/// # fn main() -> Result<()> {
/// // Create a new memory map builder.
/// let mut mmap_options = MmapOptions::new();
///
/// // Configure the memory map builder using option setters, then create
/// // a memory map using one of `mmap_options.map_anon`, `mmap_options.map`,
/// // `mmap_options.map_mut`, `mmap_options.map_exec`, or `mmap_options.map_copy`:
/// let mut mmap: MmapMut = mmap_options.len(36).map_anon()?;
///
/// // Use the memory map:
/// mmap.copy_from_slice(b"...data to copy to the memory map...");
/// # Ok(())
/// # }
/// ```
pub fn new() -> MmapOptions {
    MmapOptions::default()
}
```

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

### MmapRaw Pointer Access

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapRaw

Documentation for methods to get raw pointers to the memory-mapped buffer.

```APIDOC
## pub fn as_ptr(&self) -> *const u8

### Description
Returns a raw pointer to the memory mapped file. Before dereferencing this pointer, you have to make sure that the file has not been truncated since the memory map was created. Avoiding this will not introduce memory safety issues in Rust terms, but will cause SIGBUS (or equivalent) signal.

### Method
`pub fn as_ptr(&self) -> *const u8`

## pub fn as_mut_ptr(&self) -> *mut u8

### Description
Returns an unsafe mutable pointer to the memory mapped file. Before dereferencing this pointer, you have to make sure that the file has not been truncated since the memory map was created. Avoiding this will not introduce memory safety issues in Rust terms, but will cause SIGBUS (or equivalent) signal.

### Method
`pub fn as_mut_ptr(&self) -> *mut u8`
```

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

### Create Copy-on-Write Memory Map using memmap2::map_copy

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapOptions

This example shows how to create a copy-on-write memory map from a file using `MmapOptions::map_copy`. It opens a file and creates a memory map where writes are isolated and not reflected in the original file. The example then writes data to the memory map, demonstrating that modifications are local to the map. This is useful for scenarios where you need to modify file data temporarily without altering the source file.

```rust
use memmap2::MmapOptions;
use std::fs::File;
use std::io::Write;

let file = File::open("LICENSE-APACHE")?;
let mut mmap = unsafe { MmapOptions::new().map_copy(&file)? };
(&mut mmap[..]).write_all(b"Hello, world!")?;
```

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

### Get element offset from slice pointer (Rust - Experimental)

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Returns the index of an element within a slice given a reference to that element. It uses pointer arithmetic and does not compare elements. Returns `None` if the element reference is not aligned to the start of an element. This API is nightly-only and panics if `T` is zero-sized.

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

let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

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

let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

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

### MmapOptions::new()

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapOptions

Creates a new `MmapOptions` instance with default settings, ready for configuration.

```APIDOC
## `MmapOptions::new()`

### Description
Creates a new set of options for configuring and creating a memory map.

### Method
`new()`

### Endpoint
N/A (Constructor)

### Parameters
None

### Request Example
```rust
use memmap2::MmapOptions;

let mut mmap_options = MmapOptions::new();
```

### Response
#### Success Response
- `MmapOptions` - A new instance of `MmapOptions`.

#### Response Example
```rust
// Successfully created MmapOptions instance
```
```

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

### Iterating and Modifying Elements in Mutable Chunks (Rust)

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapMut

This example demonstrates how to iterate over a mutable slice in chunks of a specified size and modify elements within each chunk. It uses `chunks_mut` to get mutable references to sub-slices and then `iter_mut` to modify individual elements. The loop updates elements based on a counter, showing in-place modification.

```rust
let v = &mut [0, 0, 0, 0, 0];
let mut count = 1;

for chunk in v.chunks_mut(2) {
    for elem in chunk.iter_mut() {
        *elem += count;
    }
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 3]);
```

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

### MmapRaw OS Advice

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapRaw

Documentation for methods to advise the operating system about memory access patterns.

```APIDOC
## pub fn advise(&self, advice: Advice) -> Result<()>

### Description
Advise OS how this memory map will be accessed. Only supported on Unix. See madvise() map page.

### Method
`pub fn advise(&self, advice: Advice) -> Result<()>`

## pub unsafe fn unchecked_advise(&self, advice: UncheckedAdvice) -> Result<()>

### Description
Advise OS how this memory map will be accessed. Used with the unchecked flags. Only supported on Unix. See madvise() map page.

### Method
`pub unsafe fn unchecked_advise(&self, advice: UncheckedAdvice) -> Result<()>`

## pub fn advise_range( &self, advice: Advice, offset: usize, len: usize, ) -> Result<()>

### Description
Advise OS how this range of memory map will be accessed. The offset and length must be in the bounds of the memory map. Only supported on Unix. See madvise() map page.

### Method
`pub fn advise_range( &self, advice: Advice, offset: usize, len: usize, ) -> Result<()>`
```

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

### JIT Code Execution with x86/x86_64 Mmap (Rust)

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Demonstrates Just-In-Time (JIT) code compilation and execution on x86 and x86_64 architectures using memory-mapped files. It writes a simple function (mov eax, 0xAB; ret) into a mutable map, makes it executable, and then calls it.

```rust
fn jit_x86(mut mmap: MmapMut) {
    mmap[0] = 0xB8; // mov eax, 0xAB
    mmap[1] = 0xAB;
    mmap[2] = 0x00;
    mmap[3] = 0x00;
    mmap[4] = 0x00;
    mmap[5] = 0xC3; // ret

    let mmap = mmap.make_exec().expect("make_exec");

    let jitfn: extern "C" fn() -> u8 = unsafe { mem::transmute(mmap.as_ptr()) };
    assert_eq!(jitfn(), 0xab);
}

#[test]
#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
fn jit_x86_anon() {
    jit_x86(MmapMut::map_anon(4096).unwrap());
}

#[test]
#[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
fn jit_x86_file() {
    let tempdir = tempfile::tempdir().unwrap();
    let mut options = OpenOptions::new();
    #[cfg(windows)]
    options.access_mode(GENERIC_ALL);

    let file = options
        .read(true)
        .write(true)
        .create(true)
        .truncate(true)
        .open(tempdir.path().join("jit_x86"))
        .expect("open");

    file.set_len(4096).expect("set_len");
    jit_x86(unsafe { MmapMut::map_mut(&file).expect("map_mut") });
}
```

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

### get

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Safely gets a reference to an element or subslice by index or range. Returns None if out of bounds.

```APIDOC
## get<I>(index: I)

### Description
Returns a reference to an element or subslice depending on the type of index. If given a position, returns a reference to the element at that position or `None` if out of bounds. If given a range, returns the subslice corresponding to that range, or `None` if out of bounds.

### Method
`&self` (Implicit)

### Endpoint
N/A (Method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let v = [10, 40, 30];

let element_at_1 = v.get(1); // Some(&40)
let subslice_0_to_2 = v.get(0..2); // Some(&[10, 40])
let out_of_bounds_index = v.get(3); // None
let out_of_bounds_range = v.get(0..4); // None
```

### Response
#### Success Response (Option<&<I as SliceIndex<[T]>>::Output>)
- **element_or_subslice** - A reference to the element or subslice if the index is valid.

#### Response Example
```json
// If successful, returns Some(reference_to_element_or_subslice)
// If index is out of bounds, returns None
```
```

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

### Get Unchecked Element from Slice (Rust)

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapMut

Retrieves an element from a slice using an index without bounds checking. This method is unsafe and can lead to undefined behavior if the index is out of bounds. It is similar to `get(index).unwrap_unchecked()` but enforces the safety contract directly.

```rust
let x = &[1, 2, 4];

unsafe {
    assert_eq!(x.get_unchecked(1), &2);
}
```

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

### Memory Map Advice (Unix)

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Shows how to use memory map advice flags on Unix-like systems. It demonstrates setting advice for random and sequential access on both mutable and read-only maps, and verifies data integrity after writing.

```rust
let expected_len = 128;
        let tempdir = tempfile::tempdir().unwrap();
        let path = tempdir.path().join("mmap_advise");

        let file = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(true)
            .open(path)
            .unwrap();

        file.set_len(expected_len as u64).unwrap();

        // Test MmapMut::advise
        let mut mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
        mmap.advise(Advice::Random)
            .expect("mmap advising should be supported on unix");

        let len = mmap.len();
        assert_eq!(expected_len, len);

        let zeros = vec![0; len];
        let incr: Vec<u8> = (0..len as u8).collect();

        // check that the mmap is empty
        assert_eq!(&zeros[..], &mmap[..]);

        mmap.advise_range(Advice::Sequential, 0, mmap.len())
            .expect("mmap advising should be supported on unix");

        // write values into the mmap
        (&mut mmap[..]).write_all(&incr[..]).unwrap();

        // read values back
        assert_eq!(&incr[..], &mmap[..]);

        // Set advice and Read from the read-only map
        let mmap = unsafe { Mmap::map(&file).unwrap() };

        mmap.advise(Advice::Random)
            .expect("mmap advising should be supported on unix");

        // read values back
        assert_eq!(&incr[..], &mmap[..]);
```

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

### Create File-Backed Memory Map with Pre-population using MmapOptions

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapOptions

Illustrates creating a file-backed memory map and pre-populating its page tables using the `populate()` option. This can improve performance by reducing page faults. The `unsafe` block is required, and the option is Linux-specific.

```rust
use memmap2::MmapOptions;
use std::fs::File;

let file = File::open("LICENSE-MIT")?;

let mmap = unsafe {
    MmapOptions::new().populate().map(&file)?
};

assert_eq!(&b"Copyright"[..], &mmap[..9]);
```

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

### Rust Slice ChunksExact Iterator Example

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Demonstrates the `chunks_exact` method, which provides an iterator over non-overlapping sub-slices, each guaranteed to have exactly `chunk_size` elements. The example shows how to retrieve the remaining elements (if any) using the `remainder` method, which are omitted from the main iterator. It mentions `chunks` and `rchunks_exact` as alternatives.

```Rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.chunks_exact(2);
assert_eq!(iter.next().unwrap(), &['l', 'o']);
assert_eq!(iter.next().unwrap(), &['r', 'e']);
assert!(iter.next().is_none());
assert_eq!(iter.remainder(), &['m']);
```

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

### MmapRaw::as_ptr

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Returns a raw pointer to the beginning of the memory-mapped file.

```APIDOC
## GET /mmapraw/ptr

### Description
Provides an unsafe, constant pointer to the start of the memory-mapped region. Ensure the file has not been truncated before dereferencing to avoid SIGBUS.

### Method
GET

### Endpoint
/mmapraw/ptr

### Parameters
(None)

### Response
#### Success Response (200)
- ***const u8** - A raw pointer to the memory-mapped data.

#### Response Example
```json
{
  "ptr": "0x7f8b4c1d6000"
}
```
```

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

### Rust Slice Chunks Iterator Example

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Illustrates the `chunks` method on a slice, which returns an iterator over non-overlapping sub-slices of a specified size. The example shows how the last chunk may be smaller than `chunk_size` if the slice length is not perfectly divisible by `chunk_size`. It also mentions `chunks_exact` and `rchunks` as related methods.

```Rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.chunks(2);
assert_eq!(iter.next().unwrap(), &['l', 'o']);
assert_eq!(iter.next().unwrap(), &['r', 'e']);
assert_eq!(iter.next().unwrap(), &['m']);
assert!(iter.next().is_none());
```

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

### Raw Memory Mapping (Read/Write)

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Demonstrates creating a raw memory map from a file opened with read/write permissions. It verifies the map's length, checks if the pointer is null, and reads the first byte.

```rust
let tempdir = tempfile::tempdir().unwrap();
        let path = tempdir.path().join("mmapraw");

        let mut options = OpenOptions::new();
        let mut file = options
            .read(true)
            .write(true)
            .create(true)
            .truncate(true)
            .open(path)
            .expect("open");
        file.write_all(b"abc123").unwrap();
        let mmap = MmapOptions::new().map_raw(&file).unwrap();
        assert_eq!(mmap.len(), 6);
        assert!(!mmap.as_ptr().is_null());
        assert_eq!(unsafe { std::ptr::read(mmap.as_ptr()) }, b'a');
```

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

### MmapOptions::populate

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Populates (prefaults) page tables for a memory map. For file-backed maps, this performs read-ahead on the file to reduce future blocking on page faults. This option corresponds to the `MAP_POPULATE` flag on Linux and has no effect on Windows.

```APIDOC
## MmapOptions::populate

### Description
Populates page tables for a memory map, potentially improving performance by reducing page faults.

### Method
`populate(&mut self) -> &mut Self`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None
```

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

### Rust: Get System Page Size

Source: https://docs.rs/memmap2/latest/src/memmap2/unix.rs

The `page_size` function retrieves the system's memory page size. It uses an atomic static variable to cache the value after the first call, making subsequent calls efficient. It calls `libc::_SC_PAGESIZE` via `libc::sysconf` to get the value from the operating system.

```rust
fn page_size() -> usize {
    static PAGE_SIZE: AtomicUsize = AtomicUsize::new(0);

    match PAGE_SIZE.load(Ordering::Relaxed) {
        0 => {
            let page_size = unsafe { libc::sysconf(libc::_SC_PAGESIZE) as usize };

            PAGE_SIZE.store(page_size, Ordering::Relaxed);

            page_size
        }
        page_size => page_size,
    }
}
```

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

### Advise OS on Memory Access (Unix - Rust)

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Demonstrates using `advise` to provide hints to the operating system about how a memory map will be accessed. This is a Unix-specific feature and can help optimize performance by influencing page caching and prefetching. It requires `memmap2::Advice`.

```rust
use memmap2::{Mmap, Advice};
use std::fs::File;

let file = File::open("some_file")?;
let mmap = unsafe { Mmap::map(&file)? };
mmap.advise(Advice::Sequential)?;
```

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

### Splitting Slice into Fixed-Size Arrays and Remainder (Rust)

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapMut

This example demonstrates the `as_chunks` method, which safely splits a slice into a slice of fixed-size arrays and a remainder slice. It ensures that the number of elements in the remainder is always less than the array size `N`. The example illustrates how the `chunks.len()` and `remainder.len()` relate to the original slice length and `N`.

```rust
let slice: &[i32] = &[1, 2, 3, 4, 5, 6, 7];
let (chunks, remainder): (&[[i32; 3]], &[i32]) = slice.as_chunks();

assert_eq!(chunks.len(), 2);
assert_eq!(chunks[0], &[1, 2, 3]);
assert_eq!(chunks[1], &[4, 5, 6]);

assert_eq!(remainder.len(), 1);
assert_eq!(remainder[0], 7);

// This would panic at compile time because N is 0:
// let (chunks, remainder): (&[[i32; 0]], &[i32]) = slice.as_chunks();
```

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

### MmapRaw::map_raw

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Creates a writeable memory map backed by a file. This is equivalent to `MmapOptions::new().map_raw(file)`.

```APIDOC
## POST /mmapraw

### Description
Creates a new memory map that provides raw, unsafe access to a file's contents. It's intended for scenarios requiring direct memory manipulation.

### Method
POST

### Endpoint
/mmapraw

### Parameters
#### Request Body
- **file** (T: MmapAsRawDesc) - Required - A type that can be treated as a raw file descriptor for memory mapping.

### Request Example
```json
{
  "file": "<file_descriptor_or_handle>"
}
```

### Response
#### Success Response (200)
- **MmapRaw** - A handle to the raw memory-mapped buffer.

#### Response Example
```json
{
  "ptr": "0x...",
  "len": 1024
}
```

#### Error Response
- **Err(ResultError)** - Returned when the underlying system call fails, e.g., due to insufficient file permissions.
```

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

### Rust Unsafe as_chunks_unchecked Example

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Shows the usage of the unsafe `as_chunks_unchecked` method, which splits a slice into a slice of fixed-size arrays. This method requires that the slice length be an exact multiple of the array size `N` and that `N` is not zero. The example demonstrates correct usage with different array sizes and notes the conditions under which it would be unsound.

```Rust
let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
let chunks: &[[char; 1]] = 
    // SAFETY: 1-element chunks never have remainder
    unsafe { slice.as_chunks_unchecked() };
assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);
let chunks: &[[char; 3]] = 
    // SAFETY: The slice length (6) is a multiple of 3
    unsafe { slice.as_chunks_unchecked() };
assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);
```

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

### Advise OS Memory Access Patterns (Unix)

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Advises the operating system on how a memory map will be accessed. This function is only supported on Unix-like systems and uses the `madvise()` system call. It advises the entire memory map.

```rust
#[cfg(unix)]
pub fn advise(&self, advice: Advice) -> Result<()> {
    self.inner
        .advise(advice as libc::c_int, 0, self.inner.len())
}
```

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

### starts_with

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Checks if the slice starts with a given needle (prefix).

```APIDOC
## starts_with(&self, needle: &[T]) -> bool

### Description
Returns `true` if `needle` is a prefix of the slice or equal to the slice.

### Method
`GET` (conceptually, as it's a method on a slice)

### Endpoint
N/A (method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));

let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
```

### Response
#### Success Response (200)
`bool`: `true` if the slice starts with the needle, `false` otherwise.

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

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

### Unsafe Splitting of Slice into Fixed-Size Arrays (Rust)

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapMut

This example demonstrates the unsafe `as_chunks_unchecked` method for splitting a slice into a slice of fixed-size arrays. It requires that the slice's length is an exact multiple of the array size `N`. The example shows how to use this method safely when the conditions are met and highlights potential unsoundness if conditions are violated.

```rust
let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
let chunks: &[[char; 1]] = 
    // SAFETY: 1-element chunks never have remainder
    unsafe { slice.as_chunks_unchecked() };
assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);
let chunks: &[[char; 3]] = 
    // SAFETY: The slice length (6) is a multiple of 3
    unsafe { slice.as_chunks_unchecked() };
assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);

// These would be unsound:
// let chunks: &[[_; 5]] = slice.as_chunks_unchecked() // The slice length is not a multiple of 5
// let chunks: &[[_; 0]] = slice.as_chunks_unchecked() // Zero-length chunks are never allowed
```

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

### Linux madvise: Populate Page Tables for Writing

Source: https://docs.rs/memmap2/latest/memmap2/enum.Advice

MADV_POPULATE_WRITE prefaults page tables to be writable, faulting in all pages as if for writing, but avoiding actual memory access. It can be applied to existing mappings, does not hide errors, and ensures writable page tables, potentially breaking CoW. It is not applicable to mappings without write permissions or special kernel mappings. Errors return an error code, not SIGBUS.

```c
#include <sys/mman.h>

// Populate page tables for writing
int ret = madvise(addr, length, MADV_POPULATE_WRITE);
```

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

### Rust: Get File Length from Raw File Descriptor

Source: https://docs.rs/memmap2/latest/src/memmap2/unix.rs

The `file_len` function takes a raw file descriptor (`RawFd`) and returns its size in bytes as a `u64`. It safely wraps the `RawFd` into a `std::fs::File` using `ManuallyDrop` to ensure the file descriptor is not closed prematurely. It then uses `metadata()?.len()` to get the file size.

```rust
pub fn file_len(file: RawFd) -> io::Result<u64> {
    // SAFETY: We must not close the passed-in fd by dropping the File we create,
    // we ensure this by immediately wrapping it in a ManuallyDrop.
    unsafe {
        let file = ManuallyDrop::new(File::from_raw_fd(file));
        Ok(file.metadata()?.len())
    }
}
```

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

### Linux madvise: Populate Page Tables for Reading

Source: https://docs.rs/memmap2/latest/memmap2/enum.Advice

MADV_POPULATE_READ prefaults page tables to be readable, loading all pages in the range without actual memory access after faulting. It can be applied to existing mappings, does not hide errors, and ensures readable page tables. It is not applicable to mappings without read permissions or special kernel mappings. Errors return an error code, not SIGBUS.

```c
#include <sys/mman.h>

// Populate page tables for reading
int ret = madvise(addr, length, MADV_POPULATE_READ);
```

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

### Create File-Backed Memory Map with Offset using MmapOptions

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapOptions

Illustrates creating a file-backed memory map with a specified offset from the beginning of the file. This uses `MmapOptions::new()`, configures the `offset`, and then maps the file using `map()`. The `unsafe` block is required due to the nature of memory mapping.

```rust
use memmap2::MmapOptions;
use std::fs::File;

let mmap = unsafe {
    MmapOptions::new()
                .offset(30)
                .map(&File::open("LICENSE-APACHE")?)?
};
assert_eq!(&b"Apache License"[..],
           &mmap[..14]);
```

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

### iter

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapMut

Returns an iterator over the slice, yielding items from start to end.

```APIDOC
## GET /websites/rs_memmap2/iter

### Description
Returns an iterator over the slice. The iterator yields all items from start to end.

### Method
GET

### Endpoint
/websites/rs_memmap2/iter

### Response
#### Success Response (200)
- **items** (array) - An array of items from the iterator.

#### Response Example
```json
{
  "items": [1, 2, 4]
}
```
```

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

### Rust: File Memory Map Write Operations

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Demonstrates writing data to a file-backed memory map and verifying the write by reading directly from the file. This test uses `OpenOptions` to create and open a file, sets its length, maps it mutably, writes data, flushes the map, and then reads back from the file.

```rust
    #[test]
    fn file_write() {
        let tempdir = tempfile::tempdir().unwrap();
        let path = tempdir.path().join("mmap");

        let mut file = OpenOptions::new()
            .read(true)
            .write(true)
            .create(true)
            .truncate(true)
            .open(path)
            .unwrap();
        file.set_len(128).unwrap();

        let write = b"abc123";
        let mut read = [0u8; 6];

        let mut mmap = unsafe { MmapMut::map_mut(&file).unwrap() };
        (&mut mmap[..]).write_all(write).unwrap();
        mmap.flush().unwrap();

        file.read_exact(&mut read).unwrap();
        assert_eq!(write, &read);
    }
```

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

### as_array

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Gets a reference to the underlying array if the length matches N. Nightly-only.

```APIDOC
## as_array<const N: usize>()

### Description
Gets a reference to the underlying array. If `N` is not exactly equal to the length of `self`, then this method returns `None`. This is a nightly-only experimental API.

### Method
`&self` (Implicit)

### Endpoint
N/A (Method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let data = [1, 2, 3];
let array_ref = data.as_array::<3>(); // Some(&[1, 2, 3])
let wrong_size = data.as_array::<2>(); // None
```

### Response
#### Success Response (Option<&[T; N]>)
- **array_reference** (&[T; N]) - A reference to the array if the length matches `N`.

#### Response Example
```json
// If length matches N, returns Some(array_reference)
// If length does not match N, returns None
```
```

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

### strip_prefix

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Returns a subslice with the prefix removed if the slice starts with the specified prefix.

```APIDOC
## strip_prefix<P>(&self, prefix: &P) -> Option<&[T]>

### Description
Returns a subslice with the prefix removed. If the slice starts with `prefix`, returns the subslice after the prefix, wrapped in `Some`. If `prefix` is empty, simply returns the original slice. If `prefix` is equal to the original slice, returns an empty slice. If the slice does not start with `prefix`, returns `None`.

### Method
`GET` (conceptually, as it's a method on a slice)

### Endpoint
N/A (method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let v = &[10, 40, 30];
assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
assert_eq!(v.strip_prefix(&[50]), None);
assert_eq!(v.strip_prefix(&[10, 50]), None);

let prefix : &str = "he";
assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
           Some(b"llo".as_ref()));
```

### Response
#### Success Response (200)
`Option<&[T]>`: Returns `Some(subslice)` if the prefix matches, `None` otherwise.

#### Response Example
```json
{
  "example": "Some(&[40, 30][..])"
}
```
```

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

### Populate Memory Map with MAP_POPULATE

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Populates (prefaults) page tables for a memory mapping. For file mappings, this performs read-ahead to minimize page fault delays. This option corresponds to the `MAP_POPULATE` flag on Linux and has no effect on Windows.

```rust
use memmap2::MmapOptions;
use std::fs::File;

# fn main() -> std::io::Result<()> {
let file = File::open("LICENSE-MIT")?;

let mmap = unsafe {
    MmapOptions::new().populate().map(&file)?
};

assert_eq!(&b"Copyright"[..], &mmap[..9]);
# Ok(())
# }

```

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

### as_ptr_range

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Returns the two raw pointers spanning the slice (start and one-past-the-end).

```APIDOC
## as_ptr_range()

### Description
Returns the two raw pointers spanning the slice. The returned range is half-open, meaning the end pointer points one past the last element. Useful for foreign function interfaces.

### Method
`&self` (Implicit)

### Endpoint
N/A (Method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let a = [1, 2, 3];
let ptr_range = a.as_ptr_range(); // Range<*const i32>

let x = &a[1] as *const _;
let y = &5 as *const _;

assert!(ptr_range.contains(&x));
assert!(!ptr_range.contains(&y));
```

### Response
#### Success Response (Range<*const T>)
- **start_pointer** (*const T) - A pointer to the first element.
- **end_pointer** (*const T) - A pointer one past the last element.

#### Response Example
```json
// Returns a Range object containing two raw pointers.
```
```

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

### Create Writable Memory Map from File using memmap2::map_mut

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapOptions

This example demonstrates creating a mutable (writable) memory map of a file using `MmapOptions::map_mut`. It opens a file with read, write, and create permissions, sets its length, and then maps it into memory. The example then writes data to the memory map, allowing modifications to the file through memory access. This is useful for in-place editing of files.

```rust
use std::fs::OpenOptions;
use std::path::PathBuf;

use memmap2::MmapOptions;
let path: PathBuf = /* path to file */
let file = OpenOptions::new().read(true).write(true).create(true).truncate(true).open(&path)?;
file.set_len(13)?;

let mut mmap = unsafe {
    MmapOptions::new().map_mut(&file)?
};

mmap.copy_from_slice(b"Hello, world!");
```

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

### Create Raw Memory Map using memmap2::map_raw

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapOptions

This example demonstrates the creation of a raw memory map using `MmapOptions::map_raw`. It opens a file and creates a raw memory mapping. Raw memory maps provide lower-level access and may be useful in specific scenarios where standard `Mmap` abstractions are not sufficient. The function returns a `Result<MmapRaw>`, indicating potential errors during the system call.

```rust
use memmap2::MmapOptions;
use std::fs::File;

let file = File::open("some_file.txt")?;
let mmap_raw = MmapOptions::new().map_raw(&file)?;

// Use the raw memory map...
```

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

### Rust MmapInner: Advise Memory Usage

Source: https://docs.rs/memmap2/latest/src/memmap2/unix.rs

The `advise` method allows the application to inform the kernel about expected memory access patterns, potentially improving performance. It takes an advice code (e.g., `libc::MADV_NORMAL`, `libc::MADV_RANDOM`), an offset, and a length. It handles alignment adjustments for the underlying `madvise` system call and returns an `io::Result<()>`.

```rust
pub fn advise(&self, advice: libc::c_int, offset: usize, len: usize) -> io::Result<()> {
        let alignment = (self.ptr as usize + offset) % page_size();
        let offset = offset as isize - alignment as isize;
        let len = len + alignment;
        unsafe {
            if libc::madvise(self.ptr.offset(offset), len, advice) != 0 {
                Err(io::Error::last_os_error())
            } else {
                Ok(())
            }
        }
    }
```

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

### get

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapMut

Returns a reference to an element or subslice depending on the type of index. Returns None if out of bounds.

```APIDOC
## GET /slice/get

### Description
Returns a reference to an element or subslice depending on the type of index. If the index is out of bounds, this will return `None`.

### Method
GET

### Endpoint
`/slice/get(index)`

### Parameters
#### Query Parameters
- **index** (*I*) - Required - The index or range to access. `I` must implement `SliceIndex<[T]>`.

### Response
#### Success Response (200)
- **Option<&<I as SliceIndex<[T]>>::Output>**: An optional reference to the element or subslice.

#### Response Example
```json
{
  "example": "Some(40)" 
}
```
```json
{
  "example": "Some([10, 40])"
}
```
```

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

### Mutable Memory Mapping with File Copy

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Demonstrates creating a mutable memory map from a file, writing data, flushing changes, and verifying data integrity both in the map and the original file. It also shows creating a read-only map and verifying it doesn't contain the written data.

```rust
let mmap = unsafe { MmapOptions::new().map_copy(&file).expect("map_mut") };

        let mmap = mmap.make_read_only().expect("make_read_only");
        let mut mmap = mmap.make_mut().expect("make_mut");

        let nulls = b"\0\0\0\0\0\0";
        let write = b"abc123";
        let mut read = [0u8; 6];

        (&mut mmap[..]).write_all(write).unwrap();
        mmap.flush().unwrap();

        // The mmap contains the write
        (&mmap[..]).read_exact(&mut read).unwrap();
        assert_eq!(write, &read);

        // The file does not contain the write
        file.read_exact(&mut read).unwrap();
        assert_eq!(nulls, &read);

        // another mmap does not contain the write
        let mmap2 = unsafe { MmapOptions::new().map(&file).unwrap() };
        (&mmap2[..]).read_exact(&mut read).unwrap();
        assert_eq!(nulls, &read);

        let mmap = mmap.make_exec().expect("make_exec");

        drop(mmap);
```

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

### get_unchecked

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Unsafely gets a reference to an element or subslice without bounds checking. Use with caution.

```APIDOC
## get_unchecked<I>(index: I)

### Description
Returns a reference to an element or subslice, without doing bounds checking. For a safe alternative see `get`.

### Method
`&self` (Implicit)

### Endpoint
N/A (Method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let x = &[1, 2, 4];

unsafe {
    let element_at_1 = x.get_unchecked(1); // &2
}
```

### Response
#### Success Response (&<I as SliceIndex<[T]>>::Output)
- **element_or_subslice** - A reference to the element or subslice.

#### Response Example
```json
// Returns a reference to the element or subslice.
// UB if index is out of bounds.
```

### Safety
Calling this method with an out-of-bounds index is _undefined behavior_ even if the resulting reference is not used. You can think of this like `.get(index).unwrap_unchecked()`.
```

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

### Advise Memory Map Access (Unix, Rust)

Source: https://docs.rs/memmap2/latest/src/memmap2/lib.rs

Provides advice to the operating system about how a memory map will be accessed. This functionality is only supported on Unix-like systems. It allows for performance optimizations by informing the OS about anticipated access patterns.

```rust
/// Advise OS how this memory map will be accessed.
///
/// Only supported on Unix.
///
/// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
#[cfg(unix)]
pub fn advise(&self, advice: Advice) -> Result<()> {
    self.inner
        .advise(advice as libc::c_int, 0, self.inner.len())
}
```

```rust
/// Advise OS how this memory map will be accessed.
///
/// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
///
/// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
#[cfg(unix)]
pub unsafe fn unchecked_advise(&self, advice: UncheckedAdvice) -> Result<()> {
    self.inner
        .advise(advice as libc::c_int, 0, self.inner.len())
}
```

```rust
/// Advise OS how this range of memory map will be accessed.
///
/// Only supported on Unix.
///
/// The offset and length must be in the bounds of the memory map.
///
/// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
#[cfg(unix)]
pub fn advise_range(&self, advice: Advice, offset: usize, len: usize) -> Result<()> {
    self.inner.advise(advice as libc::c_int, offset, len)
}
```

```rust
/// Advise OS how this range of memory map will be accessed.
///
/// Used with the [unchecked flags][UncheckedAdvice]. Only supported on Unix.
///
/// The offset and length must be in the bounds of the memory map.
///
/// See [madvise()](https://man7.org/linux/man-pages/man2/madvise.2.html) map page.
#[cfg(unix)]
pub unsafe fn unchecked_advise_range(
    &self,
    advice: UncheckedAdvice,
    offset: usize,
    len: usize,
) -> Result<()> {
    self.inner.advise(advice as libc::c_int, offset, len)
}
```

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

### last_chunk

Source: https://docs.rs/memmap2/latest/memmap2/struct.Mmap

Gets a reference to the last N items in the slice. Returns None if the slice is too short.

```APIDOC
## last_chunk<const N: usize>()

### Description
Returns an array reference to the last `N` items in the slice. If the slice is not at least `N` in length, this will return `None`.

### Method
`&self` (Implicit)

### Endpoint
N/A (Method on slice)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let u = [10, 40, 30];
let last_two = u.last_chunk::<2>(); // Some(&[40, 30])

let v: &[i32] = &[10];
let last_two_v = v.last_chunk::<2>(); // None

let w: &[i32] = &[];
let last_zero_w = w.last_chunk::<0>(); // Some(&[])
```

### Response
#### Success Response (Option<&[T; N]>)
- **array_suffix** (&[T; N]) - An array reference to the last N elements.

#### Response Example
```json
// If successful, returns Some(array_suffix)
// If slice is shorter than N, returns None
```
```

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

### Create Read-Only Copy-on-Write Memory Map using memmap2

Source: https://docs.rs/memmap2/latest/memmap2/struct.MmapOptions

This example demonstrates creating a read-only copy-on-write memory map from a file using `MmapOptions::map_copy_read_only`. It opens a file, reads its content into a vector, and then creates a memory map. The example asserts that the memory map's content matches the original file content. This method is primarily for read-only access and avoids direct file reads after the initial mapping.

```rust
use memmap2::MmapOptions;
use std::fs::File;
use std::io::Read;

let mut file = File::open("README.md")?;

let mut contents = Vec::new();
file.read_to_end(&mut contents)?;

let mmap = unsafe {
    MmapOptions::new().map_copy_read_only(&file)?
};

assert_eq!(&contents[..], &mmap[..]);
```