Struct Shape 

pub struct Shape(/* private fields */);

The shape of a tensor: an ordered sequence of dimension sizes.

Each dimension size is a u64. The special value DYNAMIC marks a dimension whose concrete size is unknown at descriptor-write time. A size of 0 denotes an empty dimension (the tensor contains no elements along that axis).

A Shape with no dimensions (rank == 0) represents a scalar tensor containing exactly one element.

Examples

use hurray_core::{Shape, DYNAMIC};

// 3-D tensor with all static dimensions.
let s = Shape::new(vec![3, 4, 5]).expect("valid");
assert_eq!(s.rank(), 3);
assert_eq!(s.element_count(), Some(60));

// Scalar tensor.
let scalar = Shape::scalar();
assert_eq!(scalar.rank(), 0);
assert_eq!(scalar.element_count(), Some(1));

// Shape with a dynamic dimension.
let dyn_shape = Shape::new(vec![1, DYNAMIC, 768]).expect("valid");
assert!(dyn_shape.has_dynamic());
assert!(dyn_shape.element_count().is_none());

Implementations

impl Shape

pub fn new(dims: impl Into<Vec<u64>>) -> Result<Self>

Creates a new Shape from the given dimension sizes.

Errors

Returns Error::RankExceedsMaximum if dims.len() > MAX_RANK (64).

Examples

use hurray_core::{Shape, Error};

let s = Shape::new(vec![3, 4, 5]).expect("valid");
assert_eq!(s.rank(), 3);

// Rank 65 must be rejected.
let too_many = Shape::new(vec![1u64; 65]);
assert!(matches!(too_many, Err(Error::RankExceedsMaximum { rank: 65, max: 64 })));

pub fn scalar() -> Self

Returns a Shape representing a scalar tensor (rank 0, one element).

Examples

use hurray_core::Shape;

let s = Shape::scalar();
assert_eq!(s.rank(), 0);
assert_eq!(s.dims(), &[]);
assert_eq!(s.element_count(), Some(1));

pub fn rank(&self) -> usize

Returns the number of dimensions (the rank) of this shape.

Examples

use hurray_core::Shape;

assert_eq!(Shape::scalar().rank(), 0);
assert_eq!(Shape::new(vec![3, 4]).unwrap().rank(), 2);

pub fn dims(&self) -> &[u64]

Returns the dimension sizes as a slice.

Examples

use hurray_core::Shape;

let s = Shape::new(vec![2, 3]).unwrap();
assert_eq!(s.dims(), &[2, 3]);

pub fn element_count(&self) -> Option<u64>

Returns the total number of logical elements, or None if any dimension is DYNAMIC or if the product overflows u64.

The product of an empty sequence (scalar) is 1. A tensor with any zero-size dimension has element_count == Some(0).

A reader MUST NOT use this value to compute buffer sizes or strides until all dynamic dimensions have been resolved.

Examples

use hurray_core::{Shape, DYNAMIC};

// Static shape.
assert_eq!(Shape::new(vec![3, 4, 5]).unwrap().element_count(), Some(60));

// Scalar: product of empty sequence is 1.
assert_eq!(Shape::scalar().element_count(), Some(1));

// Empty tensor: any zero dimension makes the count 0.
assert_eq!(Shape::new(vec![3, 0, 5]).unwrap().element_count(), Some(0));

// Dynamic dimension: result is unknown.
assert_eq!(Shape::new(vec![1, DYNAMIC, 768]).unwrap().element_count(), None);

pub fn is_empty_tensor(&self) -> bool

Returns true if any dimension has size 0.

An empty tensor is valid; its data buffer has size 0 bytes. Note that a DYNAMIC dimension does not make a tensor empty — its size is unknown, not zero.

Examples

use hurray_core::{Shape, DYNAMIC};

assert!(Shape::new(vec![3, 0, 5]).unwrap().is_empty_tensor());
assert!(!Shape::new(vec![3, 4, 5]).unwrap().is_empty_tensor());
// Dynamic is not empty.
assert!(!Shape::new(vec![1, DYNAMIC, 768]).unwrap().is_empty_tensor());

pub fn has_dynamic(&self) -> bool

Returns true if any dimension equals DYNAMIC.

Examples

use hurray_core::{Shape, DYNAMIC};

assert!(Shape::new(vec![1, DYNAMIC, 768]).unwrap().has_dynamic());
assert!(!Shape::new(vec![1, 128, 768]).unwrap().has_dynamic());

Trait Implementations

impl Clone for Shape

fn clone(&self) -> Shape

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Shape

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

Formats the value using the given formatter.

impl Display for Shape

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

Formats the shape as a bracket-enclosed, comma-separated list of sizes.

Dynamic dimensions are shown as ?. An empty (scalar) shape is [].

Examples

use hurray_core::{Shape, DYNAMIC};

assert_eq!(Shape::scalar().to_string(), "[]");
assert_eq!(Shape::new(vec![3, 4, 5]).unwrap().to_string(), "[3, 4, 5]");
assert_eq!(Shape::new(vec![1, DYNAMIC, 768]).unwrap().to_string(), "[1, ?, 768]");

impl Eq for Shape

impl Hash for Shape

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 Shape

fn eq(&self, other: &Shape) -> 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 StructuralPartialEq for Shape