4a6b70fbd1
* mem: refactor tests of split()
- add a few cases for .rest()
- use expectEqualSlices()
* mem: add splitBackwards
Over the last couple of weeks weeks I needed to iterate over a
collection backwards at least twice. Do we want to have this in stdlib?
If yes, click "Merge" and start using today! Free shipping and returns
(before 1.0).
Why is this useful?
-------------------
I need this for building an error wrapper: errors are added in the
wrapper from "lowest" level to "highest" level, and then printed in
reverse order. Imagine `UpdateUsers` call, which needs to return
`error.InvalidInput` and a wrappable error context. In Go we would add a
context to the error when returning it:
// if update_user fails, add context on which user we are operating
if err := update_user(user); err != nil {
return fmt.Errorf("user id=%d: %w", user.id, err)
}
Since Zig cannot pass anything else than u16 with an error (#2647), I
will pass a `err_ctx: *Err`, to the callers, where they can, besides
returning an error, augment it with auxiliary data. `Err` is a
preallocated array that can add zero-byte-separated strings. For a
concrete example, imagine such a call graph:
update_user(User, *Err) error{InvalidInput}!<...>
validate_user([]const u8, *Err) error{InvalidInput}!<...>
Where `validate_user` would like, besides only the error, signal the
invalid field. And `update_user`, besides the error, would signal the
offending user id.
We also don't want the low-level functions to know in which context they
are operating to construct a meaningful error message: if validation
fails, they append their "context" to the buffer. To translate/augment
the Go example above:
pub fn validate_user(err_ctx: *Err, user: User) error{InvalidInput}!void {
const name = user.name;
if (!ascii.isAlpha(name)) {
err_ctx.print("name '{s}' must be ascii-letters only", .{name});
return error.InvalidInput;
}
<...>
}
// update_user validates each user and does something with it.
pub fn update_user(err_ctx: *Err, user: User) error{InvalidInput}!void {
// validate the user before updating it
validate_user(user) catch {
err_ctx.print("user id={d}", .{user.id});
return error.InvalidInput;
};
<...>
}
Then the top-level function (in my case, CLI) will read the buffer
backwards (splitting on `"\x00"`) and print:
user id=123: name 'Žvangalas' must be ascii-letters only
To read that buffer backwards, dear readers of this commit message, I
need `mem.splitBackwards`.
A general-purpose programming language and toolchain for maintaining robust, optimal, and reusable software.
Resources
- Introduction
- Download & Documentation
- Chapter 0 - Getting Started | ZigLearn.org
- Community
- Contributing
- Code of Conduct
- Frequently Asked Questions
- Community Projects
Installation
- download a pre-built binary
- install from a package manager
- build from source
- bootstrap zig for any target
License
The ultimate goal of the Zig project is to serve users. As a first-order effect, this means users of the compiler, helping programmers to write better software. Even more important, however, are the end-users.
Zig is intended to be used to help end-users accomplish their goals. Zig should be used to empower end-users, never to exploit them financially, or to limit their freedom to interact with hardware or software in any way.
However, such problems are best solved with social norms, not with software licenses. Any attempt to complicate the software license of Zig would risk compromising the value Zig provides.
Therefore, Zig is available under the MIT (Expat) License, and comes with a humble request: use it to make software better serve the needs of end-users.
This project redistributes code from other projects, some of which have other licenses besides MIT. Such licenses are generally similar to the MIT license for practical purposes. See the subdirectories and files inside lib/ for more details.