The m17n Library 1.8.4
Loading...
Searching...
No Matches
Functions | Variables
Property List

Functions

MPlistmplist_deserialize (MText *mt)
 Generate a property list by deserializing an M-text.
 
MPlistmplist (void)
 Create a property list object.
 
MPlistmplist_copy (MPlist *plist)
 Copy a property list.
 
MPlistmplist_put (MPlist *plist, MSymbol key, void *val)
 Set the value of a property in a property list.
 
void * mplist_get (MPlist *plist, MSymbol key)
 Get the value of a property in a property list.
 
MPlistmplist_put_func (MPlist *plist, MSymbol key, M17NFunc func)
 Set the value (function pointer) of a property in a property list.
 
M17NFunc mplist_get_func (MPlist *plist, MSymbol key)
 Get the value (function pointer) of a property in a property list.
 
MPlistmplist_add (MPlist *plist, MSymbol key, void *val)
 Add a property at the end of a property list.
 
MPlistmplist_push (MPlist *plist, MSymbol key, void *val)
 Add a property at the beginning of a property list.
 
void * mplist_pop (MPlist *plist)
 Remove a property at the beginning of a property list.
 
MPlistmplist_find_by_key (MPlist *plist, MSymbol key)
 Find a property of a specific key in a property list.
 
MPlistmplist_find_by_value (MPlist *plist, void *val)
 Find a property of a specific value in a property list.
 
MPlistmplist_next (MPlist *plist)
 Return the next sublist of a property list.
 
MPlistmplist_set (MPlist *plist, MSymbol key, void *val)
 Set the first property in a property list.
 
int mplist_length (MPlist *plist)
 Return the length of a property list.
 
MSymbol mplist_key (MPlist *plist)
 Return the key of the first property in a property list.
 
void * mplist_value (MPlist *plist)
 Return the value of the first property in a property list.
 

Variables

MSymbol Minteger
 Symbol whose name is "integer".
 
MSymbol Mplist
 Symbol whose name is "plist".
 
MSymbol Mtext
 Symbol whose name is "mtext".
 

Detailed Description

@addtogroup m17nPlist

@brief Property List objects and API for them.

A @e property @e list (or @e plist for short) is a list of zero or
more properties.  A property consists of a @e key and a @e value,
where key is a symbol and value is anything that can be cast to
<tt>(void *)</tt>.

If the key of a property is a @e managing @e key, its @e value is
a @e managed @e object.  A property list itself is a managed
objects.

If each key of a plist is one of #Msymbol, #Mtext, #Minteger, and
#Mplist, the plist is called as @e well-formed and represented by
the following notation in the documentation.
      PLIST ::= '(' ELEMENT * ')'

      ELEMENT ::= INTEGER | SYMBOL | M-TEXT | PLIST

      M-TEXT ::= '"' text data ... '"'
For instance, if a plist has four elements; integer -20, symbol of
name "sym", M-text of contents "abc", and plist of integer 10 and
symbol of name "another-symbol", it is represented as this:

  (-20 sym "abc" (10 another-symbol))

Function Documentation

◆ mplist_deserialize()

MPlist * mplist_deserialize ( MText mt)

Generate a property list by deserializing an M-text.

The mplist_deserialize() function parses M-text mt and returns a property list.

The syntax of mt is as follows.

MT ::= '(' ELEMENT * ')'

ELEMENT ::= SYMBOL | INTEGER | M-TEXT | PLIST

SYMBOL ::= ascii-character-sequence

INTEGER ::= '-' ? [ '0' | .. | '9' ]+ | '0x' [ '0' | .. | '9' | 'A' | .. | 'F' | 'a' | .. | 'f' ]+

M-TEXT ::= '"' character-sequence '"'

Each alternatives of ELEMENT is assigned one of these keys: Msymbol, Minteger, Mtext, Mplist

In an ascii-character-sequence, a backslash () is used as the escape character, which means that, for instance, abc\ def produces a symbol whose name is of length seven with the fourth character being a space.

◆ mplist()

MPlist * mplist ( void  )

Create a property list object.

The mplist() function returns a newly created property list object of length zero.

Return value:
This function returns a newly created property list.
Errors:
This function never fails.

◆ mplist_copy()

MPlist * mplist_copy ( MPlist plist)

Copy a property list.

The mplist_copy() function copies property list plist. In the copy, the values are the same as those of plist.

Return value:
This function returns a newly created plist which is a copy of plist.
Errors:
This function never fails.

◆ mplist_put()

MPlist * mplist_put ( MPlist plist,
MSymbol  key,
void *  val 
)

Set the value of a property in a property list.

The mplist_put() function searches property list plist from the beginning for a property whose key is key. If such a property is found, its value is changed to value. Otherwise, a new property whose key is key and value is value is appended at the end of plist. See the documentation of mplist_add() for the restriction on key and val.

If key is a managing key, val must be a managed object. In this case, the reference count of the old value, if not NULL, is decremented by one, and that of val is incremented by one.

