An element of structured data. More...

#include <Element.hpp>

Public Member Functions
	Element (const char *name)
	Creates a new Element with the given name.

	Element (struct stumpless_element *element)
	Creates an Element from a stumpless_element struct.

	Element (const Element &element)
	Creates an Element as a copy of another Element.

	~Element (void)

Element &	AddParam (Param &new_param)
	Adds a Param to this Element.

Element &	AddParam (Param *new_param)
	Adds a Param to this Element.

Element &	AddParam (const char param_name, const char param_value)
	Creates a new param with the given name and value and adds it to this Element.

const char *	GetName (void)
	The name of this Element.

Param	GetParam (size_t index)
	Returns the param in the given element at the specified index.

Param	GetParam (const char *name)
	Returns the first param in this element with the given name.

size_t	GetParamCount (void)
	Returns the number of params in the given element.

size_t	GetParamIndex (const char *name)
	Gets the index of the first occurrence of a Param with the given name in this Element.

const char *	GetParamName (size_t index)
	Gets the name of the Param with the given index in this Element.

size_t	GetParamNameCount (const char *name)
	Gives the number of params with the given name found in this Element.

const char *	GetParamValue (size_t index)
	Returns the value of the param at the given index in this Element.

const char *	GetParamValue (const char *name)
	Returns the value of the first param with the given name in this Element.

bool	HasParam (const char *name)
	True if this Element has a Param with the given name, false otherwise.

Element &	SetName (const char *name)
	Set the name of this Element.

Element &	SetParam (size_t index, Param *param)
	Puts the param at the given index in this Element.

Element &	SetParamValue (size_t index, const char *value)
	Sets the value of the Param at the given index in this Element.

Element &	SetParamValue (const char name, const char value)
	Sets the value of the first Param with the given name in this element.

Public Attributes
struct stumpless_element *	equivalent

Detailed Description

An element of structured data.

Elements must have a name, but may not have any parameters. Their components must comply with RFC 5424.

Constructor & Destructor Documentation

◆ Element() [1/3]

stumpless::Element::Element ( const char * name )

Creates a new Element with the given name.

Parameters

name	The name of the element.

◆ Element() [2/3]

stumpless::Element::Element ( struct stumpless_element * element )

Creates an Element from a stumpless_element struct.

Available since release v1.6.0.

Parameters

element The struct to create this Element from. The struct will be copied during this creation, and so any changes made to it after this call will not be reflected in the resulting instance.

◆ Element() [3/3]

stumpless::Element::Element ( const Element & element )

Creates an Element as a copy of another Element.

Available since release v1.6.0.

Parameters

element The Element to copy.

◆ ~Element()

stumpless::Element::~Element ( void )

Member Function Documentation

◆ AddParam() [1/3]

Element & stumpless::Element::AddParam	(	const char *	param_name,
		const char *	param_value )

Creates a new param with the given name and value and adds it to this Element.

Available since release v1.6.0.

Parameters

param_name	The name of the new Param.
param_value	The value of the new Param.

Returns: The modified Element.

◆ AddParam() [2/3]

Element & stumpless::Element::AddParam ( Param & new_param )

Adds a Param to this Element.

Parameters

new_param The Param to add to the Element.

Returns: The modified Element.

◆ AddParam() [3/3]

Element & stumpless::Element::AddParam ( Param * new_param )

Adds a Param to this Element.

Parameters

new_param The Param to add to the Element.

Returns: The modified Element.

◆ GetName()

const char * stumpless::Element::GetName ( void )

The name of this Element.

The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. In versions prior to v2.0.0, the returned pointer was to the internal buffer was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues. Available since release v1.6.0.

Returns: The name of this Element.

◆ GetParam() [1/2]

Param stumpless::Element::GetParam ( const char * name )

Returns the first param in this element with the given name.

Note that an element may contain as many instances of a param as desired according to RFC 5424, and therefore there may be other Params with the same name. If you simply need a count of params with a given name, then you can use GetParamNameCount to find this. If you need a reference to any other params, then you must loop through all params in the element using GetParam with an index, checking each name.

Available since release v1.6.0.

Parameters

name	The name of the param to get.

Returns: The param at the given index.

◆ GetParam() [2/2]

Param stumpless::Element::GetParam ( size_t index )

Returns the param in the given element at the specified index.

Available since release v1.6.0.

Parameters

index The index of the param to get.

Returns: The param at the given index.

◆ GetParamCount()

size_t stumpless::Element::GetParamCount ( void )

Returns the number of params in the given element.

Available since release v1.6.0.

Returns: The number of params this Element has.

◆ GetParamIndex()

size_t stumpless::Element::GetParamIndex ( const char * name )

Gets the index of the first occurrence of a Param with the given name in this Element.

Note that an element may contain as many instances of a param as desired according to RFC 5424, and therefore there may be other Params that this function does not recognize. If you simply need a count of params with a given name, then you can use GetParamNameCount to find this. If you need a reference to any other params, then you must loop through all params in the element using GetParam with an index, checking each name.

Available since release v1.6.0.

Parameters

name	The name of the Param to search for.

Returns: The index of the first Param with the given name. If no such Param is found, then a StumplessParamNotFound exception is thrown.

◆ GetParamName()

const char * stumpless::Element::GetParamName ( size_t index )

Gets the name of the Param with the given index in this Element.

The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. In versions prior to v2.0.0, the returned pointer was to the internal buffer was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues. Available since release v1.6.0.

Parameters

index The index of the param to get the name of.

Returns: The name of the Param at the given index. If there is no Param, or some other error occurs, a StumplessException will be thrown.

◆ GetParamNameCount()

size_t stumpless::Element::GetParamNameCount ( const char * name )

Gives the number of params with the given name found in this Element.

If you need to get an actual reference to any of these params beyond the first one, then you will need to loop through all params in the element using GetParam with an index, checking each name.

Available since release v1.6.0.

Parameters

name	The name of the Param to count.

Returns: The number of Params with the given name in this Element.

◆ GetParamValue() [1/2]

const char * stumpless::Element::GetParamValue ( const char * name )

Returns the value of the first param with the given name in this Element.

If you need to get the value of a param with the given name beyond the first one, then you will need to loop through all params in the element using GetParam with an index, checking each name. The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. In versions prior to v2.0.0, the returned pointer was to the internal buffer was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues. Available since release v1.6.0.

Parameters

name	The name of the Param to get the value of.

Returns: The value of the param at the given index.

◆ GetParamValue() [2/2]

const char * stumpless::Element::GetParamValue ( size_t index )

Returns the value of the param at the given index in this Element.

The returned character buffer must be freed by the caller when it is no longer needed to avoid memory leaks. In versions prior to v2.0.0, the returned pointer was to the internal buffer was not to be modified by the caller. This behavior changed in v2.0.0 in order to avoid thread safety issues. Available since release v1.6.0.

Parameters

index The index of the Param to get the value of.

Returns: The value of the param at the given index.

◆ HasParam()

bool stumpless::Element::HasParam ( const char * name )

True if this Element has a Param with the given name, false otherwise.

Available since release v1.6.0.

Parameters

name	The name of the Param to look for.

Returns: True if the Param is found, false if not.

◆ SetName()

Element & stumpless::Element::SetName ( const char * name )

Set the name of this Element.

Available since release v1.6.0.

Parameters

name	The new name.

Returns: The modified Element.

◆ SetParam()

Element & stumpless::Element::SetParam	(	size_t	index,
		Param *	param )

Puts the param at the given index in this Element.

The parameter previously at this position will be removed from the element, but it is NOT destroyed by this call. Callers must clean up this param separately.

A param cannot be set at an index position that does not already hold a Param. If this is attempted, then a StumplessIndexOutOfBounds exception is raised.

Available since release v1.6.0.

Parameters

index	The index to set to the Param.
param	The new Param to put at the index.

Returns: The modified Element.

◆ SetParamValue() [1/2]

Element & stumpless::Element::SetParamValue	(	const char *	name,
		const char *	value )

Sets the value of the first Param with the given name in this element.

If a Param of the given name is not found in this Element, one is created with the supplied name and value and added to the end of this Element.

If you need to set the value of a param with this name other than the first one, then you will need to loop through the params using GetParam with an index to find the params you want and then set the value using SetValue on the result.

Available since release v1.6.0.

Parameters

name	The name of the Param to set the Value of.
value	The new value of the Param with the given name.

Returns: The modified Element.

◆ SetParamValue() [2/2]

Element & stumpless::Element::SetParamValue	(	size_t	index,
		const char *	value )

Sets the value of the Param at the given index in this Element.

Available since release v1.6.0.

Parameters

index	The index of the Param to set the value of.
value	The new value of the Param at the given index.

Returns: The modified Element.

Member Data Documentation

◆ equivalent

struct stumpless_element* stumpless::Element::equivalent

The documentation for this class was generated from the following file:

Element.hpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Element() [1/3]

◆ Element() [2/3]

◆ Element() [3/3]

◆ ~Element()

Member Function Documentation

◆ AddParam() [1/3]

◆ AddParam() [2/3]

◆ AddParam() [3/3]

◆ GetName()

◆ GetParam() [1/2]

◆ GetParam() [2/2]

◆ GetParamCount()

◆ GetParamIndex()

◆ GetParamName()

◆ GetParamNameCount()

◆ GetParamValue() [1/2]

◆ GetParamValue() [2/2]

◆ HasParam()

◆ SetName()

◆ SetParam()

◆ SetParamValue() [1/2]

◆ SetParamValue() [2/2]

Member Data Documentation

◆ equivalent