Wrapper class for the UA stack structure OpcUa_String. More...

#include <uastring.h>

Public Member Functions
	UaString ()
	Default constructor. More...

	UaString (const OpcUa_String *other)
	Creates a copy of the native OpcUa_String. More...

	UaString (const OpcUa_String &other)
	Creates a copy of the native OpcUa_String. More...

	UaString (const UaString &other)
	Creates a copy of another UaString. More...

	UaString (const UaByteString &other)
	Creates a string initialized with the byte array `other`. More...

	UaString (const char *other)
	Creates a copy of a UTF-8 encoded character string. More...

	UaString (const UaUShort *other)
	Creates a copy of a UTF-16 encoded wide character string. More...

	~UaString ()
	Destroys the string. More...

UaString &	operator= (const UaString &other)
	Assigns `other` to this string and returns a reference to this string. More...

OpcUa_String *	detach (OpcUa_String *pDst)
	Detaches the internal String structure from this class. More...

int	size () const
	Returns the size in bytes that the internal UTF-8 representation needs to hold this string. More...

int	length () const
	Returns the number of characters of this string. More...

bool	isEmpty () const
	Returns true if the string is empty. More...

bool	isNull () const
	Returns true if the string is null. More...

const UaChar	at (int i) const
	Returns a read only unicode character. More...

int	find (UaChar cFind) const
	Finds the position of a UTF-8 character in the string. More...

int	find (UaChar cFind, unsigned int iStart) const
	Finds the position of a UTF-8 character in the string after start index. More...

bool	like (const UaString &pattern) const
	Implements the Like operator of the UA Specification. More...

bool	operator== (const UaString &other) const
	Returns true if `other` is equal to this. More...

bool	operator!= (const UaString &other) const
	Returns true if `other` is not equal to `this`. More...

bool	operator< (const UaString &other) const
	This operator is mainly used to sort strings. More...

UaString &	operator+= (const UaString &other)
	Appends a string to the internal string. More...

UaString	operator+ (const UaString &other)
	Addition operator. More...

UaString	arg (const UaString &a, int fieldWidth=0, const UaChar &fillChar=UaChar(' ')) const
	Returns a copy of this string with the lowest numbered place marker replaced by string a, i.e., %1, %2, ..., %99. More...

OpcUa_String *	copy () const
	Creates an independent copy of this string as OpcUa_String. More...

void	copyTo (OpcUa_String *pDst) const
	Copies the string contents into an existing OpcUa_String. More...

const OpcUa_String *	toOpcUaString () const
	Returns an OpcUa_String to be able to pass this string to low level OPC UA stack functions. More...

	operator const OpcUa_String * () const
	This implicitly casts this string to an OpcUa_String to be able to pass it to low level OPC UA stack functions. More...

const char *	toUtf8 () const
	Returns the string as a '\0'-terminated array of characters. More...

UaByteArray	toUtf16 () const
	Returns a UTF-16 representation of the string as a UaByteArray. More...

Static Public Member Functions
static bool	isLikePatternValid (const UaString &pattern)
	Tests if a given Like-Pattern is valid or not. More...

static UaString	number (int n, int base=10)
	Returns a string equivalent of the number `n` to base `base`, which is 10 by default and must be between 2 and 36. More...

static UaString	number (unsigned int n, int base=10)
	Returns a string equivalent of the number `n` to base `base`, which is 10 by default and must be between 2 and 36. More...

static OpcUa_String *	clone (const OpcUa_String &source)
	This is a convenience function to clone a native OpcUa_String that is used in the OPC UA ANSI C Stack. More...

static void	cloneTo (const OpcUa_String &source, OpcUa_String &copy)
	This is a convenience function and behaves like the function clone. More...

Friends
UABASE_EXPORT UaDataStream &	operator<< (UaDataStream &, const UaString &)
	define UaDataStream operators for UaString. More...

Detailed Description

Wrapper class for the UA stack structure OpcUa_String.

Helper class for handling the OPC UA built-in data type String. It provides conversion, comparison and string creation functions and handles memory allocation and clean-up.

The OPC UA built-in data type String defines a Unicode character string that should exclude control characters that are not whitespaces. All String values are encoded as a sequence of UTF8 characters. Therefore the internal representation is using the wire format to avoid data copying.

