Reference for Simple Datatype Classes

Caché uses a set of special classes for literal datatypes (containing simple data such as strings or numbers). See Data Types in Using Caché Objects for information about how datatype classes differ from standard object classes.

Every Caché data type is mapped to an appropriate C++ object, such as d_int or d_string. If a literal type instance is not null, it is possible to convert it to a standard C++ type: d_int can be converted to int, d_string to std::string or std::wstring, d_time, d_date, and d_timestamp to tm. The C++ object that represents a Caché datatype is determined via the CLIENTDATATYPE keyword value of the datatype class.

All simple types have:

Conversion operators that makes it possible to use them as C++ types. For example, d_int can be converted to int and d_double to double.
A value() method (for use in templates).
make_null() and is_null() methods.
An overloaded "<<" operator for output streams.
An overloaded "=" operator.

The following datatypes are supported:

Numeric — d_bool, d_int, d_double, d_numeric, d_decimal, and d_currency.
Binary — d_binary, d_longbinary, d_oid, d_status, d_string, and d_list.
Wide Strings — d_wstring, d_id, d_longwstring, and d_longstring.
Date and Time — d_date, d_timestamp, and d_timestamp.

Numeric Classes

These are simple numbers.

d_bool — %Library.BooleanOpens in a new tab corresponds to CLIENTDATATYPE keyword INTEGER.
d_int — %Library.IntegerOpens in a new tab corresponds to keyword INT or LONG.
d_double — %Library.DoubleOpens in a new tab corresponds to keyword DOUBLE.
d_numeric — %Library.NumericOpens in a new tab corresponds to keyword NUMERIC. d_numeric is a typedef of d_double.
d_decimal — %Library.DecimalOpens in a new tab corresponds to keyword DECIMAL.
d_currency — %Library.CurrencyOpens in a new tab corresponds to keyword CURRENCY.

Class InterSystems::d_int

A d_int can be converted to int and be assigned an int. It doesn't have other overloaded operators. The intended usage is to get the int value and assign a changed value back to the object if the object should be changed. For example,

   d_int t = 2;
   d_int q = int(t) + 2;

in many cases like this one the conversion is implicit, so the second line can be just

   d_int q = t + 2;

but there are cases where it is necessary.

Binary Classes

These are classes containing variable-length binary data.

d_binary — %Library.BinaryOpens in a new tab corresponds to CLIENTDATATYPE keyword BINARY.
d_longbinary —
d_oid — A complete Object ID. corresponds to keyword OID. d_oid is a typedef of d_binary.
d_status — %Library.StatusOpens in a new tab corresponds to keyword STATUS.
d_string — %Library.StringOpens in a new tab corresponds to keyword VARCHAR or LONG VARCHAR.
d_list — %Library.ListOpens in a new tab corresponds to Caché $list structure.

Class InterSystems::d_binary

A d_binary holds binary data. d_oid is a typedef of d_binary that represents a complete Object ID.

Member list

d_binary constructors

No parameters.
```
   d_binary();
```
From null terminated string
```
   d_binary(const char* cstr);
```
From std::string
```
   d_binary(const std::string& s);
```
From string of size sz, starting at cstr
```
   d_binary(const char* cstr, int sz);
```

std::string() operator — Return the data as std::string
```
   operator std::string() const;
```

Comparison operators — Compare to another d_binary

   bool operator==(const d_binary& t);
   bool operator!=(const d_binary& t);

append_bin() — Append binary data

   void append_bin(const char* buf, byte_size_t size);

assign() — Assign binary data

   void assign(const char* buf, byte_size_t size);

get_buf() — Get the address of the binary buffer
```
   const char* get_buf() const;
```
get_size() — Get the size of the binary buffer
```
   long get_size() const;
```

Class InterSystems::d_status

A d_status encapsulates %Library.StatusOpens in a new tab. It should be used only for interpreting a status from the server.

Member list

operator int() — Convert to int with the value of the error code
```
   operator int() const;
```

get_code() — Get the error code (returns 0 if no error)
```
   int get_code() const;
```
get_msg() — Get the error message
```
   const d_string& get_msg() const;
```
get_from_srv() — Analyze the status on the server with potential translation of the message to language lang (if it's a system error)
```
   void get_from_srv(Database* db, const char* lang = "", Db_err* err = 0);
```
throw_err() — Throw a Db_err with the code and the message of the error
```
   void throw_err() const;
```

Class InterSystems::d_string

A d_string holds string data. It differs from d_binary in that it automatically converts data when necessary and also provides conversion methods.

Member list

d_string constructors

No parameters.
```
   d_string();
```

From null terminated string or wide null terminated string

   d_string(const char* cstr);
   d_string(const wchar_t* cstr);

From std::string or std::wstring

   d_string(const std::string& s);
   d_string(const std::wstring& s);

From string or wide string of size sz, starting at cstr

   d_string(const char* cstr, int sz);
   d_string(const wchar_t* cstr, int sz);

is_unicode() — Test whether the string is in unicode format
```
   bool is_unicode() const;
```
to_mb() — Convert to multibyte.
- in buffer buf of capacity cap, return the number of bytes put in buf.
```
   byte_size_t to_mb(char* buf, char_size_t cap) const;
```
- Convert to multibyte in place
```
   void to_mb();
```
to_uni() — Convert to unicode.
- Store the result in buffer buf of capacity cap, return the number of characters put in buf
```
   char_size_t to_uni(wchar_t* buf, char_size_t cap) const;
```
- Convert to unicode in place
```
   void to_uni();
```

std::string() operator — Convert to std::string or std::wstring.

   operator std::string() const;
   operator std::wstring() const;

Comparison operators — Compare to another d_string

   bool operator==(const d_string& val) const;
   bool operator!=(const d_string& val) const;
   bool operator<(const d_string& val) const;

assign()

From null terminated string or wide null terminated string.

   void assign(const char* buf);
   void assign(const wchar_t* buf);

From string or wide string of size sz, starting at cstr

   void assign(const char* buf, char_size_t size);
   void assign(const wchar_t* buf, char_size_t size);

Class InterSystems::d_list

A d_list object is a C++ implementation of the $list structure in Caché. In addition to its standard methods, the d_list class has a set of static methods that allow you to extract data from a buffer containing a $list without copying it into a d_list object.

d_list methods

A d_list object is essentially a forward iterator, but it also provides methods for inserting, deleting and replacing an element at the current position, as well as other methods that work with $list as a whole. A d_list position is 0 based. Since $list is stored in contiguous memory, any operation that changes a $list element may cause a dynamic memory reallocation or copying, which may be expensive.

Member list

d_list()

   d_list(const char* buf, byte_size_t size)

append_elem()

   void append_elem(__int64 val); 
   void append_elem(double val); 
   void append_elem(const d_string& val); 
   void append_elem(const d_binary& val); 
   void append_elem(const wchar_t* p, char_size_t size); 
   void append_elem(const char* p, char_size_t size);

append_elem_null()
```
   void append_elem_null();
```
at_end()
```
   bool at_end() const;
```
clear() — Delete all elements
```
   void clear();
```
count() — Count the number of elements
```
   int count();
```
del_elem() — Delete the current element
```
   void del_elem();
```
elem_null()
```
   void ins_elem_null();
```

get_elem()

   void get_elem(__int64* val) const; 
   void get_elem(double* val) const; 
   void get_elem(d_string& val) const; 
   void get_elem(d_binary& val) const; 
   void get_elem(bool* is_uni, const char** p_buf, 
      byte_size_t* p_size) const;

get_elem_idx() — Get the index of the current element
```
   int get_elem_idx() const;
```
get_elem_type()
```
   char get_elem_type() const;
```

ins_elem()

   void ins_elem(__int64 val); 
   void ins_elem(double val); 
   void ins_elem(const d_string& val); 
   void ins_elem(const d_binary& val); 
   void ins_elem(const wchar_t* p, char_size_t size); 
   void ins_elem(const char* p, char_size_t size);

is_elem_double()
```
   bool is_elem_double() const;
```
is_elem_int()
```
   bool is_elem_int() const;
```
is_elem_null()
```
   bool is_elem_null() const;
```
is_elem_str()
```
   bool is_elem_str() const;
```
move_to() — Change the current position to idx (0 based)
```
   void move_to(int idx) const;
```
move_to_front() — Same as move_to(0) but optimized
```
   void move_to_front() const;
```
next() — Similar to move_to(), but optimized for moving to the next element
```
   void next() const;
```

reset() — Reset the buffer

   void reset(const char* buf, byte_size_t size);

set_elem()

   void set_elem(__int64 val); 
   void set_elem(double val); 
   void set_elem(const d_string& val); 
   void set_elem(const d_binary& val); 
   void set_elem(const wchar_t* p, char_size_t size); 
   void set_elem(const char* p, char_size_t size);

set_elem_null()
```
   void set_elem_null();
```

d_list static member functions

The static member functions allow you to extract data from a buffer that is a $list without copying it into a d_list object. The interface deals with the $list element specified by the buffer. The next element starts at buffer + d_list::get_elem_size(buffer).

Member list

get_elem() — Get an element

Get an element as _int64, double, d_string, or d_binary.

   static void get_elem(const char* buf, __int64* val);
   static void get_elem(const char* buf, double* val);
   static void get_elem(const char* buf, d_string& val);
   static void get_elem(const char* buf, d_binary& val);

Get an element as a pointer to the string, the string size, and find whether it's unicode or narrow

   static void get_elem(const char* buf, bool* is_uni, 
      const char** p_buf, byte_size_t* p_size);

get_elem_size() — Get element size

   static byte_size_t get_elem_size(const char* buf);

is_elem_double() — Test whether an element is stored as double
```
   static bool is_elem_double(const char* buf);
```
is_elem_int() — Test whether an element is stored as int
```
   static bool is_elem_int(const char* buf);
```

is_elem_null() — Test whether an element is null

   static bool is_elem_null(const char* buf);

is_elem_str() — Test whether an element is stored as string
```
   static bool is_elem_str(const char* buf);
```

Time and Date Classes

Objects of these types can be converted to a tm structure object with all irrelevant values set to -1. They can also be assigned a tm object. The irrelevant values from the tm structure will be ignored. Interfaces of these classes differ only in constructors and assignment operators.

d_date — %Library.DateOpens in a new tab corresponds to CLIENTDATATYPE keyword DATE.
d_time — %Library.TimeOpens in a new tab corresponds to keyword TIME.
d_timestamp — %Library.TimeStampOpens in a new tab corresponds to keyword TIMESTAMP.

Class InterSystems::d_time

Member list

d_time

From tm
```
   d_time(const tm& ts);
```
From ODBC structure for time
```
   d_time(const TIME_STRUCT& t);
```
From hour, minute, second
```
   d_time(int h, int m, int s);
```

From ODBC structure for time

   d_time& operator=(const TIME_STRUCT& t);

Class InterSystems::d_date

Member list

d_date

From tm
```
   d_date(const tm& ts);
```
From ODBC structure for date
```
   d_date(const DATE_STRUCT& d);
```
From year, month, day
```
   d_date(int y, int m, int d);
```

From ODBC structure for date

   d_date& operator=(const DATE_STRUCT& d);

Class InterSystems::d_timestamp

Member list

d_timestamp

From tm
```
   d_timestamp(const tm& ts);
```

From ODBC structure for timestamp

   d_timestamp(const TIMESTAMP_STRUCT& ts);