wiki:Documentation/API/MUI_Objectmap

Objectmap.mui

Super class

Semaphore.mui

Background

The Objectmap class serves as a simple data container, similar to Dataspace and Datamap. They both are subclasses of Semaphore.mui. The data is sorted by the string key using btree.library. This makes lookups very fast.

In contrast to Datamap Objectmap is designed to store MUI objects only. By adding an object to the map using MUIM_Objectmap_Set the application loses the ownership of the object as long as it is a member of the Objectmap. Such objects will be disposed when the Objectmap is disposed. This matches the behavior and rules of Family.mui subclasses. Removing an object from the Objectmap will return the ownership back to the application.

Attributes

Attribute Version ISG Type
MUIA_Objectmap_AutoLock V20I..BOOL
MUIA_Objectmap_CopyKeys V20I..BOOL
MUIA_Objectmap_Pool V20I..APTR


Methods

Method Version
MUIM_Objectmap_Clear V20
MUIM_Objectmap_Find V20
MUIM_Objectmap_Iterate V20
MUIM_Objectmap_IterationKey V20
MUIM_Objectmap_Remove V20
MUIM_Objectmap_Set V20


MUIA_Objectmap_AutoLock

NAME

MUIA_Objectmap_AutoLock — V20 [I..], BOOL, 0x8042e65f

FUNCTION

Setting this attribute to TRUE ensures that Objectmap methods are called under appropriate locks. Please note that this does not guarantee that the returned object will stay valid on return. It also does not protect the iteration methods. In case the Objectmap is used by multiple threads, you must put the whole iteration into an exclusive lock.

MUIA_Objectmap_CopyKeys

NAME

MUIA_Objectmap_CopyKeys — V20 [I..], BOOL, 0x8042b964

FUNCTION

Setting this attribute to FALSE will skip the copying of the passed key to MUIM_Objectmap_Set. Instead the key will be used directly for all tree related actions. It is up the the application to ensure the validity of the key as long as the corresponding object is contained in the tree.

This attribute is very useful if your application uses static strings as keys for example.

MUIA_Objectmap_Pool

NAME

MUIA_Objectmap_Pool — V20 [I..], APTR, 0x80422ed3

FUNCTION

If set to a valid memory pool pointer created by exec/CreatePool() the objectmap object will use this pool for all memory allocations instead of creating a private pool.

SEE ALSO

MUIM_Objectmap_Set, exec.library/CreatePool

MUIM_Objectmap_Clear

NAME

MUIM_Objectmap_Clear — V20, 0x80422ee5

SYNOPSIS

DoMethod(obj, MUIM_Objectmap_Clear);

FUNCTION

Remove and dispose all objects in the Objectmap object.

MUIM_Objectmap_Find

NAME

MUIM_Objectmap_Find — V20, 0x80426506

SYNOPSIS

DoMethod(obj, MUIM_Objectmap_Find, CONST_STRPTR key);

FUNCTION

Look up an object by a key.

INPUTS

CONST_STRPTR key
key to look up the object by.

RESULT

Pointer to the stored object or NULL in case the key was not found.

SEE ALSO

MUIM_Objectmap_Iterate

MUIM_Objectmap_Iterate

NAME

MUIM_Objectmap_Iterate — V20, 0x804262bc

SYNOPSIS

DoMethod(obj, MUIM_Objectmap_Iterate, ULONG *counter);

FUNCTION

This method iterates over all stored keys. It is perfectly legal to continue the iteration after removing the current object by calling MUIM_Objectmap_Remove but calling MUIM_Objectmap_Clear will make the iterator invalid.

INPUTS

ULONG *counter
pointer to a 32bit-sized storage for internal usage. This storage MUST be zeroed before starting the iteration.

RESULT

Pointer to the stored object or NULL after returning the last object

SEE ALSO

MUIM_Objectmap_IterationKey

MUIM_Objectmap_IterationKey

NAME

MUIM_Objectmap_IterationKey — V20, 0x8042d7ff

SYNOPSIS

DoMethod(obj, MUIM_Objectmap_IterationKey, ULONG *counter);

FUNCTION

Returns the key associated with the current iteration stage.

INPUTS

ULONG *counter
pointer to the 32bit-sized storage used for MUIM_Objectmap_Iterate.

RESULT

Pointer to a key or NULL if the counter doesn't contain a valid entry

EXAMPLE

Object o = ObjectmapObject, End;
Object *obj;
ULONG counter;

/* assume data has been inserted into the map before */
counter = 0;
while((obj = (Object *)DoMethod(o, MUIM_Objectmap_Iterate, &counter)) != NULL)
{
  CONST_STRPTR key = (CONST_STRPTR)DoMethod(o, MUIM_Objectmap_IterationKey, &counter);

  printf("key '%s', object %p\n", key, item);
}

SEE ALSO

MUIM_Objectmap_Iterate

MUIM_Objectmap_Remove

NAME

MUIM_Objectmap_Remove — V20, 0x8042f649

SYNOPSIS

DoMethod(obj, MUIM_Objectmap_Remove, CONST_STRPTR key);

FUNCTION

Removes the object corresponding to the specified key. After removing the object from the Objectmap the ownership by Objectmap end and the object must be disposed separately again.

INPUTS

CONST_STRPTR key
key to look up the object by.

RESULT

NULL if no corresponding object was not found.

SEE ALSO

MUIM_Objectmap_Set

MUIM_Objectmap_Set

NAME

MUIM_Objectmap_Set — V20, 0x80421ec5

SYNOPSIS

DoMethod(obj, MUIM_Objectmap_Set, Object *o, CONST_STRPTR key);

FUNCTION

This method adds or changes an object corresponding to the specified key. Keys are considered to be unique within a tree. Hence calling MUIM_Objectmap_Set multiple times with the same key will overwrite the object set before.

INPUTS

Object *o
pointer to an object to store in the map.
CONST_STRPTR key
the key to index the data by.

RESULT

NULL on failure or a non-NULL value on success.

SEE ALSO

MUIM_Objectmap_Remove, MUIM_Objectmap_Find, MUIM_Objectmap_Iterate


Copyright © 1992-2006 by Stefan Stuntz
Copyright © 2006-2017 by Thore Böckelmann, Jens Maus

MUI for AmigaOS - MUI-Autodocs

Updated: 13-Jul-2017

Last modified 5 months ago Last modified on Mar 27, 2017, 4:06:51 PM