Unity: unity.h File Reference

Unity 1.0 Parser for unit strings

- Main Page
- Data Structures
- Files

- File List
- Globals

Data Structures | Defines | Typedefs | Enumerations | Functions
unity.h File Reference

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

`#include <stdio.h>`
Include dependency graph for unity.h:

Go to the source code of this file.

## 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

1. ‘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;
2. ‘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
3. ‘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

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines