### List Comprehension Example

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

List comprehensions are generally faster than explicit `for` loops with `list.append()` for creating lists.

```Starlark
[x for x in data if condition]
```

--------------------------------

### Custom Datetime Formatting During Decode

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Provide a custom `datetime_formatter` function to `toml.decode` to control how temporal types are converted to strings upon decoding. This example uses `toml.datetime_to_string` as the formatter.

```starlark
load("@toml.bzl", "toml")

# Use as custom datetime formatter during decode
def my_formatter(dt):
    return toml.datetime_to_string(dt)

toml_input = '''
created = 2024-01-15T10:30:00Z
updated = 2024-06-15
'''

config = toml.decode(toml_input, datetime_formatter = my_formatter)
print(config["created"])
print(config["updated"])
```

--------------------------------

### String Partition Method

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Use `partition()` to efficiently jump to delimiters within a string, as character iteration in Starlark can be slow.

```Starlark
s.partition(delimiter)
```

--------------------------------

### Native String Startswith Method

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Utilize native string methods like `startswith()` for performance, as they are implemented in Java/C++.

```Starlark
s.startswith(prefix)
```

--------------------------------

### Load and Use toml.bzl in Starlark

Source: https://github.com/jvolkman/toml.bzl/blob/main/README.md

Demonstrates how to load the toml module and use its decode and encode functions within a Starlark file. Ensure the toml.bzl repository is correctly loaded.

```starlark
load("@toml.bzl", "toml")

content = """
[database]
server = "192.168.1.1"
ports = [ 8000, 8001, 8002 ]
"""

# Decode
config = toml.decode(content)
print(config["database"]["server"])

# Encode
encoded = toml.encode(config)
print(encoded)
```

--------------------------------

### List Copy Comparison

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Use slicing `[:]` for list copying as it is faster than `list(original)`.

```Starlark
list_copy = original[:]
```

```Starlark
list_copy = list(original)
```

--------------------------------

### List Append Comparison

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Use `+= [item]` for list appends as it is significantly faster than `list.append(item)`.

```Starlark
list += [item]
```

```Starlark
list.append(item)
```

--------------------------------

### Bounded While Loop Workaround

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Simulate a 'bounded while' loop using a `for` loop with a maximum iteration count and a `break` statement, as `while` loops are not supported in Starlark.

```Starlark
for _ in range(MAX_ITERATIONS):
    # loop body
    if condition_to_break:
        break
```

--------------------------------

### Add toml.bzl as a Bazel dependency

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Include toml.bzl as a dependency in your MODULE.bazel file to use its functionalities.

```starlark
# MODULE.bazel
bazel_dep(name = "toml.bzl", version = "0.1.0")
```

--------------------------------

### Native String Find Method

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Utilize native string methods like `find()` for performance, as they are implemented in Java/C++.

```Starlark
s.find(substring)
```

--------------------------------

### Round-Trip TOML Encoding and Decoding

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Demonstrates parsing TOML, modifying the data, and then re-encoding it back to TOML format. Verifies the round-trip process.

```starlark
load("@toml.bzl", "toml")

# Original TOML configuration
original_toml = """
[package]
name = "my-app"
version = "1.0.0"

[dependencies]
requests = "2.28.0"
"""

# Parse the TOML
config = toml.decode(original_toml)

# Modify the configuration
config["package"]["version"] = "1.1.0"
config["dependencies"]["numpy"] = "1.24.0"
config["build"] = {
    "target": "x86_64-unknown-linux-gnu",
    "release": True,
}

# Encode back to TOML
updated_toml = toml.encode(config)
print(updated_toml)
# Output:
# [build]
# release = true
# target = "x86_64-unknown-linux-gnu"
#
# [dependencies]
# numpy = "1.24.0"
# requests = "2.28.0"
#
# [package]
# name = "my-app"
# version = "1.1.0"

# Verify round-trip
reparsed = toml.decode(updated_toml)
if reparsed["package"]["version"] == "1.1.0":
    print("Round-trip successful!")
```

--------------------------------

### Create an OffsetDateTime struct

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Construct an `OffsetDateTime` struct to represent a date and time with a timezone offset, used for TOML datetime values.

```starlark
load("@toml.bzl", "toml")

# Example usage (assuming toml is loaded):
t# offset_dt = toml.OffsetDateTime(year, month, day, hour, minute, second, nanosecond, offset_seconds)
```

--------------------------------

