Next: , Previous: Substring, Up: Automatic strings


10.12 Input/output with automatic strings

Libretto provides a number of functions for performing both record- or line-oriented and formatted input/output with automatic strings.

10.12.1 Record-oriented I/O with automatic strings

— Function: ssize_t astr_getdelim (Autostr *astr, FILE *file, char delim)

Deletes the contents of astr and then reads characters from file into astr until an occurrence of delim. On exit, astr does not contain delim. Null characters in the input are silently dropped (although of course delim may be the null character). Returns the length of the line read, or a negative value on end-of-file and error conditions. If file does not have a terminating delim, one is silently supplied. Returns the number of characters stored if the function succeeded, or -1 if there was insufficient memory.

— Function: ssize_t astr_getline (Autostr *astr, FILE *file)

Behaves exactly like ‘astr_getdelim’ with the exception that an ASCII newline ('\n') is used as the delimiter.

10.12.2 Formatted I/O with automatic strings

— Function: int astr_scanf (const Autostr *astr, const char *format, ...)

Reads formatted input from astr under the control of the format string format. The optional arguments are pointers to the places which receive the resulting values. The return value is normally the number of successful assignments performed. If the end of astr is encountered before any matches are performed (including matches against whitespace and literal characters in format), then ‘EOF’ is returned.

All formatting escapes provided by the ANSI standard for ‘scanf’ are translated, as are the GNU type modifiers ‘a’ for strings and ‘ll’, ‘L’ and ‘q’ for integers. In addition, the type modifier ‘t’ is supported for strings; in this last case, ‘astr_scanf’ will read into a ‘Autostr’.

— Function: int astr_vscanf (const Autostr *astr, const char *format, va_list args)

Behaves as ‘astr_scanf’ with the exception that the arguments are specified by args rather than as optional arguments.

— Function: ssize_t astr_printf (Autostr *astr, const char *format, ...)

Write the optional arguments into astr under the control of the format string format. Returns the number of characters printed, or a negative value on error. If the error is insufficient memory, the standard C library's global variable ‘errno’ is set to ‘ENOMEM’.

— Function: ssize_t astr_vprintf (Autostr *astr, const char *format, va_list args)

Behaves as ‘astr_scanf’ with the exception that the arguments to be written are specified by args rather than as optional arguments.

— Function: ssize_t astr_printa (Autostr *astr, const char *format, ...)
— Function: ssize_t astr_vprinta (Autostr *astr, const char *format, va_list args)

These functions behave exactly like ‘astr_printf’ and ‘astr_vprintf’ respectively, with the exception that the formatted string is appended onto astr instead of replacing it.