# MPDM C API

This reference documents version 1.0.8 of the C API.

## By Category

### Arrays

- mpdm_adel
- mpdm_aget
- mpdm_aset
- mpdm_bseek
- mpdm_bseek_s
- mpdm_collapse
- mpdm_expand
- mpdm_ins
- mpdm_join
- mpdm_keys
- mpdm_pop
- mpdm_push
- mpdm_queue
- mpdm_seek
- mpdm_seek_s
- mpdm_shift
- mpdm_sort
- mpdm_sort_cb
- mpdm_split

### Character Set Conversion

- mpdm_encoding
- mpdm_read
- mpdm_write

### File Management

- mpdm_app_dir
- mpdm_chdir
- mpdm_chmod
- mpdm_chown
- mpdm_close
- mpdm_encoding
- mpdm_glob
- mpdm_home_dir
- mpdm_open
- mpdm_pclose
- mpdm_popen
- mpdm_read
- mpdm_stat
- mpdm_unlink
- mpdm_write

### Hashes

- mpdm_exists
- mpdm_hdel
- mpdm_hget
- mpdm_hget_s
- mpdm_hset
- mpdm_hset_s
- mpdm_hsize
- mpdm_keys

### Localization

- mpdm_gettext
- mpdm_gettext_domain

### Regular Expressions

- mpdm_regex
- mpdm_sregex

### Strings

- mpdm_cmp
- mpdm_gettext
- mpdm_gettext_domain
- mpdm_ival
- mpdm_join
- mpdm_rval
- mpdm_splice
- mpdm_split
- mpdm_sprintf
- mpdm_sscanf
- mpdm_strcat
- mpdm_string
- mpdm_ulc

### Value Creation

- MPDM_2MBS
- MPDM_A
- MPDM_ENS
- MPDM_F
- MPDM_H
- MPDM_I
- MPDM_LS
- MPDM_MBS
- MPDM_NMBS
- MPDM_NS
- MPDM_R
- MPDM_S
- MPDM_X
- mpdm_new

### Value Management

- mpdm_clone
- mpdm_exec
- mpdm_ival
- mpdm_ref
- mpdm_root
- mpdm_rval
- mpdm_size
- mpdm_sweep
- mpdm_unref

## By Source

### mpdm_a.c

- mpdm_adel
- mpdm_aget
- mpdm_aset
- mpdm_bseek
- mpdm_bseek_s
- mpdm_collapse
- mpdm_expand
- mpdm_ins
- mpdm_join
- mpdm_pop
- mpdm_push
- mpdm_queue
- mpdm_seek
- mpdm_seek_s
- mpdm_shift
- mpdm_sort
- mpdm_sort_cb
- mpdm_split

### mpdm_d.c

- mpdm_dump
- mpdm_dump_unref
- mpdm_dumper

### mpdm_f.c

- mpdm_app_dir
- mpdm_chdir
- mpdm_chmod
- mpdm_chown
- mpdm_close
- mpdm_encoding
- mpdm_glob
- mpdm_home_dir
- mpdm_open
- mpdm_pclose
- mpdm_popen
- mpdm_read
- mpdm_stat
- mpdm_unlink
- mpdm_write

### mpdm_h.c

- mpdm_exists
- mpdm_hdel
- mpdm_hget
- mpdm_hget_s
- mpdm_hset
- mpdm_hset_s
- mpdm_hsize
- mpdm_keys

### mpdm_r.c

- mpdm_regex
- mpdm_sregex

### mpdm_s.c

- mpdm_cmp
- mpdm_gettext
- mpdm_gettext_domain
- mpdm_ival
- mpdm_rval
- mpdm_splice
- mpdm_sprintf
- mpdm_sscanf
- mpdm_strcat
- mpdm_string
- mpdm_ulc

### mpdm_v.c

- MPDM_2MBS
- MPDM_A
- MPDM_ENS
- MPDM_F
- MPDM_H
- MPDM_I
- MPDM_IS_ARRAY
- MPDM_IS_EXEC
- MPDM_IS_HASH
- MPDM_IS_STRING
- MPDM_LS
- MPDM_MBS
- MPDM_NMBS
- MPDM_NS
- MPDM_R
- MPDM_S
- MPDM_X
- mpdm_clone
- mpdm_exec
- mpdm_new
- mpdm_ref
- mpdm_root
- mpdm_shutdown
- mpdm_size
- mpdm_startup
- mpdm_sweep
- mpdm_unref

## Alphabetical

- MPDM_2MBS - Creates a multibyte string value from a wide char string.
- MPDM_A - Creates an array value.
- MPDM_ENS - Creates a string value from an external string, with size.
- MPDM_F - Creates a file value.
- MPDM_H - Creates a hash value.
- MPDM_I - Creates an integer value.
- MPDM_IS_ARRAY - Tests if a value is an array.
- MPDM_IS_EXEC - Tests if a value is executable.
- MPDM_IS_HASH - Tests if a value is a hash.
- MPDM_IS_STRING - Tests if a value is a string.
- MPDM_LS - Creates a string value from a literal string.
- MPDM_MBS - Creates a string value from a multibyte string.
- MPDM_NMBS - Creates a string value from a multibyte string, with size.
- MPDM_NS - Creates a string value from a string, with size.
- MPDM_R - Creates a real value.
- MPDM_S - Creates a string value from a string.
- MPDM_X - Creates a new executable value.
- mpdm_adel - Deletes an element of an array.
- mpdm_aget - Gets an element of an array.
- mpdm_app_dir - Returns the applications directory.
- mpdm_aset - Sets the value of an array's element.
- mpdm_bseek - Seeks a value in an array (binary).
- mpdm_bseek_s - Seeks a value in an array (binary, string version).
- mpdm_chdir - Changes the working directory
- mpdm_chmod - Changes a file's permissions.
- mpdm_chown - Changes a file's owner.
- mpdm_clone - Creates a clone of a value.
- mpdm_close - Closes a file descriptor.
- mpdm_cmp - Compares two values.
- mpdm_collapse - Collapses an array.
- mpdm_dump - Dumps a value to stdin.
- mpdm_dump_unref - Dumps all unreferenced values.
- mpdm_dumper - Returns a visual representation of a complex value.
- mpdm_encoding - Sets the current charset encoding for files.
- mpdm_exec - Executes an executable value.
- mpdm_exists - Tests if a key exists.
- mpdm_expand - Expands an array.
- mpdm_gettext - Translates a string to the current language.
- mpdm_gettext_domain - Sets domain and data directory for translations.
- mpdm_glob - Executes a file globbing.
- mpdm_hdel - Deletes a key from a hash.
- mpdm_hget - Gets a value from a hash.
- mpdm_hget_s - Gets the value from a hash (string version).
- mpdm_home_dir - Returns the home user directory.
- mpdm_hset - Sets a value in a hash.
- mpdm_hset_s - Sets a value in a hash (string version).
- mpdm_hsize - Returns the number of pairs of a hash.
- mpdm_ins - Insert an element in an array.
- mpdm_ival - Returns a value's data as an integer.
- mpdm_join - Joins all elements of an array into one.
- mpdm_keys - Returns the keys of a hash.
- mpdm_new - Creates a new value.
- mpdm_open - Opens a file.
- mpdm_pclose - Closes a pipe.
- mpdm_pop - Pops a value from an array.
- mpdm_popen - Opens a pipe.
- mpdm_push - Pushes a value into an array.
- mpdm_queue - Implements a queue in an array.
- mpdm_read - Reads a line from a file descriptor.
- mpdm_ref - Increments the reference count of a value.
- mpdm_regex - Matches a regular expression.
- mpdm_root - Returns the root hash.
- mpdm_rval - Returns a value's data as a real number (double).
- mpdm_seek - Seeks a value in an array (sequential).
- mpdm_seek_s - Seeks a value in an array (sequential, string version).
- mpdm_shift - Extracts the first element of an array.
- mpdm_shutdown - Shuts down MPDM.
- mpdm_size - Returns the size of an element.
- mpdm_sort - Sorts an array.
- mpdm_sort_cb - Sorts an array with a special sorting function.
- mpdm_splice - Creates a new string value from another.
- mpdm_split - Separates a string into an array of pieces.
- mpdm_sprintf - Formats a `sprintf()`-like string.
- mpdm_sregex - Matches and substitutes a regular expression.
- mpdm_sscanf - Extracts data like `sscanf()`.
- mpdm_startup - Initializes MPDM.
- mpdm_stat - Gives status from a file.
- mpdm_strcat - Concatenates two strings.
- mpdm_string - Returns a printable representation of a value.
- mpdm_sweep - Sweeps unreferenced values.
- mpdm_ulc - Converts a string to uppercase or lowecase.
- mpdm_unlink - Deletes a file.
- mpdm_unref - Decrements the reference count of a value.
- mpdm_write - Writes a value into a file.

## MPDM_2MBS

### Name

MPDM_2MBS - Creates a multibyte string value from a wide char string.

### Synopsis

     mpdm_t MPDM_2MBS(wchar_t * wcs);

### Arguments

wcs | the wide char string

### Description

Creates a multibyte string value from the wcs wide char string, converting it by `mpdm_wcstombs()`. Take note that multibyte string values are not properly strings, so they cannot be used for string comparison and such.

### Categories

- Value Creation

## MPDM_A

### Name

MPDM_A - Creates an array value.

### Synopsis

     mpdm_t MPDM_A(int n);

### Arguments

n | Number of elements

### Description

Creates a new array value with n elements.

### Categories

- Value Creation

## MPDM_ENS

### Name

MPDM_ENS - Creates a string value from an external string, with size.

### Synopsis

     mpdm_t MPDM_ENS(wchar_t * wcs, int s);

### Arguments

wcs | the external wide character string
s | the size in chars the string will hold

### Description

Creates a new string value with size s. The wcs string must be a dynamic value (i.e. allocated by `malloc()`) that will be freed on destruction.

### Categories

- Value Creation

## MPDM_F

### Name

MPDM_F - Creates a file value.

### Synopsis

     mpdm_t MPDM_F(FILE * f);

### Arguments

f | the file descriptor

### Description

Creates a new file value.

### Categories

- Value Creation

## MPDM_H

### Name

MPDM_H - Creates a hash value.

### Synopsis

     mpdm_t MPDM_H(int n);

### Arguments

n | Number of buckets in the hash (0: use default)

### Description

Creates a new hash value with n buckets. The number of buckets must be a prime number. If n is 0, an optimal number of buckets will be used.

### Categories

- Value Creation

## MPDM_I

### Name

