RSIPStack

https://docs.rs/rsipstack/latest/rsipstack/
Admin
RSIPStack is a comprehensive Session Initiation Protocol (SIP) implementation written in Rust,...
Tokens:2,081,628
Snippets:15,295
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### EndpointBuilder usage example

Source: https://docs.rs/rsipstack/latest/rsipstack/transaction/endpoint/struct.Endpoint.html

Shows how to build an Endpoint with EndpointBuilder, set a user agent, retrieve incoming transactions, and start the endpoint by spawning its inner handle. Requires the tokio_util CancellationToken import and a #[tokio::main] runtime.

```rust
use rsipstack::EndpointBuilder;
use tokio_util::sync::CancellationToken;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let endpoint = EndpointBuilder::new()
        .with_user_agent("MyApp/1.0")
        .build();
     
    // Get incoming transactions
    let mut incoming = endpoint.incoming_transactions().expect("incoming_transactions");
     
    // Start the endpoint
    let endpoint_inner = endpoint.inner.clone();
    tokio::spawn(async move {
         endpoint_inner.serve().await;
    });
    Ok(())  
}
```

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

### Basic BTreeMap usage example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.BTreeMap.html

Demonstrates inserting, checking, removing, and iterating over entries in a BTreeMap. Shows type inference, contains_key, remove, get, indexing, and iteration.

```rust
use std::collections::BTreeMap;

// type inference lets us omit an explicit type signature (which
// would be `BTreeMap<&str, &str>` in this example).
let mut movie_reviews = BTreeMap::new();

// review some movies.
movie_reviews.insert("Office Space",       "Deals with real issues in the workplace.");
movie_reviews.insert("Pulp Fiction",       "Masterpiece.");
movie_reviews.insert("The Godfather",      "Very enjoyable.");
movie_reviews.insert("The Blues Brothers", "Eye lyked it a lot.");

// check for a specific one.
if !movie_reviews.contains_key("Les Misérables") {
    println!("We've got {} reviews, but Les Misérables ain't one.",
             movie_reviews.len());
}

// oops, this review has a lot of spelling mistakes, let's delete it.
movie_reviews.remove("The Blues Brothers");

// look up the values associated with some keys.
let to_find = ["Up!", "Office Space"];
for movie in &to_find {
    match movie_reviews.get(movie) {
       Some(review) => println!("{movie}: {review}"),
       None => println!("{movie} is unreviewed.")
    }
}

// Look up the value for a key (will panic if the key is not found).
println!("Movie review: {}", movie_reviews["Office Space"]);

// iterate over everything.
for (movie, review) in &movie_reviews {
    println!("{movie}: \"{review}\"");
}
```

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

### Getting a Mutable Reference with get_mut

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/atomic64/type.AtomicU64.html

Example for the get_mut method, which returns a mutable reference to the underlying integer. The example creates an AtomicU64, gets a mutable reference, modifies it, and verifies the change.

```rust
use std::sync::atomic::{AtomicU64, Ordering};

let mut some_var = AtomicU64::new(10);
assert_eq!(*some_var.get_mut(), 10);
*some_var.get_mut() = 5;
assert_eq!(some_var.load(Ordering::SeqCst), 5);
```

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

### Basic SIP Registration with Credential

Source: https://docs.rs/rsipstack/latest/rsipstack/dialog/registration/struct.Registration.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a Credential, build a Registration, and perform a single SIP registration. The example checks the response status and prints the registration success and expiration time. Requires an existing endpoint and uses the rsipstack crate.

```rust
let credential = Credential {
    username: "alice".to_string(),
    password: "secret123".to_string(),
    realm: Some("example.com".to_string()),
    auth_username: None,
};

let mut registration = Registration::new(endpoint.inner.clone(), Some(credential));
let server = rsipstack::sip::Uri::try_from("sip:sip.example.com").unwrap();
let response = registration.register(server.clone(), None).await?;

if response.status_code == rsipstack::sip::StatusCode::OK {
    println!("Registration successful");
    println!("Expires in: {} seconds", registration.expires());
}
}
```

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

