Struct blather::Telegram

pub struct Telegram { /* fields omitted */ }

Representation of a Telegram; a buffer which contains a topic and a set of key/value parameters.

Implementations

impl Telegram

pub fn new() -> Self

Create a new telegram object, with an unset topic.

Note that a telegram object without a topic is invalid. set_topic() must be called to set a topic to make the object valid. Use new_topic() to create a new Telegram object with a topic.

pub fn new_topic(topic: &str) -> Result<Self, Error>

Create a new telegram object with a topic.

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new_topic("Hello").unwrap();
  assert_eq!(tg.get_topic(), Some("Hello"));
}

pub fn clear(&mut self)

Clear topic and internal parameters buffer.

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new();
  tg.add_param("cat", "meow");
  assert_eq!(tg.num_params(), 1);
  tg.clear();
  assert_eq!(tg.num_params(), 0);
}

pub fn num_params(&self) -> usize

Return the number of key/value parameters in the Telegram object.

Examples

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new();
  assert_eq!(tg.num_params(), 0);
  tg.add_param("cat", "meow");
  assert_eq!(tg.num_params(), 1);
}

Notes

This is a wrapper around Params::len().

pub fn get_params(&self) -> &Params

Get a reference to the internal parameters object.

pub fn get_params_mut(&mut self) -> &mut Params

Get a mutable reference to the inner Params object.

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new();
  tg.add_param("cat", "meow");
  assert_eq!(tg.num_params(), 1);
  tg.get_params_mut().clear();
  assert_eq!(tg.num_params(), 0);
}

pub fn get_params_inner(&self) -> &HashMap<String, String>

Get a reference the the parameter’s internal HashMap.

Note: The inner representation of the Params object may change in the future.

pub fn set_topic(&mut self, topic: &str) -> Result<(), Error>

Set topic for telegram.

Overwrites current topic is one has already been set.

Examples

use blather::{Telegram, Error};
fn main() {
  let mut tg = Telegram::new();
  assert_eq!(tg.set_topic("Hello"), Ok(()));

  let e = Error::BadFormat("Invalid topic character".to_string());
  assert_eq!(tg.set_topic("Hell o"), Err(e));
}

pub fn get_topic(&self) -> Option<&str>

Get a reference to the topic string, or None if topic is not been set.

Examples

use blather::{Telegram, Error};
fn main() {
  let tg = Telegram::new_topic("shoe0nhead").unwrap();
  assert_eq!(tg.get_topic(), Some("shoe0nhead"));

  let tg = Telegram::new();
  assert_eq!(tg.get_topic(), None);
}

pub fn add_param<T: ToString, U: ToString>(
    &mut self,
    key: T,
    value: U
) -> Result<(), Error>

Add a parameter to the telegram.

The key and value parameters are generic over the trait ToString, allowing a polymorphic behavior.

Examples

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new();
  tg.add_param("integer", 42).unwrap();
  tg.add_param("string", "hello").unwrap();
}

Notes

• This is a thin wrapper around Params::add_param().

pub fn add_str(&mut self, key: &str, value: &str) -> Result<(), Error>

Add a string parameter to the telegram.

Notes

• This function exists primarily for parity with a C++ library; it is just a wrapper around add_param(), which is recommended over add_str().

pub fn add_strit<I, S>(&mut self, key: &str, c: I) -> Result<(), Error> where
    I: IntoIterator<Item = S>,
    S: AsRef<str>, 

Add parameter where the value is generated from an iterator over a string container, where entries will be comma-separated.

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new();
  tg.add_strit("Cat", &["meow", "paws", "tail"]).unwrap();
  assert_eq!(tg.get_str("Cat"), Some("meow,paws,tail"));
}

Notes

• This is a thin wrapper for Params::add_strit().

pub fn add_bool<K: ToString>(
    &mut self,
    key: K,
    value: bool
) -> Result<(), Error>

Add a boolean value to Telegram object.

Notes

• This is a thin wrapper around Params::add_bool().

pub fn have_param(&self, key: &str) -> bool

Check whether a parameter exists in Telegram object.

Returns true is the key exists, and false otherwise.

