UaString Class Reference

This class encapsulates the native OpcUa_String structure and handles memory allocation and cleanup for you. More...

#include <uastring.h>

Public Member Functions
	UaString ()
	Default constructor.
	UaString (const OpcUa_String *other)
	Creates a copy of the native OpcUa_String.
	UaString (const UaString &other)
	Creates a copy of another UaString.
	UaString (const UaByteString &other)
	Creates a string initialized with the byte array other.
	UaString (const char *other)
	Creates a copy of an UTF-8 encoded character string.
	UaString (const UaUShort *other)
	Creates a copy of an UTF-16 encoded wide character string.
	~UaString ()
	Destroys the string.
UaString &	operator= (const UaString &other)
	Assigns other to this string and returns a reference to this string.
int	size () const
	Returns the size in bytes that the internal UTF-8 representation needs to hold this string.
int	length () const
	Returns the number of characters of this string.
bool	isEmpty () const
	Returns true if the string is empty.
bool	isNull () const
	Returns true if the string is null.
const UaChar	at (int i) const
	Returns a read only unicode character.
int	find (UaChar cFind) const
	Finds the position of an UTF-8 character in the string.
int	find (UaChar cFind, unsigned int iStart) const
	Finds the position of an UTF-8 character in the string after start index.
bool	like (const UaString &pattern) const
	Implements the Like-Operator of the UA-Specification.
bool	operator== (const UaString &other) const
	Returns true if other is equal to this.
bool	operator!= (const UaString &other) const
	Returns true if other is not equal to this.
bool	operator< (const UaString &other) const
	This operator is mainly used to sort strings.
UaString &	operator+= (const UaString &other)
	Appends a string to the internal string.
UaString	operator+ (const UaString &other)
	Addition operator.
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.
OpcUa_String *	copy () const
	Creates an independent copy of this string as OpcUa_String.
void	copyTo (OpcUa_String *pDst) const
	Copies the string contents into an existing OpcUa_String.
const OpcUa_String *	toOpcUaString () const
	Returns an OpcUa_String to be able to pass this string to low level OPC UA stack functions.
	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.
const char *	toUtf8 () const
	Returns the string as a '\0'-terminated array of characters.
UaByteArray	toUtf16 () const
	Returns a UTF-16 representation of the string as a UaByteArray.

Static Public Member Functions
static bool	isLikePatternValid (const UaString &pattern)
	Tests if a given Like-Pattern is valid or not.
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.
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.
static OpcUa_String *	clone (const OpcUa_String &source)
	This is a convenience function to clone native OpcUa_String that are used in the OPC UA ANSI Stack.
static void	cloneTo (const OpcUa_String &source, OpcUa_String &copy)
	This is a convenience function and behaves like the function above.

Detailed Description

This class encapsulates the native OpcUa_String structure and handles memory allocation and cleanup for you.

Additionally you can extract native UTF-8 (char*) strings or UTF-16 (ushort*) strings for further processing in other applications. 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.

int foo(OpcUa_String *native)
{
    UaString str(native);
    UaByteArray array = str.toUtf16();
    const ushort *wszUtf16 = array;
    wprintf(L"%s\\n", wszUtf16);
    str += "abc";
    native = str.toOpcUaString();
}  

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 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. The the array is not 0 terminated a 0 will be appended.

Parameters

other

the byte array to copy.

UaString::UaString

(

const char *

other

)

Creates a copy of an 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 an 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 native OpcUa_String that are used in the OPC UA ANSI 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 above.

The difference is, that is 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 into another structure.

Parameters

source	he 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.

int UaString::find

(

UaChar

cFind

)

const

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

Parameters

cFind

the char to find the position of.

Returns

the position of an 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 an 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 an 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.

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	a 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 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.

---

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

• /home/buildbot/work/uasdkcpp/src/uabase/uabasecpp/uastring.h
• /home/buildbot/work/uasdkcpp/src/uabase/uabasecpp/uastring.cpp