MPDM_I - Creates an integer value.

### Synopsis

     mpdm_t MPDM_I(int i);

### Arguments

i | the integer

### Description

Creates a new integer value. MPDM integers are strings.

### Categories

- Value Creation

## MPDM_IS_ARRAY

### Name

MPDM_IS_ARRAY - Tests if a value is an array.

### Synopsis

     int MPDM_IS_ARRAY(mpdm_t v);

### Arguments

v | the value

### Description

Returns non-zero if v is an array.

## MPDM_IS_EXEC

### Name

MPDM_IS_EXEC - Tests if a value is executable.

### Synopsis

     int MPDM_IS_EXEC(mpdm_t v);

### Arguments

v | the value

### Description

Returns non-zero if v is executable.

## MPDM_IS_HASH

### Name

MPDM_IS_HASH - Tests if a value is a hash.

### Synopsis

     int MPDM_IS_HASH(mpdm_t v);

### Arguments

v | the value

### Description

Returns non-zero if v is a hash.

## MPDM_IS_STRING

### Name

MPDM_IS_STRING - Tests if a value is a string.

### Synopsis

     int MPDM_IS_STRING(mpdm_t v);

### Arguments

v | the value

### Description

Returns non-zero if v is a string.

## MPDM_LS

### Name

MPDM_LS - Creates a string value from a literal string.

### Synopsis

     mpdm_t MPDM_LS(wchar_t * wcs);

### Arguments

wcs | the wide character string

### Description

Creates a new string value from a literal, wide character string. A pointer to the string will be stored in the value (not a copy).

### Categories

- Value Creation

## MPDM_MBS

### Name

MPDM_MBS - Creates a string value from a multibyte string.

### Synopsis

     mpdm_t MPDM_MBS(char * mbs);

### Arguments

mbs | the multibyte string

### Description

Creates a new string value from a multibyte string, that will be converted to wcs by `mpdm_mbstowcs()`.

### Categories

- Value Creation

## MPDM_NMBS

### Name

MPDM_NMBS - Creates a string value from a multibyte string, with size.

### Synopsis

     mpdm_t MPDM_NMBS(char * mbs, int s);

### Arguments

mbs | the multibyte string
s | the size

### Description

Creates a new string value with the first s characters from the mbs multibyte string, that will be converted to wcs by `mpdm_mbstowcs()`.

### Categories

- Value Creation

## MPDM_NS

### Name

MPDM_NS - Creates a string value from a string, with size.

### Synopsis

     mpdm_t MPDM_NS(wchar_t * wcs, int s);

### Arguments

wcs | the wide character string
s | the size in chars the string will hold

### Description

Creates a new string value with a copy of the first s characters from the wcs string.

### Categories

- Value Creation

## MPDM_R

### Name

MPDM_R - Creates a real value.

### Synopsis

     mpdm_t MPDM_R(double r);

### Arguments

r | the real number

### Description

Creates a new real value. MPDM integers are strings.

### Categories

- Value Creation

## MPDM_S

### Name

MPDM_S - Creates a string value from a string.

### Synopsis

     mpdm_t MPDM_S(wchar_t * wcs);

### Arguments

wcs | the wide character string

### Description

Creates a new string value from a wide character string. The value will store a copy of the string that will be freed on destruction.

### Categories

- Value Creation

## MPDM_X

### Name

MPDM_X - Creates a new executable value.

### Synopsis

     mpdm_t MPDM_X(mpdm_t (* func)(mpdm_t args));

### Arguments

func | the C code function

### Description

Creates a new executable value given a pointer to the func C code function. The function must receive an mpdm_t array value (that will hold their arguments) and return another one.

### Categories

- Value Creation

## mpdm_adel

### Name

mpdm_adel - Deletes an element of an array.

### Synopsis

     mpdm_t mpdm_adel(mpdm_t a, int offset);

### Arguments

a | the array
offset | subscript of the element to be deleted

### Description

Deletes the element at offset of the a array. The array is shrinked by one. If offset is negative, is counted from the end of the array (so a value of -1 means delete the last element of the array).

Returns the deleted element.

### Categories

- Arrays

## mpdm_aget

### Name

mpdm_aget - Gets an element of an array.

### Synopsis

     mpdm_t mpdm_aget(const mpdm_t a, int offset);

### Arguments

a | the array
offset | the subscript of the element

### Description

Returns the element at offset of the array a.

### Categories

- Arrays

## mpdm_app_dir

### Name

mpdm_app_dir - Returns the applications directory.

### Synopsis

     mpdm_t mpdm_app_dir(void);

### Description

Returns a system-dependent directory where the applications store their private data, as components or resources.

### Categories

- File Management

## mpdm_aset

### Name

mpdm_aset - Sets the value of an array's element.

### Synopsis

     mpdm_t mpdm_aset(mpdm_t a, mpdm_t e, int offset);

### Arguments

a | the array
e | the element to be assigned
offset | the subscript of the element

### Description

Sets the element of the array a at offset to be the e value. Returns the previous element.

### Categories

- Arrays

## mpdm_bseek

### Name

mpdm_bseek - Seeks a value in an array (binary).

### Synopsis

     int mpdm_bseek(const mpdm_t a, const mpdm_t k, int step, int *pos);

### Arguments

a | the ordered array
k | the key
step | number of elements to step
pos | the position where the element should be, if it's not found