### Getting Atomic Access to a &mut u64 with from_mut

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/atomic64/type.AtomicU64.html

Example for the from_mut method, which gets atomic access to a &mut u64. The example creates a mutable integer, gets an atomic reference, stores a value, and verifies the change. This function is only available on targets where AtomicU64 has the same alignment as u64.

```rust
use std::sync::atomic::{AtomicU64, Ordering};

let mut some_int = 123;
let a = AtomicU64::from_mut(&mut some_int);
a.store(100, Ordering::Relaxed);
assert_eq!(some_int, 100);
```

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

### capacity() example

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/mpsc/struct.Receiver.html

Shows how capacity() changes as messages are sent, received, and reserved. The example creates a channel with capacity 5, then demonstrates that reserving a permit drops capacity to 4, sending and receiving restores it, and direct sends and receives adjust capacity accordingly.

```rust
use tokio::sync::mpsc;

let (tx, mut rx) = mpsc::channel::<()>(5);

assert_eq!(rx.capacity(), 5);

// Making a reservation drops the capacity by one.
let permit = tx.reserve().await.unwrap();
assert_eq!(rx.capacity(), 4);
assert_eq!(rx.len(), 0);

// Sending and receiving a value increases the capacity by one.
permit.send(());
assert_eq!(rx.len(), 1);
rx.recv().await.unwrap();
assert_eq!(rx.capacity(), 5);

// Directly sending a message drops the capacity by one.
tx.send(()).await.unwrap();
assert_eq!(rx.capacity(), 4);
assert_eq!(rx.len(), 1);

// Receiving the message increases the capacity by one.
rx.recv().await.unwrap();
assert_eq!(rx.capacity(), 5);
assert_eq!(rx.len(), 0);
```

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

### resize_with example

Source: https://docs.rs/rsipstack/latest/rsipstack/sip/uri/type.UriWithParamsList.html?search=

Shows how to resize a Vec using a closure or Default::default. The first example uses Default::default to fill with zeros; the second uses a closure that doubles a value. Panics if new capacity exceeds isize::MAX bytes.

```rust
let mut vec = vec![1, 2, 3];
vec.resize_with(5, Default::default);
assert_eq!(vec, [1, 2, 3, 0, 0]);

let mut vec = vec![];
let mut p = 1;
vec.resize_with(4, || { p *= 2; p });
assert_eq!(vec, [2, 4, 8, 16]);
```

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

### as_chunks_mut example: mutable chunking from start

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

Splits a mutable slice into N-element chunks starting from the beginning, with a remainder slice of length less than N. The example modifies chunks and the remainder. Panics if N is zero.

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

let (chunks, remainder) = v.as_chunks_mut();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[1, 1, 2, 2, 9]);
```

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

### Creating a SIP endpoint with EndpointBuilder

Source: https://docs.rs/rsipstack/latest/rsipstack/index.html

Example showing how to create a SIP endpoint using EndpointBuilder, retrieve incoming transactions, and process them. The endpoint's serve() method is commented out for demonstration purposes.

```rust
use rsipstack::EndpointBuilder;
use tokio_util::sync::CancellationToken;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a SIP endpoint
    let endpoint = EndpointBuilder::new()
        .with_user_agent("MyApp/1.0")
        .build();

    // Get incoming transactions
    let mut incoming = endpoint.incoming_transactions().expect("incoming_transactions");

    // Start the endpoint (in production, you'd run this in a separate task)
    // let endpoint_inner = endpoint.inner.clone();
    // tokio::spawn(async move {
    //     endpoint_inner.serve().await.ok();
    // });

    // Process incoming requests
    while let Some(transaction) = incoming.recv().await {
        // Handle the transaction
        println!("Received: {}", transaction.original.method);
        break; // Exit for example
    }

    Ok(())
}
```

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

### as_ptr() example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.String.html?search=std%3A%3Avec

Converts a string slice to a raw pointer. The example shows getting a pointer to the first byte.

```rust
let s = "Hello";
let ptr = s.as_ptr();
```

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

### get() example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.String.html?search=std%3A%3Avec

Returns a subslice of a string without panicking. The example shows valid and invalid indices, including out-of-bounds.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

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

### Basic Call Setup with do_invite

Source: https://docs.rs/rsipstack/latest/rsipstack/dialog/dialog_layer/struct.DialogLayer.html

Shows how to initiate an outbound call using do_invite and handle the final response. The response status code is matched to determine if the call was answered, busy, or failed. Requires an InviteOption and a DialogStateSender.

```rust
let (dialog, response) = dialog_layer.do_invite(invite_option, state_sender).await?;