### Create and Encode LocalTime

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Create LocalTime structs for times of day without date or timezone, used for TOML time-local values. Supports microseconds.

```starlark
load("@toml.bzl", "toml")

# Create local time
opening_time = toml.LocalTime(hour = 9, minute = 0, second = 0, microsecond = 0)
closing_time = toml.LocalTime(17, 30, 0)
precise_time = toml.LocalTime(12, 0, 0, 123456)

# Encode to TOML
data = {
    "schedule": {
        "open": opening_time,
        "close": closing_time,
        "lunch": precise_time,
    },
}

print(toml.encode(data))
```

--------------------------------

### Create and Encode LocalDate

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Create LocalDate structs for dates without time or timezone, used for TOML date-local values. Supports multiple argument styles.

```starlark
load("@toml.bzl", "toml")

# Create local date
release_date = toml.LocalDate(year = 2024, month = 3, day = 15)
birthday = toml.LocalDate(1990, 5, 20)

# Encode to TOML
data = {
    "release": {
        "date": release_date,
        "version": "2.0.0",
    },
    "user": {
        "birthday": birthday,
    },
}

print(toml.encode(data))
```

--------------------------------

### Create and Encode OffsetDateTime

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Create OffsetDateTime structs with UTC, positive, and negative offsets. These can be used in data structures and encoded to TOML.

```starlark
load("@toml.bzl", "toml")

# Create UTC datetime (offset = 0)
utc_time = toml.OffsetDateTime(
    year = 2024,
    month = 6,
    day = 15,
    hour = 14,
    minute = 30,
    second = 45,
    microsecond = 123456,
    offset_minutes = 0
)

# Create datetime with positive offset (+05:30 = 330 minutes)
ist_time = toml.OffsetDateTime(2024, 6, 15, 20, 0, 0, 0, 330)

# Create datetime with negative offset (-08:00 = -480 minutes)
pst_time = toml.OffsetDateTime(2024, 6, 15, 6, 30, 0, 0, -480)

# Use in data structure and encode
data = {
    "timestamps": {
        "created_utc": utc_time,
        "created_ist": ist_time,
        "created_pst": pst_time,
    },
}

tom_output = toml.encode(data)
print(toml_output)
```

--------------------------------

### toml.LocalDate

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Represents a date with year, month, and day.

```APIDOC
## toml.LocalDate

### Description
Represents a date with year, month, and day.

### Parameters
#### Path Parameters
- **year** (int) - Required - The year.
- **month** (int) - Required - The month.
- **day** (int) - Required - The day.

### Request Example
```
load("@toml.bzl", "toml")

toml.LocalDate(year=2023, month=10, day=27)
```
```

--------------------------------

### Create and Encode LocalDateTime

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Create LocalDateTime structs for date and time without timezone information, suitable for TOML datetime-local values. Supports microseconds.

```starlark
load("@toml.bzl", "toml")

# Create local datetime without timezone
local_dt = toml.LocalDateTime(
    year = 2024,
    month = 12,
    day = 25,
    hour = 9,
    minute = 0,
    second = 0,
    microsecond = 0
)

# Create with microseconds
precise_dt = toml.LocalDateTime(2024, 12, 25, 9, 30, 15, 500000)

# Encode to TOML
data = {
    "meeting": {
        "start": local_dt,
        "end": precise_dt,
    },
}

print(toml.encode(data))
```

--------------------------------

### toml.LocalDateTime

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Represents a date and time with year, month, day, hour, minute, second, and microsecond.

```APIDOC
## toml.LocalDateTime

### Description
Represents a date and time with year, month, day, hour, minute, second, and microsecond.

### Parameters
#### Path Parameters
- **year** (int) - Required - The year.
- **month** (int) - Required - The month.
- **day** (int) - Required - The day.
- **hour** (int) - Required - The hour.
- **minute** (int) - Required - The minute.
- **second** (int) - Required - The second.
- **microsecond** (int) - Optional - The microsecond. Defaults to 0.

### Request Example
```
load("@toml.bzl", "toml")

toml.LocalDateTime(year=2023, month=10, day=27, hour=10, minute=30, second=0, microsecond=500000)
```
```

--------------------------------

### toml.LocalTime

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Represents a time with hour, minute, second, and microsecond.

```APIDOC
## toml.LocalTime

### Description
Represents a time with hour, minute, second, and microsecond.

### Parameters
#### Path Parameters
- **hour** (int) - Required - The hour.
- **minute** (int) - Required - The minute.
- **second** (int) - Required - The second.
- **microsecond** (int) - Optional - The microsecond. Defaults to 0.

### Request Example
```
load("@toml.bzl", "toml")

toml.LocalTime(hour=10, minute=30, second=0, microsecond=500000)
```
```

--------------------------------

### Parse Cargo.lock File Content

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Parses a Cargo.lock file content to extract dependency information. Requires the `toml.bzl` library to be loaded.

```starlark
load("@toml.bzl", "toml")

def parse_cargo_lock(cargo_lock_content):
    """Parse a Cargo.lock file and return structured dependency data."""
    lock = toml.decode(cargo_lock_content)

    deps = {}
    for package in lock.get("package", []):
        name = package["name"]
        version = package["version"]
        source = package.get("source", "")
        checksum = package.get("checksum", "")

        deps[name] = {
            "version": version,
            "source": source,
            "checksum": checksum,
            "dependencies": package.get("dependencies", []),
        }

    return deps

# Example usage in a repository rule
cargo_lock = """
[[package]]
name = "serde"
version = "1.0.195"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "abc123..."
dependencies = [
    "serde_derive",
]

[[package]]
name = "serde_derive"
version = "1.0.195"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "def456..."
"""

dependencies = parse_cargo_lock(cargo_lock)
for name, info in dependencies.items():
    print("%s @ %s" % (name, info["version"]))
# Output:
# serde @ 1.0.195
# serde_derive @ 1.0.195
```

--------------------------------

### Efficient String Concatenation

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Avoid repeated string concatenation with `+=` in loops due to O(N^2) performance. Instead, collect string parts in a list and use `"'.join(parts)` at the end.

```Starlark
parts = []
# ... collect parts ...
result = "".join(parts)
```

--------------------------------

### Native String Isdigit Method

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Utilize native string methods like `isdigit()` for performance, as they are implemented in Java/C++.

```Starlark
s.isdigit()
```

--------------------------------

### Decode TOML with LocalTime

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Decode TOML strings containing local time values into LocalTime structs. Access attributes like hour, minute, and second.

```starlark
load("@toml.bzl", "toml")

# Decode TOML with local time
toml_input = 'alarm = 07:30:00'
parsed = toml.decode(toml_input)
alarm = parsed["alarm"]
print(alarm.hour, alarm.minute, alarm.second)
```

--------------------------------

### Native String Endswith Method

Source: https://github.com/jvolkman/toml.bzl/blob/main/GEMINI.md

Utilize native string methods like `endswith()` for performance, as they are implemented in Java/C++.

```Starlark
s.endswith(suffix)
```

--------------------------------

### toml.OffsetDateTime

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Represents a date and time with an offset.

```APIDOC
## toml.OffsetDateTime

### Description
Represents a date and time with an offset.

### Parameters
#### Path Parameters
- **year** (int) - Required - The year.
- **month** (int) - Required - The month.
- **day** (int) - Required - The day.
- **hour** (int) - Required - The hour.
- **minute** (int) - Required - The minute.
- **second** (int) - Required - The second.
- **microsecond** (int) - Optional - The microsecond. Defaults to 0.
- **offset_minutes** (int) - Optional - The offset in minutes from UTC. Defaults to 0.

### Request Example
```
load("@toml.bzl", "toml")

toml.OffsetDateTime(year=2023, month=10, day=27, hour=10, minute=30, second=0, microsecond=500000, offset_minutes=-300)
```
```

--------------------------------

### Decode TOML with LocalDateTime

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Decode TOML strings containing local datetime values into LocalDateTime structs. Access attributes like year, month, hour, and minute.

```starlark
load("@toml.bzl", "toml")

# Decode TOML with local datetime
toml_input = 'event = 2024-07-04T12:00:00'
parsed = toml.decode(toml_input)
event_dt = parsed["event"]
print(event_dt.year, event_dt.month, event_dt.day)
print(event_dt.hour, event_dt.minute)
```

--------------------------------

### Decode TOML with LocalDate

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Decode TOML strings containing local date values into LocalDate structs. Access attributes like year, month, and day.

```starlark
load("@toml.bzl", "toml")

# Decode TOML with local date
toml_input = 'due_date = 2024-12-31'
parsed = toml.decode(toml_input)
due = parsed["due_date"]
print(due.year, due.month, due.day)
```

--------------------------------

### Convert TOML Temporal Structs to String

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Use `toml.datetime_to_string` to convert OffsetDateTime, LocalDateTime, LocalDate, and LocalTime structs to their ISO 8601 string representations.

```starlark
load("@toml.bzl", "toml")

# Convert OffsetDateTime to string
odt = toml.OffsetDateTime(2024, 1, 15, 10, 30, 0, 500000, -300)
print(toml.datetime_to_string(odt))

# Convert LocalDateTime to string
ldt = toml.LocalDateTime(2024, 6, 15, 14, 0, 0, 0)
print(toml.datetime_to_string(ldt))

# Convert LocalDate to string
ld = toml.LocalDate(2024, 12, 25)
print(toml.datetime_to_string(ld))

# Convert LocalTime to string
lt = toml.LocalTime(9, 30, 45, 123000)
print(toml.datetime_to_string(lt))
```

--------------------------------

### toml.encode API

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Encodes a Starlark dictionary into a TOML string.

```APIDOC
## toml.encode

### Description
Encodes a Starlark dictionary into a TOML string.

### Method
Starlark function call

### Endpoint
N/A (Starlark function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
load("@toml.bzl", "toml")

encoded_string = toml.encode(data=starlark_dict, max_tables=1000000)
```

### Response
#### Success Response (200)
- **encoded_string** (string) - A string containing the TOML representation of the data.

#### Response Example
```json
{
  "example": "toml_string_representation"
}
```
```

--------------------------------

### toml.decode API

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Decodes a TOML string into a Starlark structure.

```APIDOC
## toml.decode

### Description
Decodes a TOML string into a Starlark structure.

### Method
Starlark function call

