unitHelpers: Unit assignment helpers

In Rdistance: Density and Abundance from Distance-Sampling Surveys

Unit assignment helpers

Description

Helper functions for assigning physical measurement units in Rdistance. All are convenience wrappers for units::set_units.

Usage

x %#% u

x %acre% .

x %cm% .

x %ft% .

x %ha% .

x %inches% .

x %km% .

x %km^2% .

x %m% .

x %m^2% .

x %mi% .

x %mi^2% .

x %yd% .

dropUnits(x)

setUnits(x, u)

Arguments

x	A numeric vector or matrix.
u	A string representing physical measurement units to assign to x, e.g., "m", "km", "m^2". Valid units are listed in columns "(symbol|name)" of valid_udunits.
.	Placeholder for the fixed unit assignment operators. Ignored. See Details.

Details

The fixed unit assignment operators are designed to behave somewhat like unary operators (i.e., 1 argument); but, R does not allow user defined unary operators. Technically, the fixed unit assignment operators are instances of R's user-defined infix operator, and as such they require two arguments. Their syntax must be x %<units>% <something>; but, the second argument is ignored and '.' is suggested. See Examples.

Value

For %#% and setUnits, argument x with units u attached.

For all the fixed unit assignment operators (i.e., %<units>%), argument x with the respective units assigned.

For dropUnits, argument x with no units. If input x has no units, x is returned unchanged.

Examples

2 %#% "m" 
setUnits(2,"km")
x <- 2 %#% "km^2"
10 %#% units(x)
2 %#% "km^2" %#% "acres" # Convert km^2 to acres
x %#% "acres"            # Same
x %#% NULL    # Drop units
dropUnits(x)  # Same

# %#%'s precedence is below "^" but above "+" and "*"
# The following fails: 
# 2 %#% "m" / (2 %#% "ha") %#% "in/acre"
# The following succeeds:
(2 %#% "m" / (2 %#% "ha")) %#% "in/acre"
1 %m%. ^ 2      # [m]
(1 %m%.) ^ 2    # [m^2]


# For fixed unit assignment, 2nd argument does not matter
# All of the following are equivalent
2 %m%.
2 %m% x
2 %m% 3
2 %m% NULL
2 %m% NA

# Conversion:
x <- 10 %#% "ft"
x %m%.

Rdistance documentation built on Jan. 10, 2026, 1:07 a.m.