Return value:
If the operation was successful, mplist_put() returns a sublist of plist whose first element is the just modified or added one. Otherwise, it returns NULL.

◆ mplist_get()

void * mplist_get ( MPlist plist,
MSymbol  key 
)

Get the value of a property in a property list.

The mplist_get() function searches property list plist from the beginning for a property whose key is key. If such a property is found, its value is returned as the type of (void *). If not found, NULL is returned.

When NULL is returned, there are two possibilities: one is the case where no property is found (see above); the other is the case where a property is found and its value is NULL. In case that these two cases must be distinguished, use the mplist_find_by_key() function.

See Also:
mplist_find_by_key()

◆ mplist_put_func()

MPlist * mplist_put_func ( MPlist plist,
MSymbol  key,
M17NFunc  func 
)

Set the value (function pointer) of a property in a property list.

The mplist_put_func() function is similar to mplist_put() but for setting function pointer func in property list plist for key key. key must not be a managing key.

See Also:
mplist_put(), M17N_FUNC()

◆ mplist_get_func()

M17NFunc mplist_get_func ( MPlist plist,
MSymbol  key 
)

Get the value (function pointer) of a property in a property list.

The mplist_get_func() function is similar to mplist_get() but for getting a function pointer from property list plist by key key.

See Also:
mplist_get()

◆ mplist_add()

MPlist * mplist_add ( MPlist plist,
MSymbol  key,
void *  val 
)

Add a property at the end of a property list.

The mplist_add() function appends at the end of property list plist a property whose key is key and value is val. key can be any symbol other than Mnil.

If key is a managing key, val must be a managed object. In this case, the reference count of val is incremented by one.

Return value:
If the operation was successful, mplist_add() returns a sublist of plist whose first element is the just added one. Otherwise, it returns NULL.

◆ mplist_push()

MPlist * mplist_push ( MPlist plist,
MSymbol  key,
void *  val 
)

Add a property at the beginning of a property list.

The mplist_push() function inserts at the beginning of property list plist a property whose key is key and value is val.

If key is a managing key, val must be a managed object. In this case, the reference count of val is incremented by one.

Return value:
If the operation was successful, this function returns plist. Otherwise, it returns NULL.

◆ mplist_pop()

void * mplist_pop ( MPlist plist)

Remove a property at the beginning of a property list.

The mplist_pop() function removes a property at the beginning of property list plist. As a result, the second key and value of the plist become the first ones.

Return value:
If the operation was successful, this function return the value of the just popped property. Otherwise, it returns NULL.

◆ mplist_find_by_key()

MPlist * mplist_find_by_key ( MPlist plist,
MSymbol  key 
)

Find a property of a specific key in a property list.

The mplist_find_by_key() function searches property list plist from the beginning for a property whose key is key. If such a property is found, a sublist of plist whose first element is the found one is returned. Otherwise, NULL is returned.

If key is Mnil, it returns a sublist of plist whose first element is the last one of plist.

◆ mplist_find_by_value()

MPlist * mplist_find_by_value ( MPlist plist,
void *  val 
)

Find a property of a specific value in a property list.

The mplist_find_by_value() function searches property list plist from the beginning for a property whose value is val. If such a property is found, a sublist of plist whose first element is the found one is returned. Otherwise, NULL is returned.

◆ mplist_next()

MPlist * mplist_next ( MPlist plist)

Return the next sublist of a property list.

The mplist_next() function returns a pointer to the sublist of property list plist, which begins at the second element in plist. If the length of plist is zero, it returns NULL.

◆ mplist_set()

MPlist * mplist_set ( MPlist plist,
MSymbol  key,
void *  val 
)

Set the first property in a property list.

The mplist_set() function sets the key and the value of the first property in property list plist to key and value, respectively. See the documentation of mplist_add() for the restriction on key and val.

Return value:
If the operation was successful, mplist_set() returns plist. Otherwise, it returns NULL.

◆ mplist_length()

int mplist_length ( MPlist plist)

Return the length of a property list.

The mplist_length() function returns the number of properties in property list plist.

◆ mplist_key()

MSymbol mplist_key ( MPlist plist)

Return the key of the first property in a property list.

The mplist_key() function returns the key of the first property in property list plist. If the length of plist is zero, it returns Mnil.

◆ mplist_value()

void * mplist_value ( MPlist plist)

Return the value of the first property in a property list.

The mplist_value() function returns the value of the first property in property list plist. If the length of plist is zero, it returns NULL.

Variable Documentation

◆ Minteger

MSymbol Minteger

Symbol whose name is "integer".

The symbol Minteger has the name "integer". The value of a property whose key is Minteger must be an integer.

◆ Mplist

MSymbol Mplist

Symbol whose name is "plist".

The symbol Mplist has the name "plist". It is a managing key. A value of a property whose key is Mplist must be a plist.

◆ Mtext

MSymbol Mtext

Symbol whose name is "mtext".

The symbol Mtext has the name "mtext". It is a managing key. A value of a property whose key is Mtext must be an M-text.


m17n-lib Home