ruma_events/poll/
start.rs

Help
1//! Types for the `m.poll.start` event.
2
3use std::ops::Deref;
4
5use js_int::{uint, UInt};
6use ruma_common::{serde::StringEnum, MilliSecondsSinceUnixEpoch};
7use ruma_macros::EventContent;
8use serde::{Deserialize, Serialize};
9
10use crate::PrivOwnedStr;
11
12mod poll_answers_serde;
13
14use poll_answers_serde::PollAnswersDeHelper;
15
16use super::{
17    compile_poll_results,
18    end::{PollEndEventContent, PollResultsContentBlock},
19    generate_poll_end_fallback_text, PollResponseData,
20};
21use crate::{message::TextContentBlock, room::message::Relation};
22
23/// The payload for a poll start event.
24///
25/// This is the event content that should be sent for room versions that support extensible events.
26/// As of Matrix 1.7, none of the stable room versions (1 through 10) support extensible events.
27///
28/// To send a poll start event for a room version that does not support extensible events, use
29/// [`UnstablePollStartEventContent`].
30///
31/// [`UnstablePollStartEventContent`]: super::unstable_start::UnstablePollStartEventContent
32#[derive(Clone, Debug, Serialize, Deserialize, EventContent)]
33#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
34#[ruma_event(type = "m.poll.start", kind = MessageLike, without_relation)]
35pub struct PollStartEventContent {
36    /// The poll content of the message.
37    #[serde(rename = "m.poll")]
38    pub poll: PollContentBlock,
39
40    /// Text representation of the message, for clients that don't support polls.
41    #[serde(rename = "m.text")]
42    pub text: TextContentBlock,
43
44    /// Information about related messages.
45    #[serde(
46        flatten,
47        skip_serializing_if = "Option::is_none",
48        deserialize_with = "crate::room::message::relation_serde::deserialize_relation"
49    )]
50    pub relates_to: Option<Relation<PollStartEventContentWithoutRelation>>,
51
52    /// Whether this message is automated.
53    #[cfg(feature = "unstable-msc3955")]
54    #[serde(
55        default,
56        skip_serializing_if = "ruma_common::serde::is_default",
57        rename = "org.matrix.msc1767.automated"
58    )]
59    pub automated: bool,
60}
61
62impl PollStartEventContent {
63    /// Creates a new `PollStartEventContent` with the given fallback representation and poll
64    /// content.
65    pub fn new(text: TextContentBlock, poll: PollContentBlock) -> Self {
66        Self {
67            poll,
68            text,
69            relates_to: None,
70            #[cfg(feature = "unstable-msc3955")]
71            automated: false,
72        }
73    }
74
75    /// Creates a new `PollStartEventContent` with the given plain text fallback
76    /// representation and poll content.
77    pub fn with_plain_text(plain_text: impl Into<String>, poll: PollContentBlock) -> Self {
78        Self::new(TextContentBlock::plain(plain_text), poll)
79    }
80}
81
82impl OriginalSyncPollStartEvent {
83    /// Compile the results for this poll with the given response into a `PollEndEventContent`.
84    ///
85    /// It generates a default text representation of the results in English.
86    ///
87    /// This uses [`compile_poll_results()`] internally.
88    pub fn compile_results<'a>(
89        &'a self,
90        responses: impl IntoIterator<Item = PollResponseData<'a>>,
91    ) -> PollEndEventContent {
92        let full_results = compile_poll_results(
93            &self.content.poll,
94            responses,
95            Some(MilliSecondsSinceUnixEpoch::now()),
96        );
97        let results =
98            full_results.into_iter().map(|(id, users)| (id, users.len())).collect::<Vec<_>>();
99
100        // Construct the results and get the top answer(s).
101        let poll_results = PollResultsContentBlock::from_iter(
102            results
103                .iter()
104                .map(|(id, count)| ((*id).to_owned(), (*count).try_into().unwrap_or(UInt::MAX))),
105        );
106
107        // Get the text representation of the best answers.
108        let answers = self
109            .content
110            .poll
111            .answers
112            .iter()
113            .map(|a| {
114                let text = a.text.find_plain().unwrap_or(&a.id);
115                (a.id.as_str(), text)
116            })
117            .collect::<Vec<_>>();
118        let plain_text = generate_poll_end_fallback_text(&answers, results.into_iter());
119
120        let mut end = PollEndEventContent::with_plain_text(plain_text, self.event_id.clone());
121        end.poll_results = Some(poll_results);
122
123        end
124    }
125}
126
127/// A block for poll content.
128#[derive(Clone, Debug, Serialize, Deserialize)]
129#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
130pub struct PollContentBlock {
131    /// The question of the poll.
132    pub question: PollQuestion,
133
134    /// The kind of the poll.
135    #[serde(default, skip_serializing_if = "ruma_common::serde::is_default")]
136    pub kind: PollKind,
137
138    /// The maximum number of responses a user is able to select.
139    ///
140    /// Must be greater or equal to `1`.
141    ///
142    /// Defaults to `1`.
143    #[serde(
144        default = "PollContentBlock::default_max_selections",
145        skip_serializing_if = "PollContentBlock::max_selections_is_default"
146    )]
147    pub max_selections: UInt,
148
149    /// The possible answers to the poll.
150    pub answers: PollAnswers,
151}
152
153impl PollContentBlock {
154    /// Creates a new `PollStartContent` with the given question and answers.
155    pub fn new(question: TextContentBlock, answers: PollAnswers) -> Self {
156        Self {
157            question: question.into(),
158            kind: Default::default(),
159            max_selections: Self::default_max_selections(),
160            answers,
161        }
162    }
163
164    pub(super) fn default_max_selections() -> UInt {
165        uint!(1)
166    }
167
168    fn max_selections_is_default(max_selections: &UInt) -> bool {
169        max_selections == &Self::default_max_selections()
170    }
171}
172
173/// The question of a poll.
174#[derive(Clone, Debug, Serialize, Deserialize)]
175#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
176pub struct PollQuestion {
177    /// The text representation of the question.
178    #[serde(rename = "m.text")]
179    pub text: TextContentBlock,
180}
181
182impl From<TextContentBlock> for PollQuestion {
183    fn from(text: TextContentBlock) -> Self {
184        Self { text }
185    }
186}
187
188/// The kind of poll.
189#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
190#[derive(Clone, Default, PartialEq, Eq, StringEnum)]
191#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
192pub enum PollKind {
193    /// The results are revealed once the poll is closed.
194    #[default]
195    #[ruma_enum(rename = "m.undisclosed")]
196    Undisclosed,
197
198    /// The votes are visible up until and including when the poll is closed.
199    #[ruma_enum(rename = "m.disclosed")]
200    Disclosed,
201
202    #[doc(hidden)]
203    _Custom(PrivOwnedStr),
204}
205
206/// The answers to a poll.
207///
208/// Must include between 1 and 20 `PollAnswer`s.
209///
210/// To build this, use the `TryFrom` implementations.
211#[derive(Clone, Debug, Deserialize, Serialize)]
212#[serde(try_from = "PollAnswersDeHelper")]
213pub struct PollAnswers(Vec<PollAnswer>);
214
215impl PollAnswers {
216    /// The smallest number of values contained in a `PollAnswers`.
217    pub const MIN_LENGTH: usize = 1;
218
219    /// The largest number of values contained in a `PollAnswers`.
220    pub const MAX_LENGTH: usize = 20;
221}
222
223/// An error encountered when trying to convert to a `PollAnswers`.
224#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq, thiserror::Error)]
225#[non_exhaustive]
226pub enum PollAnswersError {
227    /// There are more than [`PollAnswers::MAX_LENGTH`] values.
228    #[error("too many values")]
229    TooManyValues,
230    /// There are less that [`PollAnswers::MIN_LENGTH`] values.
231    #[error("not enough values")]
232    NotEnoughValues,
233}
234
235impl TryFrom<Vec<PollAnswer>> for PollAnswers {
236    type Error = PollAnswersError;
237
238    fn try_from(value: Vec<PollAnswer>) -> Result<Self, Self::Error> {
239        if value.len() < Self::MIN_LENGTH {
240            Err(PollAnswersError::NotEnoughValues)
241        } else if value.len() > Self::MAX_LENGTH {
242            Err(PollAnswersError::TooManyValues)
243        } else {
244            Ok(Self(value))
245        }
246    }
247}
248
249impl TryFrom<&[PollAnswer]> for PollAnswers {
250    type Error = PollAnswersError;
251
252    fn try_from(value: &[PollAnswer]) -> Result<Self, Self::Error> {
253        Self::try_from(value.to_owned())
254    }
255}
256
257impl Deref for PollAnswers {
258    type Target = [PollAnswer];
259
260    fn deref(&self) -> &Self::Target {
261        &self.0
262    }
263}
264
265/// Poll answer.
266#[derive(Clone, Debug, Serialize, Deserialize)]
267#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
268pub struct PollAnswer {
269    /// The ID of the answer.
270    ///
271    /// This must be unique among the answers of a poll.
272    #[serde(rename = "m.id")]
273    pub id: String,
274
275    /// The text representation of the answer.
276    #[serde(rename = "m.text")]
277    pub text: TextContentBlock,
278}
279
280impl PollAnswer {
281    /// Creates a new `PollAnswer` with the given id and text representation.
282    pub fn new(id: String, text: TextContentBlock) -> Self {
283        Self { id, text }
284    }
285}
ruma_events/poll/start.rs

ruma_events/poll/
start.rs
