### PasetoNonce Usage Example

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/core/key/paseto_nonce.rs.html

Example demonstrating how to create and use a PasetoNonce with Paseto encryption.

```APIDOC
## PasetoNonce

### Description
A nonce key for use in PASETO algorithms. Key sizes for nonces are either 32 or 24 bytes in size. Nonces can be specified directly for testing or randomly in production.

### Method
N/A (Struct definition and usage example)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```rust
use serde_json::json;
use rusty_paseto::core::*;

// Assuming V4 and Local are defined and feature flags are enabled
let key = PasetoSymmetricKey::<V4, Local>::from(Key::<32>::try_from("707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f")?);
// generate a random nonce with
let nonce = Key::<32>::try_new_random()?;
let nonce = PasetoNonce::<V4, Local>::from(&nonce);

let payload = json!({{"data": "this is a secret message", "exp":"2022-01-01T00:00:00+00:00"}}).to_string();
let payload = payload.as_str();
let payload = Payload::from(payload);

//create a public v4 token
let token = Paseto::<V4, Local>::builder()
  .set_payload(payload)
  .try_encrypt(&key, &nonce)?;
```

### Response
N/A (This is a code example, not an API endpoint response)
```

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

### Example: Encrypt and Decrypt V2 Local PASETO Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/generic/parsers/generic_parser.rs.html

Illustrates the process of creating, encrypting, and then decrypting a V2 Local PASETO token. This example includes setting various standard and custom claims, a footer, and then verifying the decrypted content.

```rust
///     let key = PasetoSymmetricKey::<V2, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
///     let footer = Footer::from("some footer");
///     //create a builder, add some claims and then build the token with the key
///     let token = GenericBuilder::<V2, Local>::default()
///       .set_claim(AudienceClaim::from("customers"))
///       .set_claim(SubjectClaim::from("loyal subjects"))
///       .set_claim(IssuerClaim::from("me"))
///       .set_claim(TokenIdentifierClaim::from("me"))
///       .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
///       .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
///       .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
///       .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
///       .set_claim(CustomClaim::try_from(("seats", 4))?)
///       .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
///       .set_footer(footer)
///       .try_encrypt(&key)?;
///     //now let's decrypt the token and verify the values
///     let json = GenericParser::<V2, Local>::default()
///       .set_footer(footer)
///       .parse(&token, &key)?;
///     assert_eq!(json["aud"], "customers");
///     assert_eq!(json["jti"], "me");
///     assert_eq!(json["iss"], "me");
///     assert_eq!(json["data"], "this is a secret message");
///     assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
///     assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
///     assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
///     assert_eq!(json["sub"], "loyal subjects");
///     assert_eq!(json["pi to 6 digits"], 3.141526);
///     assert_eq!(json["seats"], 4);
///  # }
/// # Ok::<(),anyhow::Error>(())
```

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

### GenericBuilder Usage Example

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/generic/builders/generic_builder.rs.html

Demonstrates how to create, configure, and encrypt a PASETO token using the GenericBuilder.

```APIDOC
## GenericBuilder Usage Example

### Description
This example shows how to use the `GenericBuilder` to construct a PASETO token with various claims and a footer, then encrypt it using a symmetric key. It also demonstrates how to parse and verify the token using `GenericParser`.

### Method
N/A (This is a usage example, not a direct API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```rust
# #[cfg(all(feature = "generic", feature="v2_local"))]
# {
use rusty_paseto::generic::*;
  let key = PasetoSymmetricKey::<V2, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
  let footer = Footer::from("some footer");
  //create a builder, add some claims and then build the token with the key
  let token = GenericBuilder::<V2, Local>::default()
    .set_claim(AudienceClaim::from("customers"))
    .set_claim(SubjectClaim::from("loyal subjects"))
    .set_claim(IssuerClaim::from("me"))
    .set_claim(TokenIdentifierClaim::from("me"))
    .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
    .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
    .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
    .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
    .set_claim(CustomClaim::try_from(("seats", 4))?)
    .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
    .set_footer(footer)
    .try_encrypt(&key)?;
  //now let's decrypt the token and verify the values
  let json = GenericParser::<V2, Local>::default()
    .set_footer(footer)
    .parse(&token, &key)?;
  assert_eq!(json["aud"], "customers");
  assert_eq!(json["jti"], "me");
  assert_eq!(json["iss"], "me");
  assert_eq!(json["data"], "this is a secret message");
  assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
  assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
  assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
  assert_eq!(json["sub"], "loyal subjects");
  assert_eq!(json["pi to 6 digits"], 3.141526);
  assert_eq!(json["seats"], 4);
