Skip to main content
Previous sectionNext section

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:

Stream classes:

  • 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:

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.

List Operations, Stack Operations, and Element Access

  • erase() — Deletes the element at position pos.

       iterator erase(iterator pos);
    Copy code to clipboard
  • insert() — Inserts at position pos an element of value val.

       iterator insert(iterator pos, const value_type& val);
    Copy code to clipboard
  • pop_back() — Removes the final element of the list, which must be non-empty.

       void pop_back();
    Copy code to clipboard
  • push_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 clipboard
  • 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;
    Copy code to clipboard
Size and Capacity

  • capacity() — Returns the storage currently allocated for the list.

       size_type capacity() const;
    Copy code to clipboard
  • empty() — Checks if the list is empty and returns true if it is.

       bool empty() const;
    Copy code to clipboard
  • max_size() — Returns the maximum allowable length of the list.

       size_type max_size() const;
    Copy code to clipboard
  • 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);
    Copy code to clipboard
  • size() — Returns the length of the list.

       size_type size();
    Copy code to clipboard
Iterators

  • begin() — Returns a random-access iterator pointing to the list's first element.

       iterator begin();
    Copy code to clipboard
  • end() — Returns a random-access iterator pointing to the one-past-last element of the array.

       iterator end();
    Copy code to clipboard
  • 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();
    Copy code to clipboard
  • 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();
    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.

List Operations and Element Access

  • erase() — Removes an element

    • Removes the array element specified by pos.

         iterator erase(iterator pos);
      Copy code to clipboard
    • Removes 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 clipboard
    • Inserts 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
Size and Capacity

  • capacity() — Returns the storage currently allocated for the array.

       size_type capacity() const;
    Copy code to clipboard
  • empty() — Returns true if the array is empty.

       bool empty() const;
    Copy code to clipboard
  • max_size() — Returns the maximum number of elements that the array can contain.

       size_type max_size() const;
    Copy code to clipboard
  • size() — Returns the number of elements in the array.

       size_type size();
    Copy code to clipboard
Iterators

  • begin() — Returns a bi-directional iterator pointing to the array's first element.

       iterator begin();
    Copy code to clipboard
  • end() — Returns a bi-directional iterator to the one-past-last element of the array.

       iterator end();
    Copy code to clipboard
  • 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();
    Copy code to clipboard
  • 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();
    Copy code to clipboard
  • 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);
    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).

Stream Objects

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.

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:

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);
Copy code to clipboard

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);
Copy code to clipboard

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();
Copy code to clipboard
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();
Copy code to clipboard
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();
Copy code to clipboard

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);
Copy code to clipboard

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);
Copy code to clipboard

Methods specific to binary streams are:

   void read(d_int& len, d_binary& res); 
   void write(const d_binary& data);
Copy code to clipboard
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*
Copy code to clipboard

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();
    Copy code to clipboard
  • end() — Returns a bi-directional iterator.

       iterator end();
    Copy code to clipboard
  • rbegin() — Returns a reverse iterator.

       reverse_iterator rbegin();
    Copy code to clipboard
  • rend() — Returns a reverse iterator.

       reverse_iterator rend();
    Copy code to clipboard