Base abstract class for defining a hierarchical data structure in GCGlib for key/value mappings. It indicates the minimum methods that all data structures for kay/value mapping must provide. Note that some data maps might provide other interfaces to handle their elements. The data maps might use fixed or variable length keys and a careful reading of their documentation is recommended. The value is assumed to be an instance of gcgDATA. Data maps differs from gcgLISTSTRUCTURE and gcgORDEREDSTRUCTURE in the sense that only the key is used for indexing the gcgDATA nodes. The key and the value are explicitaly separated internally. Also, the gcgDATA instances are not linked explicitally. The underlying key/value mappings are driven by internal nodes specially designed for the data map. The drawback is that this might lead to more memory fragmentation when compared with gcgLISTSTRUCTURE and gcgORDEREDSTRUCTURE. A key is assumed a digital sequence that can be null terminated strings or a sequence of bytes with fixed size (MSB first order). Keys having size up to sizeof(intptr_t), i.e. integers that fit within the same number of bits of a pointer, are copied for performance purposes (also MSB first order). If the keys are null terminated strings or fixed size greater than sizeof(intptr_t), their contents are not copied: only the pointer to the actual key is stored internally. If used as a pointer to the actual key, it can point to any memory region holding the digital sequence. However, its content must NEVER change while in use. The behaviour of the data map is undefined if that happens. A common practice is to point to an internal attribute of the corresponding gcgDATA instance (if not using integer keys). See the data map documentation. For ease of use, several constructors (GCGDIGITALKEY) are provided for integer keys. More...

#include <gcg.h>

Inheritance diagram for gcgDATAMAP:

Public Member Functions
virtual gcgDATA *	insert (GCGDIGITALKEY key, gcgDATA *value)=0
	Inserts a new pair key/value* in* the data map. In general, data maps require unique keys. However, this requirement can be relaxed by combining other data structures with a data map. In most cases, the data map only works for unique keys and they must be mutually different in the digital sense. More...

virtual gcgDATA *	search (GCGDIGITALKEY key)=0
	Retrieves the gcgDATA pointer value of the data map that is similar in the digital sense (they have the same size and all bits are equal) to the key. In general, data maps require the keys to be unique. More...

virtual gcgDATA *	remove (GCGDIGITALKEY key)=0
	Removes the key/value entry of the data map that has the key similar to the key in the digital sense (they have the same size and all bits are equal). In general, data maps require the keys to be unique. More...

Public Member Functions inherited from gcgCLASS
void *	operator new (size_t size)
	Defines a new operator to be used by instatiations of GCGlib classes instead the global one. More...

