RFC for Fn::Length

RFCs/0070-Fn::Length.md

@@ -0,0 +1,106 @@
+# RFC for Fn::Length
+
+* **Original Author(s):**: @juegong2
+* **Tracking Issue**: https://github.com/aws-cloudformation/cfn-language-discussion/issues/70
+
+# Summary
+
+We will support an intrinsic function called `Fn::Length` that will return the number of elements in a given list.
+
+# Motivation
+
+CloudFormation users may want to get the number of elements in a given list to set certain resource parameters or generate conditions. It may also help to check if index is out of bound for !Select function. This RFC proposes to support the use case of getting the number of elements of a given list.
+
+* Reference:
+  * https://github.com/aws-cloudformation/cfn-language-discussion/issues/61
+
+# Example(s)
+
+Use `Ref` on a Parameter of type `CommaDelimitedList` or `List<Number>`
+
+```json
+{
+  "Parameters": {
+    "InstanceTypes": {
+      "Type": "CommaDelimitedList"
+    },
+    "NumberList": {
+      "Type": "List<Number>"
+    }
+  },
+  "Conditions": {
+    "Has3InstanceTypes": {
+      "Fn::Equals": [
+        {
+          "Fn::Length": {"Ref": "InstanceTypes"}
+        },
+        3
+      ]
+    },
+    "Has2NumbersInList": {
+      "Fn::Equals": [
+        {
+          "Fn::Length": {"Ref": "NumberList"}
+        },
+        2
+      ]
+    }
+  }
+}
+```
+
+Use a hardcoded list
+```json
+{
+  "Conditions": {
+    "Has3InstanceTypes": {
+      "Fn::Equals": [
+        {
+          "Fn::Length": [ "m5.large", "m5.xlarge" ]
+        },
+        3
+      ]
+    }
+  }
+}
+```
+
+# Limitation
+
+`Fn::Length` will not work with lists that are dynamically generated at provisioning time. For example, assuming MyBucket is the logical id of a AWS::S3::Bucket resource, the following is not supported:
+```json
+{
+  "Fn::Length": { "Fn::Split": [":", { "Fn::GetAtt": [ "MyBucket", "Arn" ] } ] }
+}
+```
+because the ARN of MyBucket is not known until during provisioning.
+
+**Note:** This limitation is due to underlying implementation constraints. In the fullness of time, this limitation should be removed.
+
+# Details
+
+`Fn::Length` is an intrinsic function that takes in a list and returns the length of the given list. The list could be:
+
+* hardcoded list in template
+* array generated by intrinsic functions like `Fn::Split` with parameters of hardcoded values or of `Ref` to template parameters
+* `Ref` to a parameter of type `CommaDelimitedList`
+* `Ref` to a parameter of type `List<Number>`
+* `Ref` to a parameter of type `List<AWS-specific parameter types>`
+* `Ref` to a parameter of type
+  * `AWS::SSM::Parameter::Value<List<String>>`
+  * `AWS::SSM::Parameter::Value<CommaDelimitedList>`
+  * `AWS::SSM::Parameter::Value<List<AWS-specific parameter type>>`
+
+Within `Fn::Length`, following intrinsic functions with parameters of hardcoded values or of `Ref` to template parameters will be supported:
+* Condition functions
+* Fn::FindInMap
+* Fn::Base64
+* Fn::Join
+* Fn::Select
+* Fn::Split
+* Fn::Sub
+
+# FAQ
+1. **Will the CloudFormation Linter (cfn-lint) support validations regarding Fn::Length?**
+
+    Yes. cfn-lint will be updated to validate if the parameter of Fn::Length is a list. It will also validate if it is used for integer-type resource properties or function parameters.