Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members

c4_View Class Reference

A collection of data rows. More...

Inheritance diagram for c4_View:

Inheritance graph
[legend]
List of all members.

Public Member Functions

 c4_View (c4_Sequence *=0)
 Construct a view based on a sequence.
 c4_View (c4_CustomViewer *)
 Construct a view based on a custom viewer.
 c4_View (c4_Stream *)
 Construct a view based on an input stream.
 c4_View (const c4_Property &property_)
 Construct an empty view with one property.
 c4_View (const c4_View &)
 Copy constructor.
 ~c4_View ()
 Destructor, decrements reference count.
c4_View & operator= (const c4_View &)
 Makes this view the same as another one.
c4_Persist * Persist () const
 Return a pointer to the persistence handler, or zero.
int GetSize () const
 Returns the number of entries in this view.
void SetSize (int, int=-1)
 Change the size of this view Since views act like dynamic arrays, you can quickly change their size.
void RemoveAll ()
 Removes all entries (sets size to zero).
c4_RowRef GetAt (int) const
 Returns a reference to specified entry, for use as RHS or LHS.
c4_RowRef operator[] (int) const
 Element access, shorthand for GetAt.
void SetAt (int, const c4_RowRef &)
 Change the value of the specified entry.
c4_RowRef ElementAt (int)
 Element access, shorthand for GetAt.
bool GetItem (int, int, c4_Bytes &) const
 Get a single data item in a generic way.
void SetItem (int, int, const c4_Bytes &) const
 Set a single data item in a generic way.
void SetAtGrow (int, const c4_RowRef &)
 Set an entry, growing the view if needed.
int Add (const c4_RowRef &)
 Add a new entry, same as "SetAtGrow(GetSize(), .
void InsertAt (int, const c4_RowRef &, int=1)
 Insert a copy of the contents of another view.
void RemoveAt (int, int=1)
 Remove entries starting at the given index.
void InsertAt (int, const c4_View &)
 Insert copies of all rows of the specified view.
void RelocateRows (int, int, c4_View &, int)
 Move attached rows to somewhere else in same storage.
int NumProperties () const
 Return the number of properties present in this view.
const c4_Property & NthProperty (int) const
 Returns the N-th property (using zero-based indexing).
int FindProperty (int)
 Find the index of a property, given its id.
int FindPropIndexByName (const char *) const
 Find the index of a property, given its name.
c4_View Duplicate () const
 Construct a new view with a copy of the data.
c4_View Clone () const
 Constructs a new view with the same structure but no data.
int AddProperty (const c4_Property &)
 Adds a property column to a view if not already present.
c4_View operator, (const c4_Property &) const
 Defines a column for a property.
const char * Description () const
 Return a decription if there is a fixed structure, else zero.
c4_View Sort () const
 Create view with all rows in natural (property-wise) order.
c4_View SortOn (const c4_View &) const
 Create view sorted according to the specified properties.
c4_View SortOnReverse (const c4_View &, const c4_View &) const
 Create sorted view, with some properties sorted in reverse.
c4_View Select (const c4_RowRef &) const
 Create view with rows matching the specified value.
c4_View SelectRange (const c4_RowRef &, const c4_RowRef &) const
 Create view with row values within the specified range.
c4_View Project (const c4_View &) const
 Create view with the specified property arrangement.
c4_View ProjectWithout (const c4_View &) const
 Create derived view with some properties omitted.
int GetIndexOf (const c4_RowRef &) const
 Return the index of the specified row in this view (or -1).
int RestrictSearch (const c4_RowRef &, int &, int &)
 Restrict the search range for rows.
c4_View Slice (int, int=-1, int=1) const
 Create view which is a segment/slice (default is up to end).
c4_View Product (const c4_View &) const
 Create view which is the cartesian product with given view.
c4_View RemapWith (const c4_View &) const
 Create view which remaps another given view.
c4_View Pair (const c4_View &) const
 Create view which pairs each row with corresponding row.
c4_View Concat (const c4_View &) const
 Create view with rows from another view appended.
c4_View Rename (const c4_Property &, const c4_Property &) const
 Create view with one property renamed (must be of same type).
c4_View GroupBy (const c4_View &, const c4_ViewProp &) const
 Create view with a subview, grouped by the specified properties.
c4_View Counts (const c4_View &, const c4_IntProp &) const
 Create view with count of duplicates, when grouped by key.
c4_View Unique () const
 Create view with all duplicate rows omitted.
c4_View Union (const c4_View &) const
 Create view which is the set union (assumes no duplicate rows).
c4_View Intersect (const c4_View &) const
 Create view with all rows also in the given view (no dups).