void *	operator new (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by instantiations of GCGlib classes instead the global one. Returns a NULL pointer instead of throwing an exception if an error occurs. More...

void *	operator new[] (size_t size)
	Defines a new operator to be used by GCGlib array allocations instead the global one. More...

void *	operator new[] (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by vector allocations instead the global one. More...

void	operator delete (void *p)
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...

void	operator delete (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...

void	operator delete[] (void *p)
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

void	operator delete[] (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

Detailed Description

Base abstract class for defining a hierarchical data structure in GCGlib for key/value mappings. It indicates the minimum methods that all data structures for kay/value mapping must provide. Note that some data maps might provide other interfaces to handle their elements. The data maps might use fixed or variable length keys and a careful reading of their documentation is recommended. The value is assumed to be an instance of gcgDATA. Data maps differs from gcgLISTSTRUCTURE and gcgORDEREDSTRUCTURE in the sense that only the key is used for indexing the gcgDATA nodes. The key and the value are explicitaly separated internally. Also, the gcgDATA instances are not linked explicitally. The underlying key/value mappings are driven by internal nodes specially designed for the data map. The drawback is that this might lead to more memory fragmentation when compared with gcgLISTSTRUCTURE and gcgORDEREDSTRUCTURE. A key is assumed a digital sequence that can be null terminated strings or a sequence of bytes with fixed size (MSB first order). Keys having size up to sizeof(intptr_t), i.e. integers that fit within the same number of bits of a pointer, are copied for performance purposes (also MSB first order). If the keys are null terminated strings or fixed size greater than sizeof(intptr_t), their contents are not copied: only the pointer to the actual key is stored internally. If used as a pointer to the actual key, it can point to any memory region holding the digital sequence. However, its content must NEVER change while in use. The behaviour of the data map is undefined if that happens. A common practice is to point to an internal attribute of the corresponding gcgDATA instance (if not using integer keys). See the data map documentation. For ease of use, several constructors (GCGDIGITALKEY) are provided for integer keys.

Since: 0.04.211

Member Function Documentation

◆ insert()

virtual gcgDATA* gcgDATAMAP::insert	(	GCGDIGITALKEY	key,
		gcgDATA *	value
	)

pure virtual

Inserts a new pair key/value in the data map. In general, data maps require unique keys. However, this requirement can be relaxed by combining other data structures with a data map. In most cases, the data map only works for unique keys and they must be mutually different in the digital sense.

Parameters

[in]	key	a unique sequence of bytes that refers to the value data. If a key already in the data map is similar to key in the digital sense (they have the same size and all bits are equal), it returns the pointer of its corresponding gcgDATA instance value. A key is assumed a digital sequence that can be null terminated strings or a sequence of bytes with fixed size (in MSB first order). Keys having size up to sizeof(intptr_t), i.e. integers that fit within the same number of bits of a pointer, are copied for performance purposes (also in MSB first order). If the keys are null terminated strings or fixed size greater than sizeof(intptr_t), their contents are not copied: only the pointer to the actual key is stored internally. If used as a pointer to the actual key, it can point to any memory region holding the digital sequence. However, its content must NEVER change while in use. The behaviour of the data map is undefined if that happens. A common practice is to point to an internal attribute of the corresponding gcgDATA instance (if not using integer keys). See the data map documentation. For ease of use, several constructors (GCGDIGITALKEY) are provided for integer keys.
[in]	value	a pointer to a gcgDATA instance that actually holds information. If key is a pointer, it is recommended to point to a value attribute holding the key.

Returns: if key is similar in the digital sense (they have the same size and all bits are equal) to an existing key/value pair of the data map, the method returns the pointer of the existing gcgDATA value. If key/value pair is correctly inserted, it returns the gcgDATA pointer value. If it returns NULL, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: remove(); search()

Implemented in gcgPATRICIAMAP.

◆ remove()

virtual gcgDATA* gcgDATAMAP::remove ( GCGDIGITALKEY key )

pure virtual

Removes the key/value entry of the data map that has the key similar to the key in the digital sense (they have the same size and all bits are equal). In general, data maps require the keys to be unique.

Parameters

[in] key a unique sequence of bytes that refers to the value data. If a key already in the data map is similar to key in the digital sense (they have the same size and all bits are equal), its key/value pair is removed from the data map and the gcgDATA pointer is returned. If a similar key is not found in the data map, it returns NULL. A key is assumed a digital sequence that can be null terminated strings or a sequence of bytes with fixed size (MSB first order). Keys having size up to sizeof(intptr_t), i.e. integers that fit within the same number of bits of a pointer, are copied for performance purposes (also in MSB first order). If the keys are null terminated strings or fixed size greater than sizeof(intptr_t), their contents are not copied: only the pointer to the actual key is stored internally. If used as a pointer to the actual key, it can point to any memory region holding the digital sequence. However, its content must NEVER change while in use. The behaviour of the data map is undefined if that happens. A common practice is to point to an internal attribute of the corresponding gcgDATA instance (if not using integer keys). See the data map documentation. For ease of use, several constructors (GCGDIGITALKEY) are provided for integer keys.

Returns: if key is similar in the digital sense (they have the same size and all bits are equal) to an existing key/value pair of the data map, the method removes the key/value pair from the data map and returns the pointer of the gcgDATA value. If no similar key is found, it returns NULL. Check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem, if any.

See also: insert(); search()

Implemented in gcgPATRICIAMAP.

◆ search()

virtual gcgDATA* gcgDATAMAP::search ( GCGDIGITALKEY key )

pure virtual

Retrieves the gcgDATA pointer value of the data map that is similar in the digital sense (they have the same size and all bits are equal) to the key. In general, data maps require the keys to be unique.

Parameters

[in] key a unique sequence of bytes that refers to the value data. If a key already in the data map is similar to key in the digital sense (they have the same size and all bits are equal), it returns the pointer of its corresponding gcgDATA instance value. If a similar key is not found in the data map, it returns NULL. A key is assumed a digital sequence that can be null terminated strings or a sequence of bytes with fixed size (MSB first order). Keys having size up to sizeof(intptr_t), i.e. integers that fit within the same number of bits of a pointer, are copied for performance purposes (also in MSB first order). If the keys are null terminated strings or fixed size greater than sizeof(intptr_t), their contents are not copied: only the pointer to the actual key is stored internally. If used as a pointer to the actual key, it can point to any memory region holding the digital sequence. However, its content must NEVER change while in use. The behaviour of the data map is undefined if that happens. A common practice is to point to an internal attribute of the corresponding gcgDATA instance (if not using integer keys). See the data map documentation. For ease of use, several constructors (GCGDIGITALKEY) are provided for integer keys.

Returns: if key is similar in the digital sense (they have the same size and all bits are equal) to an existing key/value pair of the data map, the method returns the pointer of the existing gcgDATA value. If no similar key is found, it returns NULL. Check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem, if any.

See also: insert(); remove()

Implemented in gcgPATRICIAMAP.

The documentation for this class was generated from the following file:

M:/Documentos/Projetos/Projetos/GCGlib/src/gcg.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ insert()

◆ remove()

◆ search()