Savetxt unit

[fiolj]

This PR aims to add optional arguments to savetxt, that behave similar to numpy's savetxt.

This is associated with Issue 263 and this discussion thread.

It add the possibility of supplying the unit of an open file instead of a filename (which could be used for output_unit for instance)

This implementation is quite simple. The main changes are:

1. Add optional header and footer (that could be commented out with a character, currently defaults to '#')
2. Changes delimiter to an arbitrary length string. I am not completely sure that is really useful. Initially I've added this because np.savetxt (Numpy's) allows character or arbitrary strings but np.loadtxt requires it to be a length 1 char.
3. Add the possibility to override default format for saving data

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.42%. Comparing base (5a4b3bf) to head (50eb65f).
⚠️ Report is 34 commits behind head on master.

Files with missing lines	Patch %	Lines
example/io/example_savetxt.f90	0.00%	13 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1085      +/-   ##
==========================================
- Coverage   68.52%   68.42%   -0.11%     
==========================================
  Files         396      399       +3     
  Lines       12746    12866     +120     
  Branches     1376     1389      +13     
==========================================
+ Hits         8734     8803      +69     
- Misses       4012     4063      +51     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jalvesz]

Thanks for this @fiolj. Would you mind reverting the changes not related to the implementation? (styling) There are too many and it renders difficult to read through the PR. You can check the style_guide for info https://github.com/fortran-lang/stdlib/blob/master/STYLE_GUIDE.md

One thing, white spaces in-between parentheses and an intrinsic function are not recommended ( open (...), allocate (...), etc )

[fiolj]

Thanks @jalvesz, I've fixed the formatting

[jvdp1]

Thank you @fiolj . Here are some suggestions

[fiolj]

Reviewing the arguments of savetxt I've rechecked and Numpy's has the following order:
np.savetxt(fname, X, fmt, delimiter, newline, header, footer, comments, encoding)

Currently, we have the order of fmt and delimiter inverted. Should we make it as Numpy or should we keep it?

[fiolj]

I think that it this version is close to apt to be merged, except for the codecov failings (which I have no idea what they mean).

@fiolj could you update the tests to cover the different changes in the API?

Yes. I've commited some tests.
I noticed that loadtxt is currently setting delimiter to a single char, thus I've kept the same convention to savetxt.
It is quite easy to change savetxt to arbitrary length strings; I would wait until loadtxt is also modified.

[jalvesz]

I am confused. This shows that some lines of example_savetxt are not covered. Or do I miss-interpret the report?

I'm also confused now, codecov is supposed to ignore files in the examples directory after the PR #1074 ... I would say for the moment to ignore this false error.

[Copilot]

Pull request overview

This PR adds optional arguments to the savetxt function to provide more flexibility when saving 2D arrays to text files, making it more similar to NumPy's savetxt functionality.

Changes:

• Added ability to specify an already-opened file unit instead of a filename, enabling writing to stdout or appending to files
• Added optional header and footer parameters that are automatically commented with a configurable comment character
• Added optional fmt parameter to customize output format
• Modified format string construction to support custom delimiters (though delimiter parameter still limited to single character)

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 18 comments.

File	Description
src/io/stdlib_io.fypp	Core implementation: generates two variants of savetxt (filename and unit), adds format customization, header/footer support via new prepend helper function
test/io/test_savetxt.f90	Updated tests to exercise new delimiter, fmt, header, footer, and comments parameters
doc/specs/stdlib_io.md	Updated documentation to describe new optional parameters and unit-based interface
example/io/example_savetxt.f90	Added examples demonstrating new features including writing to stdout

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jvdp1]

Thank oyu @fiolj . Overall it looks good. Here are some minor suggestions.

[jvdp1]

LGTM. Thank you @fiolj

[fiolj]

In my opinion it has converged, I would be happy to make changes if necessary. Could we get a new review and try to complete the task and merge this PR?

[jvdp1]

Thank you @fiolj . Overall LGTM. There are still a few open comments/suggestions. Could you review them and implement/close them, please?

[jvdp1]

@fiolj Is this a valid suggestion?

[fiolj]

Thanks @jvdp1 for the review.
With regard to this comment, I do not understand well the question.

• I've simplified the error handling when something happens at reading the values (message formatted with format 1) by using a string variable fout.
• I've now also added a call to error_stop() when unit is not open (line 332).
• Also I've cleaned-up some comments

[fiolj]

I've updated the specs to clarify the behavior when the file already exists (as suggested in the discussion thread):

• When used with filename as a first argument it will overwrite the file
• When used with unit as first argument it will append data

[fiolj]

I've updated the specs to clarify the behavior when the file already exists (as suggested in the discussion thread):

* When used with `filename` as a first argument it will overwrite the file

* When used with `unit` as first argument it will append data

I've been thinking on the suggestion on the the discussion thread) about consistency of the arguments. The use of an additional argument append would give a consistent behavior.
The spec would change to something like:

---

Syntax

call savetxt(filename, array [, delimiter] [, fmt] [, header] [, footer] [, comments] [, append])

call savetxt(unit, array[, delimiter] [, fmt] [, header] [, footer] [, comments] [, append])

Arguments

...

append (optional): Shall be a logical flag. If .true. data will be appended at the end of the file or unit. If .false. file will be overwritten. Default: .false.

---

The only problem that I can see is that when used with an unit number, the function will always be modifying the position of the file (to the beginning or the end). In the previous version the user could in principle position it arbitrarily.

Thoughts, preferences?