The Library to support parsing unit strings. More...

#include <stdio.h>

Include dependency graph for unity.h:

Data Structures
struct	function_definition
	Represents the definition of a known function. More...
struct	FunctionApplication
	A unit corresponding to an application of a function to a unit sequence. More...
struct	SimpleUnit
	A simple unit, corresponding to, for example, ‘MHz’. More...
struct	unit_struct
	A single parsed unit. More...
struct	UnitDef
	Encapsulates per-syntax information about a unit. More...
struct	UnitExpression
	The parsed version of a unit string. More...
Defines
#define	UNITY_CHECK_ALL UNITY_CHECK_RECOGNISED \| UNITY_CHECK_RECOMMENDED \| UNITY_CHECK_CONSTRAINTS
	Flag: perform all checks.
#define	UNITY_CHECK_CONSTRAINTS 4
	Flag: check whether the unit is used in a way which satisfies constraints.
#define	UNITY_CHECK_RECOGNISED 1
	Flag: check whether the unit is recognised.
#define	UNITY_CHECK_RECOMMENDED 2
	Flag: check whether the unit is recommended.
Typedefs
typedef struct unit_struct	Unit
	A clearer name for struct unit_struct.
Enumerations
enum	UnitTypes { simple_unit_type, function_application_type }
	An enumeration indicating the two types of unit possible in unit_struct. More...
enum	UnitySyntax { UNITY_SYNTAX_FITS, UNITY_SYNTAX_OGIP, UNITY_SYNTAX_CDS, UNITY_SYNTAX_VOUNITS, UNITY_SYNTAX_LATEX, UNITY_SYNTAX_DEBUG, UNITY_SYNTAX_NONE }
	Constants for the various syntaxes which the library knows about. More...
Functions
int	unity_check_expression (const UnitExpression *ue, const UnitySyntax syntax, const int flags)
	Indicates whether the units in the expression are being used in a way which satisfies the indicated constraints.
int	unity_check_unit (const Unit *u, const UnitySyntax syntax, const int flags)
	Indicates whether the unit is being used in a way which satisfies the indicated constraints in the gived syntax.
int	unity_equal_expression_p (const UnitExpression , const UnitExpression )
	Tests whether two unit expressions are equal.
int	unity_equal_unit_p (const Unit , const Unit )
	Test whether two units are equal.
const char **	unity_formatter_names (void)
	Return the available formatter names.
void	unity_free_expression (const UnitExpression *u)
	Frees a previously obtained unit-expression.
const FunctionDef *	unity_get_functiondef_from_string (const char *abbrev, UnitySyntax syntax)
	Retrieves a function definition object.
const FunctionDef *	unity_get_functiondef_from_unit (const Unit *)
	Retrieves the definition of a known function-application unit.
const char *	unity_get_syntax_name (UnitySyntax syntax)
	Looks up the name of the syntax with the given index.
const Unit *	unity_get_unit_by_index (const UnitExpression *, int i)
	Returns the i'th unit in the given expression.
const char *	unity_get_unit_description (const UnitDef *)
	Returns a description of the unit.
const char *	unity_get_unit_dimension (const UnitDef *)
	Returns the dimensions of the unit.
const char *	unity_get_unit_latex_form (const UnitDef *)
	A LaTeX version of the unit symbol, if there is one defined.
const char *	unity_get_unit_name (const UnitDef *)
	Returns the name of the unit.
const char *	unity_get_unit_type (const UnitDef *)
	Returns the type of the unit, as a URI naming the 'kind' of thing this measures.
const char *	unity_get_unit_uri (const UnitDef *)
	Returns the name of this unit, as a URI.
const UnitDef *	unity_get_unitdef_from_string (const char *abbrev, UnitySyntax syntax)
	Retrieves a unit definition.
const UnitDef *	unity_get_unitdef_from_unit (const Unit *)
	Retrieves the definition of a known unit.
UnitySyntax	unity_identify_parser (const char *parser_name)
	Obtain the parser ID from a parser name.
