DBValue

DBValue

Inherits From: Object

Conforms To: DBExpressionValues

Declared In: dbkit/DBValue.h

Class Description

The DBValue class provides objects that can embody different types of data. DBValue objects are used throughout the Database Kit to retrieve and modify arbitrarily typed values.
A DBValue object consists of two parts: a value and a type. The value and type are set at the same time, through methods such as setIntValue: and setStringValue:; the value is passed as the argument, the type is set as indicated by the method's name. Once this information has been set, you can retrieve the DBValue's value through methods such as intValue and stringValue. The value is converted, if possible, to the requested return type. You can retrieve a DBValue's type--the type that was named by the method that set the value--as a DBTypes-conforming object through the valueType method.
The type of a DBValue object can be one of the following:

An object

A string

An integer

A single-precision floating-point number

A double-precision floating point number

NULL

The type conversion mentioned above applies only to strings, numeric values, and NULL; you can't convert an object to or from the other data types.
The primary use the Database Kit makes of DBValue objects is to store the values that are contained in a record. The objects are necessary because you can't examine or set a record's values directly: You have to get a record value (indexed by property) into a DBValue object, examine and/or modify the DBValue, and set the DBValue back into the record. Getting and setting record values is typically done through the DBRecordList (or DBRecordStream) methods getValue:forProperty: and setValue:ForProperty:.
The following example demonstrates how to use a DBRecordList and a DBValue to modify the record that the DBRecordList is currently pointing to:

/* Create a DBValue to retrieve and modify a record value. */
DBValue *age = [[DBValue alloc] init];

/* Retrieve the value of a property from a DBRecordList. */
/* (aRecordList and aProperty are assumed to exist. */
[aRecordList getValue:age forProperty:ageProperty];

/* Modify the value and write it back to the record. */
[birthRight setFloatValue:[age intValue]+1.0];
[aRecordList setValue:age forProperty:aProperty];

DBBinder also defines a method, valueForProperty:, that returns a DBValue that contains the value of the current record for a particular property. However, unlike with a DBRecordList, you can modify the DBValue returned by this method and so modify the record directly.
DBValues are also used to store the values of a record's key properties, and to store the value that's embodied in a DBAssociation.

Instance Variables

None declared in this class.

Adopted Protocols

DBExpressionValues expressionValue

isDeferredExpression

Method Types

Creating and Freeing + initialize

init
free

Setting values setDoubleValue:

setFloatValue:
setIntValue:
setObjectValue:
setObjectValueNoCopy:
setStringValue:
setStringValueNoCopy:
setValueFrom:
setNull

Reporting values valueType

isEqual:
doubleValue
floatValue
intValue
objectValue
stringValue
isNull

Archiving read:

write:

Class Methods

initialize

+ initialize

Prepares the class for use. You normally don't need to invoke this method; however, if you're creating a subclass that implements an initialize method, you should certainly send initialize to super as part of the implementation. Returns self.

Instance Methods

doubleValue

(double)doubleValue

Returns the DBValue's value converted to a double-precision floating-point number. If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

floatValue

(float)floatValue

Returns the DBValue's value converted to a single-precision floating-point number. If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

free

free

Frees the DBValue.

init

init

The designated initializer for the DBValue class, init initializes a newly allocated DBValue object.

intValue

(int)intValue

Returns the DBValue's value converted to an integer. If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

isEqual:

(BOOL)isEqual:(DBValue *)anotherValue

Compares the DBValue with anotherValue and returns YES or NO as their values are or aren't equivalent. The two objects' types needn't be the same; the method will convert the argument's value to that of the receiving DBValue, if necessary, and then perform the comparison. A DB_COERCION_ERROR exception is raised if the conversion isn't supported.

isNull

(BOOL)isNull

Returns YES if the DBValue's value hasn't been set, or if it's been set to the null value appropriate for its type.

objectValue

objectValue

Returns the DBValue's value. The value must be an object, otherwise a DB_COERCION_ERROR exception is raised.

read:

read:(NXTypedStream *)stream

Reads the DBValue from the typed stream stream. Returns self.

setDoubleValue:

setDoubleValue:(double)aDouble

Sets the DBValue's value to aDouble and declares its type to be a double. Returns self.

setFloatValue:

setFloatValue:(float)aFloat

Sets the DBValue's value to aFloat and declares its type to be a float. Returns self.

setIntValue:

setIntValue:(int)anInt

Sets the DBValue's value to anInt and declares its type to be an integer. Returns self.

setNull

setNull

Sets the DBValue's value and type to NULL. Returns self.

setObjectValue:

setObjectValue:(id)anObject

Sets the DBValue's value to a copy of anObject and declares its type to be an object. Returns self.

setObjectValueNoCopy:

setObjectValueNoCopy:(id)anObject

Sets the DBValue's value to anObject and declares its type to be an object. Returns self.

setStringValue:

setStringValue:(const char *)aString

Sets the DBValue's value to a copy of aString and declares its type to be a string. Returns self.

setStringValueNoCopy:

setStringValueNoCopy:(const char *)aString

Sets the DBValue's value to point to aString and declares its type to be a string. Returns self.

setValueFrom:

setValueFrom:(DBValue *)aValue

Sets the DBValue's value and type to those of aValue. Returns self.

stringValue

(const char *)stringValue

Returns the DBValue's value converted to a string. If the conversion can't be performed, a DB_COERCION_ERROR exception is raised.

valueType

(id <DBTypes>)valueType

Returns a private, DBTypes-conforming object that stores the DBValue's type. To get a string that represents the Objective C data type from this object, you would send it an objcType message. The following table gives DBTypes string representations of the DBValue types:

DBValue type DBTypes representation

object "@"

string "*"

integer "i"

float "f"

double "d"

NULL NULL

write:

write:(NXTypedStream *)stream

Writes the DBValue object to the typed stream stream. Returns self.

	Inherits From:	Object

	Conforms To:	DBExpressionValues

	Declared In:	dbkit/DBValue.h

		An object
		A string
		An integer
		A single-precision floating-point number
		A double-precision floating point number
		NULL

	DBValue type	DBTypes representation

	object	"@"
	string	"*"
	integer	"i"
	float	"f"
	double	"d"
	NULL	NULL