if let Some(resp) = response {
    match resp.status_code {
        rsipstack::sip::StatusCode::OK => {
            println!("Call answered!");
            // Process SDP answer in resp.body
        },
        rsipstack::sip::StatusCode::BusyHere => {
            println!("Called party is busy");
        },
        _ => {
            println!("Call failed: {}", resp.status_code);
        }
    }
}
```

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

### trim_start_matches examples

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.String.html?search=std%3A%3Avec

Trims all prefixes that match a pattern repeatedly. The pattern can be a &str, char, slice of chars, or closure. The examples show trimming '1' and numeric characters from the start.

```rust
assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
```

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

### Result product example

Source: https://docs.rs/rsipstack/latest/rsipstack/type.Result.html

Demonstrates using product to multiply parsed numbers, returning Err if any parse fails.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

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

### Using slice::iter to iterate over elements

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

Example for the `iter` method. Returns an iterator over the slice, yielding all items from start to end. The example shows iterating over a slice of integers and asserting each next value.

```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

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

### parse example

Source: https://docs.rs/rsipstack/latest/rsipstack/sip/uri/struct.OtherParam.html?search=u32+-%3E+bool

Shows how to use `parse` to convert a string to a `u32`. Includes basic usage, the turbofish syntax, and a failing parse.

```rust
let four: u32 = "4".parse().unwrap();

assert_eq!(4, four);
```

```rust
let four = "4".parse::<u32>();

assert_eq!(Ok(4), four);
```

```rust
let nope = "j".parse::<u32>();

assert!(nope.is_err());
```

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

### get example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

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

```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

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

### make_response: Success Response Example

Source: https://docs.rs/rsipstack/latest/rsipstack/transaction/endpoint/struct.EndpointInner.html

Creates a SIP 200 OK response with an SDP body. The body is provided as a byte vector from a string. Additional headers like Content-Length and Content-Type should be added separately.

```rust
let response = endpoint.make_response(
    &request,
    rsipstack::sip::StatusCode::OK,
    Some(sdp_answer.into_bytes())
);
```

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

### Arc::get_mut example

Source: https://docs.rs/rsipstack/latest/rsipstack/transaction/endpoint/type.EndpointInnerRef.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to get a mutable reference to the inner value of an Arc when there are no other Arc or Weak pointers. The example mutates the value and verifies that get_mut returns None when another Arc clone exists.

```rust
use std::sync::Arc;

let mut x = Arc::new(3);
*Arc::get_mut(&mut x).unwrap() = 4;
assert_eq!(*x, 4);

let _y = Arc::clone(&x);
assert!(Arc::get_mut(&mut x).is_none());

```

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

### ok example

Source: https://docs.rs/rsipstack/latest/rsipstack/type.Result.html

Demonstrates converting a Result to an Option, returning Some(value) for Ok and None for Err.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

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

### Consuming iterator example for Vec::into_iter

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

Creates a consuming iterator that moves each value out of the vector from start to end. The vector cannot be used after calling this. The example shows iterating over a vector of Strings and asserting the yielded values.

```rust
let v = vec!["a".to_string(), "b".to_string()];
let mut v_iter = v.into_iter();

let first_element: Option<String> = v_iter.next();

assert_eq!(first_element, Some("a".to_string()));
assert_eq!(v_iter.next(), Some("b".to_string()));
assert_eq!(v_iter.next(), None);
```

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

### AtomicU64::store example

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/atomic64/type.AtomicU64.html

Shows how to use `store` with `Ordering::Relaxed` and verify with `load`. Panics if `order` is `Acquire` or `AcqRel`.

```rust
use std::sync::atomic::{AtomicU64, Ordering};

