CGGeometry Reference

Overview

CGGeometry Reference defines structures for geometric primitives and functions that operate on them. The data structure CGPoint represents a point in a two-dimensional coordinate system. The data structure CGRect represents the location and dimensions of a rectangle. The data structure CGSize represents the dimensions of width and height.

The height and width stored in a CGRect data structure can be negative. For example, a rectangle with an origin of [0.0, 0.0] and a size of [10.0,10.0] is exactly equivalent to a rectangle with an origin of [10.0, 10.0] and a size of [-10.0,-10.0]. Your application can standardize a rectangle—that is, ensure that the height and width are stored as positive values—by calling the CGRectStandardize function. All functions described in this reference that take CGRect data structures as inputs implicitly standardize those rectangles before calculating their results. For this reason, your applications should avoid directly reading and writing the data stored in the CGRect data structure. Instead, use the functions described here to manipulate rectangles and to retrieve their characteristics.

Functions by Task

Creating a Dictionary Representation from a Geometric Primitive

• CGPointCreateDictionaryRepresentation
• CGSizeCreateDictionaryRepresentation
• CGRectCreateDictionaryRepresentation

Creating a Geometric Primitive from a Dictionary Representation

• CGPointMakeWithDictionaryRepresentation
• CGSizeMakeWithDictionaryRepresentation
• CGRectMakeWithDictionaryRepresentation

Creating a Geometric Primitive from Values

• CGPointMake
• CGRectMake
• CGSizeMake

Modifying Rectangles

• CGRectDivide
• CGRectInset
• CGRectIntegral
• CGRectIntersection
• CGRectOffset
• CGRectStandardize
• CGRectUnion

Comparing Values

• CGPointEqualToPoint
• CGSizeEqualToSize
• CGRectEqualToRect
• CGRectIntersectsRect

Checking for Membership

• CGRectContainsPoint
• CGRectContainsRect

Getting Min, Mid, and Max Values

• CGRectGetMinX
• CGRectGetMinY
• CGRectGetMidX
• CGRectGetMidY
• CGRectGetMaxX
• CGRectGetMaxY

Getting Height and Width

• CGRectGetHeight
• CGRectGetWidth

Checking Rectangle Characteristics

• CGRectIsEmpty
• CGRectIsNull
• CGRectIsInfinite

Functions

CGPointCreateDictionaryRepresentation

Returns a dictionary representation of the specified point.

CFDictionaryRef CGPointCreateDictionaryRepresentation(
   CGPoint point
);

CGPointEqualToPoint

Returns whether two points are equal.

bool CGPointEqualToPoint (
   CGPoint point1,
   CGPoint point2
);

CGPointMake

Returns a point with the specified coordinates.

CGPoint CGPointMake (
   CGFloat x,
   CGFloat y
);

CGPointMakeWithDictionaryRepresentation

Fills in a point using the contents of the specified dictionary.

bool CGPointMakeWithDictionaryRepresentation(
   CFDictionaryRef dict,
   CGPoint *point
);

CGRectContainsPoint

Returns whether a rectangle contains a specified point.

bool CGRectContainsPoint (
   CGRect rect,
   CGPoint point
);

CGRectContainsRect

Returns whether the first rectangle contains the second rectangle.

bool CGRectContainsRect (
   CGRect rect1,
   CGRect rect2
);

CGRectCreateDictionaryRepresentation

Returns a dictionary representation of the provided rectangle.

CFDictionaryRef CGRectCreateDictionaryRepresentation(
   CGRect rect
);

CGRectDivide

Divides a source rectangle into two component rectangles.

void CGRectDivide (
   CGRect rect,
   CGRect *slice,
   CGRect *remainder,
   CGFloat amount,
   CGRectEdge edge
);

CGRectEqualToRect

Returns whether two rectangles are equal in size and position.

bool CGRectEqualToRect (
   CGRect rect1,
   CGRect rect2
);

CGRectGetHeight

Returns the height of a rectangle.

CGFloat CGRectGetHeight (
   CGRect rect
);