### Description

Seeks the value k in the a array in increments of step. The array should be sorted to work correctly. A complete search should use a step of 1.

If the element is found, returns the offset of the element as a positive number; otherwise, -1 is returned and the position where the element should be is stored in pos. You can set pos to NULL if you don't mind.

### Categories

- Arrays

## mpdm_bseek_s

### Name

mpdm_bseek_s - Seeks a value in an array (binary, string version).

### Synopsis

     int mpdm_bseek_s(const mpdm_t a, const wchar_t * k, int step, int *pos);

### Arguments

a | the ordered array
k | the key
step | number of elements to step
pos | the position where the element should be, if it's not found

### Description

Seeks the value k in the a array in increments of step. The array should be sorted to work correctly. A complete search should use a step of 1.

If the element is found, returns the offset of the element as a positive number; otherwise, -1 is returned and the position where the element should be is stored in pos. You can set pos to NULL if you don't mind.

### Categories

- Arrays

## mpdm_chdir

### Name

mpdm_chdir - Changes the working directory

### Synopsis

     int mpdm_chdir(const mpdm_t dir);

### Arguments

dir | the new path

### Description

Changes the working directory

### Categories

- File Management

## mpdm_chmod

### Name

mpdm_chmod - Changes a file's permissions.

### Synopsis

     int mpdm_chmod(const mpdm_t filename, mpdm_t perms);

### Arguments

filename | the file name
perms | permissions (element 2 from `mpdm_stat()`)

### Description

Changes the permissions for a file.

### Categories

- File Management

## mpdm_chown

### Name

mpdm_chown - Changes a file's owner.

### Synopsis

     int mpdm_chown(const mpdm_t filename, mpdm_t uid, mpdm_t gid);

### Arguments

filename | the file name
uid | user id (element 4 from `mpdm_stat()`)
gid | group id (element 5 from `mpdm_stat()`)

### Description

Changes the owner and group id's for a file.

### Categories

- File Management

## mpdm_clone

### Name

mpdm_clone - Creates a clone of a value.

### Synopsis

     mpdm_t mpdm_clone(const mpdm_t v);

### Arguments

v | the value

### Description

Creates a clone of a value. If the value is multiple, a new value will be created containing clones of all its elements; otherwise, the same unchanged value is returned.

### Categories

- Value Management

## mpdm_close

### Name

mpdm_close - Closes a file descriptor.

### Synopsis

     mpdm_t mpdm_close(mpdm_t fd);

### Arguments

fd | the value containing the file descriptor

### Description

Closes the file descriptor.

### Categories

- File Management

## mpdm_cmp

### Name

mpdm_cmp - Compares two values.

### Synopsis

     int mpdm_cmp(const mpdm_t v1, const mpdm_t v2);

### Arguments

v1 | the first value
v2 | the second value

### Description

Compares two values. If both has the MPDM_STRING flag set, a comparison using `wcscmp()` is returned; if both are arrays, the size is compared first and, if they have the same number elements, each one is compared; otherwise, a simple pointer comparison is done.

### Categories

- Strings

## mpdm_collapse

### Name

mpdm_collapse - Collapses an array.

### Synopsis

     mpdm_t mpdm_collapse(mpdm_t a, int offset, int num);

### Arguments

a | the array
offset | deletion offset
num | number of elements to collapse

### Description

Collapses an array value, deleting num elements at the specified offset.

### Categories

- Arrays

## mpdm_dump

### Name

mpdm_dump - Dumps a value to stdin.

### Synopsis

     void mpdm_dump(const mpdm_t v);

### Arguments

v | The value

### Description

Dumps a value to stdin. The value can be complex. This function is for debugging purposes only.

## mpdm_dump_unref

### Name

mpdm_dump_unref - Dumps all unreferenced values.

### Synopsis

     void mpdm_dump_unref(void);

### Description

Dumps all unreferenced values.

## mpdm_dumper

### Name

mpdm_dumper - Returns a visual representation of a complex value.

### Synopsis

     mpdm_t mpdm_dumper(const mpdm_t v);

### Arguments

v | The value

### Description

Returns a visual representation of a complex value.

## mpdm_encoding

### Name

mpdm_encoding - Sets the current charset encoding for files.

### Synopsis

     int mpdm_encoding(mpdm_t charset);

### Arguments

charset | the charset name.

### Description

Sets the current charset encoding for files. Future opened files will be assumed to be encoded with charset, which can be any of the supported charset names (utf-8, iso-8859-1, etc.), and converted on each read / write. If charset is NULL, it is reverted to default charset conversion (i.e. the one defined in the locale).

This function stores the charset value into the ENCODING item of the `mpdm_root()` hash.

Returns a negative number if charset is unsupported, or zero if no errors were found.

### Categories

- File Management
- Character Set Conversion

## mpdm_exec

### Name

mpdm_exec - Executes an executable value.

### Synopsis

     mpdm_t mpdm_exec(mpdm_t c, mpdm_t args);

### Arguments

c | the code value
args | the arguments

### Description

Executes an executable value. If c is a scalar value, its data should be a pointer to a directly executable C function with a prototype of mpdm_t func(mpdm_t args); if it's a multiple one, the first value's data should be a pointer to a directly executable C function with a prototype of mpdm_t func(mpdm_t b, mpdm_t args) and the second value will be passed as the b argument. This value is used to store bytecode or so when implementing virtual machines or compilers.