c4_View Different (const c4_View &) const
 Create view with all rows not in both views (no dups).
c4_View Minus (const c4_View &) const
 Create view with all rows not in the given view (no dups).
c4_View JoinProp (const c4_ViewProp &, bool=false) const
 Create view with a specific subview expanded, like a join.
c4_View Join (const c4_View &, const c4_View &, bool=false) const
 Create view which is the relational join on the given keys.
c4_View ReadOnly () const
 Create an identity view which only allows reading.
c4_View Hash (const c4_View &, int=1) const
 Create mapped view which adds a hash lookup layer.
c4_View Blocked () const
 Create mapped view which blocks its rows in two levels.
c4_View Ordered (int=1) const
 Create mapped view which keeps its rows ordered.
c4_View Indexed (const c4_View &, const c4_View &, bool=false) const
 Create mapped view which maintains an index permutation.
int Find (const c4_RowRef &, int=0) const
 Find index of the the next entry matching the specified key.
int Search (const c4_RowRef &) const
 Search for a key, using the native sort order of the view.
int Locate (const c4_RowRef &, int *=0) const
 Return number of matching keys, and pos of first one as arg.
int Compare (const c4_View &) const
 Compare two views lexicographically (rows 0..N-1).

Protected Member Functions

void _IncSeqRef ()
 Increase the reference count of the associated sequence.
void _DecSeqRef ()
 Decrease the reference count of the associated sequence.

Friends

class c4_ViewRef
 View references are allowed to peek inside view objects.
bool operator== (const c4_View &, const c4_View &)
 Return true if the contents of both views are equal.
bool operator!= (const c4_View &, const c4_View &)
 Return true if the contents of both views are not equal.
bool operator< (const c4_View &, const c4_View &)
 True if first view is less than second view.
bool operator> (const c4_View &, const c4_View &)
 True if first view is greater than second view.
bool operator<= (const c4_View &, const c4_View &)
 True if first view is less or equal to second view.
bool operator>= (const c4_View &, const c4_View &)
 True if first view is greater or equal to second view.

Detailed Description

A collection of data rows.

This is the central public data structure of Metakit (often called "table", "array", or "relation" in other systems).

Views are smart pointers to the actual collections, setting a view to a new value does not alter the collection to which this view pointed previously.

The elements of views can be referred to by their 0-based index, which produces a row-reference of type c4_RowRef. These row references can be copied, used to get or set properties, or dereferenced (in which case an object of class c4_Row is returned). Taking the address of a row reference produces a c4_Cursor, which acts very much like a pointer.

The following code creates a view with 1 row and 2 properties: 

    c4_StringProp pName ("name");
    c4_IntProp pAge ("age");
    c4_Row data;
    pName (data) = "John Williams";
    pAge (data) = 43;
    c4_View myView;
    myView.Add(row);

Member Function Documentation

int c4_View::Add (  const c4_RowRef &  newElem_  ) 
 

Add a new entry, same as "SetAtGrow(GetSize(), .

..)"

Returns:
the index of the newly added row

int c4_View::AddProperty (  const c4_Property &  prop_  ) 
 

Adds a property column to a view if not already present.

Returns:
0-based column position of the property

c4_View c4_View::Blocked (   )  const
 

Create mapped view which blocks its rows in two levels.

This view acts like a large flat view, even though the actual rows are stored in blocks, which are rebalanced automatically to maintain a good trade-off between block size and number of blocks.

The underlying view must be defined with a single view property, with the structure of the subview being as needed. An example of a blocked view definition which will act like a single one containing 2 properties: 

  c4_View raw = storage.GetAs("people[_B[name:S,age:I]]");
  c4_View flat = raw.Blocked();
  ... flat.GetSize() ...
  flat.InsertAt(...)

This view operation is based on a custom viewer and is modifiable.

c4_View c4_View::Clone (   )  const
 

Constructs a new view with the same structure but no data.

Structural information can only be maintain for the top level, subviews will be included but without any properties themselves.

c4_View c4_View::Concat (  const c4_View &  view_  )  const
 

Create view with rows from another view appended.

Constructs a view which has all rows of this view, and all rows of the second view appended. The structure of the second view is assumed to be identical to this one. This operation is a bit similar to appending all rows from the second view, but it does not actually store the result anywhere, it just looks like it.

This view operation is based on a custom viewer and is modifiable.

c4_View c4_View::Counts (  const c4_View &  keys_,
const c4_IntProp &  result_
)  const
 

Create view with count of duplicates, when grouped by key.

This is similar to c4_View::GroupBy, but it determines only the number of rows in each group and does not create a nested view.

