Dtype

When designing the element structure for a new NumPy dtype, consideration should be given to the behaviour with respect to np.empty(), np.zeros(). In other words, are all byte patterns valid values? And is the all-zero byte pattern a valid value?

Example structures

The following structure can hold invalid values for both random bytes and zero bytes:

typedef struct {
    int32_t year;   // -2147483648 to 2147483647
    uint8_t month;  // 1 to 12
    uint8_t day;    // 1 to 30
} dt360;

Alternatively, we could change the ranges to ensure the zero-bytes pattern is valid:

typedef struct {
    int32_t year;   // -2147483648 to 2147483647
    uint8_t month;  // 0 to 11
    uint8_t day;    // 0 to 29
} dt360;

Or, we could use a structure which is always valid:

typedef struct {
    int32_t day;           // -2147483648 to 2147483647 (range approx. +/- 6 megayears)
    uint32_t day_fraction;  // 0 to 4294967295 (resolution approx. 20 usec)
} dt360;

Printing

The __str__() and __repr__() methods on an array use the f->getitem member of the dtype to convert each printed array entry to its corresponding scalar object. If this process raises an exception (e.g. because there is no valid scalar object) it's not possible to print the array.

Obviously, an alternative is to return some kind of "invalid" value - e.g. None.

Pickling

The documentation for the pickle module states we can only pickle classes that are defined at the top level of a module because classes are pickled by named reference. Hence all our scalar time classes must be explicitly declared in the module.

This suggests we should have explicit classes for the common calendars (Time360, Time365, etc) each with a corresponding dtype, and (eventually) a single additional class TimeCustom which handles custom calendars. Each instance of TimeCustom would contain its calendar definition - it would not be part of the class definition. As usual there would be a single dtype corresponding to this class which would also have to include the calendar definition within each array item. Hence this would allow mixed calendars in a single array. The array operations must check the calendar definitions where appropriate and raise errors.

Other notes

• When creating an array from scalar objects there is no need to explicitly supply the corresponding dtype. Numpy will do this for us automatically when all the values have the correct type. For example, if we define a time360 dtype with Time360 as its scalar class, then np.array([Time360(2013, 6, 19, 13, 25)]) will automatically return an array with a dtype of time360.

• NB. This is only true for v1.6, or for v1.7 where the scalar is subclass of np.generic.