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
d_char_stream
d_bin_stream
d_file_bin_stream
d_file_char_stream
Relationships:
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é %ListOfObjects and %ListOfDataTypes classes.
d_map array collections — correspond to the Caché %ArrayOfObjects and %ArrayOfDataTypes classes.
Operations on a C++ client usually assume the collection's prior existence.
Class Template d_vector<S> (List Collections)
Proxies for %ListOfObjects and %ListOfDataTypes 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.
erase() — Deletes the element at position pos.
iterator erase(iterator pos);
Copy code to clipboardinsert() — Inserts at position pos an element of value val.
iterator insert(iterator pos, const value_type& val);
Copy code to clipboardpop_back() — Removes the final element of the list, which must be non-empty.
void pop_back();
Copy code to clipboardpush_back() — Inserts an element of the value val at the end of a list.
void push_back(const value_type& val);
Copy code to clipboard[] operator — Supports unchecked element access by overloading the "[]" operator:
reference operator[](size_type index); const;_reference operator[](size_type index) const;
Copy code to clipboardat() — 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;
Copy code to clipboard
capacity() — Returns the storage currently allocated for the list.
size_type capacity() const;
Copy code to clipboardempty() — Checks if the list is empty and returns true if it is.
bool empty() const;
Copy code to clipboardmax_size() — Returns the maximum allowable length of the list.
size_type max_size() const;
Copy code to clipboardreserve() — 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);
Copy code to clipboardsize() — Returns the length of the list.
size_type size();
Copy code to clipboard
begin() — Returns a random-access iterator pointing to the list's first element.
iterator begin();
Copy code to clipboardend() — Returns a random-access iterator pointing to the one-past-last element of the array.
iterator end();
Copy code to clipboardrbegin() — 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();
Copy code to clipboardrend() — 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();
Copy code to clipboard
Class Template d_map<S> (Array Collections)
Proxies for %ArrayOfObjects and %ArrayOfDataTypes 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.
erase() — Removes an element
Removes the array element specified by pos.
iterator erase(iterator pos);
Copy code to clipboardRemoves the element uniquely identified by the key k (if present).
size_type erase(const key_type& k);
Copy code to clipboard
insert() — Inserts an element.
Inserts an element of value val, using pos as a hint
iterator insert(iterator pos, const value_type& val);
Copy code to clipboardInserts an element of value val.
std::pair<iterator, bool> insert(const value_type& val);
Copy code to clipboard
[] operator — tbd
mapped_type& operator[](const key_type& key); const mapped_type& operator[](const key_type& key) const;
Copy code to clipboard
capacity() — Returns the storage currently allocated for the array.
size_type capacity() const;
Copy code to clipboardempty() — Returns true if the array is empty.
bool empty() const;
Copy code to clipboardmax_size() — Returns the maximum number of elements that the array can contain.
size_type max_size() const;
Copy code to clipboardsize() — Returns the number of elements in the array.
size_type size();
Copy code to clipboard
begin() — Returns a bi-directional iterator pointing to the array's first element.
iterator begin();
Copy code to clipboardend() — Returns a bi-directional iterator to the one-past-last element of the array.
iterator end();
Copy code to clipboardrbegin() — Returns a reverse iterator pointing to the beginning of the array's reverse sequence (just beyond the array's last element).
reverse_iterator rbegin();
Copy code to clipboardrend() — Returns a reverse iterator pointing to the end of the array's reverse sequence (just before the array's first element).
reverse_iterator rend();
Copy code to clipboardfind() — 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);
Copy code to clipboard
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).
The following table describes the mapping of Caché stream classes:
Caché Class |
C++ Class |
---|---|
d_char_stream |
|
d_bin_stream |
|
d_file_bin_stream |
|
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.
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
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();
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();
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.
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);
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).
The d_relationship<P> class is a standard container that supports the following methods:
begin() — Returns a bi-directional iterator.
iterator begin();
Copy code to clipboardend() — Returns a bi-directional iterator.
iterator end();
Copy code to clipboardrbegin() — Returns a reverse iterator.
reverse_iterator rbegin();
Copy code to clipboardrend() — Returns a reverse iterator.
reverse_iterator rend();
Copy code to clipboard