Paginate rest::get_guilds and add helper methods

Paginate the rest::get_guilds endpoint, which can be used to retrieve
the guilds after-or-before a certain guild's Id, with a limit of results
to return (100 is the max).

Example usage:

```rs
use serenity::client::rest::GuildPagination;

let target = GuildPagination::After(GuildId(81384788765712384));

let guilds = context.get_guilds(target, 50);
```

Additionally, add a method of `CurrentUser::guilds()`, to retrieve the
current user's guilds. A limit of 100 is set, as (most) users can not be
in more than 100 guilds.

1 files changed, 43 insertions, 5 deletions

diff --git a/src/client/rest/mod.rs b/src/client/rest/mod.rs
index da16671..a325f15 100644
--- a/src/client/rest/mod.rs
+++ b/src/client/rest/mod.rs
@@ -1125,11 +1125,38 @@ pub fn get_guild_webhooks(guild_id: u64) -> Result<Vec<Webhook>> {
     decode_array(try!(serde_json::from_reader(response)), Webhook::decode)
 }
 
-/// Gets all guilds we're connected to.
-pub fn get_guilds() -> Result<Vec<GuildInfo>> {
-    let response = request!(Route::UsersMeGuilds,
-                            get,
-                            "/users/@me/guilds");
+/// Gets a paginated list of the current user's guilds.
+///
+/// The `limit` has a maximum value of 100.
+///
+/// [Discord's documentation][docs]
+///
+/// # Examples
+///
+/// Get the first 10 guilds after a certain guild's Id:
+///
+/// ```rust,no_run
+/// use serenity::rest::{GuildPagination, get_guilds};
+///
+/// let guild_id = 81384788765712384;
+///
+/// let guilds = get_guilds(GuildPagination::after(guild_id), 10).unwrap();
+/// ```
+///
+/// [docs]: https://discordapp.com/developers/docs/resources/user#get-current-user-guilds
+pub fn get_guilds(target: GuildPagination, limit: u64) -> Result<Vec<GuildInfo>> {
+    let mut uri = format!("/users/@me/guilds?limit={}", limit);
+
+    match target {
+        GuildPagination::After(id) => {
+            try!(write!(uri, "&after={}", id));
+        },
+        GuildPagination::Before(id) => {
+            try!(write!(uri, "&before={}", id));
+        },
+    }
+
+    let response = request!(Route::UsersMeGuilds, get, "{}", uri);
 
     decode_array(try!(serde_json::from_reader(response)), GuildInfo::decode)
 }
@@ -1534,3 +1561,14 @@ fn verify(expected_status_code: u16,
 
     Err(Error::Client(ClientError::UnexpectedStatusCode(response.status)))
 }
+
+/// Representation of the method of a query to send for the [`get_guilds`]
+/// function.
+///
+/// [`get_guilds`]: fn.get_guilds.html
+pub enum GuildPagination {
+    /// The Id to get the guilds after.
+    After(GuildId),
+    /// The Id to get the guilds before.
+    Before(GuildId),
+}