Returns the return value of the code. If c is NULL or not executable, returns NULL.

### Categories

- Value Management

## mpdm_exists

### Name

mpdm_exists - Tests if a key exists.

### Synopsis

     int mpdm_exists(const mpdm_t h, const mpdm_t k);

### Arguments

h | the hash
k | the key

### Description

Returns 1 if k is defined in h, or 0 othersize.

### Categories

- Hashes

## mpdm_expand

### Name

mpdm_expand - Expands an array.

### Synopsis

     mpdm_t mpdm_expand(mpdm_t a, int offset, int num);

### Arguments

a | the array
offset | insertion offset
num | number of elements to insert

### Description

Expands an array value, inserting num elements (initialized to NULL) at the specified offset.

### Categories

- Arrays

## mpdm_gettext

### Name

mpdm_gettext - Translates a string to the current language.

### Synopsis

     mpdm_t mpdm_gettext(const mpdm_t str);

### Arguments

str | the string

### Description

Translates the str string to the current language.

This function can still be used even if there is no real gettext `support()` by manually filling the I18N hash.

If the string is found in the current table, the translation is returned; otherwise, the same str value is returned.

### Categories

- Strings
- Localization

## mpdm_gettext_domain

### Name

mpdm_gettext_domain - Sets domain and data directory for translations.

### Synopsis

     int mpdm_gettext_domain(const mpdm_t dom, const mpdm_t data);

### Arguments

dom | the domain (application name)
data | directory contaning the .mo files

### Description

Sets the domain (application name) and translation data for translating strings that will be returned by `mpdm_gettext()`.data must point to a directory containing the .mo (compiled .po) files.

If there is no gettext support, returns 0, or 1 otherwise.

### Categories

- Strings
- Localization

## mpdm_glob

### Name

mpdm_glob - Executes a file globbing.

### Synopsis

     mpdm_t mpdm_glob(const mpdm_t spec, const mpdm_t base);

### Arguments

spec | Globbing spec
base | Optional base directory

### Description

Executes a file globbing. spec is system-dependent, but usually the * and ? metacharacters work everywhere. base can contain a directory; if that's the case, the output strings will include it. In any case, each returned value will be suitable for a call to `mpdm_open()`.

Returns an array of files that match the globbing (can be an empty array if no file matches), or NULL if globbing is unsupported.

### Categories

- File Management

## mpdm_hdel

### Name

mpdm_hdel - Deletes a key from a hash.

### Synopsis

     mpdm_t mpdm_hdel(mpdm_t h, const mpdm_t k);

### Arguments

h | the hash
k | the key

### Description

Deletes the key k from the hash h. Returns the previous value, or NULL if the key was not defined.

### Categories

- Hashes

## mpdm_hget

### Name

mpdm_hget - Gets a value from a hash.

### Synopsis

     mpdm_t mpdm_hget(const mpdm_t h, const mpdm_t k);

### Arguments

h | the hash
k | the key

### Description

Gets the value from the hash h having k as key, or NULL if the key does not exist.

### Categories

- Hashes

## mpdm_hget_s

### Name

mpdm_hget_s - Gets the value from a hash (string version).

### Synopsis

     mpdm_t mpdm_hget_s(const mpdm_t h, const wchar_t * k);

### Arguments

h | the hash
k | the key

### Description

Gets the value from the hash h having k as key, or NULL if the key does not exist.

### Categories

- Hashes

## mpdm_home_dir

### Name

mpdm_home_dir - Returns the home user directory.

### Synopsis

     mpdm_t mpdm_home_dir(void);

### Description

Returns a system-dependent directory where the user can write documents and create subdirectories.

### Categories

- File Management

## mpdm_hset

### Name

mpdm_hset - Sets a value in a hash.

### Synopsis

     mpdm_t mpdm_hset(mpdm_t h, mpdm_t k, mpdm_t v);

### Arguments

h | the hash
k | the key
v | the value

### Description

Sets the value v to the key k in the hash h. Returns the previous value of the key, or NULL if the key was previously undefined.

### Categories

- Hashes

## mpdm_hset_s

### Name

mpdm_hset_s - Sets a value in a hash (string version).

### Synopsis

     mpdm_t mpdm_hset_s(mpdm_t h, const wchar_t * k, mpdm_t v);

### Arguments

h | the hash
k | the key
v | the value

### Description

Sets the value v to the key k in the hash h. Returns the previous value of the key, or NULL if the key was previously undefined.

### Categories

- Hashes

## mpdm_hsize

### Name

mpdm_hsize - Returns the number of pairs of a hash.

### Synopsis

     int mpdm_hsize(const mpdm_t h);

### Arguments

h | the hash

### Description

Returns the number of key-value pairs of a hash.

### Categories

- Hashes

## mpdm_ins

### Name

mpdm_ins - Insert an element in an array.

### Synopsis

     mpdm_t mpdm_ins(mpdm_t a, mpdm_t e, int offset);

### Arguments

a | the array
e | the element to be inserted
offset | subscript where the element is going to be inserted

### Description

Inserts the e value in the a array at offset. Further elements are pushed up, so the array increases its size by one. Returns the inserted element.

### Categories

- Arrays

## mpdm_ival

### Name

mpdm_ival - Returns a value's data as an integer.

### Synopsis

     int mpdm_ival(mpdm_t v);

