units

units

units offers shared code for handling standard units of measurement. It takes inspiration from Golang's time library and applies similar ideas to other units of measure. This is achieved through a common declaration called a Unit, which organizes measurements in increasing order, often derived from a base unit. A Unit also facilitates parsing and formatting of measurements to improve computer use and human readability (respectively). To get a better understanding of its functioning, you can explore the provided packages for more specific information.

import "go.pitz.tech/units"

Usage

Customize existing units

One nice thing about the way this library works is that it gives you the ability to define your own custom units used to format and parse text. Using the existing length package, we can reduce the number of units down to the measures we care about. Now, you can use this new unit to parse string text or format lengths as strings. For example, with ballistics we seldom care about millimeters and decameters and instead focus on kilometer (range to target), meter (size of target), and centimeter (drop of projectile). Similarly in the US, we think of this as yards (range to target), feet (size of target), and inches (drop of projectile).

package main

import "go.pitz.tech/units/length"
import "go.pitz.tech/units"

var (
	simplified = units.Unit[length.Length]{
		{length.Centimeter, []string{"cm"}},
		{length.Meter, []string{"m"}},
		{length.Kilometer, []string{"km"}},
	}
)

Declare your own

If customizing an existing unit isn't enough for you, then you can always look at declaring your own unit. For example, the other day I learned that in x-ray astronomy, flux density can be measured using crabs or millicrabs. To illustrate how we might define this using the units package, we can consider the following snippet.

package astronomy

import "go.pitz.tech/units"

type FluxDensity int64

const (
	MilliCrab FluxDensity = 1
	Crab FluxDensity = 1000 * MilliCrab
)

var (
	Standard = units.Unit[Flux]{
		{MilliCrab, []string{"??"}},
		{Crab, []string{"??"}},
	}
)

Now, I'm no astronomer so it's entirely possible that these representative values are completely incorrect. However, these values do illustrate how we can apply this library to other areas.

License

Copyright (c) 2023 Mya Pitzeruse

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
OR OTHER DEALINGS IN THE SOFTWARE.