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 |
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 |
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