triptico.com

MPDM overview

MPDM (Minimum Profit Data Manager) is a lightweight library that provides C programs with a rich set of useful data types as scalars, dynamic arrays or hashes, similar to those of the Perl language. Also, it contains a rudimentary garbage collector that alleviates the need to keep track of data no longer useful, as well as help for operating system abstraction and portability, regular expressions, string manipulation, character set conversions, localization and file I/O access.

Values

The basic unit of information under MPDM is the value. It's declared inside the C code as a variable of mpdm_t type:

 /* a MPDM value, initialized as NULL */
 mpdm_t v = NULL;

MPDM values can be single or multiple ones. A single value is a scalar and contains meaning by itself; a multiple one contains one or more MPDM values, that can be accessed by different means, depending on its nature.

A value also has an internal reference count; when it's 0, the value is suitable for being swept by the garbage collector. The reference count of a value can be manipulated by calling mpdm_ref() and mpdm_unref() on it. Also, whenever a value is stored inside a multiple one, its reference count is automatically incremented, and decremented when deleted from it. All newly created values are unreferenced.

Scalars

The simplest scalar is a string one:

 /* a scalar string MPDM value */
 mpdm_t v = MPDM_S(L"I'm a happy scalar");

The MPDM_S() macro creates an MPDM value from a dinamically allocated copy of a wide-character string. MPDM works internally with wide-character strings; though this can seem awkward, it's the only way to do character set manipulation (i.e. Unicode) correctly.

A more memory-efficient way of creating a string scalar from a literal string is using the MPDM_LS() macro:

 /* another scalar string, this time storing the string directly */
 mpdm_t w = MPDM_LS(L"I'm also a happy scalar");

Both are semantically the same. Many string manipulation functions, however, return values of the first kind.

Creating values from integers and real numbers (doubles) is also easy:

 /* a scalar value, from an integer */
 mpdm_t i = MPDM_I(16384);
 
 /* another scalar, this time from a double */
 mpdm_t pi = MPDM_R(3.1416);

Again, those new values are stored as dinamically allocated wide-char strings, so they are no different from the first one.

Backwards, an MPDM value can always be converted to integer or real:

 /* converts i to integer */
 int n = mpdm_ival(i);
 
 /* converts pi to real */
 double d = mpdm_rval(pi);

Sometimes you don't have a wide-char string available, but a multibyte one. The handy macro MPDM_MBS() does the conversion for you:

 /* create a value with the value of the HOME environment variable
    (no error condition checked) */
 mpdm_t home = MPDM_MBS(getenv("HOME"));

Take note that MPDM_MBS() relies on a correctly working locale subsystem for character set conversion.

There are many more value creation macros for scalars; see the reference documentation for further details.

Value sizes

An MPDM value always have a size. For scalar values, the size is usually the length of its string representation. It's returned by the mpdm_size() function:

 /* prints 6 */
 printf("%d\n", mpdm_size(pi));

The mpdm_size() function, when applied to arrays, returns the number of elements instead:

 /* A new array */
 mpdm_t ary = MPDM_A(0);
 
 /* two new values pushed */
 mpdm_push(ary, MPDM_LS(L"Hey!");
 mpdm_push(ary, MPDM_LS(L"You!");
 
 /* prints 2 */
 printf("%d\n", mpdm_size(ary));

On hashes it's a little different, as mpdm_size() returns the number of buckets in it, which is probably not very useful; this is a side effect of hashes being implemented as arrays. To avoid this, the mpdm_hsize() special function returns the number of key/value pairs stored in the hash:

 /* a new hash */
 mpdm_t en2es = MPDM_H(0);
 
 /* three new pairs added */
 mpdm_hset(en2es, MPDM_LS(L"monday"), MPDM_LS(L"lunes"));
 mpdm_hset(en2es, MPDM_LS(L"tuesday"), MPDM_LS(L"martes"));
 mpdm_hset(en2es, MPDM_LS(L"friday"), MPDM_LS(L"viernes"));
 
 /* prints 3 */
 printf("%d\n", mpdm_hsize(en2es));
 
 /* prints the number of buckets (probably 31) */
 printf("%d\n", mpdm_size(en2es));

Arrays

To be written.

Hashes

To be written.

The 'garbage collector'

To be written.

Executable values

To be written.

Regular expressions

To be written.

File I/O

To be written.

Charset conversions

To be written.

Localization

To be written.

Environment variables

To be written.

MPDM_NULL_HASH

To be written.