---
title: CodeTimerItem
summary: API reference for CodeTimerItem.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.CodeTimer
reference_type: package
---

# CodeTimerItem

`CodeTimerItem` is the hierarchical result/data-transfer node used only for reporting output, not for live timing state. The internal `CodeTimerResult` type builds a tree of these nodes from the flat `;`-delimited timer key space before serializing results.

## Purpose
- Represent one node (leaf or branch) of the hierarchical timing-result tree, carrying aggregated statistics for output as XML or console text.

## Context
- Namespace: `SAIF.Framework.CodeTimer`
- Assembly/package: `SAIF.Framework.CodeTimer.dll`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| Name | `public string Name { get; }` | The name/key segment for this result node. |
| Elapsed | `public double Elapsed { get; }` | Cumulative elapsed time for this node, in milliseconds. |
| Qty | `public int Qty { get; }` | Number of times the underlying timer was started. |
| Average | `public double Average { get; }` | Computed as `Elapsed / Qty` when `Elapsed >= 0`; otherwise `-1`. |
| Started | `public DateTime Started { get; }` | Timestamp when the underlying timer was first started (set only via the extended constructor). |
| Stopped | `public DateTime Stopped { get; }` | Timestamp when the underlying timer was last stopped (set only via the extended constructor). |
| Shortest | `public int Shortest { get; }` | Shortest recorded span, in milliseconds (set only via the extended constructor). |
| Longest | `public int Longest { get; }` | Longest recorded span, in milliseconds (set only via the extended constructor). |
| Spans | `public List<CustomTimeSpan> Spans { get; }` | Captured span history for this node (set only via the extended constructor). |
| Children | `public List<CodeTimerItem> Children` | Child nodes representing nested/sub-timers in the hierarchy. |
| CodeTimerItem | `public CodeTimerItem(string name, int elapsed, int qty)` | Minimal constructor; leaves `Started`/`Stopped`/`Shortest`/`Longest`/`Spans` unset. |
| CodeTimerItem | `public CodeTimerItem(string name, int elapsed, int qty, DateTime started, DateTime stopped, int shortest, int longest, List<CustomTimeSpan> spans)` | Extended constructor populating all statistics fields. |
| IsLeaf | `public bool IsLeaf()` | Returns `true` when `Children` is empty. |

## Behavioral notes
- `Average` returns `-1` only when `Elapsed < 0`, which does not occur in normal usage since elapsed values are non-negative durations; in practice `Average` is always `Elapsed / Qty`*.
- Nodes are assembled into a tree by the internal `CodeTimerResult.CreateItems()`, which splits each timer's `;`-delimited hierarchical key and merges shared prefix segments into parent/child `CodeTimerItem` relationships.
- XML serialization (`CodeTimerResult.OutputXml`/`RecurseXml`) omits `Qty`, `Shortest`, `Longest`, and `Average` attributes when `Qty <= 1`, and does not recurse into children when `Elapsed <= 0` (see [BR-006](../../business-rules.md#br-006-result-xml-omits-statistically-insignificant-attributes)).

## Constraints and usage notes
- This type is a plain data-transfer object; it has no behavior beyond `IsLeaf()` and the computed `Average` property.
- `Children` is a public mutable list; callers building trees externally must populate it directly rather than through a constructor parameter.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Sources
- SAIF.Framework.CodeTimer\SAIF.Framework.CodeTimer\CodeTimerItem.cs