valuestl.cpp

Open VXI. This is a open source.

 *
 * @return   New map on success, NULL otherwise
 */
VXIVALUE_API VXIMap *VXIMapCreate(void)
{
  return new VXIMap;
}


/**
 * Map destructor
 *
 * Note: this recursively destroys all the values contained within the
 * Map, including all the values of Maps and Vectors stored
 * within this map. However, for Ptr values the user is
 * responsible for freeing the held memory if appropriate.
 *
 * @param m   Map to destroy 
 */
VXIVALUE_API void VXIMapDestroy(VXIMap **m)
{
  if (( m ) && ( *m ) && ( (*m)->GetType( ) == VALUE_MAP )) {
    delete *m;
    *m = NULL;
  }
}


/**
 * Map clone
 *
 * Recursively copies all values contained within the map,
 * including all the values of Maps and Vectors stored within this
 * map.
 *
 * Note: functionally redundant with VXIValueClone( ), but provided to
 * reduce the need for C casts for this common operation
 *
 * @param    m   Map to clone
 * @return       Clone of the Map on success, NULL otherwise 
 */
VXIVALUE_API VXIMap *VXIMapClone(const VXIMap *m)
{
  if (( m == NULL ) || ( m->GetType( ) != VALUE_MAP ))
    return NULL;

  return new VXIMap (*m);
}


/**
 * Set a named property on an Map
 *
 * The value can be an Map so a tree can be constructed.
 *
 * If the property already exists, the existing value is first
 * destroyed using VXIValueDestroy( ) (thus recursively deleting held
 * values within it if it is an Map or Vector), then does the
 * set operation with the new value.
 *
 * @param   m     Map to access
 * @param   key   NULL terminated property name
 * @param   val   Value to set the property to, ownership is passed
 *                to the Map (a simple pointer copy is done), so on
 *                success the user must not delete, modify, or otherwise
 *                use this. Also be careful to not add a Map as a
 *                property of itself (directly or indirectly), otherwise
 *                infinite loops may occur on access or deletion.
 * @return        VXIvalue_RESULT_SUCCESS on success
 */
VXIVALUE_API VXIvalueResult VXIMapSetProperty(VXIMap         *m, 
					      const VXIchar  *key,
					      VXIValue       *val)
{
  if (( m == NULL ) || ( m->GetType( ) != VALUE_MAP ) ||
      ( key == NULL ) || ( key[0] == 0 ) || ( val == NULL ))
    return VXIvalue_RESULT_INVALID_ARGUMENT;

  // Destroy any existing element with that key
  VXIElement element (key, val);
  VXIMap::MAPSET::iterator vi = m->container.find (element);
  if ( vi != m->container.end( ) ) {
    (*vi).DestroyValue( );
    m->container.erase (vi);
  }

  // Insert the new element
  std::pair<VXIMap::MAPSET::iterator, bool> rc = m->container.insert (element);
  if ( rc.second != true ) {
    return VXIvalue_RESULT_OUT_OF_MEMORY;
  } else if ( (*rc.first).GetValue( ) == NULL ) {
    // Ran out of memory, erase the corrupt value
    (*rc.first).DestroyValue( );
    m->container.erase (rc.first);
    return VXIvalue_RESULT_OUT_OF_MEMORY;
  }

  return VXIvalue_RESULT_SUCCESS;
}


/**
 * Get a named property from an Map
 *
 * The property value is returned for read-only access and is
 * invalidated if the Map is modified. The client must clone it if
 * they wish to perform modifications or wish to retain the value even
 * afer modifying this Map.
 *
 * @param   m     Map to access
 * @param   key   NULL terminated property name
 * @return        On success the value of the property for read-only 
 *                access (invalidated if the Map is modified), NULL
 *                if the property was never set or was deleted 
 */
VXIVALUE_API const VXIValue *VXIMapGetProperty(const VXIMap    *m, 
					       const VXIchar   *key)
{
  if (( m == NULL ) || ( m->GetType( ) != VALUE_MAP ) || 
      ( key == NULL ) || ( key[0] == 0 ))
    return NULL;

  // Find the element with that key
  VXIElement element (key, NULL);
  VXIMap::MAPSET::const_iterator vi = m->container.find (element);
  if ( vi != m->container.end( ) )
    return (*vi).GetValue( );

  return NULL;
}


/**
 * Delete a named property from an Map
 *
 * This does a VXIValueDestroy( ) on the value for the named property
 * (thus recursively deleting held values within it if it is an Map
 * or Vector). However, for Ptr properties the user is responsible for
 * freeing the held memory if appropriate.
 *
 * @param   m     Map to access
 * @param   key   NULL terminated property name
 * @return        VXIvalue_RESULT_SUCCESS on success 
 */
VXIVALUE_API VXIvalueResult VXIMapDeleteProperty(VXIMap         *m, 
						 const VXIchar  *key)
{
  if (( m == NULL ) || ( m->GetType( ) != VALUE_MAP ) || 
      ( key == NULL ) || ( key[0] == 0 ))
    return VXIvalue_RESULT_INVALID_ARGUMENT;

  // Destroy any existing element with that key
  VXIElement element (key, NULL);
  VXIMap::MAPSET::iterator vi = m->container.find (element);
  if ( vi == m->container.end( ) )
    return VXIvalue_RESULT_FAILURE;

  (*vi).DestroyValue( );
  m->container.erase (vi);
  return VXIvalue_RESULT_SUCCESS;
}


/**
 * Return the number of properties for an Map
 *
 * Note: this only returns the number of properties that are direct
 * children of the Map, it does not include the number of properties
 * held in Maps and Vectors stored within this map.
 *
 * @param   m   Map to access
 * @return      Number of properties stored in the Map
 */
VXIVALUE_API VXIunsigned VXIMapNumProperties(const VXIMap *m)
{
  if (( m == NULL ) || ( m->GetType( ) != VALUE_MAP ))
    return 0;

  return m->container.size( );
}


/**
 * Get the first property of an Map and an iterator
 *
 * Note: this is used to traverse all the properties within an map,
 * there is no guarantee on what order the properties will be
 * returned. The iterator must be eventually freed with
 * VXIMapIteratorDestroy( ), and is invalidated if the Map is
 * modified in any way.
 *
 * @param   m      Map to access
 * @param   key    Set to point at the property name for read-only 
 *                 access (must not be modified)                 
 * @param   value  Set to point at the property value for read-only 
 *                 access (must not be modified)
 * @return         Pointer to an iterator that may be used to get
 *                 additional properties via VXIMapGetNextProperty( ),
 *                 or NULL on failure (typically no properties in the map)
 */
VXIVALUE_API 
VXIMapIterator *VXIMapGetFirstProperty(const VXIMap     *m,
				       const VXIchar   **key,
				       const VXIValue  **value)
{
  if (( m == NULL ) || ( m->GetType( ) != VALUE_MAP ) ||
      ( m->container.size( ) == 0 ) || ( key == NULL ) || ( value == NULL ))
    return NULL;

  // Allocate an iterator map
  VXIMapIterator *it = new VXIMapIterator (m);
  if ( it == NULL )
    return NULL;
  
  // Get the first property
  it->GetKeyValue (key, value);
  return it;
}


/**
 * Get the next property of an Map based on an iterator
 *
 * Note: this is used to traverse all the properties within an map,
 * there is no gaurantee on what order the properties will be
 * returned.
 *
 * @param   it     Iterator used to access the map as obtained
 *                 from VXIMapGetFirstProperty( ), this operation
 *                 will advance the iterator to the next property on
 *                 success
 * @param   key    Set to point at the property name for read-only 
 *                 access (must not be modified, invalidated if the
 *                 Map is modified)                 
 * @param   value  Set to point at the property value for read-only 
 *                 access (must not be modified, invalidated if the
 *                 Map is modified)
 * @return         VXIvalue_RESULT_SUCCESS on success (property name 
 *                 and value returned, iterator advanced), 
 *                 VXIvalue_RESULT_FAILURE if there are no more properties
 *                 to read, or a VXIvalueResult error code for severe errors
 */
VXIVALUE_API VXIvalueResult VXIMapGetNextProperty(VXIMapIterator  *it,
						  const VXIchar  **key,
						  const VXIValue **value)
{
  if (( it == NULL ) || ( key == NULL ) || ( value == NULL ))
    return VXIvalue_RESULT_INVALID_ARGUMENT;

  (*it)++;
  return it->GetKeyValue (key, value);
}


/**
 * Destroy an iterator
 *
 * @param   it     Iterator to destroy as obtained from 
 *                 VXIMapGetFirstProperty( )
 */
VXIVALUE_API void VXIMapIteratorDestroy(VXIMapIterator **it)
{
  if (( it ) && ( *it )) {
    delete *it;
    *it = NULL;
  }
}


/**
 * Create an empty Vector
 *
 * @return   New vector on success, NULL otherwise
 */
VXIVALUE_API VXIVector *VXIVectorCreate(void)
{
  return new VXIVector;
}


/**
 * Vector destructor
 *
 * Note: this recursively destroys all the values contained within the
 * Vector, including all the values of Vectors stored within this
 * vector. However, for Ptr values the user is responsible for
 * freeing the held memory if appropriate.
 *
 * @param   v   Vector to destroy 
 */
VXIVALUE_API void VXIVectorDestroy(VXIVector **v)
{
  if (( v ) && ( *v ) && ( (*v)->GetType( ) == VALUE_VECTOR )) {
    delete *v;
    *v = NULL;
  }
}


/**
 * Vector clone
 *
 * Recursively copies all values contained within the vector,
 * including all the values of Vectors and Maps stored within this
 * vector.
 *
 * Note: functionally redundant with VXIValueClone( ), but provided to
 * reduce the need for C casts for this common operation
 *
 * @param    v   Vector to clone
 * @return Clone of the Vector on success, NULL otherwise */
VXIVALUE_API VXIVector *VXIVectorClone(const VXIVector *v)
{
  if (( v == NULL ) || ( v->GetType( ) != VALUE_VECTOR ))
    return NULL;

  return new VXIVector (*v);
}


/**
 * Adds an element to the end of the Vector
 *
 * The value can be a Vector so frames can be implemented.
 *
 * @param   v    Vector to access
 * @param   val  Value to append to the vector, ownership is passed
 *               to the Vector (a simple pointer copy is done), so on
 *               success the user must not delete, modify, or otherwise
 *               use this. Also be careful to not add a Vector as a
 *               element of itself (directly or indirectly), otherwise
 *               infinite loops may occur on access or deletion.
 * @return       VXIvalue_RESULT_SUCCESS on success
 */
VXIVALUE_API VXIvalueResult VXIVectorAddElement(VXIVector      *v, 
						VXIValue       *val)
{
  if (( v == NULL ) || ( v->GetType( ) != VALUE_VECTOR ) || 
      ( val == NULL ))
    return VXIvalue_RESULT_INVALID_ARGUMENT;

  // Insert the new element
  VXIElement element (L"", val);
  v->container.push_back (element);
  return VXIvalue_RESULT_SUCCESS;
}


/**
 * Set an indexed vector element
 *
 * Overwrites the specified element with the new value. The existing
 * value is first destroyed using VXIValueDestroy( ) (thus recursively
 * deleting held values within it if it is an Map or Vector), then
 * does the set operation with the new value.
 *
 * The value can be a Vector so frames can be implemented.
 *
 * @param   v     Vector to access
 * @param   n     Element index to set, it is an error to pass a
 *                index that is greater then the number of values
 *                currently in the vector
 * @param   val   Value to set the element to, ownership is passed
 *                to the Vector (a simple pointer copy is done), so on
 *                success the user must not delete, modify, or otherwise
 *                use this. Also be careful to not add a Vector as a
 *                element of itself (directly or indirectly), otherwise
 *                infinite loops may occur on access or deletion.
 * @return        VXIvalue_RESULT_SUCCESS on success
 */
VXIVALUE_API VXIvalueResult VXIVectorSetElement(VXIVector      *v, 
						VXIunsigned     n, 
						VXIValue       *val)
{
  if (( v == NULL ) || ( v->GetType( ) != VALUE_VECTOR ) || 
      ( val == NULL ) || ( n >= v->container.size( ) ))
    return VXIvalue_RESULT_INVALID_ARGUMENT;

  // Set the element
  v->container[n].SetValue (val, true);
  return VXIvalue_RESULT_SUCCESS;
}


/**
 * Get an indexed vector element
 *
 * The element value is returned for read-only access and is
 * invalidated if the Vector is modified. The client must clone it if
 * they wish to perform modifications or wish to retain the value even
 * after modifying this Vector.
 *
 * @param   v     Vector to access
 * @param   n     Element index to set, it is an error to pass a
 *                index that is greater or equal to then the number of values
 *                currently in the vector (i.e. range is 0 to length-1)
 * @return        On success the value of the property for read-only 
 *                access (invalidated if the Vector is modified), NULL
 *                on error 
 */
VXIVALUE_API const VXIValue *VXIVectorGetElement(const VXIVector *v, 
						 VXIunsigned      n)
{
  if (( v == NULL ) || ( v->GetType( ) != VALUE_VECTOR ) ||
      ( n >= v->container.size( ) ))
    return NULL;

  return v->container[n].GetValue( );
}


/**
 * Return number of elements in a Vector
 *
 * This computes only the length of the Vector, elements within
 * Vectors and Maps within it are not counted.
 *
 * @param   v    Vector to access
 * @return       Number of elements stored in the Vector
 */
VXIVALUE_API VXIunsigned VXIVectorLength(const VXIVector *v)
{
  if (( v == NULL ) || ( v->GetType( ) != VALUE_VECTOR ))
    return 0;

  return v->container.size( );
}