This view operation is based on a read-only custom viewer.

Parameters:
keys_  properties in this view determine grouping
result_  new count property defined in result

c4_View c4_View::Different (  const c4_View &  view_  )  const
 

Create view with all rows not in both views (no dups).

Calculates the "XOR" of two sets. This will only work if both input views are sets, i.e. they have no duplicate rows in them.

This view operation is based on a read-only custom viewer.

c4_View c4_View::Duplicate (   )  const
 

Construct a new view with a copy of the data.

The copy is a deep copy, because subviews are always copied in full.

c4_RowRef c4_View::ElementAt (  int  index_  )  [inline]
 

Element access, shorthand for GetAt.

Returns:
A reference to the specified row in the view. This reference can be used on either side of the assignment operator.
Parameters:
index_  zero-based row index

int c4_View::Find (  const c4_RowRef &  crit_,
int  start_ = 0
)  const
 

Find index of the the next entry matching the specified key.

Defaults to linear search, but hash- and ordered-views will use a better algorithm if possible. Only the properties present in the search key are used to determine whether a row matches the key.

Returns:
position where match occurred
Return values:
-1 if not found
Parameters:
crit_  the value to look for
start_  the index to start with

int c4_View::FindProperty (  int  propId_  )  [inline]
 

Find the index of a property, given its id.

Parameters:
propId_ Unique id associated to a specific propoerty
Returns:
The index of the property, or -1 of it was not found

int c4_View::FindPropIndexByName (  const char *  name_  )  const
 

Find the index of a property, given its name.

Returns:
0-based column index
Return values:
-1 property not present in this view
Parameters:
name_  property name (case insensitive)

int c4_View::GetIndexOf (  const c4_RowRef &  row_  )  const
 

Return the index of the specified row in this view (or -1).

This function can be used to "unmap" an index of a derived view back to the original underlying view.

bool c4_View::GetItem (  int  row_,
int  col_,
c4_Bytes &  buf_
)  const
 

Get a single data item in a generic way.

This can be used to access view data in a generalized way. Useful for c4_CustomViewers which are based on other views.

Returns:
true if the item is non-empty

c4_View c4_View::GroupBy (  const c4_View &  keys_,
const c4_ViewProp &  result_
)  const
 

Create view with a subview, grouped by the specified properties.

This operation is similar to the SQL 'GROUP BY', but it takes advantage of the fact that Metakit supports nested views. The view returned from this member has one row per distinct group, with an extra view property holding the remaining properties. If there are N rows in the original view matching key X, then the result is a row for key X, with a subview of N rows. The properties of the subview are all the properties not in the key.

This view operation is based on a read-only custom viewer.

Parameters:
keys_  properties in this view determine grouping
result_  name of new subview defined in result

c4_View c4_View::Hash (  const c4_View &  map_,
int  numKeys_ = 1
)  const
 

Create mapped view which adds a hash lookup layer.

This view creates and manages a special hash map view, to implement a fast find on the key. The key is defined to consist of the first numKeys_ properties of the underlying view.

The map_ view must be empty the first time this hash view is used, so that Metakit can fill it based on whatever rows are already present in the underlying view. After that, neither the underlying view nor the map view may be modified other than through this hash mapping layer. The defined structure of the map view must be "_H:I,_R:I".

This view is modifiable. Insertions and changes to key field properties can cause rows to be repositioned to maintain hash uniqueness. Careful: when a row is changed in such a way that its key is the same as in another row, that other row will be deleted from the view.

Example of use: 

  c4_View data = storage.GetAs("people[name:S,age:I]");
  c4_View datah = storage.GetAs("people_H[_H:I,_R:I]");
  c4_View hash = raw.Hash(datah, 1);
  ... hash.GetSize() ...
  hash.Add(...)

c4_View c4_View::Indexed (  const c4_View &  map_,
const c4_View &  props_,
bool  unique_ = false
)  const
 

Create mapped view which maintains an index permutation.

This is an identity view which somewhat resembles the ordered view, it maintains a secondary "map" view to contain the permutation to act as an index. The indexed view presents the same order of rows as the underlying view, but the index map is set up in such a way that binary search is possible on the keys specified. When the "unique" parameter is true, insertions which would create a duplicate key are ignored.

This view is modifiable. Careful: when a row is changed in such a way that its key is the same as in another row, that other row will be deleted from the view.

void c4_View::InsertAt (  int  index_,
const c4_RowRef &  newElem_,
int  count_ = 1
)  [inline]
 

Insert a copy of the contents of another view.

This is identical to inserting the specified number of default entries and then setting each of them to the new element value passed as argument.

