Add Shard Id helpers

Add helpers to retrieve the shard Id for guilds, and count how many
guilds are handled by a Shard.

Helpers to retrieve the shard Id of a guild have been added as:

- `Guild::shard_id`
- `GuildId::shard_id`

These are in two forms: one working with the cache feature, and one
without. The function that works with the cache will automatically
retrieve the total number of shards from the Cache, while the uncached
version requires passing in the total number of shards used.

With the cache enabled, this might look like:

```rust
guild.shard_id();
// which calls:
guild_id.shard_id();
```

Without the cache enabled, this looks like:

```rust
let shard_count = 7;

guild.shard_id(shard_count);
// which calls:
guild_id.shard_id(shard_count);
```

These two variants on `Guild` and `GuildId` are helper sugar methods
over the new function `utils::shard_id`, which accepts a `guild_id` and
a `shard_count`:

```rust
use serenity::utils;

assert_eq!(utils::shard_id(81384788765712384, 17), 7);
```

You would use `utils::shard_id` when you have the total number of shards
due to `{Guild,GuildId}::shard_id` unlocking the cache to retrieve the
total number of shards. This avoids some amount of work

1 files changed, 4 insertions, 0 deletions

diff --git a/src/ext/cache/mod.rs b/src/ext/cache/mod.rs
index 84c21a7..d3479da 100644
--- a/src/ext/cache/mod.rs
+++ b/src/ext/cache/mod.rs
@@ -139,6 +139,8 @@ pub struct Cache {
     /// A map of direct message channels that the current user has open with
     /// other users.
     pub private_channels: HashMap<ChannelId, Arc<RwLock<PrivateChannel>>>,
+    /// The total number of shards being used by the bot.
+    pub shard_count: u64,
     /// A list of guilds which are "unavailable". Refer to the documentation for
     /// [`Event::GuildUnavailable`] for more information on when this can occur.
     ///
@@ -877,6 +879,7 @@ impl Cache {
         }
 
         self.presences.extend(ready.presences);
+        self.shard_count = ready.shard.map_or(1, |s| s[1]);
         self.user = ready.user;
     }
 
@@ -938,6 +941,7 @@ impl Default for Cache {
             notes: HashMap::default(),
             presences: HashMap::default(),
             private_channels: HashMap::default(),
+            shard_count: 1,
             unavailable_guilds: HashSet::default(),
             user: CurrentUser {
                 avatar: None,