Struct serenity::utils::builder::Search [−] [src]

pub struct Search(pub BTreeMap<&'static str, String>);

A builder used to query a Channel or Guild for its Messages, specifying certain parameters to narrow down the returned messages.

Many methods are provided to narrow down the results, such as sort_by - which is used with the SortingMode enum to sort the results - or limit, which can be used in conjunction with offset to paginate results.

Examples

Provided are multiple in-depth examples for searching through different means. Also see example 08 for a fully runnable bot.

Searching a Channel

Search for messages via Context::search_channel with the content "rust", which have no embed, no attachment, searching by relevance in ascending order, and limiting to 5 results:

// assuming you are in a context

let res = context.search_channel(message.channel_id, |s| s
    .content("rust")
    .has_embed(false)
    .has_attachment(false)
    .limit(5)
    .sort_by(SortingMode::Relevance)
    .sort_order(SortingOrder::Ascending));

Searching a Guild's Channels

Search for messages with a query provided by a user, which have an embed, have no attachment, searching by timestamp in descending order, limiting to 2 results, and only searching channels that have a name prefixed with "search-":

use serenity::client::{Client, Context};
use serenity::model::Message;
use serenity::utils::builder::{SortingMode, SortingOrder};
use std::env;

let mut client = Client::login_bot(&env::var("DISCORD_BOT_TOKEN").unwrap());

client.with_framework(|f| f
    .configure(|c| c.prefix("~").on_mention(true))
    .on("search", search));

command!(search(context, message, args) {
    let query = args.join(" ");

    if query.is_empty() {
        let _ = context.say("You must provide a query");

        return Ok(());
    }

    let guild = message.guild().unwrap();

    let channel_ids = guild
        .channels
        .values()
        .filter(|c| c.name.starts_with("search-"))
        .map(|c| c.id)
        .collect();

    let search = context.search_guild(guild.id, channel_ids, |s| s
        .content(&query)
        .context_size(0)
        .has_attachment(true)
        .has_embed(true)
        .max_id(message.id.0 - 1)
        .sort_by(SortingMode::Timestamp)
        .sort_order(SortingOrder::Descending));

    let mut messages = match search {
        Ok(messages) => messages,
        Err(why) => {
            println!("Error performing search '{}': {:?}", query, why);

            let _ = context.say("Error occurred while searching");

            return Ok(());
        },
    };

    let _ = context.send_message(message.channel_id, |m| m
        .content(&format!("Found {} total results", messages.total))
        .embed(|mut e| {
            for (i, messages) in messages.results.iter_mut().enumerate() {
                let mut message = match messages.get_mut(i) {
                    Some(message) => message,
                    None => break,
                };

                message.content.truncate(1000);

                e = e.field(|f| f
                    .name(&format!("Result {}", i))
                    .value(&message.content));
             }

             e
        }));
});

Methods

impl Search
[src]

Sets the list of attachment extensions to search by.

When providing a vector of extensions, do not include the period (.) character as part of the search.

This is sent to Discord as a comma-separated value list of extension names.

Sets the filename of the attachments to search for.

Sets the Id of the author of Messages to search for. This excludes all messages by other Users.

Sets the content of the Message to search for. This is a fuzzy search, and can partially match the given query content.

Sets the amount of "context" Messages to provide, at maximum. This is the number of messages to provide around each side (ascending+descending) of the "hit" (aka found) message.

The default value is 2. The minimum value is 0. The maximum value is 2.

Sets the embed providers to search by.

This is a list of the providers' names.

This is sent to Discord as a comma-separated value list of provider names.

Sets the type of Embeds to search by.

An example of an embed type is "rich".

Sets whether to search for methods that do - or do not - have an attachment.

Do not specify to search for both.

Sets whether to search for methods that do - or do not - have an embed.

Do not specify to search for both.

Sets the number of messages to retrieve at maximum. This can be used in conjunction with offset.

The minimum value is 1. The maximum value is 25.

Set the maximum Message Id to search up to. All messages with an Id greater than the given value will be ignored.

Set the minimum Messages Id to search down to. All messages with an Id less than the given value will be ignored.

Set the offset of Messages to return. This can be used in conjunction with limit.

The minimum value is 0. The maximum value is 5000.

The sorting mode to use.

Refer to SortingMode for more information.

The order to sort results by.

Refer to the documentation for SortingOrder for more information.

Trait Implementations

impl Default for Search
[src]

Creates a new builder for searching for [Message]s. Refer to each method to learn what minimum and maximum values are available for each field, as well as restrictions and other useful information.

The library does not provide defaults differently than what Discord itself defaults to.

This list of defaults is: