unit.md (9310B)
1 <a name="Unit"></a> 2 ## Unit 3 * [new Unit([value], [name])](#new_Unit_new) 4 * _instance_ 5 * [.valueOf](#Unit+valueOf) ⇒ <code>string</code> 6 * [.clone()](#Unit+clone) ⇒ <code>Unit</code> 7 * [._isDerived()](#Unit+_isDerived) ⇒ <code>boolean</code> 8 * [.hasBase(base)](#Unit+hasBase) 9 * [.equalBase(other)](#Unit+equalBase) ⇒ <code>boolean</code> 10 * [.equals(other)](#Unit+equals) ⇒ <code>boolean</code> 11 * [.multiply(other)](#Unit+multiply) ⇒ <code>Unit</code> 12 * [.divide(other)](#Unit+divide) ⇒ <code>Unit</code> 13 * [.pow(p)](#Unit+pow) ⇒ <code>Unit</code> 14 * [.abs(x)](#Unit+abs) ⇒ <code>Unit</code> 15 * [.to(valuelessUnit)](#Unit+to) ⇒ <code>Unit</code> 16 * [.toNumber(valuelessUnit)](#Unit+toNumber) ⇒ <code>number</code> 17 * [.toNumeric(valuelessUnit)](#Unit+toNumeric) ⇒ <code>number</code> | <code>BigNumber</code> | <code>Fraction</code> 18 * [.toString()](#Unit+toString) ⇒ <code>string</code> 19 * [.toJSON()](#Unit+toJSON) ⇒ <code>Object</code> 20 * [.formatUnits()](#Unit+formatUnits) ⇒ <code>string</code> 21 * [.format([options])](#Unit+format) ⇒ <code>string</code> 22 * _static_ 23 * [.parse(str)](#Unit.parse) ⇒ <code>Unit</code> 24 * [.isValuelessUnit(name)](#Unit.isValuelessUnit) ⇒ <code>boolean</code> 25 * [.fromJSON(json)](#Unit.fromJSON) ⇒ <code>Unit</code> 26 27 <a name="new_Unit_new"></a> 28 ### new Unit([value], [name]) 29 A unit can be constructed in the following ways: 30 31 ```js 32 const a = new Unit(value, name) 33 const b = new Unit(null, name) 34 const c = Unit.parse(str) 35 ``` 36 37 Example usage: 38 39 ```js 40 const a = new Unit(5, 'cm') // 50 mm 41 const b = Unit.parse('23 kg') // 23 kg 42 const c = math.in(a, new Unit(null, 'm') // 0.05 m 43 const d = new Unit(9.81, "m/s^2") // 9.81 m/s^2 44 ``` 45 46 | Param | Type | Description | 47 | --- | --- | --- | 48 | [value] | <code>number</code> | <code>BigNumber</code> | <code>Fraction</code> | <code>Complex</code> | <code>boolean</code> | A value like 5.2 | 49 | [name] | <code>string</code> | A unit name like "cm" or "inch", or a derived unit of the form: "u1[^ex1] [u2[^ex2] ...] [/ u3[^ex3] [u4[^ex4]]]", such as "kg m^2/s^2", where each unit appearing after the forward slash is taken to be in the denominator. "kg m^2 s^-2" is a synonym and is also acceptable. Any of the units can include a prefix. | 50 51 <a name="Unit+valueOf"></a> 52 ### unit.valueOf ⇒ <code>string</code> 53 Returns the string representation of the unit. 54 55 **Kind**: instance property of <code>Unit</code> 56 <a name="Unit+clone"></a> 57 ### unit.clone() ⇒ <code>Unit</code> 58 create a copy of this unit 59 60 **Kind**: instance method of <code>Unit</code> 61 **Returns**: <code>Unit</code> - Returns a cloned version of the unit 62 <a name="Unit+_isDerived"></a> 63 ### unit._isDerived() ⇒ <code>boolean</code> 64 Return whether the unit is derived (such as m/s, or cm^2, but not N) 65 66 **Kind**: instance method of <code>Unit</code> 67 **Returns**: <code>boolean</code> - True if the unit is derived 68 <a name="Unit+hasBase"></a> 69 ### unit.hasBase(base) 70 check if this unit has given base unit 71 If this unit is a derived unit, this will ALWAYS return false, since by definition base units are not derived. 72 73 **Kind**: instance method of <code>Unit</code> 74 75 | Param | Type | 76 | --- | --- | 77 | base | <code>BASE_UNITS</code> | <code>STRING</code> | <code>undefined</code> | 78 79 <a name="Unit+equalBase"></a> 80 ### unit.equalBase(other) ⇒ <code>boolean</code> 81 Check if this unit has a base or bases equal to another base or bases 82 For derived units, the exponent on each base also must match 83 84 **Kind**: instance method of <code>Unit</code> 85 **Returns**: <code>boolean</code> - true if equal base 86 87 | Param | Type | 88 | --- | --- | 89 | other | <code>Unit</code> | 90 91 <a name="Unit+equals"></a> 92 ### unit.equals(other) ⇒ <code>boolean</code> 93 Check if this unit equals another unit 94 95 **Kind**: instance method of <code>Unit</code> 96 **Returns**: <code>boolean</code> - true if both units are equal 97 98 | Param | Type | 99 | --- | --- | 100 | other | <code>Unit</code> | 101 102 <a name="Unit+multiply"></a> 103 ### unit.multiply(other) ⇒ <code>Unit</code> 104 Multiply this unit with another one 105 106 **Kind**: instance method of <code>Unit</code> 107 **Returns**: <code>Unit</code> - product of this unit and the other unit 108 109 | Param | Type | 110 | --- | --- | 111 | other | <code>Unit</code> | 112 113 <a name="Unit+divide"></a> 114 ### unit.divide(other) ⇒ <code>Unit</code> 115 Divide this unit by another one 116 117 **Kind**: instance method of <code>Unit</code> 118 **Returns**: <code>Unit</code> - result of dividing this unit by the other unit 119 120 | Param | Type | 121 | --- | --- | 122 | other | <code>Unit</code> | 123 124 <a name="Unit+pow"></a> 125 ### unit.pow(p) ⇒ <code>Unit</code> 126 Calculate the power of a unit 127 128 **Kind**: instance method of <code>Unit</code> 129 **Returns**: <code>Unit</code> - The result: this^p 130 131 | Param | Type | 132 | --- | --- | 133 | p | <code>number</code> | <code>Fraction</code> | <code>BigNumber</code> | 134 135 <a name="Unit+abs"></a> 136 ### unit.abs(x) ⇒ <code>Unit</code> 137 Calculate the absolute value of a unit 138 139 **Kind**: instance method of <code>Unit</code> 140 **Returns**: <code>Unit</code> - The result: |x|, absolute value of x 141 142 | Param | Type | 143 | --- | --- | 144 | x | <code>number</code> | <code>Fraction</code> | <code>BigNumber</code> | 145 146 <a name="Unit+to"></a> 147 ### unit.to(valuelessUnit) ⇒ <code>Unit</code> 148 Convert the unit to a specific unit name. 149 150 **Kind**: instance method of <code>Unit</code> 151 **Returns**: <code>Unit</code> - Returns a clone of the unit with a fixed prefix and unit. 152 153 | Param | Type | Description | 154 | --- | --- | --- | 155 | valuelessUnit | <code>string</code> | <code>Unit</code> | A unit without value. Can have prefix, like "cm" | 156 157 <a name="Unit+toNumber"></a> 158 ### unit.toNumber(valuelessUnit) ⇒ <code>number</code> 159 Return the value of the unit when represented with given valueless unit 160 161 **Kind**: instance method of <code>Unit</code> 162 **Returns**: <code>number</code> - Returns the unit value as number. 163 164 | Param | Type | Description | 165 | --- | --- | --- | 166 | valuelessUnit | <code>string</code> | <code>Unit</code> | For example 'cm' or 'inch' | 167 168 <a name="Unit+toNumeric"></a> 169 ### unit.toNumeric(valuelessUnit) ⇒ <code>number</code> | <code>BigNumber</code> | <code>Fraction</code> 170 Return the value of the unit in the original numeric type 171 172 **Kind**: instance method of <code>Unit</code> 173 **Returns**: <code>number</code> | <code>BigNumber</code> | <code>Fraction</code> - Returns the unit value 174 175 | Param | Type | Description | 176 | --- | --- | --- | 177 | valuelessUnit | <code>string</code> | <code>Unit</code> | For example 'cm' or 'inch' | 178 179 <a name="Unit+toString"></a> 180 ### unit.toString() ⇒ <code>string</code> 181 Get a string representation of the unit. 182 183 **Kind**: instance method of <code>Unit</code> 184 <a name="Unit+toJSON"></a> 185 ### unit.toJSON() ⇒ <code>Object</code> 186 Get a JSON representation of the unit 187 188 **Kind**: instance method of <code>Unit</code> 189 **Returns**: <code>Object</code> - Returns a JSON object structured as: 190 `{"mathjs": "Unit", "value": 2, "unit": "cm", "fixPrefix": false}` 191 <a name="Unit+formatUnits"></a> 192 ### unit.formatUnits() ⇒ <code>string</code> 193 Get a string representation of the units of this Unit, without the value. 194 195 **Kind**: instance method of <code>Unit</code> 196 <a name="Unit+format"></a> 197 ### unit.format([options]) ⇒ <code>string</code> 198 Get a string representation of the Unit, with optional formatting options. 199 200 **Kind**: instance method of <code>Unit</code> 201 202 | Param | Type | Description | 203 | --- | --- | --- | 204 | [options] | <code>Object</code> | <code>number</code> | <code>function</code> | Formatting options. See lib/utils/number:format for a description of the available options. | 205 206 <a name="Unit.parse"></a> 207 ### Unit.parse(str) ⇒ <code>Unit</code> 208 Parse a string into a unit. The value of the unit is parsed as number, 209 BigNumber, or Fraction depending on the math.js config setting `number`. 210 211 Throws an exception if the provided string does not contain a valid unit or 212 cannot be parsed. 213 214 **Kind**: static method of <code>Unit</code> 215 **Returns**: <code>Unit</code> - unit 216 217 | Param | Type | Description | 218 | --- | --- | --- | 219 | str | <code>string</code> | A string like "5.2 inch", "4e2 cm/s^2" | 220 221 <a name="Unit.isValuelessUnit"></a> 222 ### Unit.isValuelessUnit(name) ⇒ <code>boolean</code> 223 Test if the given expression is a unit. 224 The unit can have a prefix but cannot have a value. 225 226 **Kind**: static method of <code>Unit</code> 227 **Returns**: <code>boolean</code> - true if the given string is a unit 228 229 | Param | Type | Description | 230 | --- | --- | --- | 231 | name | <code>string</code> | A string to be tested whether it is a value less unit. The unit can have prefix, like "cm" | 232 233 <a name="Unit.fromJSON"></a> 234 ### Unit.fromJSON(json) ⇒ <code>Unit</code> 235 Instantiate a Unit from a JSON object 236 237 **Kind**: static method of <code>Unit</code> 238 239 | Param | Type | Description | 240 | --- | --- | --- | 241 | json | <code>Object</code> | A JSON object structured as: `{"mathjs": "Unit", "value": 2, "unit": "cm", "fixPrefix": false}` | 242