format_string {formatBibtex}

Format a Character Vector

Description

This function formats a character vector by following APA (American Psychological Assoication) style.

Usage

format_string(
  x,
  style = c("title", "sentence"),
  str2ws = "_",
  str4split = " |-",
  strict = TRUE,
  arguments = list(),
  protect_curly_braces = FALSE,
  lowercase_words = getOption("formatBibtex.lowercase_words"),
  protected_words = getOption("formatBibtex.protected_words"),
  punctuation = getOption("formatBibtex.punctuation"),
  ...
)

Arguments

x

A character vector that needs formatting.

style

A character string for specifying case style. "title" for title case or "sentence" for sentence case.

str2ws

Character expression that would be replaced with white space. By default, underscores will be replaced with white spaces.

str4split

Character expression that would be used to split the string into individual words.

strict

A logical value specifying whether to lower the cases for letters after the first letter. The default value is TRUE.

arguments

An optional argument list for specifying more details when replacing specified characters with whitespaces by using gsub.

protect_curly_braces

A logical vector of length one indicating if curly braces represent a block that needs protection. This argument is mainly intended to format BibTeX entries.

lowercase_words

Some words that should be almost always be lowercase.

protected_words

Some words that should be kept in original case and should be not be convert to lowercase or uppercase.

punctuation

A character expression that should be considered as punctuation and should not be considered as a part of the protected words. The function would remove these punctuation before checking whether the words need protecting.

...

Other arguments that are not used now.

Details

The available style options are title case and sentence case. The first word of the string and the first word after colon will be always capitalized. For title case (default), the function would capitalize each word with a few exceptions, such as short conjunctions and prepositions. For sentence case, the function would not capitalize a word unless it starts a string, come after a colon, or is a proper noun. We may specify some words that need protection from any kind of case conversion.

The function would also replace possible splitting characters, such as underscores with white spaces. Empty strings ("" or ''), NA, character(0), and NULL are allowed and returned as they were.

Value

A character vector of the same length as the input.

Examples

library(formatBibtex)

## simple examples
foo <- c("iT IS_A_sIMPLe_ExamplE.", "let'S_do soMe_tesTs!")
format_string(foo, style = "title")
format_string(foo, style = "sentence")

## protect some words from formatting
## check out the built-in
(default_protected_words <- getOption("formatBibtex.protected_words"))

## e.g., protect ABCD from being converted to lowercase
bar <- c("on_the_convergence properties of the ABCD_algorithm",
         "teSt: tHe cluster is Running MCMC!")
format_string(bar, style = "sentence",
              protected_words = c(default_protected_words, "ABCD"))

## more tricky examples: protected words contain `str4split`
foo <- c("nineteenth- and twentieth-century writers",
         "well-differentiated cells with arXiv e-prints")
format_string(foo, str4split = "-| ",
              protected_words = c("arXiv", "e-prints"))

## trivial examples
format_string(NULL)
format_string(character(0))
format_string(character(3))
format_string(c(NA, "", "hello world!"))