### Arguments

v | the value

### Description

Returns a value's data as an integer. If the value is a string, it's converted via sscanf and returned; non-string values have all an ival of 0. The converted integer is cached, so costly string conversions are only done once. Values created with the MPDM_IVAL flag set have its ival cached from the beginning.

### Categories

- Strings
- Value Management

## mpdm_join

### Name

mpdm_join - Joins all elements of an array into one.

### Synopsis

     mpdm_t mpdm_join(const mpdm_t s, const mpdm_t a);

### Arguments

s | joiner string
a | array to be joined

### Description

Joins all elements from a into one string, using s as a glue.

### Categories

- Arrays
- Strings

## mpdm_keys

### Name

mpdm_keys - Returns the keys of a hash.

### Synopsis

     mpdm_t mpdm_keys(const mpdm_t h);

### Arguments

h | the hash

### Description

Returns an array containing all the keys of the h hash.

### Categories

- Hashes
- Arrays

## mpdm_new

### Name

mpdm_new - Creates a new value.

### Synopsis

     mpdm_t mpdm_new(int flags, const void *data, int size);

### Arguments

flags | flags
data | pointer to real data
size | size of data

### Description

Creates a new value. flags is an or-ed set of flags, data is a pointer to the data the value will store and size the size of these data (if value is to be a multiple one, size is a number of elements, or a number of bytes otherwise).

This function is normally not directly used; use any of the type creation macros instead.

### Categories

- Value Creation

## mpdm_open

### Name

mpdm_open - Opens a file.

### Synopsis

     mpdm_t mpdm_open(const mpdm_t filename, const mpdm_t mode);

### Arguments

filename | the file name
mode | an fopen-like mode string

### Description

Opens a file. If filename can be open in the specified mode, an mpdm_t value will be returned containing the file descriptor, or NULL otherwise.

If the file is open for reading, some charset detection methods are used. If any of them is successful, its name is stored in the DETECTED_ENCODING element of the `mpdm_root()` hash. This value is suitable to be copied over ENCODING or TEMP_ENCODING.

If the file is open for writing, the encoding to be used is read from the ENCODING element of `mpdm_root()` and, if not set, from the TEMP_ENCODING one. The latter will always be deleted afterwards.

### Categories

- File Management

## mpdm_pclose

### Name

mpdm_pclose - Closes a pipe.

### Synopsis

     mpdm_t mpdm_pclose(mpdm_t fd);

### Arguments

fd | the value containing the file descriptor

### Description

Closes a pipe.

### Categories

- File Management

## mpdm_pop

### Name

mpdm_pop - Pops a value from an array.

### Synopsis

     mpdm_t mpdm_pop(mpdm_t a);

### Arguments

a | the array

### Description

Pops a value from the array (i.e. deletes from the end and returns it).

### Categories

- Arrays

## mpdm_popen

### Name

mpdm_popen - Opens a pipe.

### Synopsis

     mpdm_t mpdm_popen(const mpdm_t prg, const mpdm_t mode);

### Arguments

prg | the program to pipe
mode | an fopen-like mode string

### Description

Opens a pipe to a program. If prg can be open in the specified mode, an mpdm_t value will be returned containing the file descriptor, or NULL otherwise.

### Categories

- File Management

## mpdm_push

### Name

mpdm_push - Pushes a value into an array.

### Synopsis

     mpdm_t mpdm_push(mpdm_t a, mpdm_t e);

### Arguments

a | the array
e | the value

### Description

Pushes a value into an array (i.e. inserts at the end).

### Categories

- Arrays

## mpdm_queue

### Name

mpdm_queue - Implements a queue in an array.

### Synopsis

     mpdm_t mpdm_queue(mpdm_t a, mpdm_t e, int size);

### Arguments

a | the array
e | the element to be pushed
size | maximum size of array

### Description

Pushes the e element into the a array. If the array already has size elements, the first (oldest) element is deleted from the queue and returned.

Returns the deleted element, or NULL if the array doesn't have size elements yet.

### Categories

- Arrays

## mpdm_read

### Name

mpdm_read - Reads a line from a file descriptor.

### Synopsis

     mpdm_t mpdm_read(const mpdm_t fd);

### Arguments

fd | the value containing the file descriptor

### Description

Reads a line from fd. Returns the line, or NULL on EOF.

### Categories

- File Management
- Character Set Conversion

## mpdm_ref

### Name

mpdm_ref - Increments the reference count of a value.

### Synopsis

     mpdm_t mpdm_ref(mpdm_t v);

### Arguments

v | the value

### Description

Increments the reference count of a value.

### Categories

- Value Management

## mpdm_regex

### Name

mpdm_regex - Matches a regular expression.

### Synopsis

     mpdm_t mpdm_regex(mpdm_t r, const mpdm_t v, int offset);

### Arguments

r | the regular expression
v | the value to be matched
offset | offset from the start of v->data

### Description

Matches a regular expression against a value. Valid flags are 'i', for case-insensitive matching, 'm', to treat the string as a multiline string (i.e., one containing newline characters), so that ^ and $ match the boundaries of each line instead of the whole string, 'l', to return the last matching instead of the first one, or 'g', to match globally; in that last case, an array containing all matches is returned instead of a string scalar.

If r is a string, an ordinary regular expression matching is tried over the v string. If the matching is possible, the match result is returned, or NULL otherwise.

