.\"* strcase: Multiway branch (switch) for short strings in C (in one header file)
.\" Copyright (C) 2019 Renzo Davoli. University of Bologna. <renzo@cs.unibo.it>
.\"
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library 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
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

.TH strcase 3 2019-01-11 "VirtualSquare" "Linux Programmer's Manual"
.SH NAME
STRCASE, strcase, strcase_tolower \- Multiway branch (switch) for short strings
.SH SYNOPSIS
.B #include <strcase.h>
.br
.BI "STRCASE(" ... ")"
.br
.BI "static inline uint64_t strcase(const char *" s ");"
.br
.BI "static inline uint64_t strcase_tolower(const char *" s ");"
.sp
.SH DESCRIPTION

\fBstrcase.h\fR provides two inline functions \fBstrcase\fR, \fBstrcase_tolower\fR  and a macro \fBSTRCASE\fR, all of them
convert a \fIstring\fR in a \fBuint64_t\fR integer value. Only the \fIfirst 8 characters\fR are significative.

\fBstrcase_tolower\fR works like \fBstrcase\fR but it converts uppercase letters as if they were lowercase.

\fBstrcase\fR or \fBstrcase_tolower\fR can be used in the expression of a switch statement to convert a string
to an integer type, \fBSTRCASE\fR generates at compile time the integer constants for the \fIcase\fR
stanzas of the switch.

Actually \fBSTRCASE\fR (C language):

.IP * 3
requires the string to be specified as comma separated characters,
.IP *
supports "strings" using only literals, digits and underscore. Other symbols can appear using their name, as in:
.nf
\fBSTRCASE(slash, e, t, c)\fR
.fi
.IP "" 0
.BR

Regardless of its limitations this macro library is quite useful to write switch statements
in C language using strings (almost) as if it were integers (as in the example below).
Although \fBSTRCASE\fR needs commas between characters the string is still readable, and it
is simple to add cases or change the tags.

When the string contains only one char, the value of strcase is the code of the character (e.g. the value of
\fBstrcase("a")\fR as well as the value of \fBSTRCASE(a)\fR is \fB'a'\fR)

Strcase is a portable alternative to multi-character constants in C.

Strcase is available for C++ users, too. STRCASE argument in C++ is a short string.

.SH EXAMPLE
The following C program shows the use of \fBstrcase\fR:
.BR
.sp
\&
.nf
     #include <stdio.h>
     #include <strcase.h>

     int yes_or_not(const char *s) {
       switch (strcase_tolower(s)) {
         case STRCASE(y,e,s):
         case 'y':
             return 1;
         case STRCASE(n,o):
         case 'n':
             return 0;
         default:
             return -1;
       }
     }

     int main(int argc,char *argv[]) {
       for(argc--, argv++; argc > 0; argc--, argv++)
         printf("%s %d\\n", *argv, yes_or_not(*argv));
     }
.fi

The same example can be translated in C++ as follows:
.BR
.sp
\&
.nf
     #include <iostream>
     #include <strcase.h>

     using namespace std;

     int yes_or_not(const char *s) {
       switch (strcase_tolower(s)) {
         case STRCASE("yes"):
         case 'y':
             return 1;
         case STRCASE("no"):
         case 'n':
             return 0;
         default:
             return -1;
       }
     }

     int main(int argc,char *argv[]) {
       for(argc--, argv++; argc > 0; argc--, argv++)
         cout << *argv << " " << yes_or_not(*argv) << endl;
     }
.fi

.SH BUGS
Bug reports should be addressed to <info@virtualsquare.org>
.SH AUTHORS
Renzo Davoli <renzo@cs.unibo.it>