google / google/jsonnet

Document that std.stripChars/lstripChars/rstripChars accept array as chars parameter

Open
#1,325 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Jsonnet
Stars
7.6k
Forks
475
PR merge metrics
No merged PRs in 30d

Description

## Summary

The documentation for `std.stripChars`, `std.lstripChars`, and `std.rstripChars` currently only shows string arguments for the `chars` parameter. However, the reference implementation in `stdlib/std.jsonnet` inherently supports arrays because it uses `std.member(chars, str[0])`, which works with both strings and arrays.

## Current behavior

When `chars` is an array, `std.member` checks if the character is an element of the array. This means:

- **Single-character string elements** are used as characters to strip
- **Multi-character strings, numbers, booleans, null, objects, arrays** are silently ignored (they never match a single character)

### Examples

```jsonnet
// Works with string (documented)
std.lstripChars("aaabcdef", "a") // "bcdef"

// Works with array (undocumented but functional)
std.lstripChars("forward", ["f", "o"]) // "rward"
std.stripChars("UwU Lel Stosh", ["h", "U", "s", {}, [], null, "w"]) // " Lel Sto"
std.lstripChars("123abc", [1, 2, 3]) // "123abc" (numbers ignored)
std.lstripChars("aabc", ["ab"]) // "aabc" (multi-char string ignored)
```

## Cross-implementation verification

All major implementations support this behavior:

| Expression | cpp-jsonnet | go-jsonnet | sjsonnet | jrsonnet |
|------------|-------------|------------|----------|----------|
| `std.lstripChars("forward", ["f","o"])` | `"rward"` | `"rward"` | `"rward"` | `"rward"` |
| `std.rstripChars("cool just cool", ["o","l"])` | `"cool just c"` | `"cool just c"` | `"cool just c"` | `"cool just c"` |
| `std.stripChars("UwU Lel Stosh", ["h","U","s",{},[],null,"w"])` | `" Lel Sto"` | `" Lel Sto"` | `" Lel Sto"` | `" Lel Sto"` |

## Proposal

Document the array parameter support in `doc/ref/stdlib.html` for `std.stripChars`, `std.lstripChars`, and `std.rstripChars`, noting that:

1. `chars` can be a string or an array
2. When an array is provided, only single-character string elements are used as characters to strip
3. Non-string and multi-character string elements are silently ignored

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.