### Endpoint
N/A (Starlark function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
load("@toml.bzl", "toml")

decoded_data = toml.decode(data=toml_string, default=None, datetime_formatter=None, max_depth=128, expand_values=False)
```

### Response
#### Success Response (200)
- **decoded_data** (Starlark structure) - The decoded Starlark structure.

#### Response Example
```json
{
  "example": "decoded_starlark_structure"
}
```
```

--------------------------------

### toml.datetime_to_string

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Converts a datetime/date/time struct to an ISO 8601 string.

```APIDOC
## toml.datetime_to_string

### Description
Converts a datetime/date/time struct to an ISO 8601 string.

### Parameters
#### Path Parameters
- **dt** (struct) - Required - The struct to convert.

### Returns
String representation of the datetime.

### Request Example
```
load("@toml.bzl", "toml")

# Assuming 'my_datetime_struct' is a valid date/time struct
toml.datetime_to_string(dt=my_datetime_struct)
```
```

--------------------------------

### Temporal Types

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Provides types for representing TOML temporal values within Starlark.

```APIDOC
## Temporal Types

### Description
These types represent TOML temporal values (OffsetDateTime, LocalDateTime, LocalDate, LocalTime) within Starlark.

### Types

#### `toml.OffsetDateTime(year, month, day, hour, minute, second, nanosecond, offset_hours, offset_minutes)`

Creates an `OffsetDateTime` struct representing a date and time with timezone offset. Used for TOML datetime values with explicit timezone information.

### Request Example
```starlark
load("@toml.bzl", "toml")

offset_dt = toml.OffsetDateTime(2024, 1, 15, 10, 30, 0, 0, 0, 0)
```

#### `toml.LocalDateTime(year, month, day, hour, minute, second, nanosecond)`

Creates a `LocalDateTime` struct representing a date and time without timezone information.

### Request Example
```starlark
load("@toml.bzl", "toml")

local_dt = toml.LocalDateTime(2024, 1, 15, 10, 30, 0, 0)
```

#### `toml.LocalDate(year, month, day)`

Creates a `LocalDate` struct representing a date without time or timezone information.

### Request Example
```starlark
load("@toml.bzl", "toml")

local_date = toml.LocalDate(2024, 1, 15)
```

#### `toml.LocalTime(hour, minute, second, nanosecond)`

Creates a `LocalTime` struct representing a time without date or timezone information.

### Request Example
```starlark
load("@toml.bzl", "toml")

local_time = toml.LocalTime(10, 30, 0, 0)
```
```

--------------------------------

### Access OffsetDateTime Attributes

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Access individual components of an OffsetDateTime struct, such as year, month, microsecond, and offset_minutes.

```starlark
print(utc_time.year)
print(utc_time.month)
print(utc_time.microsecond)
print(utc_time.offset_minutes)
```

--------------------------------

### Encode Starlark Dictionary to TOML

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Use toml.encode to convert a Starlark dictionary into a TOML string. The data must be a top-level dictionary. An optional max_tables parameter limits the number of tables processed.

```Starlark
load("@toml.bzl", "toml")

toml.encode(data, max_tables=1000000)
```

--------------------------------

### toml.decode API

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Decodes a TOML string into a Starlark dictionary structure. Supports optional default values, custom datetime formatters, nesting depth limits, and toml-test compatible output.

```APIDOC
## toml.decode

### Description
Decodes a TOML string into a Starlark dictionary structure. Supports optional default values for error handling, custom datetime formatters, configurable nesting depth limits, and toml-test compatible output format.

### Method
`toml.decode(content, default=None, max_depth=None, datetime_formatter=None, expand_values=False)`

### Parameters
#### Arguments
- **content** (string) - Required - The TOML string to decode.
- **default** (any, optional) - If provided, this value is returned if decoding fails.
- **max_depth** (int, optional) - The maximum nesting depth allowed for the TOML structure.
- **datetime_formatter** (function, optional) - A function to format TOML temporal types into strings.
- **expand_values** (bool, optional) - If True, output values will be expanded to include their type and value, similar to toml-test.

### Request Example
```starlark
load("@toml.bzl", "toml")

config_toml = """
[database]
server = \"192.168.1.1\"
ports = [8000, 8001, 8002]
enabled = true

[database.credentials]
username = \"admin\"
password = \"secret\"

[[servers]]
name = \"alpha\"
ip = \"10.0.0.1\"

[[servers]]
name = \"beta\"
ip = \"10.0.0.2\"
"""

config = toml.decode(config_toml)
print(config["database"]["server"])

# Decode with default value on parse failure
result = toml.decode("invalid [ toml", default = {"fallback": True})
print(result)

# Decode with custom datetime formatter
def format_datetime(dt):
    return toml.datetime_to_string(dt)

config_with_dates = toml.decode(
    'timestamp = 2024-01-15T10:30:00Z',
    datetime_formatter = format_datetime
)
print(config_with_dates["timestamp"])
```

### Response
#### Success Response (dict)
- Returns a Starlark dictionary representing the decoded TOML structure.

#### Response Example
```json
{
  "database": {
    "server": "192.168.1.1",
    "ports": [8000, 8001, 8002],
    "enabled": true,
    "credentials": {
      "username": "admin",
      "password": "secret"
    }
  },
  "servers": [
    {
      "name": "alpha",
      "ip": "10.0.0.1"
    },
    {
      "name": "beta",
      "ip": "10.0.0.2"
    }
  ]
}
```
```

--------------------------------

### Decode TOML String

Source: https://github.com/jvolkman/toml.bzl/blob/main/docs/toml.md

Use toml.decode to convert a TOML string into a Starlark structure. Optional parameters allow for default values, custom datetime formatting, maximum nesting depth, and output compatibility.

```Starlark
load("@toml.bzl", "toml")

toml.decode(data, default, datetime_formatter, max_depth, expand_values)
```

--------------------------------

### Decode TOML string to Starlark dictionary

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Use `toml.decode` to parse a TOML formatted string into a Starlark dictionary. It supports default values, custom datetime formatters, and depth limits.

```starlark
load("@toml.bzl", "toml")

# Basic decoding
config_toml = """
[database]
server = "192.168.1.1"
ports = [8000, 8001, 8002]
enabled = true
connection_max = 5000

[database.credentials]
username = "admin"
password = "secret"

[[servers]]
name = "alpha"
ip = "10.0.0.1"

[[servers]]
name = "beta"
ip = "10.0.0.2"
"""

config = toml.decode(config_toml)

# Access nested values
print(config["database"]["server"])
print(config["database"]["ports"])
print(config["database"]["enabled"])
print(config["database"]["credentials"]["username"])

# Access array of tables
for server in config["servers"]:
    print(server["name"], server["ip"])
# Output: alpha 10.0.0.1
#         beta 10.0.0.2

# Decode with default value on parse failure
result = toml.decode("invalid [ toml", default = {"fallback": True})
print(result)  # {"fallback": True}

# Decode with max depth limit
shallow_config = toml.decode(config_toml, max_depth = 2)

# Decode with custom datetime formatter (converts temporal types to strings)
def format_datetime(dt):
    return toml.datetime_to_string(dt)

config_with_dates = toml.decode(
    'timestamp = 2024-01-15T10:30:00Z',
    datetime_formatter = format_datetime
)
print(config_with_dates["timestamp"])  # "2024-01-15T10:30:00Z"

# Decode with toml-test compatible expanded format
expanded = toml.decode('name = "test"\ncount = 42', expand_values = True)
print(expanded)  # {"name": {"type": "string", "value": "test"}, "count": {"type": "integer", "value": "42"}}
```

--------------------------------

### toml.encode API

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Encodes a Starlark dictionary into a TOML-formatted string. Handles nested tables, arrays, inline tables, arrays of tables, and all scalar types including temporal structs.

```APIDOC
## toml.encode

### Description
Encodes a Starlark dictionary into a TOML-formatted string. Handles nested tables, arrays, inline tables, arrays of tables, and all scalar types including temporal structs.

### Method
`toml.encode(data, max_tables=None)`

### Parameters
#### Arguments
- **data** (dict) - Required - The Starlark dictionary to encode.
- **max_tables** (int, optional) - The maximum number of tables allowed in the encoded TOML. Defaults to a large number to prevent excessive memory usage.

### Request Example
```starlark
load("@toml.bzl", "toml")

# Basic encoding
data = {
    "title": "TOML Example",
    "owner": {
        "name": "Tom Preston-Werner",
        "enabled": True,
    },
    "database": {
        "server": "192.168.1.1",
        "ports": [8001, 8002, 8003],
        "connection_max": 5000,
        "enabled": True,
    },
}

toml_string = toml.encode(data)
print(toml_string)

# Encoding arrays of tables (list of dicts)
data_with_aot = {
    "products": [
        {"name": "Hammer", "sku": 738594937},
        {"name": "Nail", "sku": 284758393},
    ],
}

toml_aot = toml.encode(data_with_aot)
print(toml_aot)

# Encoding with temporal types
data_with_datetime = {
    "event": {
        "created": toml.OffsetDateTime(2024, 1, 15, 10, 30, 0, 0, 0),
        "date": toml.LocalDate(2024, 1, 15),
        "time": toml.LocalTime(10, 30, 0),
    },
}

toml_datetime = toml.encode(data_with_datetime)
print(toml_datetime)
```

### Response
#### Success Response (string)
- Returns a TOML-formatted string.

#### Response Example
```toml
title = "TOML Example"

[database]
connection_max = 5000
enabled = true
ports = [8001, 8002, 8003]
server = "192.168.1.1"

[owner]
enabled = true
name = "Tom Preston-Werner"
```
```

--------------------------------

### Encode Starlark dictionary to TOML string

Source: https://context7.com/jvolkman/toml.bzl/llms.txt

Use `toml.encode` to serialize a Starlark dictionary into a TOML formatted string. It supports nested structures, arrays of tables, and temporal types.

```starlark
load("@toml.bzl", "toml")

# Basic encoding
data = {
    "title": "TOML Example",
    "owner": {
        "name": "Tom Preston-Werner",
        "enabled": True,
    },
    "database": {
        "server": "192.168.1.1",
        "ports": [8001, 8002, 8003],
        "connection_max": 5000,
        "enabled": True,
    },
}

toml_string = toml.encode(data)
print(toml_string)
# Output:
# title = "TOML Example"
#
# [database]
# connection_max = 5000
# enabled = true
# ports = [8001, 8002, 8003]
# server = "192.168.1.1"
#
# [owner]
# enabled = true
# name = "Tom Preston-Werner"

# Encoding arrays of tables (list of dicts)
data_with_aot = {
    "products": [
        {"name": "Hammer", "sku": 738594937},
        {"name": "Nail", "sku": 284758393},
    ],
}

toml_aot = toml.encode(data_with_aot)
print(toml_aot)
# Output:
# [[products]]
# name = "Hammer"
# sku = 738594937
#
# [[products]]
# name = "Nail"
# sku = 284758393

# Encoding with temporal types
data_with_datetime = {
    "event": {
        "created": toml.OffsetDateTime(2024, 1, 15, 10, 30, 0, 0, 0),
        "date": toml.LocalDate(2024, 1, 15),
        "time": toml.LocalTime(10, 30, 0),
    },
}

toml_datetime = toml.encode(data_with_datetime)
print(toml_datetime)
# Output:
# [event]
# created = 2024-01-15T10:30:00Z
# date = 2024-01-15
# time = 10:30:00

# Encode with custom iteration limit for large documents
large_data = {"items": [{"id": i} for i in range(100)]}
toml_large = toml.encode(large_data, max_tables = 2000000)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.