001/*
002 * ============================================================================
003 *  Copyright © 2002-2022 by Thomas Thrien.
004 *  All Rights Reserved.
005 * ============================================================================
006 *  Licensed to the public under the agreements of the GNU Lesser General Public
007 *  License, version 3.0 (the "License"). You may obtain a copy of the License at
008 *
009 *       http://www.gnu.org/licenses/lgpl.html
010 *
011 *  Unless required by applicable law or agreed to in writing, software
012 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
013 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
014 *  License for the specific language governing permissions and limitations
015 *  under the License.
016 */
017
018package org.tquadrat.foundation.lang;
019
020import static org.apiguardian.api.API.Status.STABLE;
021
022import java.util.Locale;
023
024import org.apiguardian.api.API;
025import org.tquadrat.foundation.annotation.ClassVersion;
026
027/**
028 *  <p>{@summary Prints a formatted message.}</p>
029 *  <p>This is a functional interface whose functional method is
030 *  {@link #printf(Locale,String,Object...)}.</p>
031 *
032 *  @version $Id: Printer.java 1005 2022-02-03 12:40:52Z tquadrat $
033 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
034 *  @UMLGraph.link
035 *  @since 0.1.0
036 */
037@FunctionalInterface
038@ClassVersion( sourceVersion = "$Id: Printer.java 1005 2022-02-03 12:40:52Z tquadrat $" )
039@API( status = STABLE, since = "0.1.0" )
040public interface Printer
041{
042        /*---------*\
043    ====** Methods **==========================================================
044        \*---------*/
045    /**
046     *  Prints the given message.
047     *
048     *  @param  locale  The local to use for the formatting of the message.
049     *  @param  message The message; this is a format String as defined for
050     *      {@link java.util.Formatter}.
051     *  @param  args    The optional arguments.
052     *
053     *  @see    java.util.Formatter#format(Locale,String,Object...)
054     *  @see    java.io.PrintWriter#printf(Locale,String,Object...)
055     */
056    public void printf( final Locale locale, final String message, final Object... args );
057
058    /**
059     *  Prints the given message, using the current locale.
060     *
061     *  @param  message The message; this is a format String as defined for
062     *      {@link java.util.Formatter}.
063     *  @param  args    The optional arguments.
064     *
065     *  @see    java.util.Formatter#format(Locale,String,Object...)
066     *  @see    java.io.PrintWriter#printf(Locale,String,Object...)
067     */
068    public default void printf( final String message, final Object... args )
069    {
070        printf( Locale.getDefault(), message, args );
071    }   //  printf()
072
073    /**
074     *  Prints the given object instance after converting it to a String.
075     *
076     *  @param  object  The object to print.
077     */
078    public default void print( final Object object ) { printf( "%s", Objects.toString( object ) ); }
079
080    /**
081     *  Prints the given object instance after converting it to a String,
082     *  followed by a new-line.
083     *
084     *  @param  object  The object to print.
085     */
086    public default void println( final Object object ) { printf( "%s%n", Objects.toString( object ) ); }
087
088    /**
089     *  Prints a new-line.
090     */
091    public default void println() { printf( "%n" ); }
092}
093//  interface Printer
094
095/*
096 *  End of File
097 */