## std.strings: The standard implementation of strings.
## This module is imported by default.
# reference: https://doc.rust-lang.org/std/string/struct.String.html

use std.pointers

# possible approaches: list[byte], distinct list[byte], this
# should *really* just rely on lists, i don't want to duplicate slicing logic, but... maybe...
type str = struct
  data: ptr[byte]
  length: uint
  capacity: uint

## Initialize and return an empty string.
pub func init(): str =
  ...

## Gets the length of a string.
pub func len(self: str): uint =
  self.length

pub func empty(self: str): bool =
  self.length == 0

## Gets the internal capacity of a string.
func cap(self: str): uint =
  self.capacity

## Expands the capacity of a string.
func grow(self: mut str) =
  ...

## Pushes a character to the end of a mutable string.
pub func push(self: mut str, val: chr) = # todo: `add` alias?
  ...

## Pushes an owned string to the end of a mutable string.
pub func push(self: mut str, val: str) =
  ...

## Removes and returns the last character of a string, if it exists.
pub func pop(self: mut str): chr? =
  ...

## Returns the character at the provided index, if it exists.
pub func get(self: str, i: uint): chr? =
  ...

## Sets the character at the provided index, if it exists.
## todo: what if it does not exist?
pub func set(self: mut str, i: uint, val: chr) =
  ...

## Inserts a character at an arbitrary position within a string.
## Error handling: todo
pub func insert(self: mut str, i: uint, val: chr) =
  ...

## Removes and returns a character at an arbitrary position within a string.
## Panics on failure.
pub func remove(self: mut str, i: uint): chr =
  ...

## Returns the *byte* at an arbitrary position within a string.
## Explicitly distinct from `get` as this breaks safety conventions idk
pub func get_byte(self: str): byte =
  ...

## Sets a byte at the provided index, if it exists. Do we want this?
pub func set_byte(self: mut str, i: uint, val: byte) =
  ...

## Inserts a byte into a string. Breaks string convention. Do we want this?
pub func insert_byte(self: mut str, i: uint, val: byte) =
  ...

## Removes a byte at a given offset from a string. Do we want this?
pub func remove_byte(self: mut str, i: uint): byte? =
  ...

## Converts a given string to a list of bytes for iteration purposes.
pub func bytes(self: str): list[byte] =
  ... # many performance considerations

## Converts a given string to a list of chars for iteration purposes.
pub func chars(self: str): list[chr] # todo: useful?

## The concatenation operator.
pub func &(a: str, b: str): str =
  ...

## Syntactic sugar for string appending.
pub func &=(a: mut str, b: owned str) =
  a.push(b)

# todo: many things

# pub func iter(self: str): StrIter
# pub func next(self: mut StrIter)
# pub func peek(self: mut StrIter)
# pub func peek_nth(self: mut StrIter, i: uint)