3.77 DM_ValueChange
With this function a value reference managed by IDM may be manipulated. Either the entire value can be replaced or a single element value in a collection.
There is an automatic conversion of unmanaged value references into managed value references. If the option DMF_StaticValue is set in this case, a static respectively global managed value reference is created. For better control the explicit use of DM_ValueInit is recommended.
If the value parameter is a collection, e.g. of type DT_vector, DT_list, DT_hash, DT_matrix or DT_refvec, an element value can be substituted by specifying the index parameter. Similar to predefined attributes, a collection can be extended by incrementing the index with +1. For associative arrays, simply a not yet assigned index key may be used.
If a collection in the data parameter is assigned to the target as a whole (i.e. with NULL as index parameter), the entire value with all value elements is copied. The conversion of an argument into a locally managed value also requires a complete copying to allow further manipulation.
DM_Boolean DML_default DM_EXPORT DM_ValueChange
(
DM_Value *value,
DM_Value *index,
DM_Value *data,
DM_Options options
)
Parameters
-> DM_Value * value
This parameter refers to the value reference to be changed. If it is not yet managed by the IDM, it is converted to a managed value reference.
-> DM_Value * index
This parameter can be used to change element values in collections and specifies the index. Otherwise, it should be set to NULL. This parameter does not need to be a managed value reference.
-> DM_Value * data
This parameter defines the value to be set. It may be a managed or an unmanaged value reference. If this value is NULL, the value or element is set to DT_undefined.
-> DM_Options options
These are the options available:
|
Option |
Meaning |
|---|---|
|
DMF_StaticValue |
When the value parameter is automatically converted into a managed value reference, it is treated as a static respectively global value reference. |
|
DMF_AppendValue |
For collections, the data value from data is appended at the end. The index must be NULL for this. |
|
DMF_SortBinary |
In collections, the newly set value is finally sorted. May be used in combination with DMF_SortReverse. |
|
DMF_SortLinguistic |
In collections, the newly set value is finally sorted, for strings according to linguistic rules (see the function sort()). May be used in combination with DMF_SortReverse. |
|
DMF_SortReverse |
In collections, the newly set value is finally sorted in reverse order. |
Return value
|
DM_TRUE |
The function has been completed successfully, setting the value succeeded or the value had already been set. |
|
DM_FALSE |
Value could not be set. This may be due to an faulty call, an unmanaged or invalid value reference, or an incorrect indexing. |
Example
dialog YourDialog
function anyvalue FindData(hash DataHash, string Pattern,
anyvalue FirstIndex output);
on dialog start
{
variable hash Stations := ["1"=>"ABC ","2"=>"CBS ","9"=>"HBO "];
variable anyvalue Idx;
print "Found(D)=" + FindData(Stations,"D",Idx);
print " at " + Idx;
exit();
}
...
static DM_Value InvalidIndex;
static DM_Value InvalidValue;
DM_Value * DML_default DM_ENTRY FindData(DM_Value *DataHash, DM_String Pattern,
DM_Value *FirstIndex)
{
DM_Value index;
DM_Value value;
/* initialize the managed values */
DM_ValueInit(&index, DT_void, NULL, 0);
DM_ValueInit(&value, DT_void, NULL, 0);
DM_StringInit(&retString, 0);
count = DM_ValueCount(DataHash, NULL, 0);
while(count>0)
{
/* loop through the hash */
if (DM_ValueIndex(DataHash, count--, &index, 0)
&& DM_ValueGet(DataHash, &index, &value, DMF_GetLocalString)
&& value.type == DT_string)
{
if (strstr(value.value.string, Pattern))
{
/* return the first found index & value */
DM_ValueChange(FirstIndex, NULL, &index, 0);
return DM_ValueReturn(&value, 0);
}
}
}
/* return the invalid index & value */
DM_ValueChange(FirstIndex, NULL, &InvalidIndex, 0);
return &InvalidValue;
}
...
int DML_c AppMain __2((int, argc), (char **,argv))
{
DM_Value data;
...
data.type = DT_string;
data.value.string = "NO-VALUE";
DM_ValueChange(&InvalidValue, NULL, &data, DMF_StaticValue);
data.type = DT_string;
data.value.string = "INVALID-INDEX";
DM_ValueChange(&InvalidIndex, NULL, &data, DMF_StaticValue);
...
DM_StartDialog(...)
Availability
Support