Keyring Core

https://docs.rs/keyring-core/latest/keyring_core/
Admin
Keyring Core is a library that provides a core API for interacting with system keyrings, offering...
Tokens:154,364
Snippets:1,732
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### DashMap::with_capacity_and_hasher example

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Creates a new DashMap with a specified starting capacity and hasher, then inserts two key-value pairs.

```rust
use dashmap::DashMap;
use std::collections::hash_map::RandomState;

let s = RandomState::new();
let mappings = DashMap::with_capacity_and_hasher(2, s);
mappings.insert(2, 4);
mappings.insert(8, 16);
```

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

### DashMap::with_capacity example

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Creates a new DashMap with a specified starting capacity and inserts two key-value pairs.

```rust
use dashmap::DashMap;

let mappings = DashMap::with_capacity(2);
mappings.insert(2, 4);
mappings.insert(8, 16);
```

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

### DashMap::with_capacity_and_hasher_and_shard_amount example

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Creates a new DashMap with a specified starting capacity, hasher, and shard amount. The shard amount must be greater than 0 and a power of two; otherwise the function panics.

```rust
use dashmap::DashMap;
use std::collections::hash_map::RandomState;

let s = RandomState::new();
let mappings = DashMap::with_capacity_and_hasher_and_shard_amount(2, s, 32);
mappings.insert(2, 4);
mappings.insert(8, 16);
```

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

### is_ok example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the is_ok method, which returns true if the result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

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

### DashMap::hasher example

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Returns a reference to the map's BuildHasher. The example creates a DashMap and retrieves its hasher.

```rust
use dashmap::DashMap;
use std::collections::hash_map::RandomState;

let hasher = RandomState::new();
let map: DashMap<i32, i32> = DashMap::new();
let hasher: &RandomState = map.hasher();
```

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

### is_ok_and example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the is_ok_and method, which returns true if the result is Ok and the value matches a predicate. The last case shows using as_ref to avoid consuming the result.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

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

### Box::clone_from_ref_in example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html

Example showing Box::clone_from_ref_in, which allocates memory in the given allocator and clones the source into it. Requires nightly features clone_from_ref and allocator_api.

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

use std::alloc::System;

let hello: Box<str, System> = Box::clone_from_ref_in("hello", System);
```

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

### Box::try_clone_from_ref_in example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html

Example demonstrating Box::try_clone_from_ref_in, which clones into a box with the given allocator and returns a Result, propagating errors with ?. Requires nightly features clone_from_ref and allocator_api.

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

use std::alloc::System;

let hello: Box<str, System> = Box::try_clone_from_ref_in("hello", System)?;
```

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

### Mock credential error handling example

Source: https://docs.rs/keyring-core/latest/keyring_core/mock/index.html?search=

Complete example showing how to set a mock error on a credential and verify that the error is returned once and then cleared. The error does not affect the stored password.

```rust
keyring_core::set_default_store(mock::Store::new().unwrap());
let entry = Entry::new("service", "user").unwrap();
entry.set_password("test").expect("the entry's password is now test");
let mock: &mock::Cred = entry.as_any().downcast_ref().unwrap();
mock.set_error(Error::Invalid("mock error".to_string(), "takes precedence".to_string()));
_ = entry.get_password().expect_err("the error will be returned");
let val = entry.get_password().expect("the error has been cleared");
assert_eq!(val, "test", "the error did not affect the password");
```

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

### copied example for Result<&mut T, E>

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the copied method on Result<&mut T, E>, which copies the Ok value. Requires T: Copy.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

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

### Box::take example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html

Example demonstrating Box::take, which consumes the box and returns the value and a box to uninitialized memory. It then reuses the allocation with Box::write.

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

let c = Box::new(5);

// take the value out of the box
let (value, uninit) = Box::take(c);
assert_eq!(value, 5);

