Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

Collection if is a declarative control flow element used directly within Dart collection literals (List, Set, and Map) to conditionally insert elements during instantiation. It evaluates a boolean expression and includes the subsequent element, sequence, or spread only if the expression resolves to true. Unlike standard if statements, which control program execution flow, collection if operates as an element generator within the lexical scope of a collection literal.

​
Syntax and Mechanics

The operator supports standard if, if-else, and Dart 3.0+ if-case pattern matching. Standard if and if-else 
final bool condition = true;

final list = [
  'A',
  if (condition) 'B',
  if (!condition) 'C' else 'D',
];
Map and Set Implementation The syntax applies identically to Set and Map literals. For maps, the conditional element must be a valid key-value pair. 
final bool includeAdmin = false;
final bool condition = true;

final userMap = {
  'username': 'sys_user',
  if (includeAdmin) 'role': 'admin',
};

final uniqueSet = {
  1,
  if (condition) 2,
};
If-Case (Pattern Matching) Introduced in Dart 3.0, if-case allows conditional element inclusion based on whether a value matches a specific pattern, simultaneously extracting destructured variables. 
final Object result = [200, 'Success'];

final logEntries = [
  'Operation started',
  if (result case [int code, String message]) 'Completed: $code - $message',
];

​
Technical Characteristics

Omission vs. Null Insertion When a collection if condition evaluates to false and no else branch is provided, the element is entirely omitted from the collection. It does not insert a null value, and the collection’s length property is not incremented. Compile-Time Constant Evaluation Collection if is fully supported within const collection literals, provided that the condition itself is a compile-time constant expression. The Dart compiler evaluates the condition during compilation, resulting in a fixed, immutable collection without runtime overhead. 
const bool isProduction = true;

const config = [
  'base_module',
  if (isProduction) 'prod_module' else 'dev_module',
];
Type Inference and Least Upper Bound (LUB) Elements introduced via collection if participate in the compiler’s type inference. If the collection’s generic type is not explicitly declared, the Dart analyzer calculates the Least Upper Bound (LUB) of all elements, including those in both branches of an if-else construct. 
final bool condition = true;

// The inferred type is List<num> because the LUB of int (1) and double (2.5) is num.
final numbers = [
  1,
  if (condition) 2.5 else 3,
];
Composability with Spread Operators Collection if can be composed with the spread operator (...) to conditionally insert multiple elements from an iterable. 
final bool condition = true;
final List<int> extraItems = [4, 5, 6];

final combinedList = [
  1,
  2,
  3,
  if (condition) ...extraItems,
];
Evaluation Phase For non-constant collections, collection if elements are evaluated synchronously at runtime during the instantiation of the collection literal. They are not lazy, nor can they be used to mutate a collection after it has been allocated in memory.
Master Dart with Deep Grasping Methodology!Learn More