If r is an array (of strings), each element is tried sequentially as an individual regular expression over the v string, each one using the offset returned by the previous match. All regular expressions must match to be successful. If this is the case, an array (with the same number of arguments) is returned containing the matched strings, or NULL otherwise.

If r is NULL, the result of the previous regex matching is returned as a two element array. The first element will contain the character offset of the matching and the second the number of characters matched. If the previous regex was unsuccessful, NULL is returned.

### Categories

- Regular Expressions

## mpdm_root

### Name

mpdm_root - Returns the root hash.

### Synopsis

     mpdm_t mpdm_root(void);

### Description

Returns the root hash. This hash is stored internally and can be used as a kind of global symbol table.

### Categories

- Value Management

## mpdm_rval

### Name

mpdm_rval - Returns a value's data as a real number (double).

### Synopsis

     double mpdm_rval(mpdm_t v);

### Arguments

v | the value

### Description

Returns a value's data as a real number (double float). If the value is a string, it's converted via sscanf and returned; non-string values have all an rval of 0. The converted double is cached, so costly string conversions are only done once. Values created with the MPDM_RVAL flag set have its rval cached from the beginning.

### Categories

- Strings
- Value Management

## mpdm_seek

### Name

mpdm_seek - Seeks a value in an array (sequential).

### Synopsis

     int mpdm_seek(const mpdm_t a, const mpdm_t k, int step);

### Arguments

a | the array
k | the key
step | number of elements to step

### Description

Seeks sequentially the value k in the a array in increments of step. A complete search should use a step of 1. Returns the offset of the element if found, or -1 otherwise.

### Categories

- Arrays

## mpdm_seek_s

### Name

mpdm_seek_s - Seeks a value in an array (sequential, string version).

### Synopsis

     int mpdm_seek_s(const mpdm_t a, const wchar_t * k, int step);

### Arguments

a | the array
k | the key
step | number of elements to step

### Description

Seeks sequentially the value k in the a array in increments of step. A complete search should use a step of 1. Returns the offset of the element if found, or -1 otherwise.

### Categories

- Arrays

## mpdm_shift

### Name

mpdm_shift - Extracts the first element of an array.

### Synopsis

     mpdm_t mpdm_shift(mpdm_t a);

### Arguments

a | the array

### Description

Extracts the first element of the array. The array is shrinked by one.

Returns the deleted element.

### Categories

- Arrays

## mpdm_shutdown

### Name

mpdm_shutdown - Shuts down MPDM.

### Synopsis

     void mpdm_shutdown(void);

### Description

Shuts down MPDM. No MPDM functions should be used from now on.

## mpdm_size

### Name

mpdm_size - Returns the size of an element.

### Synopsis

     int mpdm_size(const mpdm_t v);

### Arguments

v | the element

### Description

Returns the size of an element.

### Categories

- Value Management

## mpdm_sort

### Name

mpdm_sort - Sorts an array.

### Synopsis

     mpdm_t mpdm_sort(const mpdm_t a, int step);

### Arguments

a | the array
step | increment step

### Description

Sorts the array. step is the number of elements to group together.

Returns the sorted array (the original one is left untouched).

### Categories

- Arrays

## mpdm_sort_cb

### Name

mpdm_sort_cb - Sorts an array with a special sorting function.

### Synopsis

     mpdm_t mpdm_sort_cb(const mpdm_t a, int step, mpdm_t cb);

### Arguments

a | the array
step | increment step
asort_cb | sorting function

### Description

Sorts the array. step is the number of elements to group together. For each pair of elements being sorted, the executable mpdm_t value sort_cb is called with an array containing the two elements as argument. It must return a signed numerical mpdm_t value indicating the sorting order.

Returns the sorted array (the original one is left untouched).

### Categories

- Arrays

## mpdm_splice

### Name

mpdm_splice - Creates a new string value from another.

### Synopsis

     mpdm_t mpdm_splice(const mpdm_t v, const mpdm_t i, int offset, int del);

### Arguments

v | the original value
i | the value to be inserted
offset | offset where the substring is to be inserted
del | number of characters to delete

### Description

Creates a new string value from v, deleting del chars at offset and substituting them by i. If del is 0, no deletion is done. both offset and del can be negative; if this is the case, it's assumed as counting from the end of v. If v is NULL, i will become the new string, and both offset and del will be ignored. If v is not NULL and i is, no insertion process is done (only deletion, if applicable).

Returns a two element array, with the new string in the first element and the deleted string in the second (with a NULL value if del is 0).

### Categories

- Strings

## mpdm_split

### Name

mpdm_split - Separates a string into an array of pieces.

### Synopsis

     mpdm_t mpdm_split(const mpdm_t s, const mpdm_t v);

### Arguments

s | the separator
v | the value to be separated

### Description

Separates the v string value into an array of pieces, using s as a separator.

If the separator is NULL, the string is splitted by characters.

If the string does not contain the separator, an array holding the complete string is returned.

### Categories

- Arrays
- Strings

## mpdm_sprintf

### Name

mpdm_sprintf - Formats a `sprintf()`-like string.

### Synopsis

     mpdm_t mpdm_sprintf(const mpdm_t fmt, const mpdm_t args);

### Arguments

fmt | the string format
args | an array of values

### Description

Formats a string using the `sprintf()` format taking the values from args.

