From 71dcc0afe486a323e9f01a72fa7a4c93cf812ce1 Mon Sep 17 00:00:00 2001 From: "Matthew D. Steele" Date: Mon, 17 Apr 2017 10:37:20 -0400 Subject: [PATCH] Clarify Rect docs to indicate that empty Rects aren't allowed --- src/sdl2/rect.rs | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/src/sdl2/rect.rs b/src/sdl2/rect.rs index 3e9a9cef..e65624a2 100644 --- a/src/sdl2/rect.rs +++ b/src/sdl2/rect.rs @@ -57,7 +57,13 @@ fn clamped_mul(a: i32, b: i32) -> i32 { } } -/// A rectangle. +/// A (non-empty) rectangle. +/// +/// The width and height of a `Rect` must always be strictly positive (never +/// zero). In cases where empty rects may need to represented, it is +/// recommended to use `Option`, with `None` representing an empty +/// rectangle (see, for example, the output of the +/// [`intersection`](#method.intersection) method). #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct Rect { raw: ll::SDL_Rect, @@ -67,11 +73,13 @@ impl Rect { /// Creates a new rectangle from the given values. /// /// The width and height are clamped to ensure that the right and bottom - /// sides of the rectangle does not exceed i32::max_value(). - /// (The value 2147483647, the maximal positive size of an i32) + /// sides of the rectangle does not exceed i32::max_value() (the value + /// 2147483647, the maximal positive size of an i32). This means that the + /// rect size will behave oddly if you move it very far to the right or + /// downwards on the screen. /// - /// This means that the rect size will behave oddly if you move it very far - /// to the right or downwards on the screen. + /// `Rect`s must always be non-empty, so a `width` and/or `height` argument + /// of 0 will be replaced with 1. pub fn new(x: i32, y: i32, width: u32, height: u32) -> Rect { let raw = ll::SDL_Rect { x: clamp_position(x), @@ -85,11 +93,13 @@ impl Rect { /// Creates a new rectangle centered on the given position. /// /// The width and height are clamped to ensure that the right and bottom - /// sides of the rectangle does not exceed i32::max_value(). - /// (The value 2147483647, the maximal positive size of an i32) + /// sides of the rectangle does not exceed i32::max_value() (the value + /// 2147483647, the maximal positive size of an i32). This means that the + /// rect size will behave oddly if you move it very far to the right or + /// downwards on the screen. /// - /// This means that the rect size will behave oddly if you move it very far - /// to the right or downwards on the screen. + /// `Rect`s must always be non-empty, so a `width` and/or `height` argument + /// of 0 will be replaced with 1. pub fn from_center

(center: P, width: u32, height: u32) -> Rect where P: Into { let raw = ll::SDL_Rect { @@ -142,12 +152,18 @@ impl Rect { /// Sets the width of this rectangle to the given value, /// clamped to be less than or equal to i32::max_value() / 2. + /// + /// `Rect`s must always be non-empty, so a `width` argument of 0 will be + /// replaced with 1. pub fn set_width(&mut self, width: u32) { self.raw.w = clamp_size(width) as i32; } /// Sets the height of this rectangle to the given value, /// clamped to be less than or equal to i32::max_value() / 2. + /// + /// `Rect`s must always be non-empty, so a `height` argument of 0 will be + /// replaced with 1. pub fn set_height(&mut self, height: u32) { self.raw.h = clamp_size(height) as i32; }