CGRectGetMaxX

Returns the largest value of the x-coordinate for the rectangle.

CGFloat CGRectGetMaxX (
   CGRect rect
);

CGRectGetMaxY

Returns the largest value for the y-coordinate of the rectangle.

CGFloat CGRectGetMaxY (
   CGRect rect
);

CGRectGetMidX

Returns the x- coordinate that establishes the center of a rectangle.

CGFloat CGRectGetMidX (
   CGRect rect
);

CGRectGetMidY

Returns the y-coordinate that establishes the center of the rectangle.

CGFloat CGRectGetMidY (
   CGRect rect
);

CGRectGetMinX

Returns the smallest value for the x-coordinate of the rectangle.

CGFloat CGRectGetMinX (
   CGRect rect
);

CGRectGetMinY

Returns the smallest value for the y-coordinate of the rectangle.

CGFloat CGRectGetMinY (
   CGRect rect
);

CGRectGetWidth

Returns the width of a rectangle.

CGFloat CGRectGetWidth (
   CGRect rect
);

CGRectInset

Returns a rectangle that is smaller or larger than the source rectangle, with the same center point.

CGRect CGRectInset (
   CGRect rect,
   CGFloat dx,
   CGFloat dy
);

CGRectIntegral

Returns the smallest rectangle that results from converting the source rectangle values to integers.

CGRect CGRectIntegral (
   CGRect rect
);

CGRectIntersection

Returns the intersection of two rectangles.

CGRect CGRectIntersection (
   CGRect r1,
   CGRect r2
);

CGRectIntersectsRect

Returns whether two rectangles intersect.

bool CGRectIntersectsRect (
   CGRect rect1,
   CGRect rect2
);

CGRectIsEmpty

Returns whether a rectangle has zero width or height, or is a null rectangle.

bool CGRectIsEmpty (
   CGRect rect
);

CGRectIsInfinite

Returns whether a rectangle is infinite.

bool CGRectIsInfinite (
   CGRect rect
);

CGRectIsNull

Returns whether the rectangle is equal to the null rectangle.

bool CGRectIsNull (
   CGRect rect
);

CGRectMake

Returns a rectangle with the specified coordinate and size values.

CGRect CGRectMake (
   CGFloat x,
   CGFloat y,
   CGFloat width,
   CGFloat height
);

CGRectMakeWithDictionaryRepresentation

Fills in a rectangle using the contents of the specified dictionary.

bool CGRectMakeWithDictionaryRepresentation(
   CFDictionaryRef dict,
   CGRect *rect
);

CGRectOffset

Returns a rectangle with an origin that is offset from that of the source rectangle.

CGRect CGRectOffset (
   CGRect rect,
   CGFloat dx,
   CGFloat dy
);

CGRectStandardize

Returns a rectangle with a positive width and height.

CGRect CGRectStandardize (
   CGRect rect
);

CGRectUnion

Returns the smallest rectangle that contains the two source rectangles.

CGRect CGRectUnion (
   CGRect r1,
   CGRect r2
);

CGSizeCreateDictionaryRepresentation

Returns a dictionary representation of the specified size.

CFDictionaryRef CGSizeCreateDictionaryRepresentation(
   CGSize size
);

CGSizeEqualToSize

Returns whether two sizes are equal.

bool CGSizeEqualToSize (
   CGSize size1,
   CGSize size2
);

CGSizeMake

Returns a size with the specified dimension values.

CGSize CGSizeMake (
   CGFloat width,
   CGFloat height
);

CGSizeMakeWithDictionaryRepresentation

Fills in a size using the contents of the specified dictionary.

bool CGSizeMakeWithDictionaryRepresentation(
   CFDictionaryRef dict,
   CGSize *size
);

Data Types

CGFloat

The basic type for all floating-point values.

typedef float CGFloat;// 32-bit

typedef double CGFloat;// 64-bit

CGPoint

A structure that contains a point in a two-dimensional coordinate system.

struct CGPoint {
   CGFloat x;
   CGFloat y;
};
typedef struct CGPoint CGPoint;

Fields

x

The x-coordinate of the point.

y

The y-coordinate of the point.

CGRect

A structure that contains the location and dimensions of a rectangle.

struct CGRect {
   CGPoint origin;
   CGSize size;
};
typedef struct CGRect CGRect;

Fields

origin

A point that specifies the coordinates of the rectangle’s origin.

size

A size that specifies the height and width of the rectangle.

CGSize

A structure that contains width and height values.

struct CGSize {
   CGFloat width;
   CGFloat height;
};
typedef struct CGSize CGSize;

Fields

width

A width value.

height

A height value.

Constants

CGRectInfinite

A rectangle that has infinite extent.

const CGRect CGRectInfinite;

Constants

CGRectInfinite

A rectangle that has infinite extent.

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

Geometric Zeros

A zero point, zero rectangle, or zero size.

const CGPoint CGPointZero;
const CGRect CGRectZero;
const CGSize CGSizeZero;

Constants

CGPointZero

A point constant with location (0,0). The zero point is equivalent to CGPointMake(0,0).

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

CGRectZero

A rectangle constant with location (0,0), and width and height of 0. The zero rectangle is equivalent to CGRectMake(0,0,0,0).

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

CGSizeZero

A size constant with width and height of 0. The zero size is equivalent to CGSizeMake(0,0).

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

Geometrical Null

The null or empty rectangle.

const CGRect CGRectNull;

Constants

CGRectNull

The null rectangle. This is the rectangle returned when, for example, you intersect two disjoint rectangles. Note that the null rectangle is not the same as the zero rectangle. For example, the union of a rectangle with the null rectangle is the original rectangle (that is, the null rectangle contributes nothing).

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

CGRectEdge

Coordinates that establish the edges of a rectangle.

enum CGRectEdge {
   CGRectMinXEdge,
   CGRectMinYEdge,
   CGRectMaxXEdge,
   CGRectMaxYEdge
};
typedef enum CGRectEdge CGRectEdge;

Constants

CGRectMinXEdge

The minimum value for the x-coordinate of the rectangle. In OS X and iOS with the default coordinate system this is the left edge of the rectangle.

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

CGRectMinYEdge

The minimum value for the y-coordinate of the rectangle. In OS X with the default coordinate system this is the bottom edge of the rectangle. In iOS with the default coordinate system this is the top edge of the rectangle.

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

CGRectMaxXEdge

The maximum value for the x-coordinate of the rectangle. In OS X and iOS with the default coordinate system this is the right edge of the rectangle.

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

CGRectMaxYEdge

The maximum value for the y-coordinate of the rectangle. In OS X with the default coordinate system this is the top edge of the rectangle. In iOS with the default coordinate system this is the bottom edge of the rectangle.

Available in iOS 2.0 and later.

Declared in CGGeometry.h.

CGFloat Informational Macros

Informational macros for the CGFloat type.

#define CGFLOAT_MIN FLT_MIN// 32-bit

#define CGFLOAT_MAX FLT_MAX

#define CGFLOAT_IS_DOUBLE 0

#define CGFLOAT_MIN DBL_MIN// 64-bit

#define CGFLOAT_MAX DBL_MAX

#define CGFLOAT_IS_DOUBLE 1

Constants

CGFLOAT_MIN

The minimum allowable value for a CGFloat type. For 32-bit code, this value is 1.17549435e-38F. For 64-bit code, it is 2.2250738585072014e-308.

Available in iOS 2.0 and later.

Declared in CGBase.h.

CGFLOAT_MAX

The maximum allowable value for a CGFloat type. For 32-bit code, this value is 3.40282347e+38F. For 64-bit code, it is 1.7976931348623157e+308.

Available in iOS 2.0 and later.

Declared in CGBase.h.

CGFLOAT_IS_DOUBLE

Indicates whether CGFloat is defined as a float or double type.

Available in iOS 2.0 and later.

Declared in CGBase.h.