function/rfc3339_parse: Add RFC3339 parsing function

[austinvalle]

Ref: #217
Terraform core refs: hashicorp/terraform#29694, hashicorp/terraform#31751, hashicorp/terraform#25802, hashicorp/terraform#33538

This PR introduces a new provider-defined function for parsing RFC3339 timestamps:

terraform {
  required_providers {
    time = {
      source = "hashicorp/time"
    }
  }
}

output "example_output" {
  value = provider::time::rfc3339_parse("2023-07-25T23:43:16Z")
}

 $ terraform plan        

Changes to Outputs:
  + example_output = {
      + day          = 25
      + hour         = 23
      + iso_week     = 30
      + iso_year     = 2023
      + minute       = 43
      + month        = 7
      + month_name   = "July"
      + second       = 16
      + unix         = 1690328596
      + weekday      = 2
      + weekday_name = "Tuesday"
      + year         = 2023
      + year_day     = 206
    }

You can apply this plan to save these new output values to the Terraform state, without changing any real infrastructure.

Notes

• I purposefully did not include output from (time).Zone()
  • zone_name is not directly related to zone_offset, and would always be "UTC" or ""
  • zone_offset is valid and a part of the RFC3339 string. The time.Time package returns this offset in seconds east of UTC, which may be confusing to users (but potentially necessary in this format, since time zone offsets aren't necessarily in whole hours 😖 ).
  • I think if we want to return TZ name or offset info about a timestamp, we should treat it as a separate function and use (time).ParseInLocation
• I named the files function_ to follow the convention of the repository. I can also refactor all the files in this provider to match the other accepted pattern of:
  • *_function.go
  • *_resource.go

[bflad]

terraform-plugin-docs has been updated on main 👍

[bflad]

Looks good to me 🚀

[bendbennett]

LGTM 🚀

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.