let some_var = AtomicU64::new(5);

some_var.store(10, Ordering::Relaxed);
assert_eq!(some_var.load(Ordering::Relaxed), 10);
```

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

### as_rchunks_mut example: mutable chunking from end

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

Splits a mutable slice into N-element chunks starting from the end, with a remainder slice of length less than N. The example modifies the remainder and chunks. Panics if N is zero.

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

let (remainder, chunks) = v.as_rchunks_mut();
remainder[0] = 9;
for chunk in chunks {
    *chunk = [count; 2];
    count += 1;
}
assert_eq!(v, &[9, 1, 1, 2, 2]);
```

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

### Basic Registration with Credential

Source: https://docs.rs/rsipstack/latest/rsipstack/dialog/registration/struct.Registration.html

Creates a Credential with username, password, and optional realm, then creates a Registration and calls register. Checks the response status code for OK and prints success and expiration time. Requires an endpoint and uses the rsipstack::sip::Uri for the server address.

```rust
let credential = Credential {
    username: "alice".to_string(),
    password: "secret123".to_string(),
    realm: Some("example.com".to_string()),
    auth_username: None,
};

let mut registration = Registration::new(endpoint.inner.clone(), Some(credential));
let server = rsipstack::sip::Uri::try_from("sip:sip.example.com").unwrap();
let response = registration.register(server.clone(), None).await?;

if response.status_code == rsipstack::sip::StatusCode::OK {
    println!("Registration successful");
    println!("Expires in: {} seconds", registration.expires());
}
```

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

### Instant::now() example

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/struct.Instant.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates an Instant representing the current time. Used as a starting point for measuring durations.

```rust
use std::time::Instant;

let now = Instant::now();
```

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

### Get port number with port

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/enum.SocketAddr.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the port number of the socket address. The example creates a socket and checks the port.

```rust
use std::net::{IpAddr, Ipv4Addr, SocketAddr};

let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
assert_eq!(socket.port(), 8080);
```

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

### Manually create Box from scratch with system allocator

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Box.html

Demonstrates manually creating a Box from scratch using the system allocator, allocating memory with System.allocate, writing a value, and constructing the Box with Box::from_raw_in. Requires the slice_ptr_get feature.

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

use std::alloc::{Allocator, Layout, System};

unsafe {
    let ptr = System.allocate(Layout::new::<i32>())?.as_mut_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, System);
}

```

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

### Get IP address with ip

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/enum.SocketAddr.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the IP address of the socket address. The example creates a socket and checks the IP.

```rust
use std::net::{IpAddr, Ipv4Addr, SocketAddr};

let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)));
```

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

### Box::new_uninit_in example (nightly)

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Box.html

Nightly-only experimental API (allocator_ext). Constructs a new box with uninitialized contents in the provided allocator.

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

use std::alloc::System;

let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

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

### get_disjoint_mut example with range indices

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html?search=

Uses get_disjoint_mut with an array of ranges to get mutable references to slices, modifies them, and asserts the result.

```rust
if let Ok([a, b]) = v.get_disjoint_mut([0..1, 1..3]) {
    a[0] = 8;
    b[0] = 88;
    b[1] = 888;
}
assert_eq!(v, &[8, 88, 888]);
```

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

### WeakSender upgrade example

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/mpsc/struct.WeakSender.html?search=

Example demonstrating how to create a WeakSender using downgrade, upgrade it while the Sender exists, and observe that upgrade returns None after the Sender is dropped.

```rust
use tokio::sync::mpsc::channel;

let (tx, _rx) = channel::<i32>(15);
let tx_weak = tx.downgrade();

// Upgrading will succeed because `tx` still exists.
assert!(tx_weak.upgrade().is_some());

