Reference for Object Datatype Classes

This chapter describes a set of predefined proxy classes that correspond to Caché object datatype classes such as lists, arrays, and streams. All of these proxy classes inherit from both Dyn_obj and Obj_t classes. All of them have the standard open(), create_new(), openid(), and openref() methods.

Collection classes:

d_vector<S> — list collections
d_map<S> — array collections

Stream classes:

d_char_stream
d_bin_stream
d_file_bin_stream
d_file_char_stream

Relationships:

d_relationship<T>

Collection Classes

Caché supports two kinds of collections: lists and arrays. These are two different kinds of groupings of elements of a single type:

d_vector list collections — correspond to the Caché %ListOfObjectsOpens in a new tab and %ListOfDataTypesOpens in a new tab classes.
d_map array collections — correspond to the Caché %ArrayOfObjectsOpens in a new tab and %ArrayOfDataTypesOpens in a new tab classes.

Operations on a C++ client usually assume the collection's prior existence.

Class Template d_vector<S> (List Collections)

Proxies for %ListOfObjectsOpens in a new tab and %ListOfDataTypesOpens in a new tab provide an interface which is almost identical to the interface of std::vector.

Because Caché list objects are generated as d_obj_vector<T> and d_prim_vector<T> classes, they provide the same interface that is specified by d_vector.

List Operations, Stack Operations, and Element Access

erase() — Deletes the element at position pos.
```
   iterator erase(iterator pos);
```

insert() — Inserts at position pos an element of value val.

   iterator insert(iterator pos, const value_type& val);

pop_back() — Removes the final element of the list, which must be non-empty.
```
   void pop_back();
```
push_back() — Inserts an element of the value val at the end of a list.
```
   void push_back(const value_type& val);
```

[] operator — Supports unchecked element access by overloading the "[]" operator:

   reference operator[](size_type index); 
   const;_reference operator[](size_type index) const;

at() — Provides checked element access. Returns a reference to the list element at position index. If index is not a valid position, the method throws an out_of_range error.
```
   reference at(size_type index); 
   const;_reference at(size_type index) const;
```

Size and Capacity

capacity() — Returns the storage currently allocated for the list.
```
   size_type capacity() const;
```
empty() — Checks if the list is empty and returns true if it is.
```
   bool empty() const;
```
max_size() — Returns the maximum allowable length of the list.
```
   size_type max_size() const;
```
reserve() — Allocates space for a total number of n elements. This method only allocates memory for the n elements, but it does not create them.
```
   void reserve(size_type n);
```
size() — Returns the length of the list.
```
   size_type size();
```

Iterators

begin() — Returns a random-access iterator pointing to the list's first element.
```
   iterator begin();
```
end() — Returns a random-access iterator pointing to the one-past-last element of the array.
```
   iterator end();
```
rbegin() — Returns a reverse random-access iterator pointing to the beginning of the list's reverse sequence (just beyond the list's last element).
```
   reverse_iterator rbegin();
```
rend() — Returns a reverse random-access iterator pointing to the end of the list's reverse sequence (just before the list's first element).
```
   reverse_iterator rend();
```

Class Template d_map<S> (Array Collections)

Proxies for %ArrayOfObjectsOpens in a new tab and %ArrayOfDataTypesOpens in a new tab provide an interface which is almost identical to the interface of std::map.

Because Caché array objects are generated as d_obj_map<T> and d_prim_map<T> classes, they provide the same interface that is specified by d_map.

List Operations and Element Access

erase() — Removes an element
- Removes the array element specified by pos.
```
   iterator erase(iterator pos);
```
- Removes the element uniquely identified by the key k (if present).
```
   size_type erase(const key_type& k);
```

insert() — Inserts an element.

Inserts an element of value val, using pos as a hint

   iterator insert(iterator pos, const value_type& val);

Inserts an element of value val.

   std::pair<iterator, bool> insert(const value_type& val);

[] operator — tbd

   mapped_type& operator[](const key_type& key);
   const mapped_type& operator[](const key_type& key) const;

Size and Capacity

capacity() — Returns the storage currently allocated for the array.
```
   size_type capacity() const;
```
empty() — Returns true if the array is empty.
```
   bool empty() const;
```
max_size() — Returns the maximum number of elements that the array can contain.
```
   size_type max_size() const;
```
size() — Returns the number of elements in the array.
```
   size_type size();
```

Iterators

begin() — Returns a bi-directional iterator pointing to the array's first element.
```
   iterator begin();
```
end() — Returns a bi-directional iterator to the one-past-last element of the array.
```
   iterator end();
```
rbegin() — Returns a reverse iterator pointing to the beginning of the array's reverse sequence (just beyond the array's last element).
```
   reverse_iterator rbegin();
```
rend() — Returns a reverse iterator pointing to the end of the array's reverse sequence (just before the array's first element).
```
   reverse_iterator rend();
```
find() — Returns a bi-directional iterator designating the element in the array whose sort key has the equivalent ordering to key.
```
   iterator find(const key_type& key);
```

