PTDiffusionMutableRecordV2Model Class Reference

Introduction

A mutable data model based upon a schema.

An initial version of such a model can be created from a schema using createMutableModel (PTDiffusionRecordV2Schema). A model created in this way will have all mandatory fields set to default values.

The model may then be updated as required and then at any time a PTDiffusionRecordV2 object can be generated from the current state by reading the PTDiffusionRecordV2Model::value property. That object may then be used to update a topic.

When values for integer or decimal type fields are supplied the values are validated and normalized. All number values will have any insignificant leading zeroes removed. A decimal value will also be rounded to its specified scale using half-up rounding.

Since

6.0

Inheritance diagram for PTDiffusionMutableRecordV2Model:

Instance Methods
(BOOL)	- addRecordError:
(BOOL)	- addFieldValues:error:
(BOOL)	- addToRecordName:recordIndex:fieldValues:error:
(BOOL)	- clearVariableFieldsForRecordName:recordIndex:error:
(void)	- clearVariableRecords
(BOOL)	- removeFieldWithIndex:fromRecordName:recordIndex:error:
(BOOL)	- removeRecordWithIndex:error:
(BOOL)	- setRecordName:recordIndex:fieldName:fieldIndex:toFieldValue:error:
(BOOL)	- setFieldValue:forKey:error:
Instance Methods inherited from PTDiffusionRecordV2Model
(nullable PTDiffusionRecordV2 *)	- valueWithError:
(nullable NSNumber *)	- fieldCountWithRecordName:recordIndex:fieldName:error:
(nullable NSNumber *)	- recordCountWithRecordName:error:
(nullable NSString *)	- fieldValueForKey:error:
(nullable NSString *)	- fieldValueForRecordName:recordIndex:fieldName:fieldIndex:error:

Method Documentation

addFieldValues:error:

- (BOOL) addFieldValues:		(NSArray< NSString * > *)	fieldValues
error:		(NSError **)	error

Appends new values to the end of a variable length field list.

This is a convenience method for adding to the end of the last record and is therefore useful when there is only one record type.

Parameters

fieldValues	The values to add.
error	If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• details conflict with the schema, possibly because the last field of the last record is not a variable multiplicity field or the maximum number of occurrences for the field would be breached.
• one of the values is incompatible with the field type.

Exceptions

NSInvalidArgumentException

If fieldValues is `nil`.

Note

This method does nothing if fieldValues is an empty array.

Since

6.0

addRecordError:

- (BOOL) addRecordError:

(NSError **)

error

Appends a new initialized record occurrence to the end of a variable multiplicity record list.

As the only variable multiplicity record can be the last one there is no need to name the record. This method will add to the list of occurrences of the last defined record. The record will be initialized with default values appropriate to the schema definition and may then have individual field items set separately.

Parameters

error

If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• the last or only record is not a variable repeating record or has already reached the maximum number of occurrences.

Since

6.0

addToRecordName:recordIndex:fieldValues:error:

- (BOOL) addToRecordName:		(NSString *)	recordName
recordIndex:		(SInt32)	recordIndex
fieldValues:		(NSArray< NSString * > *)	fieldValues
error:		(NSError **)	error

Appends new values to the end of a variable length field list.

This can only be used for a variable multiplicity field which can only be the last field in a record and therefore the field does not need to be named.

Parameters

recordName	The name of the record.
recordIndex	The index identifying the occurrence of the record.
fieldValues	The values to add.
error	If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• details conflict with the schema, possibly because the last field of the record is not a variable multiplicity field or the maximum number of occurrences for the field would be breached.
• one of the values is incompatible with the field type.
• recordIndex is out of bounds.

Exceptions

NSInvalidArgumentException

If either recordName or fieldValues is nil, or if recordIndex is negative.

Note

This method does nothing if fieldValues is an empty array.

Since

6.0

clearVariableFieldsForRecordName:recordIndex:error:

- (BOOL) clearVariableFieldsForRecordName:		(NSString *)	recordName
recordIndex:		(SInt32)	recordIndex
error:		(NSError **)	error

Remove all optional instances of a variable multiplicity field.

As a variable repeating field can only be the last or only field within a record then the field name does not need to be specified.

This will only remove field occurrences down to the minimum number of occurrences specified by the schema.

If the last or only field within the record is not defined as variable multiplicity, this would have no effect.

Parameters

recordName	The name of the record.
recordIndex	The index of the record.
error	If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• recordName is not defined in the schema.
• recordIndex is out of bounds.

Exceptions

NSInvalidArgumentException

If recordName is `nil`, or if recordIndex is negative.

Since

6.0

clearVariableRecords

- (void) clearVariableRecords

Removes all optional instances of a variable multiplicity record.

As a variable repeating record can only be the last or only record then the record name does not need to be specified.

This will only remove record occurrences down to the minimum number of occurrences specified by the schema.

If the last or only record is not defined as variable multiplicity, calling this method has no effect.

Since

6.0

removeFieldWithIndex:fromRecordName:recordIndex:error:

- (BOOL) removeFieldWithIndex:		(SInt32)	fieldIndex
fromRecordName:		(NSString *)	recordName
recordIndex:		(SInt32)	recordIndex
error:		(NSError **)	error

Removes the specified occurrence of a variable multiplicity field.

A variable multiplicity field must be the last or only field within a record and therefore the field name is not required.

Parameters

recordName	The name of the record.
recordIndex	The record index.
fieldIndex	The index of the field to remove.
error	If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• the record is not known or the last or only field within the record is not a variable repeating field or can not be removed as it would violate the minimum number of occurrences.
• either recordIndex or fieldIndex is out of bounds.

Exceptions

NSInvalidArgumentException

If recordName is `nil`, recordIndex is negative or fieldIndex is negative.

Since

6.0

removeRecordWithIndex:error:

- (BOOL) removeRecordWithIndex:		(SInt32)	recordIndex
error:		(NSError **)	error

Removes the specified occurrence of a variable multiplicity record.

A variable multiplicity record must be the last or only record within a schema and therefore the record name is not required.

Parameters

recordIndex	The index of the record to remove.
error	If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• the last or only record is not a variable multiplicity record or can not be removed as it would violate the minimum number of occurrences.
• recordIndex is out of bounds.

Exceptions

NSInvalidArgumentException

If recordIndex is negative.

Since

6.0

setFieldValue:forKey:error:

- (BOOL) setFieldValue:		(NSString *)	fieldValue
forKey:		(NSString *)	key
error:		(NSError **)	error

Sets a specified field value.

This allows an item to be addressed using a key of the form recordName(recordIndex).fieldName(fieldIndex). Indexes may be omitted in which case 0 is assumed. The record part may also be omitted in which case the first occurrence of the first record is assumed.

Parameters

key	The field key.
fieldValue	The field value.
error	If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• the key does not address a valid field.
• a specified index is out of bounds.
• the key format is invalid.
• a specified index is not a valid number.

Exceptions

NSInvalidArgumentException

If either key or fieldValue is `nil`.

Since

6.0

setRecordName:recordIndex:fieldName:fieldIndex:toFieldValue:error:

- (BOOL) setRecordName:		(NSString *)	recordName
recordIndex:		(SInt32)	recordIndex
fieldName:		(NSString *)	fieldName
fieldIndex:		(SInt32)	fieldIndex
toFieldValue:		(NSString *)	fieldValue
error:		(NSError **)	error

Sets a specified field value.

Parameters

recordName	The name of the record containing the field.
recordIndex	The index of the record containing the field.
fieldName	The name of the field.
fieldIndex	The index of the field.
fieldValue	The new value.
error	If this method returns NO to indicate that an error occurred then this will be populated with the reason for that failure.

Returns

YES on success; or NO if an error occurred, in which case *error will be populated with the failure reason. Reasons for failure include:

• the details given conflict with the schema or the value is incompatible with the schema field type.
• either recordIndex or fieldIndex is out of bounds.

Exceptions

NSInvalidArgumentException

If recordName is `nil`, recordIndex is negative, fieldName is nil, fieldIndex is negative or fieldValue is nil.

Since

6.0