- Remove some old comments
- Fix some doc comments
- Improve some doc comments
- Unify name of the errors related to UDP packet sizes
(i.e: recv buffer too small, and message too big to send)
These are the procedures for configuring a serial port.
You simply open the port with CreateFile (os.open), followed by a call to GetCommState,
setting the DCB as desired, followed by a SetCommState call.
The DCB structure uses C bitfields, so a configuration struct is provided along with a helper procedure to make it easier
to initialize in Odin code.
This makes it possible to initialize a DCB structure with one call to the helper:
```
dcb: DCB
windows.init_dcb_with_config(&dcb, {
BaudRate = 115200,
ByteSize = 8,
Parity = .None,
StopBits = .One,
})
```
(The parity and the stopbits are actually optional in this example, as their zero-values are None and One, respectively.)
Asks the allocator to shrink the backing allocation to the current __length__, or a capacity
of the user's choosing.
Returns `(did_shrink: bool, err: mem.Allocator_Error)`.
```
shrink(&array) // shrinks to len(array)
shrink(&array, N) // shrink to N capacity
shrink(&map) // shrinks down to len(map)
shrink(&map, N) // shrink to N capacity
```
This makes passing an allocator easier, as you no longer have to resort to
named arguments:
Before:
`join(a, b, c)` became `join(elems={a, b, c}, allocator=ally)`
After:
`join({a, b, c})` becomes `join({a, b, c}, ally)`
Adds stem(), short_stem(), and long_ext(); also adds doc-comments to base() and ext().
The 'stem' is usually 'the name' of the file; the basename without the file extension.
To this end, this adds stem(), which is such that:
stem(path) + ext(path) = base(path)
However, 'file extension' has two different meanings to what constitutes it!
> What is the extension of: 'name.tar.gz' ?
Colloquially, you would likely think of it as 'a tarball' - which you might think is '.tar.gz'.
But, if you're writing code to process a file of this type, you would first treat it
as a Gzip file, and then treat the result as a TAR file - i.e: '.gz' ... _followed by_ '.tar'.
ext() returns '.gz' here, since that is the most-immediate format that you would need to use
to decode it; it would be a Gzip stream.
Sometimes though, you do actually want to consider these longer file extensions.
Perhaps you're extracting a tarball, and what to know what to call the intermediate tar file;
perhaps you want to check to see if this file is a tarball, or just a Gzip file;
or maybe you just want 'the name' of the file, and not this "strange 'name-and-part-of-the-extension' thing".
So, this also adds short_stem() and long_ext(), such that:
short_stem(path) + long_ext(path) = base(path)
Thus, we can use either, but the most immediately-useful one is the easiest to reach for:
stem('name.tar.gz') -> 'name.tar'
ext('name.tar.gz') -> '.gz'
short_stem('name.tar.gz') -> 'name'
long_ext('name.tar.gz') -> '.tar.gz'
These procedures are identical to their counterparts when the path only has a simple extension:
stem('name.txt') -> 'name'
ext('name.txt') -> '.txt'
short_stem('name.txt') -> 'name'
long_ext('name.txt') -> '.txt'
This caused all handles returned by GetStdHandle() to also not be inheritable,
which prevents you from handing them to child processes that you might create.
This fixes that.
Tetralux