const char *	unity_parse_error (void)
	Retrieve the most recent lexing or parsing error.
const UnitExpression *	unity_parse_string (const char *unit_string, const UnitySyntax syntax)
	Parse a string.
const char *	unity_parser_name (const UnitySyntax parser_id)
	Finds a parser name from an ID.
const char **	unity_parser_names (void)
	Return the available parser names.
int	unity_version_number ()
	Return a number which indicates the version and release numbers of the library.
const char *	unity_version_string ()
	Return a version string for the library.
char *	unity_write_formatted (char buf, int buflen, const UnitExpression , UnitySyntax)
	Write a unit-expression to the given buffer.

Detailed Description

The Library to support parsing unit strings.

Define Documentation

#define UNITY_CHECK_ALL UNITY_CHECK_RECOGNISED | UNITY_CHECK_RECOMMENDED | UNITY_CHECK_CONSTRAINTS

Flag: perform all checks.

Do not rely on the numerical value of this or its related constants, which may change between library versions without notice. See unity_check_unit

#define UNITY_CHECK_CONSTRAINTS 4

Flag: check whether the unit is used in a way which satisfies constraints.

See unity_check_unit

#define UNITY_CHECK_RECOGNISED 1

Flag: check whether the unit is recognised.

See unity_check_unit

#define UNITY_CHECK_RECOMMENDED 2

Flag: check whether the unit is recommended.

See unity_check_unit

Enumeration Type Documentation

enum UnitTypes

An enumeration indicating the two types of unit possible in unit_struct.

Enumerator:

simple_unit_type	Simple unit type (eg ‘MHz’)
function_application_type	Function-of unit type (eg `log(MHz)`)

enum UnitySyntax

Constants for the various syntaxes which the library knows about.

Enumerator:

UNITY_SYNTAX_FITS	Indicates the 'FITS' syntax. Parses unit strings according to the prescriptions in the FITS specification, v3.0, section 4.3 (W.D. Pence et al., A&A 524, A42, 2010. doi:10.1051/0004-6361/201015362). See also: unity_identify_parser
UNITY_SYNTAX_OGIP	Indicates the 'OGIP' syntax. The format defined in OGIP memo OGIP/93-001, 1993 (postscript via FTP) See also: unity_identify_parser
UNITY_SYNTAX_CDS	Indicates the 'CDS' syntax. A syntax based on the CDS document Standards for Astronomical Catalogues, Version 2.0, 2000, specifically section 3.2. See `http://cdsweb.u-strasbg.fr/doc/catstd-3.2.htx` See also: unity_identify_parser
UNITY_SYNTAX_VOUNITS	Indicates the 'VOUNITS' syntax. This is intended to be as nearly as possible in the intersection of the various other grammars. It is a strict subset of the FITS and CDS grammars (in the sense that any VOUnit unit string is a valid FITS and CDS string, too), and it is almost a subset of the OGIP grammar, except that it uses the dot for multiplication rather than star. See IVOA VOUnits Proposed Recommendation. See also: unity_identify_parser
UNITY_SYNTAX_LATEX	Indicates the 'LaTeX' syntax. This produces output which is intended to be used with the LaTeX 'siunitx' package. This is for writing only.
UNITY_SYNTAX_DEBUG	The formatter (not parser) for debugging output. This is intended to display the results of a parse unambiguously. The format of the output is not specified, and may change without notice.
UNITY_SYNTAX_NONE	A non-syntax. This is an error return value.

Function Documentation

int unity_check_expression	(	const UnitExpression *	ue,
		const UnitySyntax	syntax,
		const int	flags
	)

Indicates whether the units in the expression are being used in a way which satisfies the indicated constraints.

This checks each unit using unity_check_unit.

Parameters:

ue	the UnitExpression to be checked
syntax	the syntax whose rules are to be checked
flags	the checks to be performed

Returns:: true (non-zero) if the checks pass

int unity_check_unit	(	const Unit *	u,
		const UnitySyntax	syntax,
		const int	flags
	)

Indicates whether the unit is being used in a way which satisfies the indicated constraints in the gived syntax.

Units can be

‘known’, which means the (prose) definition of the syntax recognises this unit and has something to say about it -- all the syntaxes ‘know’ the metre;
‘deprecated’, which means that the definition acknowledges the existence of the unit but advises against it -- for example the ‘erg’ is either unknown or deprecated in this sense (below, we take ‘recommended’ to be a synonym for ‘not deprecated’); or
‘unknown’, which means that the definition knows nothing about this unit -- the ‘furlong’ tends not to be well-used in the scientific literature.

The checks are indicated by the bitwise OR of the following flags:

UNITY_CHECK_RECOGNISED: the unit is a ‘known’ unit, in the sense that it is listed in the specification of the corresponding syntax.

UNITY_CHECK_RECOMMENDED: the unit is a ‘known’ unit, and is additionally not deprecated.

UNITY_CHECK_CONSTRAINTS: the unit is being used in conformance with any other constraints placed on it. Most typically, it is either allowed to have such a prefix, or it has no SI prefix. Possibly surprisingly, an ‘unknown’ unit has no (known) constraints, so it satisfies all of them.

The constant UNITY_CHECK_ALL performs all checks.

The VOUnits syntax includes the notion of a ‘quoted’ unit (see unit_struct). Such a unit is always ‘unrecognised’.

Parameters:

u	the Unit to be checked
syntax	the syntax whose rules are to be checked
flags	the checks to be performed

Returns:: true (non-zero) if the checks pass

int unity_equal_expression_p	(	const UnitExpression *	ue1,
		const UnitExpression *	ue2
	)

Tests whether two unit expressions are equal.

Returns false if either argument is NULL.

Returns:: true (non-zero) if the two expressions are equal

int unity_equal_unit_p	(	const Unit *	u1,
		const Unit *	u2
	)

Test whether two units are equal.

Returns false if either argument is NULL.

Returns:: true (non-zero) if the two units are equal

const char** unity_formatter_names ( void )

Return the available formatter names.

If this is impossible for some reason (which can really only be memory exhaustion, which should never happen), print an error message and return NULL. The returned list is statically allocated, and should not be freed by the caller.

Returns:: a NULL-terminated list of pointers to formatter names

const FunctionDef* unity_get_functiondef_from_string	(	const char *	abbrev,
		const UnitySyntax	syntax
	)

Retrieves a function definition object.

Returns NULL if the abbreviation is not recognised in the indicated syntax (or if the syntax is invalid).

Parameters:

abbrev	a function abbreviation, for example "log" for Common Logarithm
syntax	one of the UNITY_SYNTAX_* constants

Returns:: a pointer to a function definitions string, or NULL if none such exists in this syntax

const FunctionDef* unity_get_functiondef_from_unit ( const Unit * u )

Retrieves the definition of a known function-application unit.

Returns null if the unit is not a function-application unit

Returns:: the functiondef if this is a known unit, or NULL if not

See also:: unity_get_unitdef_from_unit

const char* unity_get_syntax_name ( const UnitySyntax syntax )

Looks up the name of the syntax with the given index.

Thus, this is the inverse of unity_identify_parser.

Parameters:

syntax one of the constants UNITY_SYNTAX_FITS, ...

Returns:: a string name for the syntax, or NULL if this is an unrecognised syntax

const Unit* unity_get_unit_by_index	(	const UnitExpression *	ue,
		const int	idx
	)

Returns the i'th unit in the given expression.

Parameters:

ue	a non-NULL unit expression
idx	the index of the unit to be retrieved from the expression (zero-offset)

Returns:: the unit at the given position, or NULL if i is out of range

const char* unity_get_unit_description ( const UnitDef * d )

Returns a description of the unit.

This may be NULL if there is nothing more to be said beyond the unit name.

const char* unity_get_unit_dimension ( const UnitDef * d )

Returns the dimensions of the unit.

A dimensions string consists of a sequence of capital letter dimensions, and powers, for example "M L2T-2" for the dimensions of "kg m2 s-2".

The known dimensions are

Symbol	Name	SI base unit
U	Dimensionless	Unity
L	Length	Metre
M	Mass	Kilogramme
T	Time	Second
I	Electric current	Amp√®re
Œò	Thermodynamic temperature	Kelvin
N	Amount of substance	Mole
J	Luminous intensity	Candela

const char* unity_get_unit_name ( const UnitDef * d )

Returns the name of the unit.

This is a human-readable name such as 'Metre' or 'Julian year', not the abbreviation 'm'

const char* unity_get_unit_type ( const UnitDef * d )

Returns the type of the unit, as a URI naming the 'kind' of thing this measures.

This indicates 'Length' or 'Capacitance'.

const char* unity_get_unit_uri ( const UnitDef * d )

Returns the name of this unit, as a URI.

These unit definitions follow the QUDT framework, though they are not restricted to the units described there.

This framework also supports the definition of unit kinds and dimensions.

Returns:: a URI as a string

const UnitDef* unity_get_unitdef_from_string	(	const char *	abbrev,
		UnitySyntax	syntax
	)

Retrieves a unit definition.

Returns NULL if the abbreviation is not recognised in the indicated syntax (or if the syntax is invalid)

Parameters:

abbrev	a unit abbreviation, for example "m" for "metre"
syntax	one of the UNITY_SYNTAX_* constants

Returns:: a pointer to a the unit definition which this abbreviation corresponds to

const UnitDef* unity_get_unitdef_from_unit ( const Unit * u )

Retrieves the definition of a known unit.

Returns null if the unit is a function-application unit

Returns:: the unitdef if this is a known unit, or NULL if not

See also:: unity_get_functiondef_from_unit

UnitySyntax unity_identify_parser ( const char * parser_name )

Obtain the parser ID from a parser name.

The recognised parser names are those returned by unity_parser_names, and the returned IDs can be given as arguments to unity_parse_string.

An identifier for the returned parser identifier, as a UnitySyntax.

Parameters:

parser_name a name such as "fits"

Returns:: returns UNITY_SYNTAX_NONE if the name is not recognised

const char* unity_parse_error ( void )

Retrieve the most recent lexing or parsing error.

Immediately after the parser has returned with an error (that is function unity_parse_string has returned NULL) this function can be called to obtain an explanation. However, a non-null response from this function does not imply that the most recent call to `unity_parse_string' failed.

The returned string should not be freed by the caller.

Returns:: a static string containing an explanation of a parse error

const UnitExpression* unity_parse_string	(	const char *	unit_string,
		const UnitySyntax	syntax
	)

Parse a string.

If this returns with an error, then there should be an error message available from unity_parse_error.

Parameters:

unit_string	the string to be parsed
syntax	the syntax to be used to parse the string

Returns:: a parsed representation of the unit expression, or NULL on error

const char* unity_parser_name ( const UnitySyntax stx )

Finds a parser name from an ID.

Parameters:

stx	one of the members of the UnitySyntax enumeration

Returns:: a name for the parser, which will not be NULL

const char** unity_parser_names ( void )

Return the available parser names.

The returned list is statically allocated, and should not be freed by the caller.

Returns:: a NULL-terminated list of pointers to parser names

int unity_version_number ( void )

Return a number which indicates the version and release numbers of the library.

The number is formed by major_version * 1e6 + minor_version * 1e3 + release_number

See also:: unity_version_string

const char* unity_version_string ( void )

Return a version string for the library.

The form of the string is unspecified, but is intended to be printable

See also:: unity_version_number

char* unity_write_formatted	(	char *	buf,
		int	buflen,
		const UnitExpression *	ue,
		UnitySyntax	stx
	)

Write a unit-expression to the given buffer.

The available formats are those returned by the function unity_parser_names.

Parameters:

buf	the buffer to be written to
buflen	the length of the input buffer
ue	the unit-expression to be written
stx	one of the available formats

Returns:: buf on success, or NULL on error

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation