#include <blpapi_element.h>

Public Member Functions
	Element ()

	Element (blpapi_Element_t *element)

void	rebind (blpapi_Element_t *element)

void	setElement (const char *name, bool value)

void	setElement (const char *name, char value)

void	setElement (const char *name, Int32 value)

void	setElement (const char *name, Int64 value)

void	setElement (const char *name, Float32 value)

void	setElement (const char *name, Float64 value)

void	setElement (const char *name, const Datetime &value)

void	setElement (const char name, const char value)

void	setElement (const char *name, const Name &value)

void	setElement (const Name &name, bool value)

void	setElement (const Name &name, char value)

void	setElement (const Name &name, Int32 value)

void	setElement (const Name &name, Int64 value)

void	setElement (const Name &name, Float32 value)

void	setElement (const Name &name, Float64 value)

void	setElement (const Name &name, const Datetime &value)

void	setElement (const Name &name, const char *value)

void	setElement (const Name &name, const std::string &value)

void	setElement (const Name &name, const Name &value)

void	setElement (const Name &name, const void *value, size_t length)

template<typename BYTES , typename std::enable_if< IsByteSequence< BYTES >::value, bool >::type = true>
void	setElement (const Name &name, const BYTES &value)

void	setValue (bool value, size_t index=0)

void	setValue (char value, size_t index=0)

void	setValue (Int32 value, size_t index=0)

void	setValue (Int64 value, size_t index=0)

void	setValue (Float32 value, size_t index=0)

void	setValue (Float64 value, size_t index=0)

void	setValue (const Datetime &value, size_t index=0)

void	setValue (const char *value, size_t index=0)

void	setValue (const std::string &value, size_t index=0)

void	setValue (const Name &valueName, size_t index=0)

void	setValue (const void *value, size_t length, size_t index)

template<typename BYTES , typename std::enable_if< IsByteSequence< BYTES >::value, bool >::type = true>
void	setValue (const BYTES &value, size_t index=0)

void	appendValue (bool value)

void	appendValue (char value)

void	appendValue (Int32 value)

void	appendValue (Int64 value)

void	appendValue (Float32 value)

void	appendValue (Float64 value)

void	appendValue (const Datetime &value)

void	appendValue (const char *value)

void	appendValue (const std::string &value)

void	appendValue (const Name &value)

Element	appendElement ()

Element	setChoice (const char *selectionName)

Element	setChoice (const Name &selectionName)

blpapi_Element_t *	handle ()

Name	name () const

int	datatype () const

bool	isComplexType () const

bool	isArray () const

bool	isNull () const

bool	isReadOnly () const

SchemaElementDefinition	elementDefinition () const

size_t	numValues () const

size_t	numElements () const

bool	isValid () const

bool	isNullValue (size_t position=0) const

bool	hasElement (const char *name, bool excludeNullElements=false) const

bool	hasElement (const Name &name, bool excludeNullElements=false) const

int	getValueAs (bool *result, size_t index=0) const

int	getValueAs (char *result, size_t index=0) const

int	getValueAs (Int32 *result, size_t index=0) const

int	getValueAs (Int64 *result, size_t index=0) const

int	getValueAs (Float32 *result, size_t index=0) const

int	getValueAs (Float64 *result, size_t index=0) const

int	getValueAs (Datetime *result, size_t index=0) const

int	getValueAs (std::string *result, size_t index=0) const

int	getValueAs (Bytes *result, size_t index=0) const

int	getValueAs (Element *result, size_t index=0) const

int	getValueAs (Name *result, size_t index=0) const

bool	getValueAsBool (size_t index=0) const

char	getValueAsChar (size_t index=0) const

Int32	getValueAsInt32 (size_t index=0) const

Int64	getValueAsInt64 (size_t index=0) const

Float32	getValueAsFloat32 (size_t index=0) const

Float64	getValueAsFloat64 (size_t index=0) const

Datetime	getValueAsDatetime (size_t index=0) const

const char *	getValueAsString (size_t index=0) const

Bytes	getValueAsBytes (size_t index=0) const

Element	getValueAsElement (size_t index=0) const

Name	getValueAsName (size_t index=0) const

int	getElement (Element result, const char name) const

int	getElement (Element *result, const Name &name) const

int	getElement (Element *result, size_t position) const

Element	getElement (size_t position) const

Element	getElement (const Name &name) const

Element	getElement (const char *name) const

bool	getElementAsBool (const char *name) const

bool	getElementAsBool (const Name &name) const

char	getElementAsChar (const char *name) const

char	getElementAsChar (const Name &name) const

Int32	getElementAsInt32 (const char *name) const

Int32	getElementAsInt32 (const Name &name) const

Int64	getElementAsInt64 (const char *name) const

Int64	getElementAsInt64 (const Name &name) const

Float32	getElementAsFloat32 (const char *name) const

Float32	getElementAsFloat32 (const Name &name) const

Float64	getElementAsFloat64 (const char *name) const

Float64	getElementAsFloat64 (const Name &name) const

Datetime	getElementAsDatetime (const char *name) const

Datetime	getElementAsDatetime (const Name &name) const

const char *	getElementAsString (const char *name) const

const char *	getElementAsString (const Name &name) const

Bytes	getElementAsBytes (const Name &name) const

Name	getElementAsName (const char *name) const

Name	getElementAsName (const Name &name) const

Element	getChoice () const

const blpapi_Element_t *	handle () const

std::ostream &	print (std::ostream &stream, int level=0, int spacesPerLevel=4) const

Detailed Description

Element represents an item in a message.

An Element can represent: a single value of any data type supported by the Bloomberg API; an array of values; a sequence or a choice.

The value(s) in an Element can be queried in a number of ways. For an Element which represents a single value or an array of values use the getValueAs() functions or getValueAsBool() etc. For an Element which represents a sequence or choice use getElementAsBool() etc. In addition, for choices and sequences, hasElement() and getElement() are useful.

This example shows how to access the value of a scalar element s as a floating point number:

float f = s.getValueAsFloat32();

Similarly, this example shows how to retrieve the third value in an array element a, as a floating pointer number:

float f = a.getValueAsFloat32(2);

Use numValues() to determine the number of values available. For single values, it will return either 0 or 1. For arrays it will return the actual number of values in the array.

To retrieve values from a complex element types (sequences and choices) use the getElementAs...() family of methods. This example shows how to get the value of the element city in the sequence element address:

static const Name k_city { "city" };

const char* city = address.getElementAsString(k_city);

The value(s) of an Element can be set in a number of ways. For an Element which represents a single value or an array of values use the setValue() or appendValue() functions. For an element which represents a sequence or a choice use the setElement() functions.

This example shows how to set the value of an Element s from an integer:

Int32 value=5;

s.setValue(value);

This example shows how to append an integer a value to an array element a:

Int32 value=5;

s.appendValue(value);

To set values in a complex element (a sequence or a choice) use the setElement() family of functions. This example shows how to set the value of the element city in the sequence element address to a string.

static const Name k_city { "city" };
Element address;
...
address.setElement(k_city, "New York");

The API will convert data types as long as there is no loss of precision involved. So:

A BOOL can be returned as bool, char, Int32, Int64, Float32, Float64, std::string (the string will be "true" or "false")
A BOOL can be set from bool, std::string (if it has a value of "y", "n", "yes", "no", "true" or "false")
A CHAR can be returned as char, Int32, Int64, Float32, Float64, std::string
A CHAR can be set from char
An INT32 can be returned as Int32, Int64, Float64, std::string
An INT32 can be set from char, Int32, Int64 if the value is in Int32 range.
An INT64 can be returned as Int64, std::string
An INT64 can be set from char, Int32, Int64
A FLOAT32 can be returned as Float32, Float64, std::string
A FLOAT32 can be set from char
A FLOAT64 can be returned as Float64, std::string
A FLOAT64 can be set from char, Int32, Float32
A STRING can be returned as std::string, Name
A STRING can be set from bool (the string will be set to "true" or "false"), char, Int32, Int64, Float32, Float64, Name
A DATETIME can be returned as Datetime
A DATETIME can be set from Datetime
A BYTEARRAY can be set from a type that represents a contiguous sequence of bytes and returned as blpapi::Bytes.

See Component blpapi_element

Constructor & Destructor Documentation

◆ Element() [1/2]

Element ( )

Create an uninitialized Element. The only valid operations to perform on an uninitialized Element are assignment, isValid() and destruction.

◆ Element() [2/2]

Element ( blpapi_Element_t * element )

explicit

Member Function Documentation

◆ appendElement()

Element appendElement ( )

If this Element is an array of sequence or choice Elements, then append an element to this element and return the appended element; otherwise an exception is thrown.

◆ appendValue() [1/10]

void appendValue ( bool value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [2/10]

void appendValue ( char value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [3/10]

void appendValue ( Int32 value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [4/10]

void appendValue ( Int64 value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [5/10]

void appendValue ( Float32 value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [6/10]

void appendValue ( Float64 value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [7/10]

void appendValue ( const Datetime & value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [8/10]

void appendValue ( const char * value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ appendValue() [9/10]

void appendValue ( const std::string & value )

Appends the specified value to this Element as the last element. An exception is thrown if this Element's DataType means it cannot be initialized from an instance of the supplied value, or if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues(). The behaviour is undefined if the specified value contains embedded zero-characters.

◆ appendValue() [10/10]

void appendValue ( const Name & value )

Appends the specified value to this Element as the last element. An exception is thrown if this element's datatype is not an enumeration type, or if value does not refer to a constant in the enumeration type of this element. An exception is also thrown if the current size of this Element (numValues()) is equal to the maximum defined by elementDefinition().maxValues().

◆ datatype()

int datatype ( ) const

Return the basic data type used to represent a value in this element as an integer specified by the blpapi_DataType_t enumeration defined in blpapi_types.h.

◆ elementDefinition()

SchemaElementDefinition elementDefinition ( ) const

Return a reference to the read-only element definition object that defines the properties of this elements value.

◆ getChoice()

Element getChoice ( ) const

Return the selection name of this element if this element is a "choice" element. Otherwise, an exception is thrown.

◆ getElement() [1/6]

int getElement	(	Element *	result,
		const char *	name
	)		const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name then load that element into the specified result and return 0; otherwise, return an error (non-zero). The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElement() [2/6]

int getElement	(	Element *	result,
		const Name &	name
	)		const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name then load that element into the specified result and return 0; otherwise, return an error (non-zero). The behavior of this function is undefined if name is uninitialized.

◆ getElement() [3/6]

int getElement	(	Element *	result,
		size_t	position
	)		const

If this Element is either a sequence or a choice and numElements() is greater than the specified position, then load the element at position into the specified result and return 0; otherwise return an error (non-zero).

◆ getElement() [4/6]

Element getElement ( size_t position ) const

If this Element is either a sequence or a choice and numElements() is greater than the specified position return the positionth element. Otherwise, an exception is thrown.

◆ getElement() [5/6]

Element getElement ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name, then return that Element. Otherwise, an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElement() [6/6]

Element getElement ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name, then return that Element. Otherwise, an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsBool() [1/2]

bool getElementAsBool ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a bool then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsBool() [2/2]

bool getElementAsBool ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a bool then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsBytes()

Bytes getElementAsBytes ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a byte array, then a byte array struct is returned. The pointer remains valid until this Element is destroyed. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsChar() [1/2]

char getElementAsChar ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a char then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsChar() [2/2]

char getElementAsChar ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a char then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsDatetime() [1/2]

Datetime getElementAsDatetime ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a Datetime then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string. Note this function will not necessarily set all fields of the returned value – callers should check rv.hasParts(...) or rv.parts() before accessing the fields of the returned value rv.

◆ getElementAsDatetime() [2/2]

Datetime getElementAsDatetime ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as Datetime then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized. Note that this function will not necessarily set all fields of the returned value – callers should check rv.hasParts(...) or rv.parts() before accessing the fields of the returned value rv.

◆ getElementAsFloat32() [1/2]

Float32 getElementAsFloat32 ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a Float32 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsFloat32() [2/2]

Float32 getElementAsFloat32 ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a Float32 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsFloat64() [1/2]

Float64 getElementAsFloat64 ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a Float64 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsFloat64() [2/2]

Float64 getElementAsFloat64 ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a Float64 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsInt32() [1/2]

Int32 getElementAsInt32 ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as an Int32 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsInt32() [2/2]

Int32 getElementAsInt32 ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as an Int32 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsInt64() [1/2]

Int64 getElementAsInt64 ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as an Int64 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsInt64() [2/2]

Int64 getElementAsInt64 ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as an Int64 then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsName() [1/2]

Name getElementAsName ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a Name then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsName() [2/2]

Name getElementAsName ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a Name then its value is returned. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.

◆ getElementAsString() [1/2]

const char * getElementAsString ( const char * name ) const

Deprecated:: Use the form that takes Name instead of const char*.

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a null-terminated string then a pointer to a string is returned. The pointer remains valid until this Element is destroyed. Otherwise an exception is thrown. The behavior of this function is undefined unless name is a valid null-terminated string.

◆ getElementAsString() [2/2]

const char * getElementAsString ( const Name & name ) const

If this Element is either a sequence or a choice and contains a valid Element identified by the specified name which can be returned as a null-terminated string then a pointer to a string is returned. The pointer remains valid until this Element is destroyed. Otherwise an exception is thrown. The behavior of this function is undefined if name is uninitialized.