// If we drop `tx`, then it will fail.
drop(tx);
assert!(tx_weak.clone().upgrade().is_none());
```

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

### trim_start directionality example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.String.html?search=std%3A%3Avec

Demonstrates that trim_start removes leading whitespace from the start of the byte string, which is the left side for left-to-right languages.

```rust
let s = "  English  ";
assert!(Some('E') == s.trim_start().chars().next());
```

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

### pub async fn register(&mut self, server: Uri, expires: Option<u32>) -> Result<Response>

Source: https://docs.rs/rsipstack/latest/rsipstack/dialog/registration/struct.Registration.html?search=std%3A%3Avec

Performs SIP registration with the specified server. Sends a REGISTER request, handles authentication challenges, and returns the final response.

```APIDOC
## pub async fn register(&mut self, server: Uri, expires: Option<u32>) -> Result<Response>

### Description
Performs SIP registration with the server. Sends a REGISTER request to the specified SIP server to register the user agent's current location. This method handles the complete registration process including DNS resolution, authentication challenges, and response processing.

### Method
async fn

### Parameters
- **server** (Uri) - Required - SIP server hostname or IP address (e.g., "sip.example.com")
- **expires** (Option<u32>) - Optional - Registration expiration time in seconds

### Returns
- **Ok(Response)** - Final response from the registration server
- **Err(Error)** - Registration failed due to network or protocol error

### Registration Flow
1. **DNS Resolution** - Resolves server address and transport
2. **Request Creation** - Creates REGISTER request with proper headers
3. **Initial Send** - Sends the registration request
4. **Authentication** - Handles 401/407 challenges if credentials provided
5. **Response Processing** - Returns final response (200 OK or error)

### Response Codes
- **200 OK** - Registration successful
- **401 Unauthorized** - Authentication required (handled automatically)
- **403 Forbidden** - Registration not allowed
- **404 Not Found** - User not found
- **423 Interval Too Brief** - Requested expiration too short

### Examples
#### Successful Registration
```rust
let server = rsipstack::sip::Uri::try_from("sip:sip.example.com").unwrap();
let response = registration.register(server, None).await?;

match response.status_code {
    rsipstack::sip::StatusCode::OK => {
        println!("Registration successful");
        // Extract registration details from response
        if let Ok(_contact) = response.contact_header() {
            println!("Registration confirmed");
        }
    },
    rsipstack::sip::StatusCode::Forbidden => {
        println!("Registration forbidden");
    },
    _ => {
        println!("Registration failed: {}", response.status_code);
    }
}
```

#### Error Handling
```rust
match registration.register(server, None).await {
    Ok(response) => {
        // Handle response based on status code
    },
    Err(Error::DnsResolutionError(msg)) => {
        eprintln!("DNS resolution failed: {}", msg);
    },
    Err(Error::TransportLayerError(msg, addr)) => {
        eprintln!("Network error to {}: {}", addr, msg);
    },
    Err(e) => {
        eprintln!("Registration error: {}", e);
    }
}
```

### Authentication
If credentials are provided during Registration creation, this method will automatically handle authentication challenges:
1. Send initial REGISTER request
2. Receive 401/407 challenge with authentication parameters
3. Calculate authentication response using provided credentials
4. Resend REGISTER with Authorization header
5. Receive final response

### Contact Header
The method will automatically update the Contact header with the public address discovered during the registration process. This is essential for proper NAT traversal in SIP communications.
If you want to use a specific Contact header, you can set it manually before calling this method.
```

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

### get_disjoint_mut example with RangeInclusive indices

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html?search=

Uses get_disjoint_mut with an array of RangeInclusive indices to get mutable references to slices, modifies them, and asserts the result.

```rust
if let Ok([a, b]) = v.get_disjoint_mut([1..=2, 0..=0]) {
    a[0] = 11;
    a[1] = 111;
    b[0] = 1;
}
assert_eq!(v, &[1, 11, 111]);
```

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

### Server::new

Source: https://docs.rs/rsipstack/latest/rsipstack/sip/headers/untyped/struct.Server.html

Creates a new Server instance with the given value.

```APIDOC
## Server::new

### Description
Creates a new `Server` struct with the provided value.

### Method
`pub fn new(value: impl Into<String>) -> Self`

### Parameters
- **value** (`impl Into<String>`) - The value to store in the Server header.