// reuse the box for a second value
let c = Box::write(uninit, 6);
assert_eq!(*c, 6);
```

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

### cloned example for Result<&mut T, E>

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the cloned method on Result<&mut T, E>, which clones the Ok value. Requires T: Clone.

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

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

### cloned example for Result<&T, E>

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the cloned method on Result<&T, E>, which clones the Ok value. Requires T: Clone.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

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

### copied example for Result<&T, E>

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the copied method on Result<&T, E>, which copies the Ok value. Requires T: Copy.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

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

### map example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Shows mapping a Result's Ok value using a function, leaving Err untouched. The example parses lines of a string and prints each number multiplied by two.

```rust
let line = "1\n2\n3\n4\n";

for num in line.lines() {
    match num.parse::<i32>().map(|i| i * 2) {
        Ok(n) => println!("{n}"),
        Err(..) => {}
    }
}
```

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

### and_then control flow example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows the and_then method for control flow based on Result values. This example defines a function that squares a number and converts it to a string, returning an error on overflow.

```rust
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {
    x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed")
}
```

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

### is_err_and example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Shows how to use is_err_and to check if a Result is Err and the error value matches a predicate. The example uses std::io::Error and demonstrates true/false results for different error kinds and an Ok value.

```rust
use std::io::{Error, ErrorKind};

let x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);

let x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, "!"));
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, Error> = Ok(123);
assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);

let x: Result<u32, String> = Err("ownership".to_string());
assert_eq!(x.as_ref().is_err_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

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

### transpose example for Result<Option<T>, E>

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the transpose method on Result<Option<T>, E>, which converts a Result of an Option into an Option of a Result. Ok(None) maps to None, Ok(Some(_)) and Err(_) map to Some(Ok(_)) and Some(Err(_)).

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

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

### Non-blocking get with try_get

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Attempts to get an immutable reference without blocking; returns TryResult::Locked if the shard is locked. The example shows that holding a mutable reference causes try_get to return a locked result.

```rust
use dashmap::DashMap;
use dashmap::try_result::TryResult;

let map = DashMap::new();
map.insert("Johnny", 21);

assert_eq!(*map.try_get("Johnny").unwrap(), 21);

let _result1_locking = map.get_mut("Johnny");

let result2 = map.try_get("Johnny");
assert!(result2.is_locked());
```

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

### Store::new_with_configuration

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/struct.Store.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new store with a user-specified configuration. Allowed configuration keys are 'persist' and 'backing-file'.

```APIDOC
## Store::new_with_configuration

### Description
Creates a new store with a user-specified configuration. There are two allowed configuration keys: `persist` and `backing-file`. See the module docs for details of how these affect the store's behavior.

### Method
new_with_configuration

### Signature
pub fn new_with_configuration(config: &HashMap<&str, &str>) -> Result<Arc<Self>>

### Parameters
- **config** (&HashMap<&str, &str>) - Required - A map of configuration keys to values.

### Returns
- **Result<Arc<Self>>** - A result containing an Arc to the new store, or an error.

```

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

### ok example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

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);
```

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

### Store::new_with_backing

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/struct.Store.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new store from a backing file. The file need not exist; if it does, initial contents are loaded from it.

```APIDOC
## Store::new_with_backing

### Description
Creates a new store from a backing file. The backing file must be a valid path, but it need not exist, in which case the store starts off empty. If the file does exist, the initial contents of the store are loaded from it.

### Method
new_with_backing

### Signature
pub fn new_with_backing(path: &str) -> Result<Arc<Self>>

### Parameters
- **path** (&str) - Required - The path to the backing file.

### Returns
- **Result<Arc<Self>>** - A result containing an Arc to the new store, or an error.

```

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

### Non-blocking mutable get with try_get_mut

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Attempts to get a mutable reference without blocking; returns TryResult::Locked if the shard is locked. The example shows that holding an immutable reference causes try_get_mut to return a locked result.

```rust
use dashmap::DashMap;
use dashmap::try_result::TryResult;