# }
# Ok::<(),anyhow::Error>(())
```

### Response
N/A (This is a usage example)
```

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

### Usage of GenericBuilder and GenericParser

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/generic/struct.GenericParser.html

Example demonstrating building a token with claims and then parsing/decrypting it using GenericParser.

```rust
   use rusty_paseto::generic::*;
     let key = PasetoSymmetricKey::<V2, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
     let footer = Footer::from("some footer");
     //create a builder, add some claims and then build the token with the key
     let token = GenericBuilder::<V2, Local>::default()
       .set_claim(AudienceClaim::from("customers"))
       .set_claim(SubjectClaim::from("loyal subjects"))
       .set_claim(IssuerClaim::from("me"))
       .set_claim(TokenIdentifierClaim::from("me"))
       .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
       .set_claim(CustomClaim::try_from(("seats", 4))?)
       .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
       .set_footer(footer)
       .try_encrypt(&key)?;
     //now let's decrypt the token and verify the values
     let json = GenericParser::<V2, Local>::default()
       .set_footer(footer)
       .parse(&token, &key)?;
     assert_eq!(json["aud"], "customers");
     assert_eq!(json["jti"], "me");
     assert_eq!(json["iss"], "me");
     assert_eq!(json["data"], "this is a secret message");
     assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["sub"], "loyal subjects");
     assert_eq!(json["pi to 6 digits"], 3.141526);
     assert_eq!(json["seats"], 4);
```

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

### Parse token and verify components

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.UntrustedToken.html

Example of parsing a token and accessing its version and purpose fields.

```rust
let token = "v4.local.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAr68PS4AXe7If_ZgesdkUMvSwscFlAl1pk5HC0e8kApeaqMfGo_7OpBnwJOAbY9V7WU6abu74MmcUE8YWAiaArVI8XJ5hOb_4v9RmDkneN0S92dx0OW4pgy7omxgf3S8c3LlQg";

let untrusted = UntrustedToken::try_parse(token)?;
assert_eq!(untrusted.version(), "v4");
assert_eq!(untrusted.purpose(), "local");
```

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

### Create and Encrypt PASETO Token with Claims and Footer

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/prelude/struct.PasetoBuilder.html

This example demonstrates how to create a PASETO token with various standard and custom claims, set a footer, and encrypt it using a symmetric key. It also shows how to parse and verify the token afterwards.

```rust
use rusty_paseto::prelude::*;
     let key = PasetoSymmetricKey::<V2, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
     let footer = Footer::from("some footer");
     //create a builder, add some claims and then build the token with the key
     let token = PasetoBuilder::<V2, Local>::default()
       .set_claim(AudienceClaim::from("customers"))
       .set_claim(SubjectClaim::from("loyal subjects"))
       .set_claim(IssuerClaim::from("me"))
       .set_claim(TokenIdentifierClaim::from("me"))
       .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
       .set_claim(CustomClaim::try_from(("seats", 4))?)
       .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
       .set_footer(footer)
       .try_encrypt(&key)?;
     //now let's decrypt the token and verify the values
     let json = PasetoParser::<V2, Local>::default()
       .set_footer(footer)
       .parse(&token, &key)?;
     assert_eq!(json["aud"], "customers");
     assert_eq!(json["jti"], "me");
     assert_eq!(json["iss"], "me");
     assert_eq!(json["data"], "this is a secret message");
     assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["sub"], "loyal subjects");
     assert_eq!(json["pi to 6 digits"], 3.141526);
     assert_eq!(json["seats"], 4);
```

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

