1.12 Conventions for Datatypes

The names of all datatypes declared in the QSMM public header files and its source code are in lowercase. The suffixes of those names correspond to C language keywords used for datatype declarations:

typedef

The ‘_t’ suffix. The names of datatypes for function pointers have the ‘_func_t’ suffix.

enum

The ‘_e’ suffix.

struct

The ‘_s’ suffix.

union

The ‘_u’ suffix.

The names of all datatypes declared in the QSMM public header files have the ‘qsmm_’ prefix.

QSMM has conventions for the use of basic C language types and the types size_t, qsmm_sig_t, and qsmm_ssig_t in various situations. The API and the package source code itself¹ follow these conventions. C programs using QSMM may also follow them.

The primary conventions are that if a datatype holds signal identifiers or the numbers of signals, and such values

• – never lie outside the range 0 to 32767, then you can use the type qsmm_sig_t;
• – may be negative but never lie outside the range -32768 to 32767, then you can use the type qsmm_ssig_t;
• – are non-negative and may exceed 32767, then you should use the type qsmm_sig_t;
• – may be negative and may lie outside the range -32768 to 32767, then you should use the type qsmm_ssig_t.

The secondary convention is that for sizes of memory arrays and for non-negative indices of their elements allowed to be greater than 32767, you should use the type size_t.

For other situations, including situations when you choose not to use the type qsmm_sig_t or qsmm_ssig_t according to the first two items of primary conventions stated above, the rules are:

1. For boolean flags, use the type char or int or use specific bits in values of other numeric types.
2. For integer quantities that never lie outside the range 0 to 127, use the type char or int.
3. For integer quantities that may be negative but never lie outside the range -128 to 127, use the type signed char or int.
4. For non-negative integer quantities that may exceed 127 but never exceed 255, use the type unsigned char or int.
5. For integer quantities that may be less than -128 but never lie outside the range -32768 to 32767, use the type int.
6. For integer quantities that may exceed 255 but never lie outside the range -32768 to 32767, use the type int.
7. For non-negative integer quantities that may exceed 32767 but never exceed 65535, use the type unsigned int.
8. For non-negative integer quantities that may exceed 65535 but do not have the restriction that they must be at least 64-bit, use the type long or unsigned long.
9. For integer quantities that may be less than -32768 and may be greater than 32767 but do not have the restriction that they must be at least 64-bit, use the type long.
10. For integer quantities that must be at least 64-bit, use the type long long or unsigned long long.

For example, in QSMM:

• – the type char holds unpacked boolean flags;
• – the type int holds error codes and indices of spur types;
• – the type long holds frequencies and moments of discrete time.

The set of datatypes declared in the API with the ‘_t’ suffix in their names includes the datatypes qsmm_sig_t and qsmm_ssig_t, datatypes for function pointers with the ‘_func_t’ suffix, and datatypes for object handles. See Object Handles, for more information about datatypes for object handles.

Datatypes declared in the API with the ‘_e’ suffix in their names are enumerations. Elements of enumerations are in uppercase.

Datatypes with the suffixes ‘_s’ and ‘_u’ are structures and unions respectively. The order of their fields depends on the datatypes of those fields and is the following:

1. Fields of basic types (except for pointers of void type). The type order is the following: char, signed char, unsigned char, short, unsigned short, int, unsigned int, long, unsigned long, long long, unsigned long long, float, double, long double.
2. Fields of types declared in QSMM with the ‘_t’ suffix in their names.
3. Fields of other types, except for types with names following the specifier ‘enum’, ‘struct’, or ‘union’.
4. Fields of types with names following the specifier ‘enum’. Enumerations declared in QSMM go first.
5. Fields of types with names following the specifier ‘struct’. Structures declared in QSMM go first.
6. Fields of types with names following the specifier ‘union’. Unions declared in QSMM go first.
7. Fields with pointers of void type.

For every type name within each type category listed above, the type order is the following:

1. Non-pointer and non-array types (not applicable to the void type).
2. Arrays (but not pointers to arrays), including arrays of pointers.
3. Pointer types (except for arrays of pointers) with full names beginning with the const qualifier in the order of increasing the number of asterisks.
4. Pointer types (except for arrays of pointers) with full names that do not begin with the const qualifier in the order of increasing the number of asterisks.