Skip to content

Commit

Permalink
tags
Browse files Browse the repository at this point in the history
  • Loading branch information
@milyin
milyin committed Feb 16, 2024
1 parent ecdc8b0 commit de939d7
Show file tree
Hide file tree
Showing 5 changed files with 57 additions and 53 deletions.
25 changes: 13 additions & 12 deletions commons/zenoh-buffers/src/zbuf.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,42 +28,42 @@ fn get_mut_unchecked<T>(arc: &mut Arc<T>) -> &mut T {
}

#[derive(Debug, Clone, Default, Eq)]
// tags{zbuf, buffer}
// tags{zbuf.clone, buffer.rcinc}
// tags{rust.zbuf.zbuf, api.buffer}
// tags{rust.zbuf.zbuf.clone, api.buffer.rcinc}
pub struct ZBuf {
slices: SingleOrVec<ZSlice>,
}

impl ZBuf {
#[must_use]
// tags{zbuf.create, buffer.create}
// tags{rust.zbuf.zbuf.empty, api.buffer.create.empty}
pub fn empty() -> Self {
Self::default()
}

// tags{zbuf.clear}
// tags{rust.zbuf.zbuf.clear}
pub fn clear(&mut self) {
self.slices.clear();
}

// tags{zbuf.slices.iter}
// tags{rust.zbuf.zbuf.zslices}
pub fn zslices(&self) -> impl Iterator<Item = &ZSlice> + '_ {
self.slices.as_ref().iter()
}

// tags{zbuf.slices.iter}
// tags{rust.zbuf.zbuf.zslices_mut}
pub fn zslices_mut(&mut self) -> impl Iterator<Item = &mut ZSlice> + '_ {
self.slices.as_mut().iter_mut()
}

// tags{zbuf.slices.push}
// tags{rust.zbuf.zbuf.push_zslice}
pub fn push_zslice(&mut self, zslice: ZSlice) {
if !zslice.is_empty() {
self.slices.push(zslice);
}
}

// tags{zbuf.splice}
// tags{rust.zbuf.zbuf.splice}
pub fn splice<Range: RangeBounds<usize>>(&mut self, erased: Range, replacement: &[u8]) {
let start = match erased.start_bound() {
core::ops::Bound::Included(n) => *n,
Expand Down Expand Up @@ -147,7 +147,7 @@ impl ZBuf {
// Buffer
impl Buffer for ZBuf {
#[inline(always)]
// tags{zbuf.len, buffer.len}
// tags{rust.zbuf.zbuf.buffer.len, api.buffer.len}
fn len(&self) -> usize {
self.slices
.as_ref()
Expand All @@ -160,14 +160,14 @@ impl Buffer for ZBuf {
impl SplitBuffer for ZBuf {
type Slices<'a> = iter::Map<core::slice::Iter<'a, ZSlice>, fn(&'a ZSlice) -> &'a [u8]>;

// tags{zbuf.slices.get}
// tags{rust.zbuf.zbuf.split_buffer.slices}
fn slices(&self) -> Self::Slices<'_> {
self.slices.as_ref().iter().map(ZSlice::as_slice)
}
}

impl PartialEq for ZBuf {
// tags{zbuf.compare, buffer.compare}
// tags{rust.zbuf.zbuf.partial_eq.eq, api.buffer.compare}
fn eq(&self, other: &Self) -> bool {
let mut self_slices = self.slices();
let mut other_slices = other.slices();
Expand Down Expand Up @@ -225,6 +225,7 @@ pub struct ZBufPos {
}

#[derive(Debug, Clone)]
// tags{rust.zbuf.zbuf_reader}
pub struct ZBufReader<'a> {
inner: &'a ZBuf,
cursor: ZBufPos,
Expand Down Expand Up @@ -394,8 +395,8 @@ impl<'a> SiphonableReader for ZBufReader<'a> {
}

#[cfg(feature = "std")]
// tags{zbuf.read, buffer.read}
impl<'a> std::io::Read for ZBufReader<'a> {
// tags{rust.zbuf.zbuf_reader.read api.buffer.read}
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
match <Self as Reader>::read(self, buf) {
Ok(n) => Ok(n.get()),
Expand Down
34 changes: 17 additions & 17 deletions commons/zenoh-keyexpr/src/key_expr/borrowed.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ use zenoh_result::{bail, Error as ZError, ZResult};
/// * Two sets [intersect](keyexpr::intersects()) if they have at least one element in common. `a/*` intersects `*/a` on `a/a` for example.
/// * One set A [includes](keyexpr::includes()) the other set B if all of B's elements are in A: `a/*/**` includes `a/b/**`
/// * Two sets A and B are equal if all A includes B and B includes A. The Key Expression language is designed so that string equality is equivalent to set equality.
// tags{keyexpr}
// tags{rust.keyexpr.keyexpr, api.keyexpr}
#[allow(non_camel_case_types)]
#[repr(transparent)]
#[derive(PartialEq, Eq, Hash)]
Expand All @@ -55,8 +55,8 @@ impl keyexpr {
/// Note that to be considered a valid key expression, a string MUST be canon.
///
/// [`keyexpr::autocanonize`] is an alternative constructor that will canonize the passed expression before constructing it.
// tags{keyexpr.create}
// tags{keyexpr.is_canon}
// tags{rust.keyexpr.keyexpr.new, api.keyexpr.create.checked}
// tags{api.keyexpr.is_canon}
pub fn new<'a, T, E>(t: &'a T) -> Result<&'a Self, E>
where
&'a Self: TryFrom<&'a T, Error = E>,
Expand All @@ -70,7 +70,8 @@ impl keyexpr {
/// Will return Err if the passed value isn't a valid key expression despite canonization.
///
/// Note that this function does not allocate, and will instead mutate the passed value in place during canonization.
// tags{keyexpr.canonize}
// tags{rust.keyexpr.keyexpr.autocanonize, api.keyexpr.create.autocanonize}
// tags{api.keyexpr.canonize}
pub fn autocanonize<'a, T, E>(t: &'a mut T) -> Result<&'a Self, E>
where
&'a Self: TryFrom<&'a T, Error = E>,
Expand All @@ -81,14 +82,14 @@ impl keyexpr {
}

/// Returns `true` if the `keyexpr`s intersect, i.e. there exists at least one key which is contained in both of the sets defined by `self` and `other`.
/// tags{keyexpr.intersects}
/// tags{rust.keyexpr.keyexpr.intersects, api.keyexpr.intersects}
pub fn intersects(&self, other: &Self) -> bool {
use super::intersect::Intersector;
super::intersect::DEFAULT_INTERSECTOR.intersect(self, other)
}

/// Returns `true` if `self` includes `other`, i.e. the set defined by `self` contains every key belonging to the set defined by `other`.
// tags{keyexpr.includes}
// tags{rust.keyexpr.keyexpr.includes, api.keyexpr.includes}
pub fn includes(&self, other: &Self) -> bool {
use super::include::Includer;
super::include::DEFAULT_INCLUDER.includes(self, other)
Expand All @@ -97,7 +98,7 @@ impl keyexpr {
/// Returns the relation between `self` and `other` from `self`'s point of view ([`SetIntersectionLevel::Includes`] signifies that `self` includes `other`).
///
/// Note that this is slower than [`keyexpr::intersects`] and [`keyexpr::includes`], so you should favor these methods for most applications.
// tags{keyexpr.relation_to}
// tags{rust.keyexpr.keyexpr.relation_to, api.keyexpr.relation_to}
pub fn relation_to(&self, other: &Self) -> SetIntersectionLevel {
use SetIntersectionLevel::*;
if self.intersects(other) {
Expand Down Expand Up @@ -127,13 +128,13 @@ impl keyexpr {
/// ```
///
/// If `other` is of type `&keyexpr`, you may use `self / other` instead, as the joining becomes infallible.
// tags{keyexpr.join}
// tags{rust.keyexpr.keyexpr.join, api.keyexpr.join}
pub fn join<S: AsRef<str> + ?Sized>(&self, other: &S) -> ZResult<OwnedKeyExpr> {
OwnedKeyExpr::autocanonize(format!("{}/{}", self, other.as_ref()))
}

/// Returns `true` if `self` contains any wildcard character (`**` or `$*`).
// tags{keyexpr.is_wild}
// tags{rust.keyexpr.keyexpr.is_wild, api.keyexpr.is_wild}
pub fn is_wild(&self) -> bool {
self.0.contains(super::SINGLE_WILD as char)
}
Expand Down Expand Up @@ -166,7 +167,7 @@ impl keyexpr {
/// None,
/// keyexpr::new("dem$*").unwrap().get_nonwild_prefix());
/// ```
// tags{keyexpr.get_nonwild_prefix}
// tags{rust.keyexpr.keyexpr.get_nonwild_prefix, api.keyexpr.get_nonwild_prefix}
pub fn get_nonwild_prefix(&self) -> Option<&keyexpr> {
match self.0.find('*') {
Some(i) => match self.0[..i].rfind('/') {
Expand Down Expand Up @@ -231,7 +232,7 @@ impl keyexpr {
/// keyexpr::new("demo/example/test/**").unwrap().strip_prefix(keyexpr::new("not/a/prefix").unwrap()).is_empty()
/// );
/// ```
// tags{keyexpr.strip_prefix}
// tags{rust.keyexpr.keyexpr.strip_prefix, api.keyexpr.strip_prefix}
pub fn strip_prefix(&self, prefix: &Self) -> Vec<&keyexpr> {
let mut result = vec![];
'chunks: for i in (0..=self.len()).rev() {
Expand Down Expand Up @@ -276,7 +277,7 @@ impl keyexpr {
result
}

// tags{keyexpr.as_str}
// tags{rust.keyexpr.keyexpr.as_str, api.keyexpr.as_str}
pub fn as_str(&self) -> &str {
self
}
Expand All @@ -286,7 +287,7 @@ impl keyexpr {
///
/// Much like [`core::str::from_utf8_unchecked`], this is memory-safe, but calling this without maintaining
/// [`keyexpr`]'s invariants yourself may lead to unexpected behaviors, the Zenoh network dropping your messages.
// tags{keyexpr.create.unchecked}
// tags{rust.keyexpr.keyexpr.from_str_unchecked, api.keyexpr.create.unchecked}
pub unsafe fn from_str_unchecked(s: &str) -> &Self {
core::mem::transmute(s)
}
Expand All @@ -296,11 +297,11 @@ impl keyexpr {
///
/// Much like [`core::str::from_utf8_unchecked`], this is memory-safe, but calling this without maintaining
/// [`keyexpr`]'s invariants yourself may lead to unexpected behaviors, the Zenoh network dropping your messages.
// tags{keyexpr.create.unchecked}
// tags{rust.keyexpr.keyexpr.from_slice_unchecked, api.keyexpr.create.unchecked}
pub unsafe fn from_slice_unchecked(s: &[u8]) -> &Self {
core::mem::transmute(s)
}
// tags{keyexpr.chunks}
// tags{rust.keyexpr.keyexpr.chunks, api.keyexpr.chunks}
pub fn chunks(&self) -> impl Iterator<Item = &Self> + DoubleEndedIterator {
self.split('/').map(|c| unsafe {
// Any chunk of a valid KE is itself a valid KE => we can safely call the unchecked constructor.
Expand All @@ -321,7 +322,7 @@ impl Div for &keyexpr {
/// Note that [`Equals`](SetIntersectionLevel::Equals) implies [`Includes`](SetIntersectionLevel::Includes), which itself implies [`Intersects`](SetIntersectionLevel::Intersects).
///
/// You can check for intersection with `level >= SetIntersecionLevel::Intersection` and for inclusion with `level >= SetIntersectionLevel::Includes`.
// tags{options.keyexpr.set_intersection_level}
// rust.keyexpr.set_intersection_level, api.options.keyexpr.set_intersection_level}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum SetIntersectionLevel {
Disjoint,
Expand Down Expand Up @@ -350,7 +351,6 @@ impl fmt::Display for keyexpr {
}
}

// tags{options.keyexpr.construction_error}
#[repr(i8)]
enum KeyExprConstructionError {
LoneDollarStar = -1,
Expand Down
10 changes: 5 additions & 5 deletions commons/zenoh-keyexpr/src/key_expr/owned.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ use core::{
/// A [`Arc<str>`] newtype that is statically known to be a valid key expression.
///
/// See [`keyexpr`](super::borrowed::keyexpr).
// tags{keyexpr}
// tags{rust.keyexpr.owned_key_expr}
#[derive(Clone, PartialEq, Eq, Hash, serde::Deserialize)]
#[cfg_attr(feature = "std", derive(schemars::JsonSchema))]
#[serde(try_from = "String")]
Expand All @@ -47,7 +47,7 @@ impl OwnedKeyExpr {
/// Note that to be considered a valid key expression, a string MUST be canon.
///
/// [`OwnedKeyExpr::autocanonize`] is an alternative constructor that will canonize the passed expression before constructing it.
// tags{keyexpr.create}
// tags{rust.keyexpr.owned_key_expr, api.keyexpr.create.checked}
pub fn new<T, E>(t: T) -> Result<Self, E>
where
Self: TryFrom<T, Error = E>,
Expand All @@ -58,7 +58,7 @@ impl OwnedKeyExpr {
/// Canonizes the passed value before returning it as an `OwnedKeyExpr`.
///
/// Will return Err if the passed value isn't a valid key expression despite canonization.
// tags{keyexpr.canonize}
// tags{rust.keyexpr.owned_key_expr.autocanonize, api.keyexpr.create.autocanonize}
pub fn autocanonize<T, E>(mut t: T) -> Result<Self, E>
where
Self: TryFrom<T, Error = E>,
Expand All @@ -72,15 +72,15 @@ impl OwnedKeyExpr {
/// # Safety
/// Key Expressions must follow some rules to be accepted by a Zenoh network.
/// Messages addressed with invalid key expressions will be dropped.
// tags{keyexpr.create.unchecked}
// tags{rust.keyexpr.owned_key_expr.from_string_unchecked, api.keyexpr.create.unchecked}
pub unsafe fn from_string_unchecked(s: String) -> Self {
Self::from_boxed_string_unchecked(s.into_boxed_str())
}
/// Constructs an OwnedKeyExpr without checking [`keyexpr`]'s invariants
/// # Safety
/// Key Expressions must follow some rules to be accepted by a Zenoh network.
/// Messages addressed with invalid key expressions will be dropped.
// tags{keyexpr.create.unchecked}
// tags{rust.keyexpr.owned_key_expr.from_boxed_string_unchecked, api.keyexpr.create.unchecked}
pub unsafe fn from_boxed_string_unchecked(s: Box<str>) -> Self {
OwnedKeyExpr(s.into())
}
Expand Down
Loading

0 comments on commit de939d7

Please sign in to comment.