### Escape ASCII Bytes

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.Payload.html

Use this method to get an iterator that produces an escaped version of a byte slice, treating it as an ASCII string. The example shows how to convert the iterator to a string.

```rust
let s = b"0\t\r\n'\"\\\x9d";
let escaped = s.escape_ascii().to_string();
assert_eq!(escaped, "0\\t\\r\\n\'\\"\\\\\\x9d");
```

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

### Example: Sign and Verify V4 Public PASETO Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_parser.rs.html

Demonstrates creating, signing, and then verifying a V4 Public PASETO token with various claims and assertions. Requires specific key types and feature flags.

```rust
# #[cfg(all(feature = "prelude", feature="v4_public"))]
# {
#   use rusty_paseto::prelude::*;
# //create a key
# let private_key = Key::<64>::try_from("b4cbfb43df4ce210727d953e4a713307fa19bb7d9f85041438d9e11b942a37741eb9dbbbbc047c03fd70604e0071f0987e16b28b757225c11f00415d0e20b1a2")?;
# let pk: &[u8] = private_key.as_slice();
# let private_key = PasetoAsymmetricPrivateKey::<V4, Public>::from(pk);
# let public_key = Key::<32>::try_from("1eb9dbbbbc047c03fd70604e0071f0987e16b28b757225c11f00415d0e20b1a2")?;
# let public_key = PasetoAsymmetricPublicKey::<V4, Public>::from(&public_key);
# let footer = Footer::from("some footer");
# let implicit_assertion = ImplicitAssertion::from("some assertion");
# //sign a public V4 token
# let token = PasetoBuilder::<V4, Public>::default()
#   .set_claim(AudienceClaim::from("customers"))
#   .set_claim(SubjectClaim::from("loyal subjects"))
#   .set_claim(IssuerClaim::from("me"))
#   .set_claim(TokenIdentifierClaim::from("me"))
#   .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
#   .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
#   .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
#   .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
#   .set_claim(CustomClaim::try_from(("seats", 4))?)
#   .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
#   .set_footer(footer)
#   .set_implicit_assertion(implicit_assertion)
#   .try_sign(&private_key)?;
# //now let's try to verify it
# let json = PasetoParser::<V4, Public>::default()
#   .set_footer(footer)
#   .set_implicit_assertion(implicit_assertion)
#   .check_claim(AudienceClaim::from("customers"))
#   .check_claim(SubjectClaim::from("loyal subjects"))
#   .check_claim(IssuerClaim::from("me"))
#   .check_claim(TokenIdentifierClaim::from("me"))
#   .check_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
#   .check_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
#   .check_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
#   .check_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
#   .check_claim(CustomClaim::try_from(("seats", 4))?)
#   .check_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
#   .parse(&token, &public_key)?;
# // we can access all the values from the serde Value object returned by the parser
# assert_eq!(json["aud"], "customers");
# assert_eq!(json["jti"], "me");
# assert_eq!(json["iss"], "me");
# assert_eq!(json["data"], "this is a secret message");
# assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
# assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
# assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
# assert_eq!(json["sub"], "loyal subjects");
# assert_eq!(json["pi to 6 digits"], 3.141526);
# assert_eq!(json["seats"], 4);
#  # }
# # Ok::<(),anyhow::Error>(())
```

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

### Get multiple mutable references unchecked

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/generic/type.ValidatorMap.html

Attempts to get mutable references to multiple values in the map at once, without validating that the values are unique. Calling this method with overlapping keys is undefined behavior.

```rust
pub unsafe fn get_disjoint_unchecked_mut<Q, const N: usize>( &mut self, ks: [&Q; N], ) -> [Option<&mut V>; N]
where K: Borrow<Q>,
    Q: Hash + Eq + ?Sized,
{
    // Implementation omitted for brevity
    unimplemented!();
}
```

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

### Get multiple mutable references safely

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/generic/type.ValidatorMap.html

