Datamap.mui

DESCRIPTION

Datamap.mui/Datamap.mui

	The Datamap class serves as a simple data container, similar to Dataspace.
	They both inherit from the same superclass, Semaphore. The data is sorted
	by the string key using btree.library so that the lookups are very fast

MUIA_Datamap_AutoLock

(V20) [I..], BOOL, 0x8042fbe4

DESCRIPTION

	Ensures the Datamap methods are called under appropriate locks. Does not
	guarantee that the returned data will stay valid on return. Does not
	protect the Iterate methods - in case the object is used by multiple
	threads, you need to put the whole iteration into an exclusive lock

MUIA_Datamap_CopyKeys

(V20) [I..], BOOL, 0x8042a179

DESCRIPTION

	If you specify this tag as FALSE, the key you pass when calling
	MUIM_Datamap_Set will not be copied but instead used directly
	in the tree. It is then your responsibility to ensure the key stays
	valid as long as its corresponding entry in the tree does.
	
	Useful if your app contains the keys as static strings anway

MUIA_Datamap_Count

(V20) [..G], ULONG, 0x80427580

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIA_Datamap_Pool

(V20) [I..], APTR, 0x80424724

DESCRIPTION

	If you specify a memory pool from exec.library/CreatePool()
	here, the datamap object will use this pool for all its
	entries.

	If you omit this tag or pass NULL, the datamap object
	will create its own memory pool instead

SEE ALSO

MUIM_Datamap_Clear

MUIM_Datamap_Clear (V20) 0x8042eebc

SYNOPSIS

	DoMethod(obj,MUIM_Datamap_Clear);

DESCRIPTION

	Removes all entries in the Datamap object

MUIM_Datamap_Find

MUIM_Datamap_Find (V20) 0x8042d650

SYNOPSIS

	DoMethod(obj,MUIM_Datamap_Find,CONST_STRPTR key);

DESCRIPTION

	Finds a data entry using the passed in key

INPUTS

	key - key to find the entry by

RESULT

	Pointer to the stored data or NULL

SEE ALSO

MUIM_Datamap_Get

MUIM_Datamap_Get (V21) 0x8042c2ba

SYNOPSIS

	DoMethod(obj,MUIM_Datamap_Get,CONST_STRPTR key, ULONG *size);

DESCRIPTION

	yet undocumented, please complain in mailinglist

MUIM_Datamap_Iterate

MUIM_Datamap_Iterate (V20) 0x8042fda1

SYNOPSIS

	DoMethod(obj,MUIM_Datamap_Iterate,IPTR *counter);

DESCRIPTION

	Iterates though all stored keys. It is legal to continue an iteration
	after removing the current item, but MUIM_Datamap_Clear would make the
	iterator invalid

INPUTS

	counter - ptr to IPTR-sized storage for internal usage, MUST be zeroed 
	          at the beginning of an iteration process

RESULT

	Pointer to the stored data or NULL after returning the last item

SEE ALSO

  • MUIM_Dataspace_Iterate

MUIM_Datamap_IterationKey

MUIM_Datamap_IterationKey (V20) 0x8042bc15

SYNOPSIS

	DoMethod(obj,MUIM_Datamap_IterationKey,IPTR *counter);

DESCRIPTION

	Returns the key associated with current iteration stage

INPUTS

	counter - ptr to IPTR storage used for MUIM_Datamap_Iterate cycle

RESULT

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

EXAMPLE

	Object o = DatamapObject, End;
	APTR item;
	IPTR counter;
	
	/* insert data to the map */
	
	for (counter = 0; (item = DoMethod(o, MUIM_Datamap_Iterate, &counter)); )
	{
		CONST_STRPTR key = DoMethod(o, MUIM_Datamap_IterationKey, &counter);
	
		printf("Key %s - Data %p\n", key, item

SEE ALSO

MUIM_Datamap_Remove

MUIM_Datamap_Remove (V20) 0x804203d8

SYNOPSIS

	DoMethod(obj,MUIM_Datamap_Remove,CONST_STRPTR key);

DESCRIPTION

	Removes and entry corresponding with the passed in key

INPUTS

	key  - the key to lookup the entry by

RESULT

	NULL if the entry was not found

SEE ALSO

MUIM_Datamap_Set

MUIM_Datamap_Set (V20) 0x8042b84f

SYNOPSIS

	DoMethod(obj,MUIM_Datamap_Set,APTR data, LONG len, CONST_STRPTR key);

DESCRIPTION

	This method adds or changes an entry corresponding to the given key. There
	can only be one unique key in a tree, so calling MUIM_Datamap_Set multiple
	times with the same key will overwrite the old data

INPUTS

	data - pointer to data to store
	len  - length of the data
	key  - the key to index the data by

RESULT

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

SEE ALSO