SAIF.Framework.Common operations and processes¶

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog¶

Operation	Intent	Trigger	Inputs	Outputs	Rules
Title-case a string	Convert a string to title case using acronym/word-list rules	Caller invokes `someString.ToTitleCase()`	`string inString`	Title-cased `string`	BR-014, BR-015, BR-016, BR-017, BR-018, BR-019, BR-020, BR-021
Title-case a single word	Apply acronym/lowercase/mixed-case/ordinal rules to one word	Called once per split word by OP-001 step 4	`string inWord`	Cased `string`	BR-015, BR-016, BR-017, BR-018, BR-019
Determine whether two date ranges overlap	Test whether two date ranges intersect	Caller compares two `IDateRange` instances	`range1`, `range2`, `inAllowSameDateOverlap`	`Boolean`	BR-004, BR-001, BR-002, BR-003
Determine whether a sequence of date ranges is contiguous	Validate that consecutive date ranges connect with no gaps or overlaps	Caller validates a set of consecutive coverage/effective periods	`ranges`, `option`	`Boolean`	BR-005, BR-006, BR-007
Determine whether a sequence of date ranges overlaps itself	Detect mutual overlap within a collection of date ranges	Caller validates a set of periods for mutual exclusivity	`ranges`, `option`	`Boolean`	BR-008, BR-002, BR-009, BR-010, BR-011
Classify the overlap state of two nullable date ranges	Classify the directional overlap state between two nullable-end ranges	Caller needs a categorical (not boolean) overlap classification where the end date may be open	`rangeA`, `rangeB`	`SAIF.Common.Enums.DateRangeOverlapResult`	BR-012
Convert a Julian date string to a DateTime	Decode a Julian-format date string into a DateTime	Caller decodes a Julian-formatted date from a fixed-format interchange file*	`julian` (e.g. `25001`, `2025001`), optional `millenium`	`DateTime`	BR-022, BR-023, BR-024, BR-025, BR-026
Resolve the year and leap-year flag from a Julian string	Resolve a 4-digit calendar year and leap-year flag from a Julian string	Called by OP-007 step 3, or directly by callers	`julian`, `millenium`	`int` year, `out bool isLeapYear`	BR-024, BR-025
Encode a DateTime as a Julian string	Encode a DateTime as a Julian-format string	Caller produces a Julian-formatted date for file interchange*	`date`, `yearLength`	`string`	BR-027
Build a DateTime from EDI date/time strings	Parse a DateTime from EDI-style date and time strings	Caller parses a date/time from a fixed-format interchange file*	`date` (`yyyymmdd` or `yymmdd`), `time` (`hh24miss`)	`DateTime`	BR-028, BR-029
Split an EDI date-range string	Split a delimited EDI date-range token into start and end DateTimes	Caller parses a `yyyymmdd-yyyymmdd` token	`dateString`	`out startDate`, `out endDate`	BR-030, BR-028, BR-029
Format one or two dates as an EDI file date string	Format a start date, and optional end date, into an EDI file date string	Caller names or stamps an interchange file*	`startDate`, optional `endDate`	`String` (`yyyymmdd` or `yyyymmdd-yyyymmdd`)	BR-030
Parse a delimited date-range string into a DateRange	Parse a delimited string back into a DateRange, defaulting on any failure	Caller round-trips a `DateRange.ToString()` value	`date`, `delimiter`	`DateRange`	BR-031, BR-032
Construct a DateRange	Construct a DateRange from various inputs with sentinel defaulting	Caller creates a range	none / `IDateRange` / `DateTime` / `DateTime, DateTime`	`DateRange` instance	BR-002, BR-032, BR-033
Compare two date ranges for equality	Compare two date ranges for structural equality	Caller compares ranges	Two ranges	`Boolean` / `int`	BR-034
Filter a collection of ranges as of a date	Filter a collection of ranged records to those effective on a date	Caller selects the version(s) of a record effective on a given date	`ranges`, `date`, `rangeOption`	`IEnumerable<T>` (deferred)	BR-035, BR-036, BR-037
Enforce a method precondition	Fail fast on invalid arguments or state	Called at the top of a public method by consumers and by intra-library callers (`IEnumerableExtensions`, `DictionaryExtensions`, `UriExtensions`)	The parameter value, the parameter name, or a boolean / `Func<bool>` condition	The validated value (fluent) or `void`; throws on violation	BR-038, BR-039, BR-040, BR-041, BR-042, BR-043
Throw-if-null with a custom exception type	Throw a caller-chosen exception type when a value is null	Called by `Enforce.NotNull<T>` and by consumers directly	`instance`, `message`	`instance` (non-null) or throws `TException`	BR-042
Raise a validation failure	Build and throw a validation exception carrying structured failure detail	Caller detects invalid input or state and needs to surface property-level errors	none / `IValidationResult` / `errorMessage` / `propertyName + errorMessage`	A throwable exception carrying an `IValidationResult`	BR-044, BR-045, BR-046, BR-047
Signal a view/context failure	Signal a presentation-layer routing failure with a target view and optional model	A consuming presentation layer detects a missing, invalid, unauthorized-for-user, or disabled context*	none / `targetView` / `model`	An exception carrying `TargetView` and optionally `Model`	BR-048
Format an exception chain for display	Format an exception and its inner-exception chain for display	Caller logs or displays a caught exception	`instance`, `innerToOuter`	Multi-section `string`	BR-049, BR-050, BR-051
Format an exception for the error log	Format an exception into a sentinel-delimited error-log entry	Caller writes a caught exception to an error-log store	`instance`	`string` — short message, sentinel, then full detail	BR-049, BR-050, BR-052, BR-051
Locate a byte signature within a buffer	Locate the first occurrence of a byte signature within a buffer	Caller looks for a file-format signature (e.g. the `PDF_FILE_HEADER` constant `"%PDF-"`) inside a binary payload	`input`, `searchFor` (or an ASCII `string`), `start`, `maxBytesToSearch`	`int` index of the first match, or `-1`	BR-053, BR-054, BR-055
Strip a leading header from a byte payload	Strip a leading transport header so a payload starts at its own signature	Caller has a document payload prefixed with transport bytes and needs it to start at its own signature (e.g. "%PDF-")	`input`, `searchFor`, `maxBytesToSearch`	Trimmed `Byte[]`, `out bool found`	BR-053, BR-055, BR-056
Hash a byte payload	Compute an MD5 hash of a byte payload	Caller needs a content fingerprint	`input`	`Byte[]` MD5 digest	BR-057
Serialize / deserialize an object	Round-trip an object graph to/from JSON or XML, files or strings	Caller persists or rehydrates an object graph	A file path, a serialized string, or the instance to serialize	`T`, `string`, or a written file	BR-058, BR-059, BR-060
Set a property value by strongly-typed expression	Resolve and set a property from a strongly-typed lambda expression	Caller assigns a property — including one with a non-public setter — selected by lambda rather than by name string	`Expression<Func<TTarget,TProperty>>` or a resolved `PropertyInfo`, plus the value	`PropertyInfo`, or `void` (property mutated)	BR-061, BR-062, BR-063, BR-064
Generate the next sequence value	Generate and manage an in-memory monotonic sequence counter	Caller needs a monotonically increasing in-memory counter (e.g. record numbering in a generated file)*	Optional `startValue` (default 0)	`int` / `long`	BR-065, BR-066, BR-067
Derive MVC route parts from a request URI	Derive ASP.NET MVC-style route segments from a request URI	A consuming web layer needs the application, page, or controller/action name from the current request URL*	`Uri`	`string`	BR-068, BR-069, BR-039, BR-070
Split a Windows identity name	Split a DOMAIN\user identity name into domain and account parts	Caller has an authenticated `IIdentity` and needs the bare account name or the domain	`IIdentity`	`string`	BR-071
Interpret a string as a boolean and render booleans as flags	Convert between truthy flag strings and boolean values	Caller converts between flag strings (from files, code tables, or UI) and `bool`	`string` / `bool`	`bool` / `string`	BR-072, BR-073
Normalize text for downstream systems	Fold Unicode punctuation to ASCII and filter text by character class	Caller prepares text for a fixed-format file, a legacy system, or display*	`string`	`string`	BR-074, BR-075
Slice, truncate, and convert scalar values	Slice, truncate, and convert scalar string/decimal values	Caller formats a value for a fixed-width field or performs a numeric test*	`string` / `decimal`	`string` / `bool` / `decimal` / `int`	BR-076, BR-077, BR-078, BR-079, BR-080, BR-081
Merge or upsert dictionary entries	Merge, upsert, or safely read dictionary entries	Caller combines configuration/lookup dictionaries or reads with a fallback	Target dictionary, plus source dictionary / key / value / default	`void` / `TValue`	BR-082, BR-039, BR-083, BR-084
Join or reduce sequences	Fill LINQ gaps: iteration, joining, string-joining, and keyed distinct	Caller performs a collection operation LINQ does not provide natively	One or two sequences plus key selectors/projections	`void` / `string` / `bool` / `IEnumerable<T>`	BR-039, BR-085, BR-086, BR-087, BR-088
Convert a stream to a byte array	Materialize a stream into an in-memory byte array	Caller materialises a read/uploaded stream for hashing, storage, or header stripping	`Stream`	`byte[]`	BR-057, BR-089
Enumerate the properties of a type	Enumerate the public properties of a type via reflection	Caller needs the public property set of a type for mapping or binding*	Generic type parameter `TTarget`	`PropertyInfo[]`	BR-090
Write to the console/application log (contract only)	Define (without implementing) a console/file logging contract	A consuming console/batch application writes progress, errors, or exception detail to one or more log files*	`message`, `logId` or `LogType`, `filePath`, `Exception`	Log output (implementation-defined)	BR-091, BR-092, BR-093, BR-094

Process flow diagram¶

The following diagram visualizes the primary operational flow across this library's functional groups.

flowchart TD
    Start([Caller invokes a static/extension method]) --> Guard{Guard/precondition check?}
    Guard -->|Fails| Throw(["Throws ArgumentException /<br>ArgumentNullException /<br>custom exception"])
    Guard -->|Passes| Domain{Which functional group?}
    Domain -->|Date/date-range| DateOps["Compute validity, overlap, contiguity,<br>or EDI/Julian conversion"]
    Domain -->|Text| TextOps["Normalize, case, filter,<br>or convert scalar value"]
    Domain -->|Validation| ValidationOps["Accumulate failures into<br>ValidationResult<br>or throw SaifValidationException"]
    Domain -->|Sequence/collection| CollectionOps["Advance sequence, merge dictionary,<br>or join/filter sequence"]
    Domain -->|Serialization/bytes| SerializationOps["Serialize, deserialize, hash,<br>or search byte payload"]
    Domain -->|Logging contract| LoggingOps["Write through IConsoleLogService<br>/ ILogWriter contract"]
    DateOps --> Return([Return computed result])
    TextOps --> Return
    ValidationOps --> Return
    CollectionOps --> Return
    SerializationOps --> Return
    LoggingOps --> Return

Failure and edge-case behavior¶

Guard failures (Enforce, GenericExtensions.IfNullThrow) throw immediately rather than returning a sentinel value, so callers must catch or pre-validate.
Several operations are explicitly designed to be non-throwing on bad input (DateRange.Parse, StringExtensions.Truncate, StringExtensions.ConvertToDecimalOrZero for whitespace), trading strictness for caller convenience — see each operation's Steps for the exact behavior.
ILogWriter/IConsoleLogService are contracts only; this library defines no logging implementation, so failure behavior for logging operations is determined entirely by the consuming implementation.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources¶

Common/SAIF.Common/Utility/TitleCase.cs
Common/SAIF.Common/Classes/Julian.cs
Common/SAIF.Common/Classes/DateMaker.cs
Common/SAIF.Common/Classes/DateRange.cs
Common/SAIF.Common/Classes/NullableDateRange.cs
Common/SAIF.Common/Extensions/DateRangeExtensions.cs
Common/SAIF.Common/Extensions/IComparableExtensions.cs
Common/SAIF.Common/Classes/Enforce.cs
Common/SAIF.Common/Extensions/GenericExtensions.cs
Common/SAIF.Common/Classes/SaifValidationException.cs
Common/SAIF.Common/Classes/ValidationResult.cs
Common/SAIF.Common/Classes/ContextException.cs
Common/SAIF.Common/Extensions/ExceptionExtensions.cs
Common/SAIF.Common/Extensions/ByteExtensions.cs
Common/SAIF.Common/Extensions/FileExtensions.cs
Common/SAIF.Common/Classes/Serializer.cs
Common/SAIF.Common/Extensions/DotNet40Extensions.cs
Common/SAIF.Common/Extensions/ExpressionExtensions.cs
Common/SAIF.Common/Classes/SequenceGenerator.cs
Common/SAIF.Common/Classes/Sequence.cs
Common/SAIF.Common/Classes/LongSequence.cs
Common/SAIF.Common/Extensions/UriExtensions.cs
Common/SAIF.Common/Extensions/SecurityPrincipalExtensions.cs
Common/SAIF.Common/Extensions/StringExtensions.cs
Common/SAIF.Common/Extensions/BooleanExtensions.cs
Common/SAIF.Common/Utility/StringUtilities.cs
Common/SAIF.Common/Extensions/NumericExtensions.cs
Common/SAIF.Common/Extensions/DictionaryExtensions.cs
Common/SAIF.Common/Extensions/IEnumerableExtensions.cs
Common/SAIF.Common/Classes/Reflector.cs
Common/SAIF.Common/Interfaces/IConsoleLogService.cs
Common/SAIF.Common/Interfaces/ILogWriter.cs
Common/SAIF.Common/Enums/LogType.cs

SAIF.Framework.Common operations and processes¶

Operation catalog¶

Process flow diagram¶

Failure and edge-case behavior¶

Related documentation¶

Sources¶