Attempts to get mutable references to multiple values in the map at once. Returns an array of results, using None for missing keys. Panics if any keys are overlapping.

```rust
use std::collections::HashMap;

let mut libraries = HashMap::new();
libraries.insert("Bodleian Library".to_string(), 1602);
libraries.insert("Athenæum".to_string(), 1807);
libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691);
libraries.insert("Library of Congress".to_string(), 1800);

// Get Athenæum and Bodleian Library
let [Some(a), Some(b)] = libraries.get_disjoint_mut([
    "Athenæum",
    "Bodleian Library",
]) else { panic!() };

// Assert values of Athenæum and Library of Congress
let got = libraries.get_disjoint_mut([
    "Athenæum",
    "Library of Congress",
]);
assert_eq!(
    got,
    [
        Some(&mut 1807),
        Some(&mut 1800),
    ],
);

// Missing keys result in None
let got = libraries.get_disjoint_mut([
    "Athenæum",
    "New York Public Library",
]);
assert_eq!(
    got,
    [
        Some(&mut 1807),
        None
    ]
);
```

```rust
use std::collections::HashMap;

let mut libraries = HashMap::new();
libraries.insert("Athenæum".to_string(), 1807);

// Duplicate keys panic!
let got = libraries.get_disjoint_mut([
    "Athenæum",
    "Athenæum",
]);
```

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

### Create and Use PasetoBuilder with Claims

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_builder.rs.html

Demonstrates creating a PASETO token with various standard and custom claims, setting a footer, and then parsing and verifying the token. Requires V2 Local feature and prelude.

```rust
use rusty_paseto::prelude::*;
    let key = PasetoSymmetricKey::<V2, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
    let footer = Footer::from("some footer");
    //create a builder, add some claims and then build the token with the key
    let token = PasetoBuilder::<V2, Local>::default()
      .set_claim(AudienceClaim::from("customers"))
      .set_claim(SubjectClaim::from("loyal subjects"))
      .set_claim(IssuerClaim::from("me"))
      .set_claim(TokenIdentifierClaim::from("me"))
      .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
      .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
      .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
      .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
      .set_claim(CustomClaim::try_from(("seats", 4))?)
      .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
      .set_footer(footer)
      .try_encrypt(&key)?;
    //now let's decrypt the token and verify the values
    let json = PasetoParser::<V2, Local>::default()
      .set_footer(footer)
      .parse(&token, &key)?;
    assert_eq!(json["aud"], "customers");
    assert_eq!(json["jti"], "me");
    assert_eq!(json["iss"], "me");
    assert_eq!(json["data"], "this is a secret message");
    assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
    assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
    assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
    assert_eq!(json["sub"], "loyal subjects");
    assert_eq!(json["pi to 6 digits"], 3.141526);
    assert_eq!(json["seats"], 4);
```

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

### Get key-value pair from HashMap

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/generic/type.ValidatorMap.html

Retrieves the key-value pair corresponding to the supplied key. Useful for key types where non-identical keys can be considered equal, or for getting the stored key value from a borrowed lookup key.

```rust
use std::collections::HashMap;
use std::hash::{Hash, Hasher};

#[derive(Clone, Copy, Debug)]
struct S {
    id: u32,
    name: &'static str, // ignored by equality and hashing operations
}

impl PartialEq for S {
    fn eq(&self, other: &S) -> bool {
        self.id == other.id
    }
}

impl Eq for S {}

impl Hash for S {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.id.hash(state);
    }
}

let j_a = S { id: 1, name: "Jessica" };
let j_b = S { id: 1, name: "Jess" };
let p = S { id: 2, name: "Paul" };
assert_eq!(j_a, j_b);

let mut map = HashMap::new();
map.insert(j_a, "Paris");
assert_eq!(map.get_key_value(&j_a), Some((&j_a, &"Paris")));
assert_eq!(map.get_key_value(&j_b), Some((&j_a, &"Paris"))); // the notable case
assert_eq!(map.get_key_value(&p), None);
```

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

### Basic V3 Public PASETO Parser Test Setup

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_parser.rs.html

Sets up the necessary components for a basic V3 Public PASETO parser test, including defining a public key.

```rust
let public_key = Key::<49>::try_from(
  "02fbcb7c69ee1c60579be7a334134878d9c5c5bf35d552dab63c0140397ed14cef637d7720925c44699ea30e72874c72fb",
)?;
```

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

### as_array

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.Footer.html

Gets a reference to the underlying array.

```APIDOC
## as_array

### Description
Attempts to return a reference to the underlying array of size N. Returns None if the slice length does not match N.

### Parameters
#### Generic Parameters
- **N** (usize) - Required - The expected length of the array.

### Response
- **return** (Option<&[T; N]>) - The array reference if lengths match, otherwise None.
```

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

### Example: Encrypt and Decrypt V1 Local PASETO Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/generic/parsers/generic_parser.rs.html

Demonstrates creating, encrypting, and then decrypting a V1 Local PASETO token with custom claims and a footer. Verifies the decrypted claims against expected values.

```rust
///       .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
///       .set_claim(CustomClaim::try_from(("seats", 4))?)
///       .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
///       .set_footer(footer)
///       .try_encrypt(&key)?;
///     //now let's decrypt the token and verify the values
///     let json = GenericParser::<V1, Local>::default()
///       .set_footer(footer)
///       .parse(&token, &key)?;
///     assert_eq!(json["aud"], "customers");
///     assert_eq!(json["jti"], "me");
///     assert_eq!(json["iss"], "me");
///     assert_eq!(json["data"], "this is a secret message");
///     assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
///     assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
///     assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
///     assert_eq!(json["sub"], "loyal subjects");
///     assert_eq!(json["pi to 6 digits"], 3.141526);
///     assert_eq!(json["seats"], 4);
///  # }
/// # Ok::<(),anyhow::Error>(())
```

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

### starts_with

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.PasetoNonce.html

Checks if the slice starts with the given prefix.

```APIDOC
## starts_with

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

### Parameters
- **needle** (&[T]) - Required - The prefix to check.

### Response
- **bool** - True if it starts with the prefix.
```

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

### starts_with

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.Payload.html

Checks if the slice starts with the provided needle.

```APIDOC
## starts_with

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

### Parameters
- **needle** (&[T]) - Required - The prefix to check for.
```

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

### Build and Encrypt V2 Local Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_parser.rs.html

Demonstrates building a V2 Local PASETO token with various claims and encrypting it using a PasetoSymmetricKey. This example sets audience, subject, issuer, token identifier, issued at, not before, expiration, and custom claims.

```rust
use rusty_paseto::prelude::*;
    let key = PasetoSymmetricKey::<V2, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
    let footer = Footer::from("some footer");
    //create a builder, add some claims and then build the token with the key
    let token = PasetoBuilder::<V2, Local>::default()
      .set_claim(AudienceClaim::from("customers"))
```

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

### trim_prefix

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.Payload.html

Returns a subslice with the optional prefix removed. If the slice starts with `prefix`, returns the subslice after the prefix. If `prefix` is empty or the slice does not start with `prefix`, simply returns the original slice. If `prefix` is equal to the original slice, returns an empty slice.

```APIDOC
## trim_prefix

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

### Method
N/A (This is a method on slices)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

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

// Prefix present - removes it
assert_eq!(v.trim_prefix(&[10]), &[40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 40]), &[30][..]);
assert_eq!(v.trim_prefix(&[10, 40, 30]), &[][..]);

// Prefix absent - returns original slice
assert_eq!(v.trim_prefix(&[50]), &[10, 40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 50]), &[10, 40, 30][..]);

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

### Response
#### Success Response (200)
N/A (This is a method, not an API endpoint)

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

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

### Build V4 Local PASETO Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_builder.rs.html

Demonstrates initializing a V4 local PASETO builder and setting initial claims.

```rust
# #[cfg(all(feature = "prelude", feature="v4_local"))]
# {
   use rusty_paseto::prelude::*;
     let key = PasetoSymmetricKey::<V4, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
     let footer = Footer::from("some footer");
     let implicit_assertion = ImplicitAssertion::from("some assertion");
     //create a builder, add some claims and then build the token with the key
     let token = PasetoBuilder::<V4, Local>::default()
       .set_claim(AudienceClaim::from("customers"))
       .set_claim(SubjectClaim::from("loyal subjects"))
       .set_claim(IssuerClaim::from("me"))
       .set_claim(TokenIdentifierClaim::from("me"))
       .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
