R: Function to Create a Unit Object

unit {grid} | R Documentation

## Function to Create a Unit Object

### Description

This function creates a unit object — a vector of unit values. A unit value is typically just a single numeric value with an associated unit.

### Usage

    unit(x, units, data=NULL)

### Arguments

`x` | A numeric vector.
`units` | A character vector specifying the units for the corresponding numeric values.
`data` | This argument is used to supply extra information for special `unit` types.

### Details

Unit objects allow the user to specify locations and dimensions in a large number of different coordinate systems. All drawing occurs relative to a viewport and the `units` specifies what coordinate system to use within that viewport.

Possible `units` (coordinate systems) are:

`"npc"`

  Normalised Parent Coordinates (the default). The origin of the viewport is (0, 0) and the viewport has a width and height of 1 unit. For example, (0.5, 0.5) is the centre of the viewport.

`"cm"`

  Centimetres.

`"inches"`

  Inches. 1 in = 2.54 cm.

`"mm"`

  Millimetres. 10 mm = 1 cm.

`"points"`

  Points. 72.27 pt = 1 in.

`"picas"`

  Picas. 1 pc = 12 pt.

`"bigpts"`

  Big Points. 72 bp = 1 in.

`"dida"`

  Dida. 1157 dd = 1238 pt.

`"cicero"`

  Cicero. 1 cc = 12 dd.

`"scaledpts"`

  Scaled Points. 65536 sp = 1 pt.

`"lines"`

  Lines of text. Locations and dimensions are in terms of multiples of the default text size of the viewport (as specified by the viewport's `fontsize` and `lineheight`).

`"char"`

  Multiples of nominal font height of the viewport (as specified by the viewport's `fontsize`).

`"native"`

  Locations and dimensions are relative to the viewport's `xscale` and `yscale`.

`"snpc"`

  Square Normalised Parent Coordinates. Same as Normalised Parent Coordinates, except gives the same answer for horizontal and vertical locations/dimensions. It uses the lesser of npc-width and npc-height. This is useful for making things which are a proportion of the viewport, but have to be square (or have a fixed aspect ratio).

`"strwidth"`

  Multiples of the width of the string specified in the `data` argument. The font size is determined by the pointsize of the viewport.

`"strheight"`

  Multiples of the height of the string specified in the `data` argument. The font size is determined by the pointsize of the viewport.

`"grobwidth"`

  Multiples of the width of the grob specified in the `data` argument.

`"grobheight"`

  Multiples of the height of the grob specified in the `data` argument.

A number of variations are also allowed for the most common units. For example, it is possible to use `"in"` or `"inch"` instead of `"inches"` and `"centimetre"` or `"centimeter"` instead of `"cm"`.

A special `units` value of `"null"` is also allowed, but only makes sense when used in specifying widths of columns or heights of rows in grid layouts (see `grid.layout`).

The `data` argument must be a list when the `unit.length()` is greater than 1. For example,

      unit(rep(1, 3), c("npc", "strwidth", "inches"),
      data = list(NULL, "my string", NULL))

.

It is possible to subset unit objects in the normal way and to perform subassignment (see the examples), but a special function `unit.c` is provided for combining unit objects.

Certain arithmetic and summary operations are defined for unit objects. In particular, it is possible to add and subtract unit objects (e.g., `unit(1, "npc") - unit(1, "inches")`), and to specify the minimum or maximum of a list of unit objects (e.g., `min(unit(0.5, "npc"), unit(1, "inches"))`).

There is a `format` method for units, which should respond to the arguments for the default `format` method, e.g., `digits` to control the number of significant digits printed for numeric values.

### Value

An object of class `"unit"`.

### WARNING

There is a special function `unit.c` for concatenating several unit objects.

The `c` function will not give the right answer.

There used to be `"mylines"`, `"mychar"`, `"mystrwidth"`, `"mystrheight"` units. These will still be accepted, but work exactly the same as `"lines"`, `"char"`, `"strwidth"`, `"strheight"`.

### Author(s)

Paul Murrell

### See Also

`unit.c`

### Examples

    unit(1, "npc")
    unit(1:3/4, "npc")
    unit(1:3/4, "npc") + unit(1, "inches")
    min(unit(0.5, "npc"), unit(1, "inches"))
    unit.c(unit(0.5, "npc"), unit(2, "inches") + unit(1:3/4, "npc"),
           unit(1, "strwidth", "hi there"))
    x <- unit(1:5, "npc")
    x[2:4]
    x[2:4] <- unit(1, "mm")
    x

[Package grid version 4.0.5 Index]