format.h File Reference

Simple string formatting. More...

#include <stdbool.h>
#include <stddef.h>

Include dependency graph for format.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	FormatJustify { JUSTIFY_LEFT = -1 , JUSTIFY_CENTER = 0 , JUSTIFY_RIGHT = 1 }
	Alignment for format_string() More...

Functions
int	format_string (struct Buffer *buf, int min_cols, int max_cols, enum FormatJustify justify, char pad_char, const char *str, size_t n, bool arboreal)
	Format a string, like snprintf()

Detailed Description

Simple string formatting.

Authors

• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file format.h.

Enumeration Type Documentation

FormatJustify

enum FormatJustify

Alignment for format_string()

Enumerator
JUSTIFY_LEFT	Left justify the text.
JUSTIFY_CENTER	Centre the text.
JUSTIFY_RIGHT	Right justify the text.

Definition at line 32 of file format.h.

{
  JUSTIFY_LEFT   = -1,       
  JUSTIFY_CENTER =  0,       
  JUSTIFY_RIGHT  =  1,       
};

Function Documentation

format_string()

int format_string	(	struct Buffer *	buf,
		int	min_cols,
		int	max_cols,
		enum FormatJustify	justify,
		char	pad_char,
		const char *	str,
		size_t	n,
		bool	arboreal
	)

Format a string, like snprintf()

Parameters

[out]	buf	Buffer in which to save string
[in]	min_cols	Minimum number of screen columns to use
[in]	max_cols	Maximum number of screen columns to use
[in]	justify	Justification, e.g. JUSTIFY_RIGHT
[in]	pad_char	Padding character
[in]	str	String to format
[in]	n	Number of bytes of string to format
[in]	arboreal	If true, string contains graphical tree characters

Return values

obj	Number of bytes and screen columns used

This formats a string, a bit like sprintf(buf, "%-*.*s", min_cols, max_cols, str), except that the max_cols refer to the number of character cells when printed.

Definition at line 108 of file format.c.

{
  wchar_t wc = 0;
  int w = 0;
  size_t k = 0;
  char scratch[MB_LEN_MAX] = { 0 };
  mbstate_t mbstate1 = { 0 };
  mbstate_t mbstate2 = { 0 };
  bool escaped = false;
  int used_cols = 0;
 
  for (; (n > 0) && (k = mbrtowc(&wc, str, n, &mbstate1)); str += k, n -= k)
  {
    if ((k == ICONV_ILLEGAL_SEQ) || (k == ICONV_BUF_TOO_SMALL))
    {
      if ((k == ICONV_ILLEGAL_SEQ) && (errno == EILSEQ))
        memset(&mbstate1, 0, sizeof(mbstate1));
 
      k = (k == ICONV_ILLEGAL_SEQ) ? 1 : n;
      wc = ReplacementChar;
    }
 
    // How many screen cells will the character require?
    if (escaped)
    {
      escaped = false;
      w = 0;
    }
    else if (arboreal && (wc == MUTT_SPECIAL_INDEX))
    {
      escaped = true;
      w = 0;
    }
    else if (arboreal && (wc < MUTT_TREE_MAX))
    {
      w = 1; /* hack */
    }
    else if (iswspace(wc))
    {
      w = MAX(1, wcwidth(wc));
    }
    else
    {
#ifdef HAVE_ISWBLANK
      if (iswblank(wc))
        wc = ' '; // LCOV_EXCL_LINE
      else
#endif
          if (!IsWPrint(wc))
        wc = '?';
      w = wcwidth(wc);
    }
 
    // It'll require _some_ space
    if (w >= 0)
    {
      if (w > max_cols)
        continue;
      size_t k2 = wcrtomb(scratch, wc, &mbstate2);
      if (k2 == ICONV_ILLEGAL_SEQ)
        continue; // LCOV_EXCL_LINE
 
      used_cols += w;
 
      min_cols -= w;
      max_cols -= w;
      buf_addstr_n(buf, scratch, k2);
    }
  }
 
  // How much space is left?
  w = min_cols;
  if (w > 0)
  {
    used_cols += w;
  }
 
  if (w > 0)
    buf_justify(buf, justify, buf_len(buf) + w, pad_char);
 
  return used_cols;
}

Here is the call graph for this function:

Here is the caller graph for this function: