documentation/longline.txt

   1 /*! \file util.c
   2 \brief Various useful functions.
   3 */
   4
   5
   6 /*! \def INITIAL_LINE_BUFFER_SIZE
   7 The initial buffer size to allocate to read a long line from a text file.
   8 */
   9
  10
  11
  12
  13
  14
  15 /*! \fn longline longline_create(void)
  16 Prepare the buffer to read long text lines from a file.
  17
  18 \return The object create by the function. It must be freed
  19 with a call to longline_destroy().
  20 */
  21
  22
  23
  24
  25
  26 /*! \fn void longline_reset(longline line)
  27 Reset the internal state of the object to start a new reading on a new file.
  28
  29 \param line The object created by longline_create().
  30 */
  31
  32
  33
  34
  35
  36 /*! \fn char *longline_read(FILE *fp_in,longline line)
  37 Read one long line of text from a file. If the buffer is too short, it is
  38 expended until the line can fit in it.
  39
  40 The function always read as many bytes as can fit in the buffer and split the lines
  41 to return one line at a time to the caller. The returned lines are always terminated
  42 by a null ASCII character. The CR or LF are removed.
  43
  44 Any empty line is skipped.
  45
  46 \param fp_in The file to read.
  47 \param line The object created by longline_create().
  48
  49 \return A pointer to the beginning of the string in the buffer or NULL if it is
  50 the last string read.
  51
  52 \note If not enough memory is available to read the line, the program is terminated
  53 with an error message.
  54 */
  55
  56
  57
  58
  59
  60 /*! \fn void longline_destroy(longline line)
  61 Free the memory allocated by longline_create().
  62
  63 \param line The object to destroy.
  64 */