Since the internal representation of a String in the class UaString is UTF8 encoded, the class does not provide string manipulation functions. The class UaUniString provides string manipulation functions. The necessary conversion to UTF-16 is provided by toUtf16. The native string can be extracted as char* with toUtf8.

UaString myString("This is the string to process");
UaUniString myTempString(myString.toUtf16());
myTempString.replace("string", "text");
myString = myTempString.toUtf16();
printf("%s", myString.toUtf8());
// Output is "This is the text to process"

A string can be created with arg, appended with operator+ and operator+= and created from different string formats and a number.

UaString myString;
UaString sTemp("variable string");
int iTemp = 5;
// Create the string "5 times variable string" from variables
myString = UaString::number(iTemp);
myString += " times ";
myString += sTemp;
// The following option is more efficient
myString = UaString("%1 times %2").arg(iTemp).arg(sTemp);

UaString uses implicit sharing to avoid needless copying and to boost the performance. Only if you modify a shared string it creates a copy for that (copy-on-write). So assigning another UaString or passing it as parameter needs constant time is nearly as fast as assigning a pointer.

Constructor & Destructor Documentation

UaString::UaString ( )

Default constructor.

Creates an empty UaString.

UaString::UaString ( const OpcUa_String * other )

Creates a copy of the native OpcUa_String.

Parameters

other Source string.

UaString::UaString ( const OpcUa_String & other )

Creates a copy of the native OpcUa_String.

Parameters

other Source string.

UaString::UaString ( const UaString & other )

Creates a copy of another UaString.

This operation takes constant time, because UaString is implicitly shared. This makes returning a UaString from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and that takes linear time.

Parameters

other the UaString.

UaString::UaString ( const UaByteString & other )

Creates a string initialized with the byte array other.

The given data is interpreted as UTF-8.

Stops copying at the first 0 character, otherwise copies the entire byte array. If the array is not 0 terminated, a 0 will be appended.

If the ByteString is empty (length=0), an empty string is created If the ByteString is null (length=-1), a null string is created

Parameters

other the byte array to copy.

UaString::UaString ( const char * other )

Creates a copy of a UTF-8 encoded character string.

This operation assumes that other is UTF-8 encoded. You may also pass pure ASCII strings with characters below 128. The first 128 characters from US-ASCII (Unicode range U+0000 to U+007F) are a subset of UTF-8.

UaString sample("abc");

Don't use unicode characters in hard-coded strings unless you know what you are doing. This will only work if you save your source file UTF-8 encoded.

UaString sample("öäü"); // DANGER!!!

Parameters

other the const char.

UaString::UaString ( const UaUShort * other )

Creates a copy of a UTF-16 encoded wide character string.

This is typically used on Windows with wchar_t* strings.

Parameters

other the UaUShort.

UaString::~UaString ( )

Destroys the string.

Member Function Documentation

UaString UaString::arg	(	const UaString &	a,
		int	fieldWidth = `0`,
		const UaChar &	fillChar = `UaChar(' ')`
	)		const

Returns a copy of this string with the lowest numbered place marker replaced by string a, i.e., %1, %2, ..., %99.

// This example shows how we might create a status string for reporting progress while processing a list of files:
UaString i;           // current file's number
UaString total;       // number of files to process
UaString fileName;    // current file's name
// First, arg(i) replaces %1. Then arg(total) replaces %2. Finally, arg(fileName) replaces %3.
UaString status = UaString("Processing file %1 of %2: %3")
                .arg(i).arg(total).arg(fileName);

Parameters

a	String to replace the lowest numbered place marker with.
fieldWidth	specifies the minimum amount of space that argument `a` shall occupy. If `a` requires less space than `fieldWidth`, it is padded to `fieldWidth` with character `fillChar`. A positive `fieldWidth` produces right-aligned text. A negative `fieldWidth` produces left-aligned text.
fillChar	If `a` requires less space than `fieldWidth`, it is padded to `fieldWidth` with character `fillChar`.

Returns: Returns a copy of this string with the lowest numbered place marker replaced.

const UaChar UaString::at ( int i ) const

Returns a read only unicode character.

Because UTF-8 is from variable length you cannot simply change a character. Other may need to be moved.

See also: replace()

Parameters

i	the position of the actual char in the string.

Returns: a read only unicode character.

OpcUa_String * UaString::clone ( const OpcUa_String & source )

static

