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 #

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

LstConditions #

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.

LstVars #

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

HasInternalChecks #

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

VariablesTable #

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 #

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. Results are cached so repeated calls with the same tablename parameter return immediately without re-validating. The cache is invalidated when underlying data changes (via Set LstVars or Set LstConditions).

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

ConditionString #

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.

ConditionPredicate #

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 #

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.

LstConditions #

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:

LstVars #

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

ResetCaches #

reset-caches

Clear cached table names, validation results, and diagnostics

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.

LogInfo #

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:

CachedTable #

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

ThrowError #

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.

IFormulaCondition_CheckingValues #

checking-values

Signature:

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