Ángel Ortega III

Un naufragio personal

MPDM C API

This reference documents version 2.1.1 of the C API.

By Category

Arrays

Character Set Conversion

File Management

Hashes

Localization

Regular Expressions

Strings

Threading

Value Creation

Value Management

By Source

mpdm_a.c

mpdm_d.c

mpdm_f.c

mpdm_h.c

mpdm_r.c

mpdm_s.c

mpdm_t.c

mpdm_v.c

Alphabetical

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

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

MPDM_AA

Name

MPDM_AA - Creates an array value (using alloca()).

Synopsis

 mpdm_t MPDM_AA(int n); 

Arguments

n
Number of elements

Description

Creates a new array value with n elements on the local function's stack. These values are destroyed when the function exits. They should only be used for temporary issues.

Categories

MPDM_AS

Name

MPDM_AS - Creates a string value from a literal string using alloca().

Synopsis

 mpdm_t MPDM_AS(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). These values are destroyed when the function exits. They should only be used for temporary issues and cannot be assigned to arrays nor hashes.

Categories

MPDM_C

Name

MPDM_C - Creates a new value with a copy of a buffer.

Synopsis

 mpdm_t MPDM_C(int flags, void *ptr, int size); 

Arguments

flags
additional flags
ptr
pointer to data
size
data size

Description

Create a new value with a copy of a buffer. The value will store a copy of ptr and have the additional flags.

Categories

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

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

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

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

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

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

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

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

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

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

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

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).

Always returns NULL (version prior to 1.0.10 used to return the deleted element).

Categories

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

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

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 new element (versions prior to 1.0.10 returned the old element).

Categories

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

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

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

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

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

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

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

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 wcscoll() 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 visual representation comparison is done.

Categories

mpdm_cmp_s

Name

mpdm_cmp_s - Compares two values (string version).

Synopsis

 int mpdm_cmp_s(const mpdm_t v1, const wchar_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 wcscoll() 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 visual representation comparison is done.

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

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_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

mpdm_exec

Name

mpdm_exec - Executes an executable value.

Synopsis

 mpdm_t mpdm_exec(mpdm_t c, mpdm_t args, mpdm_t ctxt);

Arguments

c
the code value
args
the arguments
ctxt
the context

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, mpdm_t ctxt); 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, mpdm_t ctxt) 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. The ctxt is meant to be used as a special context to implement local symbol tables and such. Its meaning is free and can be NULL.

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

Categories

mpdm_exec_thread

Name

mpdm_exec_thread - Runs an executable value in a new thread.

Synopsis

 mpdm_t mpdm_exec_thread(mpdm_t c, mpdm_t args, mpdm_t ctxt);

Arguments

c
the executable value
args
executable arguments
ctxt
the context

Description

Runs the c executable value in a new thread. The code starts executing immediately. The args and ctxt arguments are sent to the executable value as arguments.

Returns a handle for the thread.

Categories

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

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

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

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

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

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 NULL (versions prior to 1.0.10 returned the deleted value).

Categories

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

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

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

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 new value (versions prior to 1.0.10 returned the old value).

Categories

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 new value (versions prior to 1.0.10 returned the old value).

Categories

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

mpdm_init

Name

mpdm_init - Initializes a value.

Synopsis

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

Arguments

v
the value to initialize
flags
flags
data
pointer to real data
size
size of data

Description

Initializes a value.

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

Categories

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

mpdm_is_null

Name

mpdm_is_null - Returns 1 if a value is NULL.

Synopsis

 int mpdm_is_null(mpdm_t v);

Arguments

v
the value

Description

Returns 1 if a value is NULL. The reference count is touched.

mpdm_iterator

Name

mpdm_iterator - Iterates through the content of a hash or array.

Synopsis

 int mpdm_iterator(mpdm_t h, int *context, mpdm_t * v1, mpdm_t * v2);

Arguments

h
the hash (or array)
context
A pointer to an opaque context
v1
a pointer to a value
v2
another pointer to a value

Description

Iterates through the content of a hash, filling the v1 and v2 pointers with key-value pairs on each call until the hash is exhausted. If h is an array, only the v1 pointer is filled. v1 and v2 pointers can be NULL.

The context pointer to integer is opaque and should be initialized to zero on the first call.

Returns 0 if no more data is left in h.

Categories

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

mpdm_join

Name

mpdm_join - Joins an array.

Synopsis

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

Arguments

a
array
s
joiner string or second array

Description

If s is a string or NULL, returns a new string with all elements in a joined using s. If s is an array, it returns a new one containing all elements of a followed by all elements of s.

Categories

mpdm_join_s

Name

mpdm_join_s - Joins all elements of an array into a string (string version).

Synopsis

 mpdm_t mpdm_join_s(const mpdm_t a, const wchar_t *s);

Arguments

a
array to be joined
s
joiner string

Description

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

Categories

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

mpdm_mutex_lock

Name

mpdm_mutex_lock - Locks a mutex.

Synopsis

 void mpdm_mutex_lock(mpdm_t mutex);

Arguments

mutex
the mutex to be locked

Description

Locks a mutex. If the mutex is not already locked, it waits until it is.

Categories

mpdm_mutex_unlock

Name

mpdm_mutex_unlock - Unlocks a mutex.

Synopsis

 void mpdm_mutex_unlock(mpdm_t mutex);

Arguments

mutex
the mutex to be unlocked

Description

Unlocks a previously locked mutex. The thread unlocking the mutex must be the one who locked it.

Categories

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

mpdm_new_mutex

Name

mpdm_new_mutex - Creates a new mutex.

Synopsis

 mpdm_t mpdm_new_mutex(void);

