Unity 0.5
Parser for unit strings
Data Structures | Defines | Typedefs | 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  unit_struct
 A component of a unit expression. More...
struct  UnitExpression
 The parsed version of a unit string. More...

Defines

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

Typedefs

typedef struct unit_struct Unit
 A clearer name for struct unit_struct.

Functions

const UnitExpressionunity_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 (UnitDef *)
 Returns the name of this unit, as a URI.
const char * unity_get_unit_name (UnitDef *)
 Returns the name of the unit.
const char * unity_get_unit_type (UnitDef *)
 Returns the type of the unit, as a URI naming the 'kind' of thing this measures.
const char * unity_get_unit_dimension (UnitDef *)
 Returns the dimensions of the unit.
const char * unity_get_unit_description (UnitDef *)
 Returns a description of the unit.
const char * unity_get_unit_latex_form (UnitDef *)
 A LaTeX version of the unit symbol, or there is one defined.

Detailed Description

The Library to support parsing unit strings.


Define Documentation

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


Function Documentation

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.

Parameters:
uethe UnitExpression to be checked
syntaxone of the constants UNITY_SYNTAX_FITS or ..._OGIP or ..._CDS
flagsthe checks to be performed
Returns:
true (non-zero) if the checks pass
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.

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

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

UNITY_CHECK_RECOMMENDED: the unit is a recognised unit, and is additionally not listed in the specification as deprecated.

UNITY_CHECK_CONSTRAINTS: the unit is being used in conformance with any other constraints placed on it. Most typically, it either has no SI prefix, or is allowed to have such a prefix.

The constant UNITY_CHECK_ALL performs all checks.

Parameters:
uthe Unit to be checked
syntaxone of the constants UNITY_SYNTAX_FITS or ..._OGIP or ..._CDS
flagsthe checks to be performed
Returns:
true (non-zero) if the checks pass
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 char* unity_get_syntax_name ( const int  syntax)

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

Parameters:
syntaxone of the constants UNITY_SYNTAX_FITS, ...
Returns:
a string name for the syntax, or NULL if this is an unrecognised syntax
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)

Parameters:
abbreva unit abbreviation, for example "m" for "metre"
syntaxone of the UNITY_SYNTAX_* constants
Returns:
a pointer to a the unit definition which this abbreviation corresponds to
const char* unity_get_unit_description ( 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 ( 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

SymbolNameSI base unit
UDimensionlessUnity
LLengthMetre
MMassKilogramme
TTimeSecond
IElectric currentAmpère
ΘThermodynamic temperatureKelvin
NAmount of substanceMole
JLuminous intensityCandela
const char* unity_get_unit_name ( 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 ( 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 ( 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
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 are one of the constants UNITY_SYNTAX_*

Parameters:
parser_namea name such as "fits"
Returns:
a parser ID, or negative if the name cannot be 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.

See also:
unity_parse_string
Returns:
a static string containing an explanation of a parse error
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()'

See also:
unity_parse_error
Parameters:
unit_stringthe string to be parsed
syntaxthe 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 int  parser_id)

Finds a parser name from an ID.

Parameters:
parser_idone of the constants UNITY_SYNTAX_*
Returns:
a name for the parser, or NULL if the constant isn't recognised
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.

Returns:
a NULL-terminated list of pointers to parser names
int unity_version_number ( )

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 ( )

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,
const char *  format 
)

Write a unit-expression to the given buffer.

The available formats are those returned by the function unity_parser_names.

Parameters:
bufthe buffer to be written to
buflenthe length of the input buffer
uethe unit-expression to be written
formatone of the available formats, as a string
Returns:
buf on success, or NULL on error
 All Data Structures Files Functions Variables Typedefs Defines