unitbundle-class: Class unitbundle
In appling/unitted: Track Units as you Manipulate Data

Description Usage Arguments Details Value Definitions See Also Examples

A unitbundle is an object containing information about a single set of units - for example, kg m^2 s^-2 or mi hr^-1. This information is stored in a way that permits efficient units conversion and arithmetic.

There are several ways to create a unitbundle, all of which use the standard constructor unitbundle(...). Exactly one or zero arguments from [units, unitstr, unitdf, or unitbdl] may be specified; the choice or argument determines which construction method is used. If the units argument is specified, with or without the 'units' label, then the class of that argument determines whether it is interpreted as a unitdf argument (if it's a data.frame), a unitstr argument (if it's a character), or a unitbdl argument (if it's a unitbundle).

1	unitbundle(units, delimiter = "\|", ..., unitdf, unitstr, unitbdl)

`units`	A data.frame (unitdf method), character (parse string method), or unitbundle (replica method). Although the code is cleaner, it is slightly less efficient to use this units argument than to explicitly specify unitdf, unitstr, or unitbdl.
`delimiter`	A single-character string, relevant only when `units` or `unitstr` is a character string, used in parsing the units string into a bundle of individual units. For example, the string "tree house^2" would be parsed as two units, "tree" and "house"^2, but the default delimiter of "\|" causes the string "\|tree house\|^2" to be parsed as one squared unit, "tree house"^2.
`...`	Other arguments passed to initialize
`unitdf`	A data.frame with columns Unit=character, Power=numeric, specifying each unit-power pair in a separate row.
`unitstr`	A single character string containing one or more units to be parsed and bundled, e.g. `"kg ha^-1 yr^-1"`
`unitbdl`	A unitbundle. If this is supplied, the new unitbundle is simply a replica of unitbdl.

The basic content of a unitbundle is a collection of units each raised to a power (see Definitions below). For example, "kg ha^-1" has two units, "kg", and "ha", raised to the powers 1 and -1, respectively. In creating a unitbundle from a character string, the caret symbol (^) is used to indicate the separation between the unit and its power, and a space usually indicates the separation between two unit-power pairs.

Character strings are a potentially ambiguous way to describe units information; in particular, a unit might itself contain a space or ^. To specify the contents of a unitbundle without ambiguity, a delimiter may be used to indicate where the text part of a unit begins and ends. For example, "g soil^-1" will be incorrectly parsed into "g" and "soil^-1", but this can be avoided by wrapping the two-word unit in the delimiter: when delimiter="|", then "|g soil|^-1" will be parsed such that "g soil" is a single unit.

An initialized unitbundle

unit: A single property or thing: kg, tree house, kgC_organic
power: The power to which a unit is raised; assumed to be 1 if unspecified. 1, 0.53, and 1/2 are powers in unit-power pairs such as "apples^1" or "apples", "frequency^0.53", and "acre^1/2"
unit string: A combination of units and powers used to describe data: "kgC ha^-1 yr^-1"
vector of unit strings: c("kgC ha^-1 yr^-1", "PgN", "ft^3 s^-1")

unitted for data with unitbundles attached; unitbundle_Ops for arithmetic and other operations on unitbundles; get_units for conversion to character formats

unitbundle()
unitbundle("kg ha^-1 yr^-1")
unitbundle(units="kg ha^-1 yr^-1")
unitbundle(unitstr="kg ha^-1 yr^-1")
unitbundle(unitdf=data.frame(Unit=c("kg","ha","yr"), Power=c(1,-1,-1)))
unitbundle(unitbdl=unitbundle("kg ha^-1 yr^-1"))