Description

Creates a new mutex.

Categories

mpdm_new_semaphore

Name

mpdm_new_semaphore - Creates a new semaphore.

Synopsis

 mpdm_t mpdm_new_semaphore(int init_value);

Arguments

init_value
the initial value of the semaphore.

Description

Creates a new semaphore with an init_value.

Categories

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

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

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

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

mpdm_popen2

Name

mpdm_popen2 - Opens a pipe and returns 2 descriptors.

Synopsis

 mpdm_t mpdm_popen2(const mpdm_t prg);

Arguments

prg
the program to pipe

Description

Opens a read-write pipe and returns an array of two descriptors, one for reading and one for writing. If prg could not be piped to, returns NULL.

Categories

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

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

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

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

mpdm_regex

Name

mpdm_regex - Matches a regular expression.

Synopsis

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

Arguments

v
the value to be matched
r
the regular expression
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

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

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

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

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

mpdm_semaphore_post

Name

mpdm_semaphore_post - Increments the value of a semaphore.

Synopsis

 void mpdm_semaphore_post(mpdm_t sem);

Arguments

sem
the semaphore to increment

Description

Increments by 1 the value of a semaphore.

Categories

mpdm_semaphore_wait

Name

mpdm_semaphore_wait - Waits for a semaphore to be ready.

Synopsis

 void mpdm_semaphore_wait(mpdm_t sem);

Arguments

sem
the semaphore to wait onto

Description

Waits for the value of a semaphore to be > 0. If it's not, the thread waits until it is.

Categories

mpdm_set_ival

Name

mpdm_set_ival - Sets the integer value.

Synopsis

 mpdm_t mpdm_set_ival(mpdm_t v, int ival)
/* sets an integer value to a value */;

Arguments

v
the value
ival
the integer

Description

Sets the integer value for v. It does not change the reference count of v.

mpdm_set_rval

Name

mpdm_set_rval - Sets the real value.

Synopsis

 mpdm_t mpdm_set_rval(mpdm_t v, double rval)
/* sets a real value to a value */;

Arguments

v
the value
rval
the real

Description

Sets the real value for v. It does not change the reference count of v.

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 element.

Categories

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. It does not change the reference count of the value.

Categories

mpdm_sleep

Name

mpdm_sleep - Sleeps a number of milliseconds.

Synopsis

 void mpdm_sleep(int msecs);

Arguments

msecs
the milliseconds to sleep

Description

Sleeps a number of milliseconds.

Categories

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 same array, sorted (versions prior to 1.0.10 returned a new array).

Categories

mpdm_sort_cb

Name

mpdm_sort_cb - Sorts an array with a special sorting function.

Synopsis

 mpdm_t mpdm_sort_cb(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 same array, sorted (versions prior to 1.0.10 returned a new array).

Categories

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

mpdm_split

Name

mpdm_split - Separates a string into an array of pieces.

Synopsis

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

Arguments

v
the value to be separated
s
the separator

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

mpdm_split_s

Name

mpdm_split_s - Separates a string into an array of pieces (string version).

Synopsis

 mpdm_t mpdm_split_s(const mpdm_t v, const wchar_t *s);

Arguments

v
the value to be separated
s
the separator

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

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

mpdm_sregex

Name

mpdm_sregex - Matches and substitutes a regular expression.

Synopsis

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

Arguments

v
the value to be matched
r
the regular expression
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.

Always returns a new string (either modified or an exact copy).

Categories

mpdm_sscanf

Name

mpdm_sscanf - Extracts data like sscanf().

Synopsis

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

Arguments

str
the string to be parsed
fmt
the string format
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

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

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

mpdm_strcat_s

Name

mpdm_strcat_s - Concatenates two strings (string version).

Synopsis

 mpdm_t mpdm_strcat_s(const mpdm_t s1, const wchar_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

mpdm_strcat_sn

Name

mpdm_strcat_sn - Concatenates two strings (string with size version).

Synopsis

 mpdm_t mpdm_strcat_sn(const mpdm_t s1, const wchar_t * s2, int size);

Arguments

s1
the first string
s2
the second string
size
the size of the second string

Description

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

Categories

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.

The reference count value in v is not touched.

Categories

mpdm_string2

Name

mpdm_string2 - Returns a printable representation of a value (with buffer).

Synopsis

 wchar_t *mpdm_string2(const mpdm_t v, wchar_t *wtmp);

Arguments

v
the value
wtmp
the external buffer

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. If v is not a string, the wtmp buffer can be used as a placeholder for the string representation.

The reference count value in v is not touched.

Categories

mpdm_tr

Name

mpdm_tr - Transliterates a string.

Synopsis

 mpdm_t mpdm_tr(mpdm_t str, mpdm_t s1, mpdm_t s2);

Arguments

str
the strnig
s1
characters to be changed
s2
characters to replace those in s1

Description

Creates a copy of str, which will have all characters in s1 replaced by those in s2 matching their position.

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

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

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. If the reference count of the value reaches 0, it's destroyed.

Categories

mpdm_unrefnd

Name

mpdm_unrefnd - Decrements the reference count of a value, without destroy.

Synopsis

 mpdm_t mpdm_unrefnd(mpdm_t v);

Arguments

v
the value

Description

Decrements the reference count of a value, without destroying the value if it's unreferenced.

Categories

mpdm_void

Name

mpdm_void - Refs then unrefs a value.

Synopsis

 void mpdm_void(mpdm_t v);

Arguments

v
the value

Description

References and unreferences a value. To be used to receive the output of mpdm_exec() in case of it being void (i.e. its return value ignored).

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


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