### Categories

- Strings

## mpdm_sregex

### Name

mpdm_sregex - Matches and substitutes a regular expression.

### Synopsis

     mpdm_t mpdm_sregex(mpdm_t r, const mpdm_t v, const mpdm_t s, int offset);

### Arguments

r | the regular expression
v | the value to be matched
s | the substitution string, hash or code
offset | offset from the start of v->data

### Description

Matches a regular expression against a value, and substitutes the found substring with s. Valid flags are 'i', for case-insensitive matching, and 'g', for global replacements (all ocurrences in v will be replaced, instead of just the first found one).

If s is executable, it's executed with the matched part as the only argument and its return value is used as the substitution string.

If s is a hash, the matched string is used as a key to it and its value used as the substitution. If this value itself is executable, it's executed with the matched string as its only argument and its return value used as the substitution.

If r is NULL, returns the number of substitutions made in the previous call to `mpdm_sregex()` (can be zero if none was done).

The global variables mpdm_regex_offset and mpdm_regex_size are set to the offset of the matched string and the size of the replaced string, respectively.

Returns the modified string, or the original one if no substitutions were done.

### Categories

- Regular Expressions

## mpdm_sscanf

### Name

mpdm_sscanf - Extracts data like `sscanf()`.

### Synopsis

     mpdm_t mpdm_sscanf(const mpdm_t fmt, const mpdm_t str, int offset);

### Arguments

fmt | the string format
str | the string to be parsed
offset | the character offset to start scanning

### Description

Extracts data from a string using a special format pattern, very much like the `scanf()` series of functions in the C library. Apart from the standard percent-sign-commands (s, u, d, i, f, x, n, [, with optional size and * to ignore), it implements S, to match a string of characters upto what follows in the format string. Also, the [ set of characters can include other % formats.

Returns an array with the extracted values. If n is used, the position in the scanned string is returned as the value.

### Categories

- Strings

## mpdm_startup

### Name

mpdm_startup - Initializes MPDM.

### Synopsis

     int mpdm_startup(void);

### Description

Initializes the Minimum Profit Data Manager. Returns 0 if everything went OK.

## mpdm_stat

### Name

mpdm_stat - Gives status from a file.

### Synopsis

     mpdm_t mpdm_stat(const mpdm_t filename);

### Arguments

filename | file name to get the status from

### Description

Returns a 14 element array of the status (permissions, onwer, etc.) from the desired filename, or NULL if the file cannot be accessed. (man 2 stat).

The values are: 0, device number of filesystem; 1, inode number; 2, file mode; 3, number of hard links to the file; 4, uid; 5, gid; 6, device identifier; 7, total size of file in bytes; 8, atime; 9, mtime; 10, ctime; 11, preferred block size for system I/O; 12, number of blocks allocated and 13, canonicalized file name. Not all elements have necesarily meaningful values, as most are system-dependent.

### Categories

- File Management

## mpdm_strcat

### Name

mpdm_strcat - Concatenates two strings.

### Synopsis

     mpdm_t mpdm_strcat(const mpdm_t s1, const mpdm_t s2);

### Arguments

s1 | the first string
s2 | the second string

### Description

Returns a new string formed by the concatenation of s1 and s2.

### Categories

- Strings

## mpdm_string

### Name

mpdm_string - Returns a printable representation of a value.

### Synopsis

     wchar_t *mpdm_string(const mpdm_t v);

### Arguments

v | the value

### Description

Returns a printable representation of a value. For strings, it's the value data itself; for any other type, a conversion to string is returned instead. This value should be used immediately, as it can be a pointer to a static buffer.

### Categories

- Strings

## mpdm_sweep

### Name

mpdm_sweep - Sweeps unreferenced values.

### Synopsis

     void mpdm_sweep(int count);

### Arguments

count | number of values to be swept

### Description

Destroys values with a reference count of 0. count is the number of values to be checked for deletion; special values of count are -1, that forces a check of all currently known values (can be time-consuming) and 0, which tells `mpdm_sweep()` to check a small group of them on each call.

### Categories

- Value Management

## mpdm_ulc

### Name

mpdm_ulc - Converts a string to uppercase or lowecase.

### Synopsis

     mpdm_t mpdm_ulc(const mpdm_t s, int u);

### Arguments

s | the string
u | convert to uppercase (1) or to lowercase (0).

### Description

Converts s to uppercase (for u == 1) or to lowercase (u == 0).

### Categories

- Strings

## mpdm_unlink

### Name

mpdm_unlink - Deletes a file.

### Synopsis

     int mpdm_unlink(const mpdm_t filename);

### Arguments

filename | file name to be deleted

### Description

Deletes a file.

### Categories

- File Management

## mpdm_unref

### Name

mpdm_unref - Decrements the reference count of a value.

### Synopsis

     mpdm_t mpdm_unref(mpdm_t v);

### Arguments

v | the value

### Description

Decrements the reference count of a value.

### Categories

- Value Management

## mpdm_write

### Name

mpdm_write - Writes a value into a file.

### Synopsis

     int mpdm_write(const mpdm_t fd, const mpdm_t v);

### Arguments

fd | the file descriptor.
v | the value to be written.

### Description

Writes the v string value into fd, using the current encoding.

### Categories

- File Management
- Character Set Conversion

Angel Ortega - angel@triptico.com - Built with mp_doccer 1.2.2