twilight_http/request/guild/member/
get_guild_members.rs

1use crate::{
2    client::Client,
3    error::Error,
4    request::{Request, TryIntoRequest},
5    response::{marker::ListBody, Response, ResponseFuture},
6    routing::Route,
7};
8use std::future::IntoFuture;
9use twilight_model::{
10    guild::Member,
11    id::{
12        marker::{GuildMarker, UserMarker},
13        Id,
14    },
15};
16use twilight_validate::request::{
17    get_guild_members_limit as validate_get_guild_members_limit, ValidationError,
18};
19
20struct GetGuildMembersFields {
21    after: Option<Id<UserMarker>>,
22    limit: Option<u16>,
23}
24
25/// Get the members of a guild, by id.
26///
27/// The upper limit to this request is 1000. If more than 1000 members are needed, the requests
28/// must be chained. Discord defaults the limit to 1.
29///
30/// # Examples
31///
32/// Get the first 500 members of guild `100` after user ID `3000`:
33///
34/// ```no_run
35/// use twilight_http::Client;
36/// use twilight_model::id::Id;
37///
38/// # #[tokio::main]
39/// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
40/// let client = Client::new("my token".to_owned());
41///
42/// let guild_id = Id::new(100);
43/// let user_id = Id::new(3000);
44/// let members = client
45///     .guild_members(guild_id)
46///     .after(user_id)
47///     .limit(500)
48///     .await?;
49/// # Ok(()) }
50/// ```
51#[must_use = "requests must be configured and executed"]
52pub struct GetGuildMembers<'a> {
53    fields: Result<GetGuildMembersFields, ValidationError>,
54    guild_id: Id<GuildMarker>,
55    http: &'a Client,
56}
57
58impl<'a> GetGuildMembers<'a> {
59    pub(crate) const fn new(http: &'a Client, guild_id: Id<GuildMarker>) -> Self {
60        Self {
61            fields: Ok(GetGuildMembersFields {
62                after: None,
63                limit: None,
64            }),
65            guild_id,
66            http,
67        }
68    }
69
70    /// Sets the user ID to get members after.
71    pub fn after(mut self, after: Id<UserMarker>) -> Self {
72        if let Ok(fields) = self.fields.as_mut() {
73            fields.after = Some(after);
74        }
75
76        self
77    }
78
79    /// Sets the number of members to retrieve per request.
80    ///
81    /// The limit must be greater than 0 and less than 1000.
82    ///
83    /// # Errors
84    ///
85    /// Returns an error of type [`GetGuildMembers`] if the limit is 0 or
86    /// greater than 1000.
87    ///
88    /// [`GetGuildMembers`]: twilight_validate::request::ValidationErrorType::GetGuildMembers
89    pub fn limit(mut self, limit: u16) -> Self {
90        self.fields = self.fields.and_then(|mut fields| {
91            validate_get_guild_members_limit(limit)?;
92            fields.limit = Some(limit);
93
94            Ok(fields)
95        });
96
97        self
98    }
99}
100
101impl IntoFuture for GetGuildMembers<'_> {
102    type Output = Result<Response<ListBody<Member>>, Error>;
103
104    type IntoFuture = ResponseFuture<ListBody<Member>>;
105
106    fn into_future(self) -> Self::IntoFuture {
107        let http = self.http;
108
109        match self.try_into_request() {
110            Ok(request) => http.request(request),
111            Err(source) => ResponseFuture::error(source),
112        }
113    }
114}
115
116impl TryIntoRequest for GetGuildMembers<'_> {
117    fn try_into_request(self) -> Result<Request, Error> {
118        let fields = self.fields.map_err(Error::validation)?;
119
120        Ok(Request::from_route(&Route::GetGuildMembers {
121            after: fields.after.map(Id::get),
122            guild_id: self.guild_id.get(),
123            limit: fields.limit,
124        }))
125    }
126}
twilight_http/request/guild/member/get_guild_members.rs

twilight_http/request/guild/member/
get_guild_members.rs
