DBExpression

DBExpression

Inherits From: Object

Conforms To: DBProperties
DBExpressionValues

Declared In: dbkit/DBExpression.h

Class Description

A DBExpression encapusulates a database expression as an object. A database expression specifies a property of data to be returned from an entity in the database. A fetch is governed by a list of DBExpressions, one for each of the properties to be returned (and also by a DBQualifier that specifies which records are to be included.)
The DBExpression class provides methods that let you refer to existing properties, specify the type of data to be returned for a property, and combine existing properties to create a new one.
Every DBExpression is relative to an entity; the entity is specified in the initForEntity:... methods:

initForEntity:fromDescription:

initForEntity:fromName:usingType:

You can change the entity or description of an existing DBExpression by sending it a setEntity:andDescription: message.

Format of a DBExpression's Description
The text of a DBExpression is called its description. The description is constructed in much the same way as a printf statement. That is, it consists of a quoted string containing the symbols needed to construct the expression with placeholders for the various values, followed by the names of the objects to be substituted for the placeholders. The following substitution symbols may occur within the quoted string:

Symbol Expected value

%s A constant string (const char *).

%p A (const char *) that names one of the entity's properties.

%d An int.

%f A double or float.

%@ An object that conforms to the DBExpressionValues protocol, or a property object created by the Database Kit. (The former includes DBExpression, allowing you to created a nested expression.)

%% No value--this passes a single `%' literally.

The rest of the format string should comprise query-language operators and symbols, the names of properties, and whitespace. For example, suppose you have a boxes entity that has properties named "height", "width", and "depth." To create a DBExpression that calculates the volume of a box, you would do the following:

id h = [boxes propertyNamed:"height"];
id w = [boxes propertyNamed:"width"];
id d = [boxes propertyNamed:"depth"];

DBExpression *volume = [[DBExpression alloc] initForEntity:boxes
fromDescription:"%@ * %@ * %@", h,w,d];

/* Setting the name isn't essential, but it's a good idea. */
[volume setName:"volume"];

To evaluate a DBExpression, you send it an expressionValue message. The return is a string in the query language used by the adaptor, representing the expression.

Using a DBExpression
A DBExpression object adopts the DBProperties protocol, and so can be used in any situation that requires a property. To retrieve data for a DBExpression, before executing a fetch, you add the DBExpression to the list of expressions maintained by the object that you're using to fetch data (a DBRecordList, DBRecordStream, or DBBinder). You can use a DBExpression to get the value for a property from a record by passing it to methods such as DBBinder's valueForProperty: or DBRecordList's getValue:forProperty:.
The two most important differences between a DBExpression that you've created and a property that you've retrieved from an entity are these:

You can't write the value for a self-created DBExpression back to the source.

You create it, you free it.

Instance Variables

None declared in this class.

Adopted Protocols

DBExpressionValues expressionValue

isDeferredExpression

DBProperties name

setName:
entity
matchesProperty:
propertyType
isSingular
isReadOnly
isKey

Method Types

Creating and freeing a DBExpression

initForEntity:fromDescription:
initForEntity:fromName:usingType:
copyFromZone:
free

Setting the entity and description

setEntity:andDescription:

Archiving read:

write:

Instance Methods

copyFromZone:

copyFromZone:(NXZone *)zone

Creates and returns a copy of the receiving DBExpression. The new object is created in the given zone.

free

free

Frees the DBExpression.

initForEntity:fromDescription:

initForEntity:(id <DBEntities>)anEntity

fromDescription:(const unsigned char *)descriptionFormat, ...

A designated initializer for the DBExpression class, this initializes a freshly allocated DBExpression by setting its entity to anEntity and setting its description as specified by the other arguments. The description is in the style of a printf statement: descriptionFormat is a quoted string that establishes the format of the description, the following arguments supply the description with values. The arguments are separated by commas. See the class description above for the rules governing the format of the description string.
If the description refers to a single, unmanipulated property, then the DBExpression will be "simple"--the property that the DBExpression represents will be the property referred to in the description. If the description manipulates one or more existing properties, then the object is "derived," and a new property object is created to describe the manipulation. The data type of a derived DBExpression is a string, and it's given a unique name.
Returns self, or nil if either of the arguments is nil.
See also: initForEntity:fromName:usingType:

initForEntity:fromName:usingType:

initForEntity:(id <DBEntities>)anEntity

fromName:(const char *)aPropertyName
usingType:(const char *)aType

A designated initializer for the DBExpression class, this initializes a freshly allocated DBExpression by setting its entity to anEntity, and creating a property object (owned by the DBExpression) that points to the property named by aPropertyName. The data type of the new property is set to aType, so that data retieved by this expression will be coerced to the indicated type.
Returns self, or nil if anEntity is nil or if the named property doesn't exist in the entity.
See also: initForEntity:fromDescription:

read:

read:(NXTypedStream *)stream

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

setEntity:andDescription:

setEntity:(id <DBEntities>)anEntity

andDescription:(const unsigned char *)descriptionFormat, ...

Replaces the DBExpression's entity and description with those provided by the arguments. See the class description for more information on the format of the description string.
See also: initForEntity:fromDescription:

write:

write:(NXTypedStream *)stream

Writes the DBExpression to the typed stream stream. Returns self.

	Inherits From:	Object

	Conforms To:	DBProperties DBExpressionValues

	Declared In:	dbkit/DBExpression.h

		initForEntity:fromDescription:
		initForEntity:fromName:usingType:

	Symbol	Expected value

	%s	A constant string (const char *).

	%p	A (const char *) that names one of the entity's properties.

	%d	An int.

	%f	A double or float.

	%@	An object that conforms to the DBExpressionValues protocol, or a property object created by the Database Kit. (The former includes DBExpression, allowing you to created a nested expression.)

	%%	No value--this passes a single `%' literally.

		You can't write the value for a self-created DBExpression back to the source.
		You create it, you free it.