Column Class Reference

[libkorigin Index] [libkorigin Heirarchy]


A column of data More...

#include </home/mh/korigin/korigin/doc/tmp/column.h>

Public Members


Detailed Description

A column of data. A column is an array of data, of type Double or String. You can determinate the type of a column with the type() function. The type is defined in the column´s constructor.

Data is accessed via the value(), setValue(), and operator[] functions. Note that the operator[] does only make sence for Double columns. (type() == Column::columnDouble.) But when dealing with Double columns in numerical context, you should definitively use the operator[], since it is a) faster and b) doesn´t loose digits, since value() returns a string and has to be re-converted to double.

For each column, a title() and a format() string is stored. The function of the title is pretty obvious - it´s the name of the column. What is less obvious about the title is that it´s also used by the formula interpreter to look up a column. The format string is used to set the precision of the worksheet representation of numbers.

You can copy columns freely. They are implemented using reference counting, so copying them is cheap.

Columns are implemented with a highly efficient auto-resizing mechanism. Auto-resize is done in 1024-steps without copying, that is, it´s comparatively fast. The current maximum size of a column is 1048576 elements (8 MB + epsilon for doubles, 4 MB + epsilon + the actual text for strings).


enum ColumnType ( columnEmpty, columnDouble, columnString )

Enumeration of columns types. An columnEmpty column does not containanything; columnDouble contains doubles, columnString strings. (Pretty obvious.)

See Also:
type

Column(ColumnType col_type = columnEmpty)

Column Constructor. By default, this function generates an empty column, i.e. one without any data. You can choose one of the types enumerated in ColumnType.

Parameters:
col_type type of the new column
See Also:
typeColumnType

Column(const Column&)

Copy constructor. You may copy columns freely, since they are implemented using reference counting. Copies are "flat" copies.

~Column()

Column Destructor. The column is destroyed, and if it was the last column using the data, the data is also deleted; if, however, other columns still refer to the same data, the data is *not* deleted.

Column& operator=(const Column&)

Assignment operator. You may assign columns freely, since they are implemented using reference counting. Copies are "flat" copies.

ColumnType type()

Identify type of a column. The type returned is one of those defined in ColumnType, namely the one from the constructor call the column was created with - unless, of course, you used the assignment operator, in which case the type is the same as of the assigned column.

Returns:
type of the column
See Also:
ColumnType

int dim()

Dimension of the column. The dimension of an auto-resizing column is defined as the index of the highest (possibly) *written* element. That is, the highest index used in setValue() and operator[].

Returns:
dimension of the column as defined above
See Also:
setValueColumn::operator

const char* value(int index) const

Value of a cell, as a string. If the column holds strings, the requested string cell is directly returned. ("" if unused/unset.) If the column holds doubles, the number is sprintf´ed into a buffer using the format string of the column, and this buffer is returned. ("-" if unused/unset.)

When doing math with double columns, you should definitively prefer the operator[] due to both speed and precision. When printf´ing a value o the buffer, digits get lost because the format string might limit them to two digits. (Default; mileage may vary, but the principle remains.)

This function does not enlarge the column, even if the index is "out of range".

Parameters:
index index of the cell to be read out
See Also:
setFormatsetValueColumn::operator

void setValue(int index, const char* new_value)

Set the value of a cell. For string columns, a deep copy of the string is stored in the appropriate cell; for double columns, the given string is converted into a double using the C library routine, strtod(). If the conversion fails, the content of the cell is set to NAN (printed as "-").

If you set the last existing cell of a column to (char*)0, the dimension of the column will be decremented by one.

When doing math with double columns, you should definitively prefer the operator[], which is faster because it does not need to convert the string to double.

If the cell was not allocated yet (i.e. the index was "out of range"), the column is enlarged until it fits the index. This can cost quite a large amount of memory, especially when you pass an idiotically high index ("setValue(1000042,"42");").

If the index is higher than the current dimension of the column, the dimension is set to index. Therefore, the dim() always returns the index of the "highest" cell that is set to a value.

Parameters:
index index of the cell to be set
new_value new value of the specified cell
See Also:
dimvalueColumn::operator

double& operator[](int index)

Reference to numerical value of a cell. Use this whenever you´re doing math with double columns!

Use this only when you´re doing math with double columns!

For double columns, the operator[] provides a convenient and fast method to get/set values. Plus, it does not loose digits as value() might do.

If, however, you´re dealing with strings, this operator does not make any sence. It will just return NAN, and if you change its value, it will forget it immediately.

Parameters:
index index of the cell
Returns:
reference to the specified cell reference to the specified cell
See Also:
dimvaluesetValue

const char* title() const

Title of the column. This returns the title of the column, as used in the worksheet, and by the formula interpreter (when looking up columns).

Returns:
title of the column
See Also:
setTitleFormula

void setTitle(const char* new_title)

Change the title of the column. This changes the title of the column, as used in the worksheet, and by the formula interpreter (when looking up columns).

Parameters:
new_title the new title of the column
See Also:
title

const char* format() const

Format string of the column. The format string is used by double columns to convert doubles to strings in the value() function.

Returns:
format string of the column
See Also:
valuesetFormat

void setFormat(const char* new_format)

Change the format string of the column. The format string is used by double columns to convert doubles to strings in the value() function.

Parameters:
new_format new format string of the column
See Also:
valueformat

friend ostream& operator<<(ostream&, Column&)

Dump a column to an ostream. For debugging, you might want to dump a column to an ostream (cout or cerr, most likely). To print the column "myColumn" to the console, just go:

cout << myColumn << endl;


  • Author: Patrick Schemitz
  • Documentation generated by mh@jeff_clever on Thu Feb 5 14:15:25 MET 1998
Kdoc