//! Methods and containers for searching and search results.
//!
//! The Subsonic API works on the concept of paging, something not uncommon in
//! RESTful APIs. A search will return a number of results up to a
//! specification. The client then has a virtual "page" number they will send,
//! to offset a search by a multiple of the return number.
//!
//! # Example
//!
//! Suppose a Subsonic server has 50 albums stored on it.
//!
//! ```no_run
//! extern crate sunk;
//! use sunk::{Album, Client, ListType};
//! use sunk::search::{self, SearchPage};
//!
//! # fn run() -> sunk::Result<()> {
//! # let site = "https://demo.subsonic.org";
//! # let username = "guest3";
//! # let password = "guest";
//! let client = Client::new(site, username, password)?;
//! let mut page = SearchPage::new();
//! let list = ListType::default();
//!
//! let results = Album::list(&client, list, page, 0)?;
//! assert_eq!(results.len(), 20);
//! #
//! # page.next();
//! # let more_results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(more_results.len(), 20);
//! #
//! # page.next();
//! # let last_results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(last_results.len(), 10);
//! #
//! # let exact = SearchPage::new().with_size(50);
//! # let exact_results = Album::list(&client, list, exact, 0)?;
//! # assert_eq!(exact_results.len(), 50);
//! #
//! # let all = search::ALL;
//! # let all_results = Album::list(&client, list, all, 0)?;
//! # assert_eq!(all_results.len(), 50);
//! #
//! # Ok(())
//! # }
//! # fn main() { }
//! ```
//!
//! How do we get the remaining 30 songs from the server? By paging.
//!
//! ```no_run
//! # extern crate sunk;
//! # use sunk::{Album, Client, ListType};
//! # use sunk::search::{self, SearchPage};
//! #
//! # fn run() -> sunk::Result<()> {
//! # let site = "https://demo.subsonic.org";
//! # let username = "guest3";
//! # let password = "guest";
//! # let client = Client::new(site, username, password)?;
//! # let mut page = SearchPage::new();
//! # let list = ListType::default();
//! #
//! # let results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(results.len(), 20);
//! #
//! page.next();
//! let more_results = Album::list(&client, list, page, 0)?;
//! assert_eq!(more_results.len(), 20);
//!
//! page.next();
//! let last_results = Album::list(&client, list, page, 0)?;
//! assert_eq!(last_results.len(), 10);
//! #
//! # let exact = SearchPage::new().with_size(50);
//! # let exact_results = Album::list(&client, list, exact, 0)?;
//! # assert_eq!(exact_results.len(), 50);
//! #
//! # let all = search::ALL;
//! # let all_results = Album::list(&client, list, all, 0)?;
//! # assert_eq!(all_results.len(), 50);
//! #
//! # Ok(())
//! # }
//! # fn main() { }
//! ```
//!
//! Notice that the last set of results only returns *up to* the count in the
//! `SearchPage`.
//!
//! Of course, if we knew beforehand how many results there would be, we could
//! request exactly fifty albums.
//!
//! ```no_run
//! # extern crate sunk;
//! # use sunk::{Album, Client, ListType};
//! # use sunk::search::{self, SearchPage};
//! #
//! # fn run() -> sunk::Result<()> {
//! # let site = "https://demo.subsonic.org";
//! # let username = "guest3";
//! # let password = "guest";
//! # let client = Client::new(site, username, password)?;
//! # let mut page = SearchPage::new();
//! # let list = ListType::default();
//! #
//! # let results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(results.len(), 20);
//! #
//! # page.next();
//! # let more_results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(more_results.len(), 20);
//! #
//! # page.next();
//! # let last_results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(last_results.len(), 10);
//! #
//! let exact = SearchPage::new().with_size(50);
//! let exact_results = Album::list(&client, list, exact, 0)?;
//! assert_eq!(exact_results.len(), 50);
//! #
//! # let all = search::ALL;
//! # let all_results = Album::list(&client, list, all, 0)?;
//! # assert_eq!(all_results.len(), 50);
//! #
//! # Ok(())
//! # }
//! # fn main() { }
//! ```
//!
//! However, if we didn't, there's a convinent constant in place to return up
//! to 500 results. This is set at 500 because most Subsonic functions only
//! accept up to returning 500 results. It's still possible to page through
//! results if you have to.
//!
//! ```no_run
//! # extern crate sunk;
//! # use sunk::{Album, Client, ListType};
//! # use sunk::search::{self, SearchPage};
//! #
//! # fn run() -> sunk::Result<()> {
//! # let site = "https://demo.subsonic.org";
//! # let username = "guest3";
//! # let password = "guest";
//! # let client = Client::new(site, username, password)?;
//! # let mut page = SearchPage::new();
//! # let list = ListType::default();
//! #
//! # let results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(results.len(), 20);
//! #
//! # page.next();
//! # let more_results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(more_results.len(), 20);
//! #
//! # page.next();
//! # let last_results = Album::list(&client, list, page, 0)?;
//! # assert_eq!(last_results.len(), 10);
//! #
//! # let exact = SearchPage::new().with_size(50);
//! # let exact_results = Album::list(&client, list, exact, 0)?;
//! # assert_eq!(exact_results.len(), 50);
//! #
//! let all = search::ALL;
//! let all_results = Album::list(&client, list, all, 0)?;
//! assert_eq!(all_results.len(), 50);
//! #
//! # Ok(())
//! # }
//! # fn main() { }
//! ```
use Song;
use fmt;
use ;
/// The maximum number of results most searches will accept.
pub const ALL: SearchPage = SearchPage ;
/// Effectively makes a search ignore the field.
pub const NONE: SearchPage = SearchPage ;
/// A holding struct for a search configuration.
///
/// See the [module-level documentation](./index.html) for more information.
/// A holder struct for a search result.