Merge branch 'pb/strbuf-read-file-doc'
authorJunio C Hamano <gitster@pobox.com>
Mon, 27 Jun 2016 16:56:46 +0000 (09:56 -0700)
committerJunio C Hamano <gitster@pobox.com>
Mon, 27 Jun 2016 16:56:46 +0000 (09:56 -0700)
* pb/strbuf-read-file-doc:
strbuf: describe the return value of strbuf_read_file

1  2 
strbuf.h
diff --combined strbuf.h
index 7987405313de3a8779e338129af62f9286c9985c,773719eafb582aeb135ba17d6886a3b0999715db..83c5c98530700de35bf3e3c3ef6692c4135fec4e
+++ b/strbuf.h
@@@ -205,8 -205,7 +205,8 @@@ extern int strbuf_cmp(const struct strb
   */
  static inline void strbuf_addch(struct strbuf *sb, int c)
  {
 -      strbuf_grow(sb, 1);
 +      if (!strbuf_avail(sb))
 +              strbuf_grow(sb, 1);
        sb->buf[sb->len++] = c;
        sb->buf[sb->len] = '\0';
  }
@@@ -344,18 -343,13 +344,18 @@@ extern void strbuf_commented_addf(struc
  __attribute__((format (printf,2,0)))
  extern void strbuf_vaddf(struct strbuf *sb, const char *fmt, va_list ap);
  
 +/**
 + * Add the time specified by `tm`, as formatted by `strftime`.
 + */
 +extern void strbuf_addftime(struct strbuf *sb, const char *fmt, const struct tm *tm);
 +
  /**
   * Read a given size of data from a FILE* pointer to the buffer.
   *
   * NOTE: The buffer is rewound if the read fails. If -1 is returned,
   * `errno` must be consulted, like you would do for `read(3)`.
 - * `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline()` has the
 - * same behaviour as well.
 + * `strbuf_read()`, `strbuf_read_file()` and `strbuf_getline_*()`
 + * family of functions have the same behaviour as well.
   */
  extern size_t strbuf_fread(struct strbuf *, size_t, FILE *);
  
   */
  extern ssize_t strbuf_read(struct strbuf *, int fd, size_t hint);
  
 +/**
 + * Read the contents of a given file descriptor partially by using only one
 + * attempt of xread. The third argument can be used to give a hint about the
 + * file size, to avoid reallocs. Returns the number of new bytes appended to
 + * the sb.
 + */
 +extern ssize_t strbuf_read_once(struct strbuf *, int fd, size_t hint);
 +
  /**
   * Read the contents of a file, specified by its path. The third argument
   * can be used to give a hint about the file size, to avoid reallocs.
+  * Return the number of bytes read or a negative value if some error
+  * occurred while opening or reading the file.
   */
  extern ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint);
  
  extern int strbuf_readlink(struct strbuf *sb, const char *path, size_t hint);
  
  /**
 - * Read a line from a FILE *, overwriting the existing contents
 - * of the strbuf. The second argument specifies the line
 - * terminator character, typically `'\n'`.
 + * Write the whole content of the strbuf to the stream not stopping at
 + * NUL bytes.
 + */
 +extern ssize_t strbuf_write(struct strbuf *sb, FILE *stream);
 +
 +/**
 + * Read a line from a FILE *, overwriting the existing contents of
 + * the strbuf.  The strbuf_getline*() family of functions share
 + * this signature, but have different line termination conventions.
 + *
   * Reading stops after the terminator or at EOF.  The terminator
   * is removed from the buffer before returning.  Returns 0 unless
   * there was nothing left before EOF, in which case it returns `EOF`.
   */
 -extern int strbuf_getline(struct strbuf *, FILE *, int);
 +typedef int (*strbuf_getline_fn)(struct strbuf *, FILE *);
 +
 +/* Uses LF as the line terminator */
 +extern int strbuf_getline_lf(struct strbuf *sb, FILE *fp);
 +
 +/* Uses NUL as the line terminator */
 +extern int strbuf_getline_nul(struct strbuf *sb, FILE *fp);
 +
 +/*
 + * Similar to strbuf_getline_lf(), but additionally treats a CR that
 + * comes immediately before the LF as part of the terminator.
 + * This is the most friendly version to be used to read "text" files
 + * that can come from platforms whose native text format is CRLF
 + * terminated.
 + */
 +extern int strbuf_getline(struct strbuf *, FILE *);
 +
  
  /**
   * Like `strbuf_getline`, but keeps the trailing terminator (if
@@@ -449,16 -414,7 +451,16 @@@ extern void strbuf_add_absolute_path(st
   * Strip whitespace from a buffer. The second parameter controls if
   * comments are considered contents to be removed or not.
   */
 -extern void stripspace(struct strbuf *buf, int skip_comments);
 +extern void strbuf_stripspace(struct strbuf *buf, int skip_comments);
 +
 +/**
 + * Temporary alias until all topic branches have switched to use
 + * strbuf_stripspace directly.
 + */
 +static inline void stripspace(struct strbuf *buf, int skip_comments)
 +{
 +      strbuf_stripspace(buf, skip_comments);
 +}
  
  static inline int strbuf_strip_suffix(struct strbuf *sb, const char *suffix)
  {
@@@ -514,14 -470,6 +516,14 @@@ static inline struct strbuf **strbuf_sp
   */
  extern void strbuf_list_free(struct strbuf **);
  
 +/**
 + * Add the abbreviation, as generated by find_unique_abbrev, of `sha1` to
 + * the strbuf `sb`.
 + */
 +extern void strbuf_add_unique_abbrev(struct strbuf *sb,
 +                                   const unsigned char *sha1,
 +                                   int abbrev_len);
 +
  /**
   * Launch the user preferred editor to edit a file and fill the buffer
   * with the file's contents upon the user completing their editing. The
@@@ -539,21 -487,10 +541,21 @@@ extern void strbuf_add_lines(struct str
   */
  extern void strbuf_addstr_xml_quoted(struct strbuf *sb, const char *s);
  
 +/**
 + * "Complete" the contents of `sb` by ensuring that either it ends with the
 + * character `term`, or it is empty.  This can be used, for example,
 + * to ensure that text ends with a newline, but without creating an empty
 + * blank line if there is no content in the first place.
 + */
 +static inline void strbuf_complete(struct strbuf *sb, char term)
 +{
 +      if (sb->len && sb->buf[sb->len - 1] != term)
 +              strbuf_addch(sb, term);
 +}
 +
  static inline void strbuf_complete_line(struct strbuf *sb)
  {
 -      if (sb->len && sb->buf[sb->len - 1] != '\n')
 -              strbuf_addch(sb, '\n');
 +      strbuf_complete(sb, '\n');
  }
  
  extern int strbuf_branchname(struct strbuf *sb, const char *name);