kValue.h

Go to the documentation of this file.

/** 
 * @file    kValue.h
 * @brief   Declares the kValue type. 
 *
 * @internal
 * Copyright (C) 2012-2014 by LMI Technologies Inc.
 * Licensed under the MIT License.
 * Redistributed files must retain the above copyright notice.
 */
#include <kApi/kApiDef.h>   //--inclusion order controlled by kApiDef

#ifndef K_API_VALUE_H
#define K_API_VALUE_H

kBeginHeader()

/**
 * @class   kValue
 * @ingroup kApi
 * @brief   Root of all value types in the kType system. 
 * 
 * Value types represent structures, enumerations, and primitive values. The kValue base type defines 
 * methods that can be called on any value instance. 
 */

/**
 * Determines whether a value is equal to another value. 
 * 
 * The default implementation of this method uses type reflection to compare the values field by field. 
 * This approach is not efficient, and in some cases may not produce the desired result. Value types should 
 * override this method if it is likely that equality comparisons will be required. 
 * 
 * @public              @memberof kValue
 * @param   type        Value type. 
 * @param   value       Pointer to value. 
 * @param   other       Pointer to other value. 
 * @return              kTRUE if the values are equal.
 */
kFx(kBool) kValue_Equals(kType type, const void* value, const void* other); 

/**
 * Gets a hash code representing the state of this value.
 *
 * The default implementation of this method uses type reflection to generate a hash code that combines the 
 * hash codes from individual fields. This approach is not efficient, and may not produce an optimal hash code. 
 * Value types should override this method if it is likely that hash codes will be required. 
 *
 * @public              @memberof kValue
 * @param   type        Value type. 
 * @param   value       Pointer to value.
 * @return              Hash code. 
 */
kFx(kSize) kValue_HashCode(kType type, const void* value); 

/**
 * Imports the content of another value into this value.
 *
 * This method supports importing content from an external source, which may have a different size.
 * In particular, "array value" types such as kText32 can import from a null-terminated source array of a differnt 
 * length. 
 *
 * @public              @memberof kValue
 * @param   type        Value type. 
 * @param   value       Pointer to value.
 * @param   source      Source for import. 
 */
kFx(void) kValue_Import(kType type, void* value, const void* source); 

kEndHeader()

#include <kApi/kValue.x.h>

#endif