MBFieldListFormatter Class Reference

Inherits from NSObject
Declared in MBFieldListFormatter.h

Overview

An object that, for monospaced fonts, outputs a list of fields in an easy-to-read format. This class is typically used in debugging.

Instances can be created directly via new or, when being used to represent a particular object instance, using the formatterForObject: factory method.

Note: Classes can also inherit from MBFormattedDescriptionObject to allow its description method to be driven by an MBFieldListFormatter. This makes it easy for a class to create nicely-formatted output for use in the console when debugging.

Acquiring instances

+ formatterForObject:

Creates a new formatter to use for generating a debugging description for the specified object.

+ (nonnull instancetype)formatterForObject:(nonnull id)obj

Parameters

obj

The object whose fields are being formatted.

Return Value

A new MBFieldListFormatter.

Discussion

The passed-in object is used to set the first field of the returned formatter. The field name will be the name of the class of obj, and the value will be a hexadecimal representation of the object’s memory address.

Using a MBFieldListFormatter in this way is typically done to implement an object’s description method.

Declared In

MBFieldListFormatter.h

Adding field values

– setField:value:

Sets an object instance field on the formatter.

- (void)setField:(nonnull NSString *)fieldName value:(nullable id)val

Parameters

fieldName

The name of the field to add.

val

An object instance representing the field value.

Discussion

The object val is represented by the return value of its description method.

Declared In

MBFieldListFormatter.h

– setField:byTruncating:

Sets a string field on the formatter. The string is truncated if it is longer than the number of characters specified by the value of the constant kMBFieldListDefaultTruncateAtCharacter.

- (void)setField:(nonnull NSString *)fieldName byTruncating:(nonnull NSString *)val

Parameters

fieldName

The name of the field to add.

val

A string representing the field value.

Discussion

If the field value is truncated, it is represented with the appended string “... (# more chars)” where # represents the number of characters that were removed by the truncation process.

Declared In

MBFieldListFormatter.h

– setField:byTruncating:atCharacter:

Sets a string field on the formatter. The string is truncated if it is longer than truncateAt characters.

- (void)setField:(nonnull NSString *)fieldName byTruncating:(nonnull NSString *)val atCharacter:(NSUInteger)truncateAt

Parameters

fieldName

The name of the field to add.

val

A string representing the field value.

truncateAt

The index of the character at which val will be truncated. The portion of the string val starting with the character at index truncatAt will not be included in the value stored in the formatter.

Discussion

If the field value is truncated, it is represented with the appended string “... (# more chars)” where # represents the number of characters that were removed by the truncation process.

Declared In

MBFieldListFormatter.h

– setField:instance:

Sets an object instance field on the formatter.

- (void)setField:(nonnull NSString *)fieldName instance:(nullable id)obj

Parameters

fieldName

The name of the field to add.

obj

An object instance representing the field value.

Discussion

The object val is represented with its class name and memory address.

Declared In

MBFieldListFormatter.h

– setField:debug:

Sets an debug object instance field on the formatter.

- (void)setField:(nonnull NSString *)fieldName debug:(nullable id)obj

Parameters

fieldName

The name of the field to add.

obj

An object instance representing the field value.

Discussion

The object val is represented with its class name, memory address and an optional debug descriptor. The debug descriptor is included if obj responds to the debugDescriptor selector.

Declared In

MBFieldListFormatter.h

– setField:pointer:

Sets a memory pointer field on the formatter.

- (void)setField:(nonnull NSString *)fieldName pointer:(nullable void *)ptr

Parameters

fieldName

The name of the field to add.

ptr

A pointer representing the field value.

Declared In

MBFieldListFormatter.h

– setField:boolean:

Sets a boolean field on the formatter.

- (void)setField:(nonnull NSString *)fieldName boolean:(BOOL)val

Parameters

fieldName

The name of the field to add.

val

The boolean field value.

Declared In

MBFieldListFormatter.h

– setField:container:

Sets a container field on the formatter. Containers are objects such as NSArray, NSSet, and NSDictionary that respond to the selector count.

- (void)setField:(nonnull NSString *)fieldName container:(nullable id)val

Parameters

fieldName

The name of the field to add.

val

A container object instance representing the field value.

Discussion

A container is represented with its class name, memory address and the count of its contents.

Declared In

MBFieldListFormatter.h

– setFields:

Sets a field on the receiver for each key/value pair contained in the passed-in dictionary.

- (void)setFields:(nonnull NSDictionary *)fields

Parameters

fields

The dictionary whose key/value pairs will be added as fields.

Declared In

MBFieldListFormatter.h

Truncating strings

+ truncateString:atCharacter:

Truncates the string val at the character index truncateAt if val the length of the string is greater than truncateAt.

+ (nonnull NSString *)truncateString:(nonnull NSString *)val atCharacter:(NSUInteger)truncateAt

Parameters

val

The value to (possibly) truncate.

truncateAt

The index of the character at which val should be truncated.

Discussion

Note: This is intended to be used for visual formatting, not for ensuring that val is a specified length. Truncated strings will have some additional information appended, to make it clear that the string was truncated. As a result, if a string is truncated by this method, the returned string will be longer than truncateAt.

Declared In

MBFieldListFormatter.h

Converting the fields into strings

– asString

Converts the fields in the receiver into a string representation.

- (nonnull NSString *)asString

Return Value

The string representation of the receiver’s fields.

Declared In

MBFieldListFormatter.h

– asStringWithIndentation:

Converts the fields in the receiver into a string representation.

- (nonnull NSString *)asStringWithIndentation:(nonnull NSString *)indentation

Parameters

indentation

The indentation prefix to use for the output.

Return Value

The string representation of the receiver’s fields.

Discussion

The passed-in string indentation will appear before each line in the returned string.

Declared In

MBFieldListFormatter.h

– asStringWithIndentation

Converts the fields in the receiver into a string representation.

- (nonnull NSString *)asStringWithIndentation

Return Value

The string representation of the receiver’s fields.

Discussion

Each line in the returned string is prefixed with a tab (0x09) character.

Declared In

MBFieldListFormatter.h

Debugging output

– asDescription

Returns the field list in a format suitable for the implementation of an object’s description method.

- (nonnull NSString *)asDescription

Return Value

The description.

Discussion

This method returns a string containing the output of asStringWithIndentation prefixed and suffixed with carriage returns to make it stand out more in console output.

Declared In

MBFieldListFormatter.h