pub fn get_param<T: FromStr>(&self, key: &str) -> Result<T, Error>

Get a parameter. Fail if the parameter does not exist.

Notes

• This is a thin wrapper around Params::get_param().

pub fn get_param_def<T: FromStr>(&self, key: &str, def: T) -> Result<T, Error>

Get a parameter. Return a default value if the parameter does not exist.

Notes

• This is a thin wrapper around Params::get_param_def().

pub fn get_str(&self, key: &str) -> Option<&str>

Get a string representation of a parameter. Return None is parameter does not exist.

Notes

• This is a thin wrapper around Params::get_str()

pub fn get_str_def<'a>(&'a self, key: &str, def: &'a str) -> &'a str

Get a string representation of a parameter. Returns a default value is the parameter does not exist.

Notes

• This is a thin wrapper around Params::get_str_def()

pub fn get_int<T: FromStr>(&self, key: &str) -> Result<T, Error>

Get an integer representation of a parameter.

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new();
  tg.add_param("Num", 7);
  assert_eq!(tg.get_int::<usize>("Num").unwrap(), 7);
}

Notes

• This function uses the FromStr trait on the return-type so it technically isn’t limited to integers.
• The method exists to mimic a C++ library. It is recommeded that applications use Telegram::get_param() instead.

pub fn get_int_def<T: FromStr>(&self, key: &str, def: T) -> Result<T, Error>

Try to get the parameter value of a key and interpret it as an integer. If the key does not exist then return a default value supplied by the caller.

use blather::Telegram;
fn main() {
  let mut tg = Telegram::new();
  tg.add_param("num", 11);
  assert_eq!(tg.get_int_def::<u32>("num", 5).unwrap(), 11);
  assert_eq!(tg.get_int_def::<u32>("nonexistent", 17).unwrap(), 17);
}

pub fn get_bool(&self, key: &str) -> Result<bool, Error>

Return a boolean value. Return error if parameter does not exist.

If a value exist but can not be parsed as a boolean value the error Error::BadFormat will be returned.

Notes

• This is a thing wrapper around Params::get_bool().

pub fn get_bool_def(&self, key: &str, def: bool) -> Result<bool, Error>

Return a boolean value. Return a default value if parameter does not exist.

Notes

• This is a thing wrapper around Params::get_bool().

pub fn get_strvec(&self, key: &str) -> Result<Vec<String>, Error>

Parse the value of a key as a comma-separated list of strings and return it as a Vec<String>. Only non-empty entries are returned.

Notes

• This is a thin wrapper around Params::get_strvec().

pub fn get_hashset(&self, key: &str) -> Result<HashSet<String>, Error>

Parse the value of a key as a comma-separated list of strings and return it as a HashSet<String>. Only non-empty entries are returned.

Notes

• This is a thin wrapper around Params::get_hashset().

pub fn calc_buf_size(&self) -> usize

Calculate the size of a serialized version of this Telegram object. If no topic has been set it is simply ignored. In the future this might change to something more dramatic, like a panic. Telegrams should always contain a topic when transmitted.

Each line is terminated by a newline character. The last line consists of a single newline character.

pub fn serialize(&self) -> Result<Vec<u8>, Error>

pub fn encoder_write(&self, buf: &mut BytesMut) -> Result<(), Error>

Write the Telegram to a BytesMut buffer.

pub fn into_params(self) -> Params

Consume the Telegram buffer and return the internal parameters object.

Trait Implementations

impl Clone for Telegram

fn clone(&self) -> Telegram

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Telegram

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Telegram

fn default() -> Telegram

Returns the “default value” for a type.

impl Display for Telegram

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Encoder<&'_ Telegram> for Codec

type Error = Error

The type of encoding errors.

fn encode(&mut self, tg: &Telegram, buf: &mut BytesMut) -> Result<(), Error>

Encodes a frame into the buffer provided.

impl From<HashMap<String, String, RandomState>> for Telegram

fn from(hm: HashMap<String, String>) -> Self

Performs the conversion.

impl From<Params> for Telegram

fn from(params: Params) -> Self

Performs the conversion.

impl From<String> for Telegram

fn from(topic: String) -> Self

Performs the conversion.