FormulaCondition

Couples variable names with their condition fragments, validates alignment against the dictionary, and produces structured Excel predicates for analysis formulas. The class pairs two BetterArray lists (variables and conditions), validates that all variables belong to the same table, and exposes methods to render IF-wrapped condition strings and joined predicates. Consumers interact through the IFormulaCondition interface.

Depends on: BetterArray, Checking, LLVariables, LLdictionary

Version: 1.0 (2026-02-09)

Factory

create #

Construct a FormulaCondition instance from paired arrays

Signature:

Public Function Create(ByVal formVar As BetterArray, ByVal formCond As BetterArray) As IFormulaCondition

Validate paired arrays and expose the ready-to-use condition helper. Validates that both arrays are non-Nothing and have equal lengths, then stores normalised copies with a lower bound of 1. The returned instance is cast to IFormulaCondition for consistent downstream consumption.

Parameters:

  • formVar: BetterArray. The array containing variable names.
  • formCond: BetterArray. The array containing predicate fragments.

Returns: IFormulaCondition. A ready-to-use condition helper.

Throws:

  • ProjectError.InvalidArgument When formVar or formCond is Nothing or lengths differ.
PublicAccessors

conditions #

Retrieve the stored condition fragments

Signature:

Public Property Get LstConditions() As BetterArray

Returns the internal BetterArray holding the condition predicates in the same order they were supplied at creation.

Returns: BetterArray. The condition fragments preserving the original order.

variables #

Retrieve the stored variables list

Signature:

Public Property Get LstVars() As BetterArray

Returns the internal BetterArray holding the variable names in the same order they were supplied at creation.

Returns: BetterArray. The variable names preserving the original order.

InternalState

has-internal-checks #

Determine whether diagnostics have been captured

Signature:

Private Property Get HasInternalChecks() As Boolean

Returns True when at least one LogInfo call has been made since the last ResetCaches, indicating that diagnostic information is available.

Returns: Boolean. True when internal checks exist.

MetadataHelpers

variables-table #

Resolve the table name shared by all tracked variables

Signature:

Public Property Get VariablesTable(ByVal dict As ILLdictionary) As String

Provide metadata derived from the last validation run. Returns the cached table name when validation has already occurred. When the cache is empty, triggers a full validation pass against the supplied dictionary before returning the result.

Parameters:

  • dict: ILLdictionary. The dictionary used when validation has not occurred yet.

Returns: String. Table identifier or empty string when unavailable.

Validation

valid #

Validate variable/condition lists against the dictionary

Signature:

Public Function Valid(ByVal dict As ILLdictionary, Optional ByVal tablename As String = vbNullString) As Boolean

Confirm that variables/conditions are aligned and belong to the same table. Checks that both lists are non-empty and equal in length, then verifies each variable exists in the dictionary and belongs to the expected table. When a tablename argument is supplied it overrides the table resolved from the first variable. Logs diagnostic entries on every failure path for downstream inspection.

Parameters:

  • dict: ILLdictionary. The metadata provider used for variable lookups.
  • tablename: Optional String. When supplied, forces the expected table name. Defaults to vbNullString.

Returns: Boolean. True when validation succeeds.

FormulaRendering

condition-string #

Wrap the predicate in an IF expression referencing the supplied variable

Signature:

Public Function ConditionString(ByVal tablename As String, ByVal varName As String, _
                                Optional ByVal Connector As String = "*") As String

Produce Excel-ready predicates and wrapper formulas. Joins all variable/condition pairs using ConditionPredicate, then wraps the result in an IF function that returns the variable value when the predicate evaluates to True. Returns an empty string when the predicate is empty.

Parameters:

  • tablename: String. Structured reference table name.
  • varName: String. Variable/column name to return when the condition is met.
  • Connector: Optional String. Connector used between predicates. Defaults to "*".

Returns: String. An IF expression or empty string when the predicate is empty.

condition-predicate #

Join the variable predicates using the supplied connector

Signature:

Public Function ConditionPredicate(ByVal tablename As String, Optional ByVal Connector As String = "*") As String

Iterates through all variable/condition pairs and concatenates them into a single predicate string using the supplied connector (typically "*" for AND logic). Each fragment is wrapped in parentheses using structured table references.

Parameters:

  • tablename: String. Structured reference table name.
  • Connector: Optional String. Connector between predicate fragments. Defaults to "*".

Returns: String. Concatenated predicate or empty string when inputs are missing.

Internal members (not exported)

PublicAccessors

self #

Current object instance

Signature:

Public Property Get Self() As IFormulaCondition

Provide controlled access to stored collections and interface pointer. Returns the current instance cast to its interface. Used internally by the factory method to return an IFormulaCondition reference.

Returns: IFormulaCondition. The current object.

conditions-set #

Store the condition fragments and reset caches

Signature:

Public Property Set LstConditions(ByVal formCond As BetterArray)

Copies the incoming array into a new BetterArray normalised to a lower bound of 1, then resets all cached validation artefacts so the next call to Valid triggers a fresh check.

Parameters:

variables-set #

Store the variables list, normalise bounds, and reset caches

Signature:

Public Property Set LstVars(ByVal formVar As BetterArray)

Copies the incoming array into a new BetterArray normalised to a lower bound of 1, then invalidates all cached data.

Parameters:

InternalState

reset-caches #

Clear cached table names and diagnostics information

Signature:

Public Sub ResetCaches()

Maintain cached validation artefacts and diagnostics. Resets all memoised validation state so the next call to Valid or VariablesTable triggers a fresh evaluation. Also clears any diagnostic entries accumulated during previous validations.

log-info #

Append a diagnostic entry to the internal checking log

Signature:

Private Sub LogInfo(ByVal message As String, Optional ByVal scope As Byte = checkingInfo)

Creates the checking instance on first use and appends the message using a monotonically increasing counter key. The checking store is exposed through the interface for callers needing diagnostic traces.

Parameters:

cached-table #

Retrieve the memoised table name resolved during validation

Signature:

Private Property Get CachedTable() As String

Holds the table name that all variables were confirmed to share after a successful call to Valid. Empty until validation completes.

Returns: String. Cached table identifier.

ErrorHandling

throw-error #

Raise a VBA error tagged with the class name

Signature:

Private Sub ThrowError(ByVal errNumb As Long, ByVal errorMessage As String)

Centralised helper to raise ProjectError-compliant errors. Wrapper around Err.Raise that standardises the source to "FormulaCondition", providing a consistent stack trace.

Parameters:

Throws:

Interface

IFormulaCondition_Variables #

Signature:

Private Property Get IFormulaCondition_Variables() As BetterArray

Explicit interface implementations delegating to the public members.

checking-values #

Signature:

Private Property Get IFormulaCondition_CheckingValues() As IChecking
Used in (8 file(s))