Globals: Dynamic Conversion

Dynamic Conversion

Availability  LightWave 6.0
Component  Modeler
Header  lwdyna.h

This global returns a function that converts between DynaValues of different types. This is most often useful for converting between string and numeric values. DynaValues are used by the command system and by the requester API.

Global Call

   DynaConvertFunc *dynacvt;
   dynacvt = global( LWDYNACONVERTFUNC_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to a DynaConvertFunc.

   typedef int DynaConvertFunc (const DynaValue *from, DynaValue *to,
     const DynaStringHint *hint);

from

The value to convert from.

to

Receives the converted value of the from argument. Before calling the conversion function, set the type field of the to argument to the desired type for the conversion.

hint

Specifies a mapping between DY_STRING types and certain kinds of numeric values. If the types involved in the conversion don't require a hint, this is ignored and may be NULL.

If the conversion succeeds, the function returns DYERR_NONE. Otherwise it returns an error code. Possible error codes include DYERR_MEMORY, DYERR_BADTYPE and DYERR_INTERNAL.

String Hints

If one of the DynaValues is a string and the other is a choice or a bitfield, the conversion uses the hint argument as a lookup table for translating between them. The structure used to pass hints looks like this.

   typedef struct st_DynaStringHint {
      DyChoiceHint   *chc;
      DyBitfieldHint *bits;
   } DynaStringHint;

There are two kinds of hints in a DynaStringHint structure, only one of which will be used for a given string conversion.

   typedef struct st_DyChoiceHint {
      const char *item;
      int         value;
   } DyChoiceHint;

The choice hint is an array of DyChoiceHint used when converting between DY_STRING and DY_CHOICE types. The item/value pairs indicate a mapping between choice values and strings. In other words, hint->chc[i].item will be converted to hint->chc[i].value and vice-versa. The array is terminated with a null item string.

   typedef struct st_DyBitfieldHint {
      char code;
      int  bitval;
   } DyBitfieldHint;

The bitfield hint is an array of DyBitfieldHint used when converting between an array of characters (DY_STRING) and a bitfield (the bits in a DY_INTEGER). Bitfields appear as arguments to certain CommandSequence commands. In the string representation, the presence of a given character corresponds to a set bit in a bitfield, and if that character isn't in the string, the bit is clear.

The DyBitfieldHint code field contains a character, and the bitval field is an integer with a bit pattern. When converting from a DY_STRING, if the code character (upper or lower case) is present in the string, the bitval bits will be bitwise-ORed into the conversion result. When converting from a bitfield, if the bitval pattern is present (value & bitval == bitval), the code character is appended to the string result. The hint list is terminated with a zero bitval.

Example

This code fragment converts between the string and the bitfield representations of a set of compass point flags.

   #include <lwserver.h>
   #include <lwdyna.h>

   #define FLAG_NORTH (1<<0)
   #define FLAG_SOUTH (1<<1)
   #define FLAG_EAST  (1<<2)
   #define FLAG_WEST  (1<<3)

   DyBitfieldHint compass_hint[ 5 ] = {
      'n', FLAG_NORTH,
      's', FLAG_SOUTH,
      'e', FLAG_EAST,
      'w', FLAG_WEST,
      0, 0
   };
   DynaStringHint hint = { NULL, compass_hint };
   DynaValue
      dystr = { DY_STRING },
      dyint = { DY_INTEGER };
   DynaConvertFunc *dynacvt;
   int result;

   dynacvt = global( LWDYNACONVERTFUNC_GLOBAL, GFUSE_TRANSIENT );
   if ( !dynacvt ) return AFUNC_BADGLOBAL;

   dystr.str.buf = "ns";
   result = dynacvt( &dystr, &dyint, &hint );

   if ( result == DYERR_NONE ) {
      ...dyint.intv.value should contain FLAG_NORTH | FLAG_SOUTH...