Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add 'std.format.read.formattedRead' overloads to return a Tuple with values read #8647

Merged
merged 4 commits into from
Nov 26, 2024
Merged

Add 'std.format.read.formattedRead' overloads to return a Tuple with values read #8647

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7bcb86b
refactor(formattedRead): add not is type validation to template argum…
iK4tsu Dec 10, 2022
1e68278
feat(formattedRead): add overloads to return a tuple with the read va…
iK4tsu Dec 10, 2022
e068a9e
test(formattedRead): add unnittests for the tuple return type overloads
iK4tsu Dec 10, 2022
38520d1
chore(changelog): add a changelog formattedRead entry
iK4tsu Nov 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions changelog/formatted_read_tuple_return.dd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
Extend the functionality of formattedRead to permit a std.file.slurp like execution.

Template argument types can now be passed to formattedRead along with a
format string to parse and read the input range as a Tuple of those arguments.
All arguments must be read successfully, otherwise, and unlike std.file.slurp
which has non exhaustive option for partial reads, it'll throw a std.format.FormatException.

---
import std.exception : assertThrown;
import std.format : FormatException;
import std.typecons : tuple;

@safe pure unittest
{
auto complete = "hello!34.5:124".formattedRead!(string, double, int)("%s!%s:%s");
assert(complete == tuple("hello", 34.5, 124));

assertThrown!FormatException("hello!34.5:".formattedRead!(string, double, int)("%s!%s:%s"));
}

/// The format string can be checked at compile-time:
@safe pure unittest
{
auto expected = tuple("hello", 124, 34.5);
auto result = "hello!124:34.5".formattedRead!("%s!%s:%s", string, int, double);
assert(result == expected);

assertThrown!FormatException("hello!34.5:".formattedRead!("%s!%s:%s", string, double, int));
}
---
115 changes: 113 additions & 2 deletions std/format/read.d
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,8 @@ module std.format.read;

import std.format.spec : FormatSpec;
import std.format.internal.read;
import std.traits : isSomeString;
import std.meta : allSatisfy;
import std.traits : isSomeString, isType;

/**
Reads an input range according to a format string and stores the read
Expand Down Expand Up @@ -300,7 +301,7 @@ uint formattedRead(Range, Char, Args...)(auto ref Range r, const(Char)[] fmt, au

/// ditto
uint formattedRead(alias fmt, Range, Args...)(auto ref Range r, auto ref Args args)
if (isSomeString!(typeof(fmt)))
if (!isType!fmt && isSomeString!(typeof(fmt)))
{
import std.format : checkFormatException;
import std.meta : staticMap;
Expand Down Expand Up @@ -692,6 +693,116 @@ if (isSomeString!(typeof(fmt)))
assert(aa2 == ["hello":1, "world":2]);
}

/**
Reads an input range according to a format string and returns a tuple of Args
with the read values.

Format specifiers with format character $(B 'd'), $(B 'u') and $(B
'c') can take a $(B '*') parameter for skipping values.

The second version of `formattedRead` takes the format string as
template argument. In this case, it is checked for consistency at
compile-time.

Params:
Args = a variadic list of types of the arguments
*/
template formattedRead(Args...)
if (Args.length && allSatisfy!(isType, Args))
{
import std.typecons : Tuple;

/**
Params:
r = an $(REF_ALTTEXT input range, isInputRange, std, range, primitives),
where the formatted input is read from
fmt = a $(MREF_ALTTEXT format string, std,format)
Range = the type of the input range `r`
Char = the character type used for `fmt`

Returns:
A Tuple!Args with the elements filled.

Throws:
A $(REF_ALTTEXT FormatException, FormatException, std, format)
if reading did not succeed.
*/
Tuple!Args formattedRead(Range, Char)(auto ref Range r, const(Char)[] fmt)
{
import core.lifetime : forward;
import std.format : enforceFmt;

Tuple!Args args;
const numArgsFilled = .formattedRead(forward!r, fmt, args.expand);
enforceFmt(numArgsFilled == Args.length, "Failed reading into all format arguments");
return args;
}
}

///
@safe pure unittest
{
import std.exception : assertThrown;
import std.format : FormatException;
import std.typecons : tuple;

auto complete = "hello!34.5:124".formattedRead!(string, double, int)("%s!%s:%s");
assert(complete == tuple("hello", 34.5, 124));

// reading ends early
assertThrown!FormatException("hello!34.5:".formattedRead!(string, double, int)("%s!%s:%s"));
}

/// Skipping values
@safe pure unittest
{
import std.format : FormatException;
import std.typecons : tuple;

auto result = "orange: (12%) 15.25".formattedRead!(string, double)("%s: (%*d%%) %f");
assert(result == tuple("orange", 15.25));
}

/// ditto
template formattedRead(alias fmt, Args...)
if (!isType!fmt && isSomeString!(typeof(fmt)) && Args.length && allSatisfy!(isType, Args))
{
import std.typecons : Flag, Tuple, Yes;
Tuple!Args formattedRead(Range)(auto ref Range r)
{
import core.lifetime : forward;
import std.format : enforceFmt;

Tuple!Args args;
const numArgsFilled = .formattedRead!fmt(forward!r, args.expand);
enforceFmt(numArgsFilled == Args.length, "Failed reading into all format arguments");
return args;
}
}

/// The format string can be checked at compile-time
@safe pure unittest
{
import std.exception : assertThrown;
import std.format : FormatException;
import std.typecons : tuple;

auto expected = tuple("hello", 124, 34.5);
auto result = "hello!124:34.5".formattedRead!("%s!%s:%s", string, int, double);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the format string can be checked at compile-time, why would one need to pass in types?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The format string is not responsible for unformatting into the types the user wants, it's only to know the places in the input string that need to be unformatted and to tell the formatted the restrictions of the characters it's reading. Using %f can still be valid for both float and double for example, and it asserts statically when the types are not format-compatible.

float value;
"123".formattedRead!"%d"(value);
// Error: static assert:  "incompatible format character for floating point argument: %d"

It also asserts on orphan format specifiers or if the number of arguments is higher than the required by the format string. This is useful for generic code when we don't have total control over the argument quantity or the format string. The format string might be generated during compile time causing it to assert if some malformation occurs, or the variadic template arguments might be calculated at compile time asserting for the same reasons.

Copy link
Contributor Author

@iK4tsu iK4tsu Dec 12, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually think I found a bug in checkFormatException for the %f format.

int i;
"123".formattedRead!"%f"(i);
// should static assert but instead throws at run time with:
// std.format.FormatException@/dlang/dmd/linux/bin64/../../src/phobos/std/format/internal/read.d(104): Wrong unformat specifier '%f' for int

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually think I found a bug in checkFormatException for the %f format.

int i;
"123".formattedRead!"%f"(i);
// should static assert but instead throws at run time with:
// std.format.FormatException@/dlang/dmd/linux/bin64/../../src/phobos/std/format/internal/read.d(104): Wrong unformat specifier '%f' for int

Could you please file a bug report for this?

assert(result == expected);

assertThrown!FormatException("hello!34.5:".formattedRead!("%s!%s:%s", string, double, int));
}

/// Compile-time consistency check
@safe pure unittest
{
import std.format : FormatException;
import std.typecons : tuple;

static assert(!__traits(compiles, "orange: (12%) 15.25".formattedRead!("%s: (%*d%%) %f", string, double)));
}

/**
Reads a value from the given _input range and converts it according to a
format specifier.
Expand Down
Loading