### Returns
- `Self` - A new `Server` instance.

### Example
```rust
let server = Server::new("MyServer/1.0");
```
```

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

### Example: using Permit::send

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/mpsc/struct.Permit.html

This example demonstrates how to reserve capacity with `tx.reserve()`, then send a value using the permit. It also shows that direct `try_send` fails when capacity is reserved, and that the value sent via the permit is received.

```rust
use tokio::sync::mpsc;

let (tx, mut rx) = mpsc::channel(1);

// Reserve capacity
let permit = tx.reserve().await.unwrap();

// Trying to send directly on the `tx` will fail due to no
// available capacity.
assert!(tx.try_send(123).is_err());

// Send a message on the permit
permit.send(456);

// The value sent on the permit is received
assert_eq!(rx.recv().await.unwrap(), 456);
```

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

### get_disjoint_unchecked_mut example with range indices

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html?search=

Uses unsafe get_disjoint_unchecked_mut with an array of ranges to get mutable references to slices, modifies them, and asserts the result.

```rust
unsafe {
    let [a, b] = x.get_disjoint_unchecked_mut([0..1, 1..3]);
    a[0] = 8;
    b[0] = 88;
    b[1] = 888;
}
assert_eq!(x, &[8, 88, 888]);
```

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

### BTreeMap Entry API example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.BTreeMap.html

Demonstrates the Entry API for complex operations: or_insert, or_insert_with, and_modify, and in-place mutation.

```rust
use std::collections::BTreeMap;

// type inference lets us omit an explicit type signature (which
// would be `BTreeMap<&str, u8>` in this example).
let mut player_stats = BTreeMap::new();

fn random_stat_buff() -> u8 {
    // could actually return some random value here - let's just return
    // some fixed value for now
    42
}

// insert a key only if it doesn't already exist
player_stats.entry("health").or_insert(100);

// insert a key using a function that provides a new value only if it
// doesn't already exist
player_stats.entry("defence").or_insert_with(random_stat_buff);

// update a key, guarding against the key possibly not being set
let stat = player_stats.entry("attack").or_insert(100);
*stat += random_stat_buff();

// modify an entry before an insert with in-place mutation
player_stats.entry("mana").and_modify(|mana| *mana += 200).or_insert(100);
```

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

### element_offset basic usage example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

Shows element_offset returning the index of an element reference. Returns None if the element does not point to the start of an element.

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

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

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

### basic_simd_sum example for as_simd_mut

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

Example for the as_simd_mut method, showing a basic SIMD sum over a slice. The example uses a nightly-only API (portable_simd) and demonstrates splitting a slice into SIMD-aligned parts.

```rust
let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);
```

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

### strong_count_from_raw example

Source: https://docs.rs/rsipstack/latest/rsipstack/dialog/dialog_layer/type.DialogLayerInnerRef.html

Shows how to get the strong count from a raw pointer. Requires the nightly feature arc_raw_get_strong. The pointer must point to a live Arc allocation. The example clones the Arc, converts to raw, and asserts the count is 2, then converts back to avoid leaking.

```rust
#![feature(arc_raw_get_strong)]
use std::sync::Arc;

let five = Arc::new(5);
let _also_five = Arc::clone(&five);
let ptr = Arc::into_raw(five);

unsafe {
    // This assertion is deterministic because we haven't shared
    // the `Arc` between threads.
    assert_eq!(2, Arc::strong_count_from_raw(ptr));

    // Convert back to an `Arc` to avoid leaking memory.
    let five = Arc::from_raw(ptr);
    assert_eq!(2, Arc::strong_count(&five));
}
```

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

### EndpointBuilder usage example

Source: https://docs.rs/rsipstack/latest/rsipstack/transaction/endpoint/struct.EndpointBuilder.html?search=std%3A%3Avec

Example showing how to use EndpointBuilder to create an endpoint with a user agent, timer interval, and allowed methods.

```rust
use rsipstack::EndpointBuilder;
use core::time::Duration;

