databases::Field Class Reference

Database field. More...

#include <field.h>

List of all members.

Public Types

enum  { faCase = 0x0001, faOwner = 0x0002, faOwnerUnique = 0x0004 }
 Field attributes. More...

Public Member Functions

 Field ()
 Constructor.
virtual ~Field ()
 Destructor.
virtual bool setup ()
 Sets the field up.
char const * name () const
 Returns the field name.
char const * name (char const *name)
 Sets the field name.
uint16_t version (int type) const
 Returns version numbers.
uint16_t version (int type, uint16_t ver)
 Sets version numbers.
uint16_t type () const
 Returns the type of the field.
uint16_t type (uint16_t type)
 Sets the type of the field.
size_t size () const
 Returns the size of the field.
size_t size (size_t size)
 Sets the size of the field.
uint16_t attrs () const
 Returns the attributes of the field.
uint16_t attrs_add (uint16_t attrs)
 Adds an attribute to the field.
uint16_t attrs_remove (uint16_t attrs)
 Removes an attribute from the field.
char const * default_value () const
 Returns the default value, as a string.
char const * default_value (char const *defval)
 Sets the default value of the field.
int32_t idefault_value () const
 Returns the default value, as an integer.
uint32_t uidefault_value () const
 Returns the default value, as an unsigned integer.
time_t utdefault_value () const
 Returns the default value, as a Unix timestamp.
Record::identifier_type ridefault_value () const
 Returns the default value, as a record identifier.
uint16_t tag () const
 Returns the tag of the field.
uint16_t tag (uint16_t tag)
 Sets the tag of the field.

Static Public Attributes

static uint16_t const ftString = 1
 String type.
static uint16_t const ftInteger = 2
 Integer type.
static uint16_t const ftUnsigned = 3
 Unsigned integer type.
static uint16_t const ftUnixTime = 4
 Unix timestamp type.
static uint16_t const ftIdentifier = 5
 Record identifier type.
static uint16_t const ftCount = 5
 The number of types.

Protected Attributes

misc::cstring m_name
 The name of the field.
uint16_t m_minver
 Minimum version required.
uint16_t m_maxver
 Maximum version allowed.
uint16_t m_type
 Type of the field.
size_t m_size
 Size of the field.
uint16_t m_attrs
 Attributes of the field.
misc::cstring m_default
 Default value of the field (as a string).
uint16_t m_tag
 Field tag.
bool m_setup
 Has setup() been called?
int32_t m_idefault
 Default value of the field (as an integer -- if of ftInteger type.).
uint32_t m_uidefault
 Default value of the field (as an unsigned integer -- if of ftUnsigned type.).
time_t m_utdefault
 Default value of the field (as a unix timestamp -- if of FtUnixTime type.).
Record::identifier_type m_ridefault
 Default value of the field (as a record identifier -- if of ftIdentifier type.).


Detailed Description

This is a base class for fields used by databases to have some basic information about what they store as well as to let them set values in records in a generic way.

For each field you create, you need to set its name, version information, type, size, attributes and default value.

Note that you can't change the type, size, attribute or default value of a field once it has been created in a database. Therefore, changing the type of a field and recompiling won't work because the database driver is NOT required to change existing fields in the database.

The setup() function may be overriden in derived classes.


Member Enumeration Documentation

anonymous enum
 

Enumerator:
faCase  Field value is case-sensitive.
faOwner  Field may be passed to Database::delete_owned().
faOwnerUnique  Field may be passed to Database::delete_owned(), unique owner.


Member Function Documentation

uint16_t databases::Field::attrs  )  const [inline]
 

Returns the attributes of the field.

Returns:
The attributes of the field, which consists of an or'ed set of the following:
  • faCase: if the field type if ftString, the string should be compared case-sensitively.
  • faOwner: if the field type is ftIdentifier, the field may be used with the Database::delete_owned() function.
  • faOwnerUnique: if the field type is ftIdentifier, the field may be used with the Database::delete_owned function. Each owner ID is only set for one record in the database.

char const* databases::Field::default_value char const *  defval  ) 
 

Sets the default value of the field. The default value are used by database drivers to assign the initial values for newly-created fields in the existing records. This should prevent a lot of extra work from database drivers users because otherwise they would always have to set the intended initial value for new fields themselves.

Parameters:
[in] defval The default value, which may be NULL if the field type is ftString.
Returns:
The default value of the field.

int32_t databases::Field::idefault_value  )  const [inline]
 

Returns the default value, as an integer. This function should be called only if the field is of the ftInteger type. Else, its result is unspecified.

Returns:
The default value of the field, as an integer.

char const* databases::Field::name char const *  name  ) 
 

Sets the field name.

Parameters:
[in] name The name, which must only contain characters 0-9A-Za-z_ (no checks are made so you must make sure it is correct).
Returns:
The field name.

Record::identifier_type databases::Field::ridefault_value  )  const [inline]
 

Returns the default value, as a record identifier. This function should be called only if the field is of the ftIdentifier type. Else, its result is unspecified.

Returns:
The default value of the field, as a record identifier.

virtual bool databases::Field::setup  )  [virtual]
 

Sets the field up. This is called by the Database::add_field() function before the field is added to the field list of a database.

The default implementation computes the integer default value if needed, and ensures all required information about the field has been set.

Returns:
true if successful, false otherwise.

size_t databases::Field::size size_t  size  ) 
 

Sets the size of the field.

Parameters:
[in] size The size of the field. If the type of the field is ftString, the size must be set to the maximum length allowed for the string, and if of the ftInteger or ftUnsigned types, it must be set to 1, 2 or 4 depending on the intended size for the integer (respectively 8-bit, 16-bit or 32-bit). For all other field types, the size is ignored.
Returns:
The size of the field.

uint16_t databases::Field::tag uint16_t  tag  ) 
 

Sets the tag of the field, which may be used by other modules to quickly identify a field in a database by looking up a numeric value rather than comparing a string.

The number assigned should be unique at all times in a database.

Parameters:
[in] tag The tag number (should be different than zero).
Returns:
The tag of the field.

uint16_t databases::Field::type uint16_t  type  ) 
 

Sets the type of the field.

Parameters:
[in] type The type of the field, which can be one of the following:
  • ftString: The string type. Beware that database drivers consider that a NULL string and an empty string ("") are the same thing, and they automatically convert all empty strings to NULL strings on return.
  • ftInteger: The signed integer type, which may hold up to 32 bits.
  • ftUnsigned: The unsigned integer type, which may hold up to 32 bits.
  • ftUnixTime: The Unix timestamp type (basically, time_t in C/C++).
  • ftIdentifier: The record identifier type (i.e. Record::identifier_type), used for fields that need to reference to identifiers.
Returns:
The type of the field.

uint32_t databases::Field::uidefault_value  )  const [inline]
 

Returns the default value, as an unsigned integer. This function should be called only if the field is of the ftUnsigned type. Else, its result is unspecified.

Returns:
The default value of the field, as an unsigned integer.

time_t databases::Field::utdefault_value  )  const [inline]
 

Returns the default value, as a Unix timestamp. This function should be called only if the field is of the ftUnixTime type. Else, its result is unspecified.

Returns:
The default value of the field, as a Unix timestamp.

uint16_t databases::Field::version int  type,
uint16_t  ver
 

Sets version numbers for the field.

Setting version numbers after the field has been added to a database has no effect.

Parameters:
[in] type The type of version to set, which can be either Database::vtMinimum or Database::vtMaximum.
[in] ver The version number.
Returns:
The new version number for the given type.
See also:
version(int)

uint16_t databases::Field::version int  type  )  const
 

Returns version numbers that have been set for the field. A field's value is imported when the database version is between the minimum and maximum import version (but only if the value exists in the database), and exported when the database version is between the minimum and maximum export version.

Parameters:
[in] type The type of version to return, which can be one of the following values:
  • Database::vtMinimum: The minimum version number required. If the database has a lower import or export version, then the value of this field will respectively not be imported when importing record data or not be exported to the database. The minimum version can't be zero.
  • Database::vtMaximum: The maximum version number required. If the database has a higher import or export version, then the value of this field will respectively not be imported when importing record data or not be exported to the database. If the maximum version is zero, then there won't be any check for the maximum version number.
Returns:
The requested version number.


The documentation for this class was generated from the following file:
Generated on Sun May 20 21:32:20 2007 for Epona API by  doxygen 1.4.6