Parameters:
index_  zero-based row index
newElem_  the value to insert
count_  number of copies to insert, must be > 0

c4_View c4_View::Intersect (  const c4_View &  view_  )  const
 

Create view with all rows also in the given view (no dups).

Calculates the set intersection. This will only work if both input views are sets, i.e. they have no duplicate rows in them.

This view operation is based on a read-only custom viewer.

c4_View c4_View::Join (  const c4_View &  keys_,
const c4_View &  view_,
bool  outer_ = false
)  const
 

Create view which is the relational join on the given keys.

This view operation is based on a read-only custom viewer.

Parameters:
keys_  properties in this view determine the join
view_  second view participating in the join
outer_  true: keep rows with no match in second view

c4_View c4_View::JoinProp (  const c4_ViewProp &  sub_,
bool  outer_ = false
)  const
 

Create view with a specific subview expanded, like a join.

This operation is the inverse of c4_View::GroupBy, expanding all rows in specified subview and returning a view which looks as if the rows in each subview were "expanded in place".

This view operation is based on a read-only custom viewer.

Parameters:
sub_  name of the subview to expand
outer_  true: keep rows with empty subviews

c4_View c4_View::Minus (  const c4_View &  view_  )  const
 

Create view with all rows not in the given view (no dups).

Calculates set-difference of this view minus arg view. Result is a subset, unlike c4_View::Different. Will only work if both input views are sets, i.e. they have no duplicate rows in them.

This view operation is based on a read-only custom viewer.

Parameters:
view_  the second view

const c4_Property & c4_View::NthProperty (  int  index_  )  const
 

Returns the N-th property (using zero-based indexing).

Returns:
reference to the specified property
Parameters:
index_  the zero-based property index

int c4_View::NumProperties (   )  const [inline]
 

Return the number of properties present in this view.

Returns:
A non-negative integer

c4_View c4_View::operator, (  const c4_Property &  prop_  )  const
 

Defines a column for a property.

The following code defines an empty view with three properties: 

  c4_IntProp p1, p2, p3;
  c4_View myView = (p1, p2, p3);
Returns:
the new view object (without any data rows)
See also:
c4_Property

c4_RowRef c4_View::operator[] (  int  index_  )  const [inline]
 

Element access, shorthand for GetAt.

Returns:
A reference to the specified row in the view. This reference can be used on either side of the assignment operator.
Parameters:
index_  zero-based row index

c4_View c4_View::Ordered (  int  numKeys_ = 1  )  const
 

Create mapped view which keeps its rows ordered.

This is an identity view, which has as only use to inform Metakit that the underlying view can be considered to be sorted on its first numKeys_ properties. The effect is that c4_View::Find will try to use binary search when the search includes key properties (results will be identical to unordered views, the find will just be more efficient).

This view is modifiable. Insertions and changes to key field properties can cause rows to be repositioned to maintain the sort order. Careful: when a row is changed in such a way that its key is the same as in another row, that other row will be deleted from the view.

This view can be combined with c4_View::Blocked, to create a 2-level btree structure.

c4_View c4_View::Pair (  const c4_View &  view_  )  const
 

Create view which pairs each row with corresponding row.

This is like a row-by-row concatenation. Both views must have the same number of rows, the result has all properties from this view plus any other properties from the other view.

This view operation is based on a custom viewer and is modifiable.

c4_View c4_View::Product (  const c4_View &  view_  )  const
 

Create view which is the cartesian product with given view.

The cartesian product is defined as every combination of rows in both views. The number of entries is the product of the number of entries in the two views, properties which are present in both views will use the values defined in this view.

This view operation is based on a read-only custom viewer.

c4_View c4_View::Project (  const c4_View &  in_  )  const
 

Create view with the specified property arrangement.

The result is virtual, it merely maintains a permutation to access the underlying view. This "derived" view uses change notification to track changes to the underlying view, but this only works when based on views which properly generate change notifications (.e. raw views, selections, and other projections).

c4_View c4_View::ProjectWithout (  const c4_View &  out_  )  const
 

Create derived view with some properties omitted.

The result is virtual, it merely maintains a permutation to access the underlying view. This "derived" view uses change notification to track changes to the underlying view, but this only works when based on views which properly generate change notifications (.e. raw views, selections, and other projections).

c4_View c4_View::ReadOnly (   )  const
 

Create an identity view which only allows reading.

This view operation is based on a custom viewer.

void c4_View::RelocateRows (  int  from_,
int  count_,
c4_View &  dest_,
int  pos_
) 
 

Move attached rows to somewhere else in same storage.