This is a convenience function to clone a native OpcUa_String that is used in the OPC UA ANSI C Stack.

This works without creating an instance of UaString.

Parameters

source The source string to clone.

Returns: A new OpcUa_String copy. You are responsible for deleting this string.

void UaString::cloneTo	(	const OpcUa_String &	source,
		OpcUa_String &	copy
	)

static

This is a convenience function and behaves like the function clone.

The difference is that it copies the string into an existing OpcUa_String instead of allocating a new structure. This may be used to fill an OpcUa_String that is embedded in another structure.

Parameters

source	The source string to clone.
copy	The destination string to copy the string contents to.

OpcUa_String * UaString::copy ( ) const

Creates an independent copy of this string as OpcUa_String.

Use this function if you need a copy of this string that is freed from the OPC UA stack. The returned string must be freed with OpcUa_String_Delete.

Returns: an independent copy of this string as OpcUa_String.

void UaString::copyTo ( OpcUa_String * pDst ) const

Copies the string contents into an existing OpcUa_String.

Use this function if you need to fill an OpcUa_String that is nested in another OPC UA structure.

Example:

 UaString sNodeId("Path/to/Node");
 OpcUa_NodeId id;
 id.IdentifierType = OpcUa_IdentifierType_String;
 sNodeId.copyTo(&id.Identifier.String);

Parameters

pDst	the destination of this copy operation.

OpcUa_String * UaString::detach ( OpcUa_String * pDst )

Detaches the internal String structure from this class.

This way you take over the control of releasing the String data. You can only detach the data if not more than one references exists.

It is strongly recommended to use the check in the following sample code and to do a deep copy if detach fails.

UaString     uaString;
UaString     uaString2;
OpcUa_String rawString;
OpcUa_String_Initialize(&rawString);
// If the following line of code is commented in, detach fails
// uaString2 = uaString;
// Try to detach the DataValue from the wrapper class
if ( NULL == uaString.detach(&rawString) )
{
    // Create a deep copy since the internal data is
    // referenced from another wrapper instance
    uaString.copyTo(&rawString);
}

Returns: If the functions succeeds pDst is returned, otherwise 0 is returned.

int UaString::find ( UaChar cFind ) const

Finds the position of a UTF-8 character in the string.

Parameters

cFind the char to find the position of.

Returns: the position of a UTF-8 character in the string or -1 if the character is not found.

int UaString::find	(	UaChar	cFind,
		unsigned int	iStart
	)		const

Finds the position of a UTF-8 character in the string after start index.

Parameters

cFind	the char to find the position of.
iStart	the start position to find the char.

Returns: the position of a UTF-8 character in the string after start index.

bool UaString::isEmpty ( ) const

Returns true if the string is empty.

This function will return true for a null string.

Returns: true if the string is empty.

bool UaString::isLikePatternValid ( const UaString & pattern )

static

Tests if a given Like-Pattern is valid or not.

Parameters

pattern the Like-Pattern to test.

Returns: True if the pattern is valid, otherwise false.

bool UaString::isNull ( ) const

Returns true if the string is null.

This function will return false for an empty string.

Returns: true if the string is null.

int UaString::length ( ) const

Returns the number of characters of this string.

You will need this function for displaying it. With UTF-8 strings the number of characters and the size in bytes may differ.

Returns: the number of characters of this string.

bool UaString::like ( const UaString & pattern ) const

Implements the Like operator of the UA Specification.

Checks if the given pattern matches the string.

The Like operator can be used to perform wildcard comparisons. Several special characters can be included in the Like operator. The valid characters are defined in the following table.

Special Character	Description
%	Match any string of zero or more characters (i.e. 'main%' would match any string that starts with 'main', '%en%' would match any string that contains the letters 'en' such as 'entail', 'green' and 'content'.) If a string includes the '%' sign, the list operand can be used (i.e. 5[%] would match '5%').
_	Match any single character (i.e. '_ould' would match 'would', 'could'). If a string includes a '_', then the list operand can be used (i.e. 5[_] would match '5_').
\	Escape character allows literal interpretation (i.e. \\ is \, \% is %, \_ is _)
[]	Match any single character in a list (i.e. 'abc[13-68]' would match 'abc1','abc3','abc4','abc5','abc6', and 'abc8'. 'xyz[c-f]' would match 'xyzc', 'xyzd', 'xyze', 'xyzf').
[^]	Not Matching any single character in a list. The ^ shall be the first character inside on the []. (i.e. 'ABC[^13-5]' would NOT match 'ABC1', 'ABC3', 'ABC4', and 'ABC5'. xyz[^dgh] would NOT match 'xyzd', 'xyzg', 'xyzh'. )

