lib/sf-istream.h

   1 /* A string or file based input stream.
   2    Copyright (C) 2024 Free Software Foundation, Inc.
   3
   4    This file is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU Lesser General Public License as
   6    published by the Free Software Foundation, either version 3 of the
   7    License, or (at your option) any later version.
   8
   9    This file is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU Lesser General Public License for more details.
  13
  14    You should have received a copy of the GNU Lesser General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 /* Written by Bruno Haible <bruno@clisp.org>, 2024.  */
  18
  19 #ifndef _SF_ISTREAM_H
  20 #define _SF_ISTREAM_H
  21
  22 #include <stdio.h>
  23
  24 #include "string-desc.h"
  25
  26 /* An input stream type that can read from a file or from a string.  */
  27 typedef struct sf_istream sf_istream_t;
  28 struct sf_istream
  29 {
  30   /* The input file stream, when reading from a file.  */
  31   FILE *fp;
  32   /* The input area, when reading from a string.  */
  33   const char *input;
  34   const char *input_end;
  35 };
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /* Initializes STREAM to read from FP.
  42    FP must be a FILE stream open for reading.  */
  43 extern void sf_istream_init_from_file (sf_istream_t *stream, FILE *fp);
  44 /* Initializes STREAM to read from a NUL-terminated string INPUT.
  45    The contents of INPUT must stay available and unchanged as long as STREAM
  46    is in use.  */
  47 extern void sf_istream_init_from_string (sf_istream_t *stream,
  48                                          const char *input);
  49 /* Initializes STREAM to read from a string INPUT.
  50    The contents of INPUT must stay available and unchanged as long as STREAM
  51    is in use.  Operations on STREAM will not modify the contents of INPUT.  */
  52 extern void sf_istream_init_from_string_desc (sf_istream_t *stream,
  53                                               string_desc_t input);
  54
  55 /* Reads a single 'char' from STREAM, and returns it as an 'unsigned char'.
  56    Returns EOF when the end of stream was already reached.  */
  57 extern int sf_getc (sf_istream_t *stream);
  58
  59 /* Tests whether STREAM has encountered an error.
  60    You may want to call this function after sf_getc (stream) has
  61    returned EOF; in other situations it is guaranteed to return 0.  */
  62 extern int sf_ferror (sf_istream_t *stream);
  63
  64 /* Assuming that C was the last value returned by sf_getc (stream),
  65    this call pushes back C onto the stream.
  66    Only 1 character of pushback is guaranteed.  */
  67 extern void sf_ungetc (sf_istream_t *stream, int c);
  68
  69 /* Frees all memory held by STREAM.
  70    This call has no effect on the arguments provided to sf_istream_init_*.  */
  71 extern void sf_free (sf_istream_t *stream);
  72
  73 #ifdef __cplusplus
  74 }
  75 #endif
  76
  77 #endif /* _SF_ISTREAM_H */