C++ Based OPC UA Client/Server/PubSub SDK
1.7.2.493
|
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_StatusCode | convertToSignedNumber (OpcUa_Int64 &value, OpcUa_Byte byteLength) |
Converts the string content to an signed number. More... | |
OpcUa_StatusCode | convertToUnsignedNumber (OpcUa_UInt64 &value) |
Converts the string content to an unsigned number. 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 ©) |
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... | |
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.
A string can be created with arg, appended with operator+ and operator+= and created from different string formats and a number.
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.
UaString::UaString | ( | ) |
Default constructor.
Creates an empty UaString.
UaString::UaString | ( | const OpcUa_String * | other | ) |
Creates a copy of the native OpcUa_String.
other | Source string. |
UaString::UaString | ( | const OpcUa_String & | other | ) |
Creates a copy of the native OpcUa_String.
other | Source string. |
UaString::UaString | ( | const UaString & | other | ) |
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
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!!!
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.
other | the UaUShort. |
UaString::~UaString | ( | ) |
Destroys the string.
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.
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 . |
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.
i | the position of the actual char in the string. |
|
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.
source | The source string to clone. |
|
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.
source | The source string to clone. |
copy | The destination string to copy the string contents to. |
OpcUa_StatusCode UaString::convertToSignedNumber | ( | OpcUa_Int64 & | value, |
OpcUa_Byte | targetHexLength | ||
) |
Converts the string content to an signed number.
value | a signed number which is converted from a string |
targetHexLength | is the length of the hexa decimal string in bytes |
OpcUa_StatusCode UaString::convertToUnsignedNumber | ( | OpcUa_UInt64 & | value | ) |
Converts the string content to an unsigned number.
value | an unsigned number which is converted from a string |
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.
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);
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.
int UaString::find | ( | UaChar | cFind | ) | const |
Finds the position of a UTF-8 character in the string.
cFind | the char to find the position of. |
int UaString::find | ( | UaChar | cFind, |
unsigned int | iStart | ||
) | const |
Finds the position of a UTF-8 character in the string after start index.
cFind | the char to find the position of. |
iStart | the start position to find the char. |
bool UaString::isEmpty | ( | ) | const |
Returns true if the string is empty.
This function will return true for a null string.
|
static |
Tests if a given Like-Pattern is valid or not.
pattern | the Like-Pattern to test. |
bool UaString::isNull | ( | ) | const |
Returns true if the string is null.
This function will return false for an empty string.
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.
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.).
pattern | the Like-Pattern to use. |
|
static |
Returns a string equivalent of the number n
to base base
, which is 10 by default and must be between 2 and 36.
n | a signed int number to convert to a string |
base | the base for interpreting the number |
|
static |
Returns a string equivalent of the number n
to base base
, which is 10 by default and must be between 2 and 36.
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.
bool UaString::operator!= | ( | const UaString & | other | ) | const |
Returns true if other
is not equal to this
.
other | the UaString to compare. |
other
is not equal to this
. Appends a string to the internal string.
This creates a copy of the string because the internal data needs to be changed.
other | the UaString to append. |
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.
other | the UaString to append. |
Assigns other
to this string and returns a reference to this string.
other | the UaString to assign. |
bool UaString::operator== | ( | const UaString & | other | ) | const |
Returns true if other
is equal to this.
other | the UaString to compare. |
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.
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.
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
const char * UaString::toUtf8 | ( | ) | const |
Returns the string as a '\0'-terminated array of characters.
The result remains valid until the string is modified
|
friend |
define UaDataStream operators for UaString.