The wildcard characters can be combined in a single string (i.e. 'Th[ia][ts]%' would match 'That is fine', 'This is fine', 'That as one', 'This it is', 'Then at any', etc.).

Parameters

pattern the Like-Pattern to use.

Returns: True if the pattern matches the string, otherwise false.

UaString UaString::number	(	int	n,
		int	base = `10`
	)

static

Returns a string equivalent of the number n to base base, which is 10 by default and must be between 2 and 36.

Parameters

n	a signed int number to convert to a string
base	the base for interpreting the number

UaString UaString::number	(	unsigned int	n,
		int	base = `10`
	)

static

Returns a string equivalent of the number n to base base, which is 10 by default and must be between 2 and 36.

Parameters

n	an unsigned int number to convert to a string
base	the base for interpreting the number

UaString::operator const OpcUa_String * ( ) const

This implicitly casts this string to an OpcUa_String to be able to pass it to low level OPC UA stack functions.

The result remains valid until the string is modified.

See also: toOpcUaString

Returns: an OpcUa_String to be able to pass it to low level OPC UA stack functions.

bool UaString::operator!= ( const UaString & other ) const

Returns true if other is not equal to this.

See also: operator==

Parameters

other the UaString to compare.

Returns: true if other is not equal to this.

UaString UaString::operator+ ( const UaString & other )

Addition operator.

Parameters

other the UaString for addition.

Returns: Addition operator.

UaString & UaString::operator+= ( const UaString & other )

Appends a string to the internal string.

This creates a copy of the string because the internal data needs to be changed.

Parameters

other the UaString to append.

Returns: a string to the internal string.

bool UaString::operator< ( const UaString & other ) const

This operator is mainly used to sort strings.

That is e.g. necessary to use it as a key in a binary tree.

Parameters

other the UaString to append.

Returns: operator is mainly used to sort strings.

UaString & UaString::operator= ( const UaString & other )

Assigns other to this string and returns a reference to this string.

Parameters

other the UaString to assign.

Returns: a reference to this string.

bool UaString::operator== ( const UaString & other ) const

Returns true if other is equal to this.

See also: operator!=

Parameters

other the UaString to compare.

Returns: true if other is equal to this.

int UaString::size ( ) const

Returns the size in bytes that the internal UTF-8 representation needs to hold this string.

You will only need this function if you want to allocate a native UTF-8 string that should be big enough to hold this string.

Returns: the size in bytes that the internal UTF-8 representation needs to hold this string.

const OpcUa_String * UaString::toOpcUaString ( ) const

Returns an OpcUa_String to be able to pass this string to low level OPC UA stack functions.

The result remains valid until the string is modified.

Returns: an OpcUa_String to be able to pass this string to low level OPC UA stack functions.

UaByteArray UaString::toUtf16 ( ) const

Returns a UTF-16 representation of the string as a UaByteArray.

This creates a copy of the string because the internal data needs to be converted. UaByteArray takes care of the memory.

Make sure you are always using the function together with a cast to const UaUShort* to make sure you get the right format extracted if you need a wchar_t*.

Example:

wchar_t str[512];
UaString sString("Test String");
// Wrong use
swprintf_s(str, 512, L"String:%s", sString.toUtf16());
// str = String:
// Right use
swprintf_s(str, 512, L"String:%s", (const UaUShort*)sString.toUtf16());
// str = String:Test String

Returns: a UTF-16 representation of the string as a UaByteArray.

const char * UaString::toUtf8 ( ) const

Returns the string as a '\0'-terminated array of characters.

The result remains valid until the string is modified

Returns: the string as a '\0'-terminated array of characters.

Friends And Related Function Documentation

UABASE_EXPORT UaDataStream& operator<<	(	UaDataStream &	,
		const UaString &
	)

friend

define UaDataStream operators for UaString.

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

D:/work/uasdkcpp/src/uabase/uabasecpp/uastring.h
D:/work/uasdkcpp/src/uabase/uabasecpp/uastring.cpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation