DStringProperty Class

Manages conversion among character encodings (Ansi, Unicode, UTF-8).

File

File: dstringproperty.h

Namespace: dtSearch

= Operator
DStringProperty Constructor
getUi Method

Syntax

C++

class DStringProperty;

Data Members

Show:Protected

No members matching the current filter

Data Member	Description
originalBuf	Used if the value is associated with a fixed-length buffer
pValue	Used if the value is associated with a const char * pointer that should be updated each time string contents change

Group

Classes

Members

Data Members

Show:Protected

No members matching the current filter

Data Member	Description
originalBuf	Used if the value is associated with a fixed-length buffer
pValue	Used if the value is associated with a const char * pointer that should be updated each time string contents change

Operators

Operator	Description
=(const DStringProperty&)	Copy a DStringProperty
=(const char *)	Copy a string
=(const wchar_t *)	Store a Unicode string
const char *	Get const char * pointer to the string buffer

Methods

Show:Protected

No members matching the current filter

Method	Description
DStringProperty(const DStringProperty&)	Copy constructor
DStringProperty(char , long, const char *)	Constructor attaching an existing string buffer AND a const char * pointer, for values that are stored both ways, such as dtsOptions.userThesaurusFile and dtsOptions.userThesaurusFile2
DStringProperty(char *, ptrdiff_t)	Constructor attaching an existing string buffer
DStringProperty(const char *)	Constructor initializing with a string value
DStringProperty(const char **)	Constructor initializing the DStringProperty with the address of a const char * pointer. The const char * pointer will always point to the string buffer in value.
DStringProperty(const wchar_t *)	Constructor initializing with a Unicode string value
allocNetString	Return the string as a .NET System::String
allocSysString	Convert the string to a COM BSTR and return it
clear	Clear the string
getA	Get the string as Ansi
getFromStringHandle	Convert the string from a dtsStringHandle, optionally deleting the handle after the string has been converted
getLength	Returns the length of the string
getU8	Get the string as UTF-8
getUi()	Unicode
getUi(CString &)	Unicode Get the string as TCHAR
getW	Get the string as Unicode
isBlank	Returns true if the string is empty or contains only whitespace
onValueChange	If this property is linked to an API structure string pointer or buffer, update the pointer or buffer every time its value changes.
set	Store a .NET System::String
setA	Store an Ansi string
setU8	Store a UTF-8 string
setUi	Store a const TCHAR * string
setW	Store a Unicode string
str	Get char * pointer to the string buffer

Methods

Show:Protected

No members matching the current filter

Method	Description
DStringProperty(const DStringProperty&)	Copy constructor
DStringProperty(char , long, const char *)	Constructor attaching an existing string buffer AND a const char * pointer, for values that are stored both ways, such as dtsOptions.userThesaurusFile and dtsOptions.userThesaurusFile2
DStringProperty(char *, ptrdiff_t)	Constructor attaching an existing string buffer
DStringProperty(const char *)	Constructor initializing with a string value
DStringProperty(const char **)	Constructor initializing the DStringProperty with the address of a const char * pointer. The const char * pointer will always point to the string buffer in value.
DStringProperty(const wchar_t *)	Constructor initializing with a Unicode string value
allocNetString	Return the string as a .NET System::String
allocSysString	Convert the string to a COM BSTR and return it
clear	Clear the string
getA	Get the string as Ansi
getFromStringHandle	Convert the string from a dtsStringHandle, optionally deleting the handle after the string has been converted
getLength	Returns the length of the string
getU8	Get the string as UTF-8
getUi()	Unicode
getUi(CString &)	Unicode Get the string as TCHAR
getW	Get the string as Unicode
isBlank	Returns true if the string is empty or contains only whitespace
onValueChange	If this property is linked to an API structure string pointer or buffer, update the pointer or buffer every time its value changes.
set	Store a .NET System::String
setA	Store an Ansi string
setU8	Store a UTF-8 string
setUi	Store a const TCHAR * string
setW	Store a Unicode string
str	Get char * pointer to the string buffer

Operators

Operator	Description
=(const DStringProperty&)	Copy a DStringProperty
=(const char *)	Copy a string
=(const wchar_t *)	Store a Unicode string
const char *	Get const char * pointer to the string buffer

Remarks

Set and get functions are provided for each encoding type. DStringProperty stores text internally in a DString in UTF-8, the same format that the dtSearch Engine uses.

The dtSearch Engine's C++ support classes use DStringProperty to provide easy access to strings passed to or from the dtSearch Engine. For example, DSearchJob uses a DStringProperty, "Request" for the search request string. Any changes to Request are automatically reflected in dtsSearchJob.request. The following code sets up a search job using a Unicode string to initialize the "request":

DSearchJob searchJob; searchJob.Request.setW(L"Unicode search request");

"W", "A", "U8", and "Ui" versions of "set" and "get" functions are provided to get or set the string value as Unicode (W), Ansi (A), UTF-8 (U8), or TCHAR or CString (Ui).

Implementation Details:

A DStringProperty maintains a text buffer, value, with a UTF-8 representation of the text.

DStringProperty is designed to be associated with a structure element, so that set*() or get*() calls will provide easy access to the contents of a string in a structure. A string member of a structure can be either a char * (a pointer to a memory location) or a char[N], a fixed-length buffer of N bytes. DStringProperty has constructors that will work with either variation.

Each time the string is changed, potentially causing reallocation of the buffer, the const char * string pointer is updated to point to the new buffer.

In this example, DStringProperty is declared to manage the dtsSearchJob.request string:

dtsSearchJob searchJob; DStringProperty xrequest(&searchJob.request); // Now any change to xrequest automatically causes searchJob.request to point to the // updated string xrequest.setW(L"Unicode search request");

Each time a DStringProperty changes, it calls onValueChange, which sets *pValue to the new string buffer in value. This keeps the string pointer in the API structure consistent with the contents of the string buffer.

Class Hierarchy

dtSearch::DStringProperty