```

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

### Get Slice Length

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.PasetoNonce.html

Returns the number of elements in a slice.

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

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

### Build and Encrypt V2 Local PASETO Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_builder.rs.html

Demonstrates creating a V2 local PASETO token with multiple claims and a footer, then decrypting and verifying it.

```rust
   use rusty_paseto::prelude::*;
     let key = PasetoSymmetricKey::<V2, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
     let footer = Footer::from("some footer");
     //create a builder, add some claims and then build the token with the key
     let token = PasetoBuilder::<V2, Local>::default()
       .set_claim(AudienceClaim::from("customers"))
       .set_claim(SubjectClaim::from("loyal subjects"))
       .set_claim(IssuerClaim::from("me"))
       .set_claim(TokenIdentifierClaim::from("me"))
       .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
       .set_claim(CustomClaim::try_from(("seats", 4))?)
       .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
       .set_footer(footer)
       .try_encrypt(&key)?;
     //now let's decrypt the token and verify the values
     let json = PasetoParser::<V2, Local>::default()
       .set_footer(footer)
       .parse(&token, &key)?;
     assert_eq!(json["aud"], "customers");
     assert_eq!(json["jti"], "me");
```

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

### GET /api/hashmap/get

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/generic/type.ValidatorMap.html

Retrieves a reference to the value corresponding to the key.

```APIDOC
## GET /api/hashmap/get

### Description
Returns a reference to the value corresponding to the key. The key may be any borrowed form of the map’s key type, but `Hash` and `Eq` on the borrowed form _must_ match those for the key type.

### Method
GET

### Endpoint
/api/hashmap/get

### Parameters
#### Query Parameters
- **k** (Q) - Required - The key to look up.

### Response
#### Success Response (200)
- **V** (Option<&V>) - A reference to the value if the key exists, otherwise None.

#### Response Example
```json
{
  "example": "Some(\"a\")"
}
```
```

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

### Build and Verify Asymmetric PASETO Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_builder.rs.html

Demonstrates setting various claims, signing with a private key, and verifying with a public key using V4 asymmetric tokens.

```rust
.set_claim(SubjectClaim::from("loyal subjects"))
  .set_claim(IssuerClaim::from("me"))
  .set_claim(TokenIdentifierClaim::from("me"))
  .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
  .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
  .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
  .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
  .set_claim(CustomClaim::try_from(("seats", 4))?)
  .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
  .set_footer(footer)
  .set_implicit_assertion(implicit_assertion)
  .try_sign(&private_key)?;
//now let's try to verify it
let json = PasetoParser::<V4, Public>::default()
  .set_footer(footer)
  .set_implicit_assertion(implicit_assertion)
  .check_claim(AudienceClaim::from("customers"))
  .check_claim(SubjectClaim::from("loyal subjects"))
  .check_claim(IssuerClaim::from("me"))
  .check_claim(TokenIdentifierClaim::from("me"))
  .check_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
  .check_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
  .check_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
  .check_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
  .check_claim(CustomClaim::try_from(("seats", 4))?)
  .check_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
  .parse(&token, &public_key)?;
// we can access all the values from the serde Value object returned by the parser
assert_eq!(json["aud"], "customers");
assert_eq!(json["jti"], "me");
assert_eq!(json["iss"], "me");
assert_eq!(json["data"], "this is a secret message");
assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
assert_eq!(json["sub"], "loyal subjects");
assert_eq!(json["pi to 6 digits"], 3.141526);
assert_eq!(json["seats"], 4);
```

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

### Key Struct and Initialization

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.Key.html

Details on the Key struct, its purpose, and how to create new keys.

```APIDOC
## Struct Key

### Description
A wrapper for a slice of bytes that constitute a key of a specific size.

### Constructor
#### `pub fn try_new_random() -> Result<Self, PasetoError>`
Uses the system’s RNG to create a random slice of bytes of a specific size.

##### Errors
Returns `PasetoError::Cipher` if the system’s random number generator fails to fill the buffer.
```

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

### Footer Management

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/generic/parsers/generic_parser.rs.html

Methods for getting and setting the footer associated with the parser.

```APIDOC
## GET /api/users/{id}

### Description
Gets an optional [Footer] set during parser building.

### Method
GET

### Endpoint
/api/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The ID of the user.
- **name** (string) - The name of the user.

#### Response Example
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe"
}
```

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

### get

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/core/struct.Payload.html

Returns a reference to an element or subslice depending on the type of index.

```APIDOC
## pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>

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

### Request Example
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
```

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

### Build and Encrypt V1 Local PASETO Token

Source: https://docs.rs/rusty_paseto/latest/src/rusty_paseto/prelude/paseto_builder.rs.html

Demonstrates creating a V1 local PASETO token with multiple claims and a footer, then decrypting and verifying it.

```rust
   use rusty_paseto::prelude::*;
     let key = PasetoSymmetricKey::<V1, Local>::from(Key::<32>::from(*b"wubbalubbadubdubwubbalubbadubdub"));
     let footer = Footer::from("some footer");
     //create a builder, add some claims and then build the token with the key
     let token = PasetoBuilder::<V1, Local>::default()
       .set_claim(AudienceClaim::from("customers"))
       .set_claim(SubjectClaim::from("loyal subjects"))
       .set_claim(IssuerClaim::from("me"))
       .set_claim(TokenIdentifierClaim::from("me"))
       .set_claim(IssuedAtClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(NotBeforeClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(ExpirationClaim::try_from("2019-01-01T00:00:00+00:00")?)
       .set_claim(CustomClaim::try_from(("data", "this is a secret message"))?)
       .set_claim(CustomClaim::try_from(("seats", 4))?)
       .set_claim(CustomClaim::try_from(("pi to 6 digits", 3.141526))?)
       .set_footer(footer)
       .build(&key)?;
     //now let's decrypt the token and verify the values
     let json = PasetoParser::<V1, Local>::default()
       .set_footer(footer)
       .parse(&token, &key)?;
     assert_eq!(json["aud"], "customers");
     assert_eq!(json["jti"], "me");
     assert_eq!(json["iss"], "me");
     assert_eq!(json["data"], "this is a secret message");
     assert_eq!(json["exp"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["iat"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["nbf"], "2019-01-01T00:00:00+00:00");
     assert_eq!(json["sub"], "loyal subjects");
     assert_eq!(json["pi to 6 digits"], 3.141526);
     assert_eq!(json["seats"], 4);
```

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

### GET /api/hashmap/get_key_value

Source: https://docs.rs/rusty_paseto/latest/rusty_paseto/generic/type.ValidatorMap.html

Retrieves the key-value pair corresponding to the supplied key.

```APIDOC
## GET /api/hashmap/get_key_value

### Description
Returns the key-value pair corresponding to the supplied key. This is potentially useful for key types where non-identical keys can be considered equal, for getting the `&K` stored key value from a borrowed `&Q` lookup key, or for getting a reference to a key with the same lifetime as the collection.

The supplied key may be any borrowed form of the map’s key type, but `Hash` and `Eq` on the borrowed form _must_ match those for the key type.

### Method
GET

### Endpoint
/api/hashmap/get_key_value

### Parameters
#### Query Parameters
- **k** (Q) - Required - The key to look up.

### Response
#### Success Response (200)
- **(&K, &V)** (Option<(&K, &V)>) - A tuple containing references to the key and value if the key exists, otherwise None.

#### Response Example
```json
{
  "example": "Some((&j_a, &\"Paris\"))"
}
```
```