Streams

Proxies for Caché streams use adapters that fit them into the standard C++ library streams framework and optimize their performance. There are also a set of proxy classes for streams that inherit their common interface from the d_stream class. The adapters are the recommended way of working with streams. The adapters make the streams buffered, so avoid mixing calls to adapters and proxy objects that change the stream read/write position (as a result of reading or writing to a stream or a direct change in position).

Stream Objects

The following table describes the mapping of Caché stream classes:

Caché Class	C++ Class
%Library.GlobalCharacterStreamOpens in a new tab	d_char_stream
%Library.GlobalBinaryStreamOpens in a new tab	d_bin_stream
%Library.FileBinaryStreamOpens in a new tab	d_file_bin_stream
%Library.FileCharacterStreamOpens in a new tab	d_file_char_stream

All stream classes have static open() and create_new() methods. The d_file_char_stream class has an is_unicode() method, which checks if the stream contains Unicode data.

C++ Stream Adapters

The stream adapters can be used exactly as streams from the C++ standard library, and all the unique to Caché methods that are common to all Caché streams can be also accessed from them.

The adapter classes are:

d_basic_istream with typedefs for d_istream and d_wistream
d_basic_ostream with typedefs for d_ostream and d_wostream
d_basic_iostream with typedefs for d_iostream and d_wiostream

All C++ adapter objects can be constructed from a d_ref to a stream object proxy. For example:

   // create a low level stream object
   d_ref<d_char_stream> stream = d_char_stream::create_new(&db); 
   // create an IOStreams extension stream object 
   d_iostream io(stream);

All adapters have helper methods that allow you to work with a stream only via its adapter. All C++ adapter objects can be constructed from a d_ref to a stream object proxy. For example:

   // create a low level stream object 
   d_ref<d_char_stream> stream = d_char_stream::create_new(&db); 
   // create an IOStreams extension stream object 
   d_iostream io(stream);

Stream Adapter Classes

d_basic_ostream

There are typedefs d_ostream and d_wostream. In addition to std::basic_ostream interface, the class provides the following methods:

   d_binary oid(); 
   long size(); 
   d_status erase(); 
   d_status save();

d_basic_istream

There are typedefs d_istream and d_wistream. In addition to std::basic_istream interface, the class provides the following methods:

   d_binary oid(); 
   long size(); 
   d_status rewind();

d_basic_iostream

There are typedefs d_iostream and d_wiostream. In addition to std::basic_iostream interface, the class provides the following methods:

   d_binary oid(); 
   long size(); 
   d_status rewind(); 
   d_status move_to_end(); 
   d_status erase(); 
   d_status save();

Class d_stream

The d_stream class provides the common interface for all streams. The d_file_stream class adds to it the common interface for all file streams.

d_stream Methods

The d_stream methods in common between character and binary streams are:

   d_binary oid(); 
   d_status save(); 
   d_status clear(); 
   d_status rewind(); 
   d_status move_to_end(); 
   long size(); 
   d_stream& copy(const abs_d_ref& stream);

Methods specific to character streams are:

   void read(d_int& len, d_string& res); 
   void readline(d_int& len, d_string& res); 
   void write(const d_string& data);

Methods specific to binary streams are:

   void read(d_int& len, d_binary& res); 
   void write(const d_binary& data);

d_file_stream Methods

The additionally available methods from the d_file_stream class are:

   d_string get_filename(); 
   void set_filename(const d_string& fname); 
   d_timestamp last_modified(); 
   d_status link_to_file(const_name_t fname);   
   // const_name_t is a typedef for const wchar_t*

Class Template d_relationship<S>

As in Caché, relationships are treated as properties. If there is a relationship between classes P and Q where P is the single-valued side and Q is the multi-valued side, then the single-valued side is generated as a property of type P (d_ref<P>), and the multi-valued side is generated as a property of type d_relationship<Q> (d_ref<d_relationship<Q>>). As with other properties, when P or Q can be determined only at runtime, P or Q (or both) become Dyn_obj (a dynamic object).

d_relationship Methods

The d_relationship<P> class is a standard container that supports the following methods:

begin() — Returns a bi-directional iterator.
```
   iterator begin();
```
end() — Returns a bi-directional iterator.
```
   iterator end();
```
rbegin() — Returns a reverse iterator.
```
   reverse_iterator rbegin();
```
rend() — Returns a reverse iterator.
```
   reverse_iterator rend();
```