init

docs/ai/DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities.md

@@ -0,0 +1,91 @@
+---
+source_files:
+  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/DiskUtility.cs
+  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/Exceptional.cs
+  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/ExceptionalList.cs
+  - DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Utilities/AttributeCoder.cs
+generated_at: "2026-04-17T15:53:59.285477+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "c2a6300146b5dc97"
+---
+
+# Documentation: DatabaseExport Utilities
+
+## 1. Purpose
+
+This module provides utility classes for the `DatabaseExport` subsystem within the DataPRO Version 57 codebase. It includes an exception-handling base class hierarchy (`Exceptional`, `ExceptionalList<T>`) designed to enable type-specific exception catching, a disk/file validation utility (`DiskUtility`), and a reflection-based attribute manipulation framework (`AttributeCoder<TargetType, AttributeType, AttributeValueType>`) for encoding/decoding attribute values attached to types—primarily intended for use with enumeration types.
+
+---
+
+## 2. Public Interface
+
+### `Exceptional` (abstract class)
+**Namespace:** `DatabaseExport`  
+**Inheritance:** `object` ← `Exceptional`  
+**Attributes:** `[Serializable]`
+
+An abstract marker/base class with no members. Intended as the "ultimate" base class for classes that expect to throw exceptions, allowing callers to catch exceptions by the throwing class's type.
+
+---
+
+### `ExceptionalList<T>` (generic class)
+**Namespace:** `DatabaseExport`  
+**Inheritance:** `List<T>` ← `ExceptionalList<T>`  
+**Attributes:** `[global::System.Serializable]`
+
+A generic collection that inherits from `List<T>` and is intended to provide its own exception type. No additional members are defined beyond those inherited from `List<T>`.
+
+---
+
+### `DiskUtility` (static class)
+**Namespace:** `DatabaseExport`  
+**Inheritance:** `Exceptional` ← `DiskUtility`
+
+A collection of disk-related utility methods.
+
+#### Methods
+
+| Signature | Description |
+|-----------|-------------|
+| `public static bool ValidateFileAndPathNameChars(string nameToValidate)` | Validates that the input string contains no illegal file or path characters. Returns `true` if valid, `false` otherwise. |
+
+**Validation rules applied:**
+- Rejects strings that are empty or whitespace-only after trimming
+- Rejects strings containing any character from `Path.GetInvalidFileNameChars()`
+- Rejects strings containing any character from `Path.GetInvalidPathChars()`
+- Rejects strings containing the period character (`'.'`)
+
+---
+
+### `AttributeCoder<TargetType, AttributeType, AttributeValueType>` (generic class)
+**Namespace:** `DatabaseExport`  
+**Inheritance:** `Exceptional` ← `AttributeCoder<,,>`
+
+A reflection-based utility for manipulating attributes attached to types, designed primarily for enum-to-attribute value mapping.
+
+#### Delegates
+
+| Delegate | Signature |
+|----------|-----------|
+| `AttributeValueExtractionMethod` | `AttributeValueType(AttributeType attribute)` |
+| `AttributeValueEqualityComparisonMethod` | `bool(AttributeValueType value1, AttributeValueType value2)` |
+
+#### Constructor
+
+```csharp
+public AttributeCoder(
+    AttributeValueExtractionMethod attributeValueExtractionMethod,
+    AttributeValueEqualityComparisonMethod attributeValueEqualityComparisonMethod)
+```
+
+Initializes the coder with a required extraction method and an optional equality comparison method. If `attributeValueEqualityComparisonMethod` is `null`, default equality comparison is used.
+
+#### Methods
+
+| Signature | Description |
+|-----------|-------------|
+| `public AttributeValueType DecodeAttributeValue(TargetType target)` | Returns the attribute value of `AttributeType` attached to the specified `TargetType`. Expects exactly one attribute; throws if none found. |
+| `public List<AttributeValueType> DecodeAttributeValues(TargetType target)` | Returns a list of all `AttributeValueType` values from `AttributeType` attributes attached to the specified `TargetType`. |
+| `public TargetType EncodeAttributeValue(AttributeValueType attributeValue)` | Returns the `TargetType` value that has an `AttributeType` attribute with the specified value. Expects exactly one match; throws otherwise. |
+| `public List<TargetType> DehashAttributeValue(AttributeValueType attributeValue)` | Returns