Struct Region

pub struct Region { /* private fields */ }

Region describes a region of a possibly-larger space of ranks, organized into a hyperrect.

Internally, region consist of a set of labels and a Slice, as it allows for a compact but useful representation of the ranks. However, this representation may change in the future.

Implementations

impl Region

pub fn new(labels: Vec<String>, slice: Slice) -> Self

Constructor to build arbitrary regions (incl. non-contiguous / offset).

pub fn labels(&self) -> &[String]

The labels of the dimensions of this region.

pub fn slice(&self) -> &Slice

The slice representing this region. Note: this representation may change.

pub fn into_inner(self) -> (Vec<String>, Slice)

Convert this region into its constituent labels and slice.

pub fn extent(&self) -> Extent

Returns the extent of the region.

pub fn is_subset(&self, other: &Region) -> bool

Returns true if this region is a subset of other, i.e., if other contains at least all of the ranks in this region.

pub fn remap(&self, target: &Region) -> Option<impl Iterator<Item = usize> + '_>

Remap the target to ranks in this region. The returned iterator iterates over each rank in target, providing the corresponding rank in self. This is useful when mapping between different subspaces.

let ext = extent!(replica = 8, gpu = 4);
let replica1 = ext.range("replica", 1).unwrap();
assert_eq!(replica1.extent(), extent!(replica = 1, gpu = 4));
let replica1_gpu12 = replica1.range("gpu", 1..3).unwrap();
assert_eq!(replica1_gpu12.extent(), extent!(replica = 1, gpu = 2));
// The first rank in `replica1_gpu12` is the second rank in `replica1`.
assert_eq!(
    replica1.remap(&replica1_gpu12).unwrap().collect::<Vec<_>>(),
    vec![1, 2],
);

pub fn num_ranks(&self) -> usize

Returns the total number of ranks in the region.

pub fn base_rank_of_point(&self, p: Point) -> Result<usize, RegionError>

Convert a rank in this region’s extent into its corresponding rank in the base space defined by the region’s Slice.

pub fn point_of_base_rank(&self, rank: usize) -> Result<Point, RegionError>

Convert a rank in the base space into the corresponding Point in this region’s extent (if the base rank lies within the region’s Slice).

Trait Implementations

impl Clone for Region

fn clone(&self) -> Region

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Region

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Region

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Region

Formats a Region in a compact rectangular syntax:

[offset+]label=size/stride[,label=size/stride,...]

Grammar

Region   := [ Offset "+" ] Pair ( "," Pair )*
Offset   := [0-9]+
Pair     := Label "=" Size "/" Stride
Label    := SafeIdent | Quoted
SafeIdent:= [A-Za-z0-9_]+
Quoted   := "\"" ( [^"\\] | "\\" . )* "\""   // Rust string literal style
Size     := [0-9]+
Stride   := [0-9]+

Quoting rules

• Labels that are not SafeIdent are rendered using Rust string-literal syntax (via format!("{:?}", label)).
• “Safe” means ASCII alphanumeric or underscore ([A-Za-z0-9_]+). Everything else is quoted.
• The optional Offset+ prefix appears only when the slice offset is nonzero.

Examples

x=2/1,y=3/2
8+"dim/0"=4/1,"dim,1"=5/4

Notes

This format is both human-readable and machine-parsable. The corresponding FromStr implementation accepts exactly this grammar, including quoted labels. The quoting rule makes round-trip unambiguous.

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

Formats the value using the given formatter.

impl From<&Region> for Shape

fn from(region: &Region) -> Self

Converts to this type from the input type.

impl From<&Shape> for Region

fn from(s: &Shape) -> Self

Converts to this type from the input type.

impl From<Extent> for Region

fn from(extent: Extent) -> Self

Converts to this type from the input type.

impl From<Shape> for Region

fn from(s: Shape) -> Self

Converts to this type from the input type.

impl FromStr for Region

Parses a Region from the textual form emitted by Display.

The accepted syntax and quoting rules are exactly those documented on Display: comma-separated label=size/stride pairs with an optional offset+ prefix, and labels that are either safe identifiers or Rust string literals.

Returns a RegionParseError on malformed input.

Examples

use ndslice::view::Region;

let r: Region = "x=2/1,y=3/2".parse().unwrap();
assert_eq!(r.labels(), &["x", "y"]);

let q: Region = "8+\"dim/0\"=4/1".parse().unwrap();
assert_eq!(q.labels(), &["dim/0"]);

type Err = RegionParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Region

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Region

fn eq(&self, other: &Region) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Region

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl View for Region

A Region is also a View.

type Item = usize

The type of item is the rank in the underlying space.

type View = Region

The type of sub-view is also a Region.

fn region(&self) -> Region

The ranks contained in this view.

fn subset(&self, region: Region) -> Result<Region, ViewError>

Subsets this view with the provided ranks. This is mainly used by combinators on Views themselves. The set of ranks passed in must be a subset of the ranks of the base view.

fn get(&self, rank: usize) -> Option<Self::Item>

Retrieve the item corresponding to the given rank in the Region of this view. An implementation MUST return a value for all ranks defined in this view.

impl Eq for Region

impl StructuralPartialEq for Region