There is a lot of trickery going on here. The whole point of this code is that moving rows between (compatible!) subviews should not use copying when potentially large memo's and subviews are involved. In that case, the best solution is really to move pointers, not data.

c4_View c4_View::RemapWith (  const c4_View &  view_  )  const
 

Create view which remaps another given view.

Remapping constructs a view with the rows indicated by another view. The first property in the order_ view must be an int property with index values referring to this one. The size of the resulting view is determined by the order_ view and can differ, for example to act as a subset selection (if smaller).

This view operation is based on a custom viewer and is modifiable.

void c4_View::RemoveAt (  int  index_,
int  count_ = 1
)  [inline]
 

Remove entries starting at the given index.

Entries which have other view references may cause these views to be deleted if their reference counts drop to zero because of this removal.

Parameters:
index_ the zero-based row index
count_ the number of entries to remove

c4_View c4_View::Rename (  const c4_Property &  old_,
const c4_Property &  new_
)  const
 

Create view with one property renamed (must be of same type).

This view operation is based on a custom viewer and is modifiable.

int c4_View::Search (  const c4_RowRef &  crit_  )  const
 

Search for a key, using the native sort order of the view.

Returns:
position where found, or where it may be inserted, this position can also be just past the last row

c4_View c4_View::Select (  const c4_RowRef &  crit_  )  const
 

Create view with rows matching the specified value.

The result is virtual, it merely maintains a permutation to access the underlying view. This "derived" view uses change notification to track changes to the underlying view, but this only works when based on views which properly generate change notifications (.e. raw views, other selections, and projections).

c4_View c4_View::SelectRange (  const c4_RowRef &  low_,
const c4_RowRef &  high_
)  const
 

Create view with row values within the specified range.

The result is virtual, it merely maintains a permutation to access the underlying view. This "derived" view uses change notification to track changes to the underlying view, but this only works when based on views which properly generate change notifications (.e. raw views, other selections, and projections).

Parameters:
low_  values of the lower bounds (inclusive)
high_  values of the upper bounds (inclusive)

void c4_View::SetAt (  int  index_,
const c4_RowRef &  newElem_
)  [inline]
 

Change the value of the specified entry.

If the new value has other properties, these will be added to the underlying view.

Parameters:
index_ the zero-based row index
newElem_ the row to copy to this view

void c4_View::SetSize (  int  newSize_,
int  growBy_ = -1
)  [inline]
 

Change the size of this view Since views act like dynamic arrays, you can quickly change their size.

Increasing the size will append rows with zero/empty values, while decreasing it will delete the last rows. The growBy_ parameter is currently unused.

c4_View c4_View::Slice (  int  first_,
int  limit_ = -1,
int  step_ = 1
)  const
 

Create view which is a segment/slice (default is up to end).

Returns a view which is a subset, either a contiguous range, or a "slice" with element taken from every step_ entries. If the step is negative, the same entries are returned, but in reverse order (start_ is still lower index, it'll then be returned last).

This view operation is based on a custom viewer and is modifiable.

c4_View c4_View::Sort (   )  const
 

Create view with all rows in natural (property-wise) order.

The result is virtual, it merely maintains a permutation to access the underlying view. This "derived" view uses change notification to track changes to the underlying view, but unfortunately there are some major limitations with this scheme - one of them being that deriving another view from this sorted one will not properly track changes.

c4_View c4_View::SortOn (  const c4_View &  up_  )  const
 

Create view sorted according to the specified properties.

The result is virtual, it merely maintains a permutation to access the underlying view. This "derived" view uses change notification to track changes to the underlying view, but unfortunately there are some major limitations with this scheme - one of them being that deriving another view from this sorted one will not properly track changes.

c4_View c4_View::SortOnReverse (  const c4_View &  up_,
const c4_View &  down_
)  const
 

Create sorted view, with some properties sorted in reverse.

The result is virtual, it merely maintains a permutation to access the underlying view. This "derived" view uses change notification to track changes to the underlying view, but unfortunately there are some major limitations with this scheme - one of them being that deriving another view from this sorted one will not properly track changes.

Parameters:
up_  the view which defines the sort order
down_  subset of up_, defines reverse order

c4_View c4_View::Union (  const c4_View &  view_  )  const
 

Create view which is the set union (assumes no duplicate rows).

Calculates the set union. This will only work if both input views are sets, i.e. they have no duplicate rows in them.

This view operation is based on a read-only custom viewer.

c4_View c4_View::Unique (   )  const
 

Create view with all duplicate rows omitted.

This view operation is based on a read-only custom viewer.

The documentation for this class was generated from the following files:
Metakit C++ API Reference - https://www.equi4.com/metakit.html - extracted with Doxygen