Chapter 8  Penums

Penums allow a fixed collection of source constants to be converted into integers in-memory.

8.1  Syntax

8.1.1  Example

If the physical representation consists of the following strings:S_init, S_lec, S_care, S_for, S_if, and S_tpv, then we can use the specification:

Penum orderStates Pprefix("S_"){
    init,
    lec = 2,
    care,
    my_for Pfrom("for") = 10,
    my_if  Pfrom("if"),
    tpv = 5
};

to describe the data. Because this Penum does not explicitly list a Pads type for the physical representation of the constants, the system assumes the underlying representation is a string. In this case, the labels in the enumeration correspond to the strings in the physical representation. To support physical string representations that are not valid C identifiers, the Pfrom clause allows the user to specify the physical string separately from the enumeration label, e.g., my_for in place of for. The argument to the Pfrom clause can be any character, string, or regular expression. The optional Pprefix clause indicates that all the labels in the enumeration are prefixed by the specified string in the physical representation. Pads assigns integer values to the labels in the enumeration in the same fashion that C does, so the first label is given the value zero, and each successive label is given the next higher value. The user can specify a value for a given label using the equal expression syntax. The compiler does not check that all labels are given distinct values. An artifact of the embedding into C is that all labels must be globally distinct. If two different enumerations contain the same string, one of them must be differentiated using a Pfrom clause.

To support the case where the physical representation of the constant is not a string, Pads allows users to specify in the p_enum_base_ty clause any Pads type with an integer in-memory representation as the base type of the enumeration. For example, the following code

Penum Bool_t Pfrom (Pb_uint8) { False, True };

defines a type Bool_t that is represented on disk as a one-byte, unsigned binary number. A physical value of 0 corresponds to the enumeration label False, while a value of 1 corresponds to True.

8.2  Generated library

We use the orderStates example to illustrate the data structures and functions generated for Penums.

8.2.1  In-memory representation

The following C code is the generated in memory representation for the orderStates Penum. The associated values are computed at Pads compile time and so the associated values must be compile-time constants, as in C.

typedef enum orderStates_e orderStates;
enum orderStates_e {
  S_init=0,
  S_lec=2,
  S_care=3,
  S_my_for=10,
  S_my_if=11,
  S_tpv=5
  };

8.2.2  Mask

The mask for a Penum is simply a base mask:

typedef Pbase_pd orderStates_pd;

8.2.3  Parse descriptor

The parse descriptor for a Penum is simply a base parse descriptor:

typedef Pbase_m orderStates_m;

8.2.4  Operations

The operations for Penums are those described in Chapter 3, with one addition. The orderStates2str function converts the integer representation of a Penum into a C string. These functions appear in Figure 8.1.

---

char const *orderStates2str (orderStates which);

Perror_t orderStates_init (P_t *pads,orderStates *rep);

Perror_t orderStates_pd_init (P_t *pads,orderStates_pd *pd);

Perror_t orderStates_cleanup (P_t *pads,orderStates *rep);

Perror_t orderStates_pd_cleanup (P_t *pads,orderStates_pd *pd);

Perror_t orderStates_copy (P_t *pads,orderStates *rep_dst,
                           orderStates *rep_src);

Perror_t orderStates_pd_copy (P_t *pads,orderStates_pd *pd_dst,
                              orderStates_pd *pd_src);

void orderStates_m_init (P_t *pads,orderStates_m *mask,
                         Pbase_m baseMask);

Perror_t orderStates_read (P_t *pads,orderStates_m *m,
                           orderStates_pd *pd,orderStates *rep);

int orderStates_verify (orderStates *rep);

int orderStates_genPD (P_t *pads, orderStates *rep, orderStates_pd *pd);

Figure 8.1: Prototypes of operations generated for the Penum orderStates.

---

Read Function

The error codes for Penums are:

Accumulator functions

Accumulator functions for Penums are described in Chapter 16.

Histogram functions

Histogram functions for Penums are described in Chapter 17.

Clustering functions

Clustering functions for Penums are described in Chapter 18.