Unity
0.8
Parser for unit strings
|
The Library to support parsing unit strings. More...
#include <stdio.h>
Go to the source code of this file.
Data Structures | |
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 | UnitExpression |
The parsed version of a unit string. More... | |
Macros | |
#define | UNITY_SYNTAX_FITS 0 |
Indicates the 'FITS' syntax. | |
#define | UNITY_SYNTAX_OGIP 1 |
Indicates the 'OGIP' syntax. | |
#define | UNITY_SYNTAX_CDS 2 |
Indicates the 'CDS' syntax. | |
#define | UNITY_SYNTAX_VOUNITS 3 |
Indicates the 'VOUNITS' syntax. | |
#define | UNITY_CHECK_RECOGNISED 1 |
Flag: check whether the unit is recognised. | |
#define | UNITY_CHECK_RECOMMENDED 2 |
Flag: check whether the unit is recommended. | |
#define | UNITY_CHECK_CONSTRAINTS 4 |
Flag: check whether the unit is used in a way which satisfies constraints. | |
#define | UNITY_CHECK_ALL UNITY_CHECK_RECOGNISED | UNITY_CHECK_RECOMMENDED | UNITY_CHECK_CONSTRAINTS |
Flag: perform all checks. | |
Typedefs | |
typedef struct unit_struct | Unit |
A clearer name for struct unit_struct. | |
typedef struct unit_definition | UnitDef |
Encapsulates per-syntax information about a unit. | |
Enumerations | |
enum | UnitTypes { simple_unit_type, function_application_type } |
An enumeration indicating the two types of unit possible in unit_struct. More... | |
Functions | |
const UnitExpression * | unity_parse_string (const char *unit_string, const int syntax) |
Parse a string. | |
const char * | unity_parse_error (void) |
Retrieve the most recent lexing or parsing error. | |
const char ** | unity_parser_names (void) |
Return the available parser names. | |
int | unity_identify_parser (const char *parser_name) |
Obtain the parser ID from a parser name. | |
const char * | unity_parser_name (const int parser_id) |
Finds a parser name from an ID. | |
void | unity_free_expression (const UnitExpression *u) |
Frees a previously obtained unit-expression. | |
const char * | unity_version_string () |
Return a version string for the library. | |
int | unity_version_number () |
Return a number which indicates the version and release numbers of the library. | |
int | unity_check_unit (const Unit *u, const int syntax, const int flags) |
Indicates whether the unit is being used in a way which satisfies the indicated constraints. | |
int | unity_check_expression (const UnitExpression *ue, const int syntax, const int flags) |
Indicates whether the units in the expression are being used in a way which satisfies the indicated constraints. | |
char * | unity_write_formatted (char *buf, int buflen, const UnitExpression *, const char *) |
Write a unit-expression to the given buffer. | |
const char ** | unity_formatter_names (void) |
Return the available formatter names. | |
const UnitDef * | unity_get_unit (const char *abbrev, int syntax) |
Retrieves a unit definition. | |
const char * | unity_get_syntax_name (int syntax) |
Looks up the name of the syntax with the given index. | |
const char * | unity_get_unit_uri (const UnitDef *) |
Returns the name of this unit, as a URI. | |
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_dimension (const UnitDef *) |
Returns the dimensions of the unit. | |
const char * | unity_get_unit_description (const UnitDef *) |
Returns a description of the unit. | |
const char * | unity_get_unit_latex_form (const UnitDef *) |
A LaTeX version of the unit symbol, if there is one defined. | |
The Library to support parsing unit strings.
#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
#define UNITY_SYNTAX_CDS 2 |
Indicates the 'CDS' syntax.
Do not rely on the numerical value of this constant, which may change between library versions without notice.
#define UNITY_SYNTAX_FITS 0 |
Indicates the 'FITS' syntax.
Do not rely on the numerical value of this constant, which may change between library versions without notice.
#define UNITY_SYNTAX_OGIP 1 |
Indicates the 'OGIP' syntax.
Do not rely on the numerical value of this constant, which may change between library versions without notice.
#define UNITY_SYNTAX_VOUNITS 3 |
Indicates the 'VOUNITS' syntax.
Do not rely on the numerical value of this constant, which may change between library versions without notice.
typedef struct unit_definition UnitDef |
Encapsulates per-syntax information about a unit.
This should be regarded as an opaque type, and instances of it, and its contents, should be obtained using the various unity_get_unit...
functions.
enum UnitTypes |
An enumeration indicating the two types of unit possible in unit_struct.
int unity_check_expression | ( | const UnitExpression * | ue, |
const int | 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.
ue | the UnitExpression to be checked |
syntax | one of the constants returned by unity_identify_parser or ..._OGIP or ..._CDS |
flags | the checks to be performed |
int unity_check_unit | ( | const Unit * | u, |
int | syntax, | ||
const int | flags | ||
) |
Indicates whether the unit is being used in a way which satisfies the indicated constraints.
Units can be
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.
u | the Unit to be checked |
syntax | one of the constants returned by unity_identify_parser |
flags | the checks to be performed |
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.
const char* unity_get_syntax_name | ( | const int | syntax | ) |
Looks up the name of the syntax with the given index.
Thus, this is the inverse of unity_identify_parser.
syntax | one of the constants UNITY_SYNTAX_FITS, ... |
const UnitDef* unity_get_unit | ( | const char * | abbrev, |
const int | syntax | ||
) |
Retrieves a unit definition.
Returns NULL if the abbreviation is not recognised in the indicated syntax (or if the syntax is invalid)
abbrev | a unit abbreviation, for example "m" for "metre" |
syntax | one of the UNITY_SYNTAX_* constants |
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.
int 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.
The numerical value of the returned parser identifier is one of the constants UNITY_SYNTAX_...
. It's value is not guaranteed, and may change between library releases.
parser_name | a name such as "fits" |
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.
const UnitExpression* unity_parse_string | ( | const char * | unit_string, |
const int | syntax | ||
) |
Parse a string.
If this returns with an error, then there should be an error message available from unity_parse_error.
The syntax is one of the codes obtained from unity_identify_parser.
unit_string | the string to be parsed |
syntax | the syntax to be used to parse the string |
const char* unity_parser_name | ( | const int | parser_id | ) |
Finds a parser name from an ID.
parser_id | one of the constants UNITY_SYNTAX_* |
const char** unity_parser_names | ( | void | ) |
Return the available parser 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.
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
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
char* unity_write_formatted | ( | char * | buf, |
int | buflen, | ||
const UnitExpression * | ue, | ||
const char * | format | ||
) |
Write a unit-expression to the given buffer.
The available formats are those returned by the function unity_parser_names.
buf | the buffer to be written to |
buflen | the length of the input buffer |
ue | the unit-expression to be written |
format | one of the available formats, as a string |