let map = DashMap::new();
map.insert("Johnny", 21);

*map.try_get_mut("Johnny").unwrap() += 1;
assert_eq!(*map.get("Johnny").unwrap(), 22);

let _result1_locking = map.get("Johnny");

let result2 = map.try_get_mut("Johnny");
assert!(result2.is_locked());
```

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

### Store::new

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/struct.Store.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new store with a default configuration (empty, no backing file). Returns an Arc to the store.

```APIDOC
## Store::new

### Description
Creates a new store with a default configuration. The default configuration is empty with no backing file.

### Method
new

### Signature
pub fn new() -> Result<Arc<Self>>

### Parameters
None

### Returns
- **Result<Arc<Self>>** - A result containing an Arc to the new store, or an error.

```

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

### Store::new_internal

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/struct.Store.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a store with the given credentials and backing file. This is an internal constructor.

```APIDOC
## Store::new_internal

### Description
Creates a store with the given credentials and backing file.

### Method
new_internal

### Signature
pub fn new_internal(creds: CredMap, backing: Option<String>) -> Arc<Self>

### Parameters
- **creds** (CredMap) - Required - The credentials to initialize the store with.
- **backing** (Option<String>) - Required - The backing file path, if any.

### Returns
- **Arc<Self>** - An Arc to the new store.

```

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

### Get immutable reference with get

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Gets an immutable reference to an entry by key. May deadlock if called while holding a mutable reference into the map.

```rust
use dashmap::DashMap;

let youtubers = DashMap::new();
youtubers.insert("Bosnian Bill", 457000);
assert_eq!(*youtubers.get("Bosnian Bill").unwrap(), 457000);
```

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

### expect recommended message style example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows the recommended style for expect messages: describe the reason you expect the Result to be Ok, focusing on the word 'should'.

```rust
let path = std::env::var("IMPORTANT_PATH")
    .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`");
```

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

### get

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Get an immutable reference to an entry in the map.

```APIDOC
## get

### Description
Get an immutable reference to an entry in the map.

### Method
get

### Signature
pub fn get<Q>(&'a self, key: &Q) -> Option<Ref<'a, K, V>>
where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

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

### Return Value
- Option<Ref<'a, K, V>> - An immutable reference to the entry if it exists, otherwise None.

### Locking Behaviour
May deadlock if called when holding a mutable reference into the map.

### Example
```rust
use dashmap::DashMap;

let youtubers = DashMap::new();
youtubers.insert("Bosnian Bill", 457000);
assert_eq!(*youtubers.get("Bosnian Bill").unwrap(), 457000);
```
```

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

### Box::try_map example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html

Example demonstrating Box::try_map, which attempts to map the value in a box and returns a Try type. The example uses u32::try_from and unwraps the result.

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

let b = Box::new(7);
let new = Box::try_map(b, u32::try_from).unwrap();
assert_eq!(*new, 7);
```

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

### Entry::new(service, user)

Source: https://docs.rs/keyring-core/latest/keyring_core/mock/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new credential entry for use with the mock store.

```APIDOC
## [Rust] Entry::new(service, user)

### Description
Creates a new credential entry with the given service and user. This is used to interact with the mock store.

### Method
Rust function call

### Endpoint
Entry::new(service, user)

### Parameters
- **service** (string) - Required - The service name for the credential.
- **user** (string) - Required - The user name for the credential.

### Return Value
- **Result<Entry, Error>** - A new entry or an error.

### Example
```rust
let entry = Entry::new("service", "user").unwrap();
```
```

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

### is_err example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Example for the is_err method, which returns true if the result is Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

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

### DashMap::new example

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Creates a new DashMap with a capacity of 0 and inserts a key-value pair.

```rust
use dashmap::DashMap;

let reviews = DashMap::new();
reviews.insert("Veloren", "What a fantastic game!");
```

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

### Result iterator example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html

Example usage of Result as an iterator, converting into an iterator and using sum.

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

let x: Result<u32, &str> = Err("nothing");
assert_eq!(x.iter().sum::<u32>(), 0);
```

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

### as_ref example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.Result.html?search=

Shows converting a Result to a Result of references, allowing inspection without consuming the original.

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

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

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

### Box::into_inner example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example for Box::into_inner, showing how to consume a box and retrieve the inner value.

```rust
let c = Box::new(5);
assert_eq!(Box::into_inner(c), 5);
```

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

### Box::map example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html

Example showing Box::map, which maps the value in a box and reuses the allocation if possible. The result is also boxed.

```rust
let b = Box::new(7);
let new = Box::map(b, |i| i + 7);
assert_eq!(*new, 14);
```

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

### Entry::new

Source: https://docs.rs/keyring-core/latest/keyring_core/mock/index.html?search=u32+-%3E+bool

Creates a new credential entry in the default store. This is a standard method on Entry, but is used with the mock store for testing.

```APIDOC
## Entry::new

### Description
Creates a new credential entry in the default store. This is a standard method on Entry, but is used with the mock store for testing.

### Usage
```rust
let entry = Entry::new("service", "user").unwrap();
```

### Parameters
- **service** (str) - Required - The service name.
- **user** (str) - Required - The username.

### Returns
- **Result<Entry>** - Ok containing the new entry, or Err if creation failed.

```

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

### Get mutable reference with get_mut

Source: https://docs.rs/keyring-core/latest/keyring_core/sample/store/type.CredMap.html

Gets a mutable reference to an entry, allowing in-place modification. May deadlock if called while holding any reference into the map.

```rust
use dashmap::DashMap;

let class = DashMap::new();
class.insert("Albin", 15);
*class.get_mut("Albin").unwrap() -= 1;
assert_eq!(*class.get("Albin").unwrap(), 14);
```

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

### Box::new_uninit

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html

Documentation for the `Box::new_uninit` associated function.

```APIDOC
## Box::new_uninit

### Description
Constructs a new box with uninitialized contents.

### Method
Associated function

### Signature
`pub fn new_uninit() -> Box<MaybeUninit<T>>`

### Returns
- **Box<MaybeUninit<T>>** - A box with uninitialized contents.

### Examples
```rust
let mut five = Box::<u32>::new_uninit();
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

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

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

### Box::into_inner example

Source: https://docs.rs/keyring-core/latest/keyring_core/error/type.PlatformError.html

Example showing how to use Box::into_inner to extract the value from a box. The code asserts that the extracted value equals 5.

```rust
assert_eq!(Box::into_inner(c), 5);
```

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

### mock::Store::new

Source: https://docs.rs/keyring-core/latest/keyring_core/mock/index.html?search=u32+-%3E+bool

Creates a new mock credential store. The store is platform-independent and provides no persistence.

```APIDOC
## mock::Store::new

### Description
Creates a new mock credential store. The store is platform-independent and provides no persistence.

### Usage
```rust
let store = keyring_core::mock::Store::new().unwrap();
```

### Returns
- **Result<Store>** - Ok containing the new store, or Err if creation failed.

```

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

### Store::new

Source: https://docs.rs/keyring-core/latest/keyring_core/mock/index.html?search=

Creates a new mock credential store. This store is platform-independent, provides no persistence, and allows specifying return values for each call.

```APIDOC
## Store::new

### Description
Creates a new mock credential store. This store is platform-independent, provides no persistence, and allows specifying return values for each call.

### Method
Constructor

### Signature
`Store::new() -> Result<Store, Error>`

### Usage
Call during application startup before creating any entries to use the mock store as the default.

### Example
```rust
keyring_core::set_default_store(keyring_core::mock::Store::new().unwrap());
```

### Returns
A `Result` containing the new `Store` on success, or an `Error` on failure.
```
Tokens:
Raw