let endpoint = EndpointBuilder::new()
    .with_user_agent("MyApp/1.0")
    .with_timer_interval(Duration::from_millis(10))
    .with_allows(vec![rsipstack::sip::Method::Invite, rsipstack::sip::Method::Bye])
    .build();
```

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

### get_disjoint_unchecked_mut example with RangeInclusive indices

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html?search=

Uses unsafe get_disjoint_unchecked_mut with an array of RangeInclusive indices to get mutable references to slices, modifies them, and asserts the result.

```rust
unsafe {
    let [a, b] = x.get_disjoint_unchecked_mut([1..=2, 0..=0]);
    a[0] = 11;
    a[1] = 111;
    b[0] = 1;
}
assert_eq!(x, &[1, 11, 111]);
```

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

### rchunks_mut example: mutable chunks from the end

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Vec.html

Shows how to use slice.rchunks_mut(2) to get mutable chunks from the end and modify elements. Panics if chunk_size is zero.

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

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

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

### Box::try_new_uninit example (nightly)

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.Box.html

Nightly-only experimental API (allocator_ext). Constructs a new box with uninitialized contents, returning an error if allocation fails.

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

let mut five = Box::<u32>::try_new_uninit()?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

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

### Get first entry for in-place manipulation with first_entry()

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.BTreeMap.html

Returns the entry with the minimum key, allowing in-place modification. The example updates the value if the key is positive.

```rust
use std::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert(1, "a");
map.insert(2, "b");
if let Some(mut entry) = map.first_entry() {
    if *entry.key() > 0 {
        entry.insert("first");
    }
}
assert_eq!(*map.get(&1).unwrap(), "first");
assert_eq!(*map.get(&2).unwrap(), "b");
```

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

### BTreeSet usage example

Source: https://docs.rs/rsipstack/latest/rsipstack/prelude/struct.BTreeSet.html

Demonstrates creating a BTreeSet, inserting, checking, removing, and iterating over items. Shows type inference and the order of iteration.

```rust
use std::collections::BTreeSet;

// Type inference lets us omit an explicit type signature (which
// would be `BTreeSet<&str>` in this example).
let mut books = BTreeSet::new();

// Add some books.
books.insert("A Dance With Dragons");
books.insert("To Kill a Mockingbird");
books.insert("The Odyssey");
books.insert("The Great Gatsby");

// Check for a specific one.
if !books.contains("The Winds of Winter") {
    println!("We have {} books, but The Winds of Winter ain't one.",
             books.len());
}

// Remove a book.
books.remove("The Odyssey");

// Iterate over everything.
for book in &books {
    println!("{book}");
}
```

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

### get_mut_slice: Get mutable slice of u64 from AtomicU64 slice

Source: https://docs.rs/rsipstack/latest/rsipstack/platform/atomic64/type.AtomicU64.html

Provides non-atomic mutable access to a slice of AtomicU64 values. Safe because mutable reference guarantees exclusive access. Example shows initializing an array of AtomicU64, getting a mutable slice, modifying values, and verifying with threads.

```rust
use std::sync::atomic::{AtomicU64, Ordering};

let mut some_ints = [const { AtomicU64::new(0) }; 10];

let view: &mut [u64] = AtomicU64::get_mut_slice(&mut some_ints);
assert_eq!(view, [0; 10]);
view
    .iter_mut()
    .enumerate()
    .for_each(|(idx, int)| *int = idx as _);

std::thread::scope(|s| {
    some_ints
        .iter()
        .enumerate()
        .for_each(|(idx, int)| {
            s.spawn(move || assert_eq!(int.load(Ordering::Relaxed), idx as _));
        })
});
```

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

### and_then: chaining fallible operations

Source: https://docs.rs/rsipstack/latest/rsipstack/type.Result.html?search=u32+-%3E+bool

Shows how to use Result::and_then to chain operations that may fail. The first example uses a function sq_then_to_string that returns a Result. The second example uses Path::metadata().and_then() to get the modified time, demonstrating error handling with ErrorKind::NotFound.

```rust
assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));
assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed"));
assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number"));
```

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```
Tokens:
Raw