[package]
name = "bndpresbufq"
version = "0.1.1"
edition = "2021"
license = "0BSD"
# https://crates.io/category_slugs
categories = [ "data-structures" ]
keywords = [ "buffer", "queue", "bounded", "bounds-preserving" ]
repository = "https://repos.qrnch.tech/pub/bndpresbufq"
description = "Bounds-preserving, optionally limited, buffer queue"
rust-version = "1.56"
exclude = [
  ".fossil-settings",
  ".efiles",
  ".fslckout",
  "www",
  "bacon.toml",
  "rustfmt.toml"
]

# https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section
[badges]
maintenance = { status = "passively-maintained" }

[dependencies]
limq = { version = "0.1.1" }

[package.metadata.docs.rs]
rustdoc-args = ["--generate-link-to-definition"]

[lints.clippy]
all = { level = "deny", priority = -1 }
pedantic = { level = "warn", priority = -1 }
nursery = { level = "warn", priority = -1 }
cargo = { level = "warn", priority = -1 }

# This is a configuration file for the bacon tool
#
# Bacon repository: https://github.com/Canop/bacon
# Complete help on configuration: https://dystroy.org/bacon/config/
# You can also check bacon's own bacon.toml file
#  as an example: https://github.com/Canop/bacon/blob/main/bacon.toml

#default_job = "check"
default_job = "clippy-all"

[jobs.check]
command = ["cargo", "check", "--color", "always"]
need_stdout = false

[jobs.check-all]
command = ["cargo", "check", "--all-targets", "--color", "always"]
need_stdout = false

# Run clippy on the default target
[jobs.clippy]
command = [
    "cargo", "clippy",
    "--color", "always",
]
need_stdout = false

# Run clippy on all targets
# To disable some lints, you may change the job this way:
#    [jobs.clippy-all]
#    command = [
#        "cargo", "clippy",
#        "--all-targets",
#        "--color", "always",
#    	 "--",
#    	 "-A", "clippy::bool_to_int_with_if",
#    	 "-A", "clippy::collapsible_if",
#    	 "-A", "clippy::derive_partial_eq_without_eq",
#    ]
# need_stdout = false
[jobs.clippy-all]
command = [
    "cargo", "clippy",
    "--all-targets",
    "--color", "always",
]
need_stdout = false

# This job lets you run
# - all tests: bacon test
# - a specific test: bacon test -- config::test_default_files
# - the tests of a package: bacon test -- -- -p config
[jobs.test]
command = [
    "cargo", "test", "--color", "always",
    "--", "--color", "always", # see https://github.com/Canop/bacon/issues/124
]
need_stdout = true

[jobs.doc]
command = ["cargo", "doc", "--color", "always", "--no-deps"]
need_stdout = false

# If the doc compiles, then it opens in your browser and bacon switches
# to the previous job
[jobs.doc-open]
command = ["cargo", "doc", "--color", "always", "--no-deps", "--open"]
need_stdout = false
on_success = "back" # so that we don't open the browser at each change

# You can run your application and have the result displayed in bacon,
# *if* it makes sense for this crate.
# Don't forget the `--color always` part or the errors won't be
# properly parsed.
# If your program never stops (eg a server), you may set `background`
# to false to have the cargo run output immediately displayed instead
# of waiting for program's end.
[jobs.run]
command = [
    "cargo", "run",
    "--color", "always",
    # put launch parameters for your program behind a `--` separator
]
need_stdout = true
allow_warnings = true
background = true

# This parameterized job runs the example of your choice, as soon
# as the code compiles.
# Call it as
#    bacon ex -- my-example
[jobs.ex]
command = ["cargo", "run", "--color", "always", "--example"]
need_stdout = true
allow_warnings = true

# You may define here keybindings that would be specific to
# a project, for example a shortcut to launch a specific job.
# Shortcuts to internal functions (scrolling, toggling, etc.)
# should go in your personal global prefs.toml file instead.
[keybindings]
# alt-m = "job:my-job"
c = "job:clippy-all" # comment this to have 'c' run clippy on only the default target

