001/*
002 * ============================================================================
003 *  Copyright © 2002-2026 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 1258 2026-06-04 18:33:06Z tquadrat $
033 *  @extauthor Thomas Thrien - thomas.thrien@tquadrat.org
034 *  @UMLGraph.link
035 *  @since 0.1.0
036 */
037@SuppressWarnings( "NewClassNamingConvention" )
038@FunctionalInterface
039@ClassVersion( sourceVersion = "$Id: Printer.java 1258 2026-06-04 18:33:06Z tquadrat $" )
040@API( status = STABLE, since = "0.1.0" )
041public interface Printer
042{
043        /*---------*\
044    ====** Methods **==========================================================
045        \*---------*/
046    /**
047     *  Prints the given message.
048     *
049     *  @param  locale  The local to use for the formatting of the message.
050     *  @param  message The message; this is a format String as defined for
051     *      {@link java.util.Formatter}.
052     *  @param  args    The optional arguments.
053     *
054     *  @see    java.util.Formatter#format(Locale,String,Object...)
055     *  @see    java.io.PrintWriter#printf(Locale,String,Object...)
056     */
057    public void printf( final Locale locale, final String message, final Object... args );
058
059    /**
060     *  Prints the given message, using the current locale.
061     *
062     *  @param  message The message; this is a format String as defined for
063     *      {@link java.util.Formatter}.
064     *  @param  args    The optional arguments.
065     *
066     *  @see    java.util.Formatter#format(Locale,String,Object...)
067     *  @see    java.io.PrintWriter#printf(Locale,String,Object...)
068     */
069    public default void printf( final String message, final Object... args )
070    {
071        printf( Locale.getDefault(), message, args );
072    }   //  printf()
073
074    /**
075     *  Prints the given object instance after converting it to a String.
076     *
077     *  @param  object  The object to print.
078     */
079    public default void print( final Object object ) { printf( "%s", Objects.toString( object ) ); }
080
081    /**
082     *  Prints the given object instance after converting it to a String,
083     *  followed by a new-line.
084     *
085     *  @param  object  The object to print.
086     */
087    public default void println( final Object object ) { printf( "%s%n", Objects.toString( object ) ); }
088
089    /**
090     *  Prints a new-line.
091     */
092    public default void println() { printf( "%n" ); }
093}
094//  interface Printer
095
096/*
097 *  End of File
098 */