NOTE: "complexity" is somewhat vaguely defined here. The real distinction is whether we
- expect an immediate return,
- expect some non-trivial work that is a function of input size or object size
- expect I/O-bound work
| Name / Pattern | Intended use | I/O allowed | Typical complexity expectation | Can mutate this |
Exceptions: allowed by default | "Expected failure" alternative |
|---|---|---|---|---|---|---|
of(...) |
Construct from domain parts or a domain identifier (validated factory) | No | Small | N/A | Yes (IllegalArgumentException / domain exception) |
ofOrNull, tryOf: Result<T> |
from(x) |
Convert/extract from another type (possibly lossy) | No | Small | N/A | Yes (if conversion invalid) | fromOrNull, tryFrom |
parse(text) |
Parse textual representation (format/grammar) | No | Scales with input size | N/A | Yes (IllegalArgumentException, parse exception) |
parseOrNull, tryParse |
decode(bytes) |
Parse binary encoding (wire format) | No | Scales with input size | N/A | Yes | decodeOrNull, tryDecode |
deserialize(data) |
Rehydrate object from serialized form (often structured) | No (shouldn't) | Scales with input size | N/A | Yes | tryDeserialize |
toX() |
Produce an X (conversion that may allocate/copy) |
No | O(1)-O(n) depending on structure | No | Prefer no; if can fail, make it obvious | toXOrNull, tryToX |
asX() |
View/adapt/cast-like reinterpretation (cheap) | No | O(1) | No | No (ideally) | asXOrNull |
withX(...) |
Return a copy with one field changed (structural update) | No | O(1)-O(n) depending on structure | No | No (unless validating constraints) | withXOrNull |
copy(...) |
Kotlin data-class copy semantics | No | O(1)-O(n) depending on structure | No | No | N/A |
normalize() (mutating) |
Normalize in-place | No | Scales with the object size | Yes | Yes if invariants violated | normalizedRememberingFailures() no thanks |
normalized() (pure) |
Return normalized copy | No | Scales with the object size | No | Same as above | normalizedOrNull |
sort() |
In-place ordering | No | O(n log n) | Yes | No | sorted() |
sorted() |
Return sorted copy | No | O(n log n) | No | No | N/A |
applyX(...) / updateX(...) |
Mutating update with intent | No | O(1)-O(n) depending on structure | Yes | Yes | tryUpdateX |
load...() |
Read from persistent storage | Yes (disk) | Unbounded / I/O-bound | Usually No | Yes (I/O exceptions, domain) | tryLoad, loadOrNull |
save...() |
Write to persistent storage | Yes (disk) | Unbounded / I/O-bound | Usually No | Yes | trySave |
fetch...() |
Network retrieval | Yes (network) | Unbounded / network-bound | No | Yes | tryFetch: Result<T> |
send...() / publish...() / emit...() |
Outbound side effect | Yes | Unbounded / I/O-bound | No | Yes | trySend |
now() / current...() |
Sample clock/system state | Yes-ish (system) | O(1) | No | Rarely | N/A |
getX() |
Property-like access (no work) | No | O(1) | No | No | N/A |
findX(...) |
Lookup/search (may return none) | No | O(log(n))-O(n) depending on structure | No | No | returns T? |
requireX(...) (guard) |
Validate args (public API boundary) | No | O(1)-O(n) | No | Yes: IllegalArgumentException |
Provide non-throwing validator |
checkX(...) (guard) |
Validate invariants/state (internal) | No | O(1)-O(n) | No | Yes: IllegalStateException |
Usually not needed |
validate() |
Produce diagnostics about validity | No | O(n) | No | Prefer no | return List<Error> / Validation |
validateOrThrow() |
Validate then throw on failure | No | O(n) | No | Yes | validate() |