//! `BndPresLimBufQ` is a bounds-preserving, optionally limited, buffer queue.
//!
//! # Terminology
//! _length_ is used to refer the number of elements in the queue. _size_ is
//! used to refer to the total amount of bytes in the queue.
//!
//! # Example
//! ```

  ///
  /// Passing `None` to `max_len` will disable the explicit maximum number of
  /// queue elements limitation.  Passing `None` to `max_size` will disable
  /// the explicit maximum queue buffer size.
  ///
  /// # Panics
  /// Passing a zero to either `max_len` or `max_size` will casuse a panic.
  #[must_use]
  pub fn new(max_len: Option<usize>, max_size: Option<usize>) -> Self {
    assert!(
      !matches!(max_size, Some(0)),
      "A zero-size limit is forbidden"
    );
    Self {
      q: LimQ::new(max_len),
      max_size,
      size: 0
    }
  }

  /// Change the length limit of the queue.
  ///
  /// # Panics
  /// A zero-limit will cause a panic.
  pub fn set_max_len(&mut self, max_len: Option<usize>) {
    self.q.set_max_len(max_len);
  }

  /// Change the size limit of the queue.
  ///
  /// # Panics
  /// A zero-limit will cause a panic.
  pub fn set_max_size(&mut self, max_size: Option<usize>) {
    assert!(
      !matches!(max_size, Some(0)),
      "A zero-size limit is forbidden"
    );
    self.max_size = max_size;
  }

  /// Return maximum queue length.
  #[must_use]
  pub const fn max_len(&self) -> Option<usize> {
    self.q.max_len()
  }

  /// Return maximum queue size.
  #[must_use]
  pub const fn max_size(&self) -> Option<usize> {
    self.max_size
  }

  /// Return current number of queue elements.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.q.len()
  }

  /// Return current total size of all buffers in queue.
  #[inline]
  #[must_use]
  pub const fn size(&self) -> usize {
    self.size
  }

  /// Return boolean indicating whether the queue is empty or not.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.q.is_empty()
  }

  /// Drop elements that overflow the queue limit (if a limit has been set).
  #[inline]
  pub fn purge_overflow(&mut self) {
    self.q.purge_overflow();
    if let Some(max_size) = self.max_size {
      while self.size > max_size {
        let _ = self.q.pop();
      }
    }
  }

  /// Try to push a buffer onto the queue.
  ///

  /// # Errors
  /// If the input buffer would overflow the queue (either by length or size)
  /// the buffer is returned.
  pub fn try_push(&mut self, n: Vec<u8>) -> Result<(), Vec<u8>> {
    let nlen = n.len();
    if let Some(max_size) = self.max_size {
      if self.size + nlen <= max_size {
        self.q.try_push(n)?;
        self.size += nlen;
        Ok(())

      self.size += nlen;
      Ok(())
    }
  }

  /// Forcibly add a buffer to the queue.
  ///
  /// # Errors
  /// If the input buffer `n` is larger than the configured maximum total queue
  /// size, the input buffer is returned.

  pub fn force_push(&mut self, n: Vec<u8>) -> Result<(), Vec<u8>> {
    let nlen = n.len();

    // If a maximum size has been set for this queue ..
    if let Some(max_size) = self.max_size {
      // .. then bail if the input buffer size is larger than the maximum
      // allowed total queue size.

#[cfg(test)]
mod tests {
  use super::BndPresLimBufQ;

  #[test]
  // this message is defined in the limq crate
  #[should_panic(expected = "A zero-length limit is forbidden")]
  fn zero_len() {
    let _q = BndPresLimBufQ::new(Some(0), None);
  }

  #[test]
  #[should_panic(expected = "A zero-size limit is forbidden")]
  fn zero_size() {
    let _q = BndPresLimBufQ::new(None, Some(0));
  }

  #[test]
  // this message is defined in the limq crate
  #[should_panic(expected = "A zero-length limit is forbidden")]
  fn set_zero_len() {
    let mut q = BndPresLimBufQ::new(Some(11), None);
    q.set_max_len(Some(0));
  }

  #[test]
  #[should_panic(expected = "A zero-size limit is forbidden")]
  fn set_zero_size() {
    let mut q = BndPresLimBufQ::new(None, Some(11));
    q.set_max_size(Some(0));
  }

  #[test]
  fn try_exceed_len() {
    let mut q = BndPresLimBufQ::new(Some(1), None);
    q.try_push([1].into()).unwrap();
    assert_eq!(q.len(), 1);

# Change Log

## [Unreleased]

[Details](/vdiff?from=bndpresbufq-0.1.1&to=trunk)

### Added

### Changed

### Removed

---

## [0.1.1] - 2024-09-13

[Details](/vdiff?from=bndpresbufq-0.1.0&to=bndpresbufq-0.1.1)

### Added

- Add an assertion message when a zero maximum size has been specified.

### Changed

- Use `limq` `0.1.1` to get a hard-coded panic message for zero-length queues.

---

## [0.1.0] - 2024-04-10

First release.