001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
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,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.reflect;
018
019/**
020 * Defines how array types should be formatted when rendered as strings.
021 *
022 * <p>
023 * Controls the notation used to represent array dimensions in class names.
024 *
025 * <h5 class='section'>Example:</h5>
026 * <p class='bjava'>
027 *    <jc>// Given class: String[][]</jc>
028 *
029 *    ClassArrayFormat.<jsf>JVM</jsf>        <jc>// "[[Ljava.lang.String;"</jc>
030 *    ClassArrayFormat.<jsf>BRACKETS</jsf>   <jc>// "String[][]"</jc>
031 *    ClassArrayFormat.<jsf>WORD</jsf>       <jc>// "StringArrayArray"</jc>
032 * </p>
033 *
034 * <h5 class='section'>See Also:</h5><ul>
035 *    <li class='link'><a class="doclink" href="../../../../../index.html#juneau-commons">Common</a>
036 * </ul>
037 */
038public enum ClassArrayFormat {
039
040   /**
041    * JVM bytecode notation - prefix with <c>[</c> for each dimension.
042    *
043    * <h5 class='section'>Examples:</h5>
044    * <ul class='spaced-list'>
045    *    <li><js>"[Ljava.lang.String;"</js> - <c>String[]</c>
046    *    <li><js>"[[Ljava.lang.String;"</js> - <c>String[][]</c>
047    *    <li><js>"[I"</js> - <c>int[]</c>
048    *    <li><js>"[[I"</js> - <c>int[][]</c>
049    *    <li><js>"[Z"</js> - <c>boolean[]</c>
050    * </ul>
051    *
052    * <p>
053    * This is the format returned by {@link Class#getName()} for array types.
054    * It uses JVM internal type descriptors where object arrays are prefixed with <c>[L</c>
055    * and suffixed with <c>;</c>, and primitive arrays use single-letter codes
056    * (<c>I</c>, <c>Z</c>, <c>B</c>, <c>C</c>, <c>D</c>, <c>F</c>, <c>J</c>, <c>S</c>).
057    *
058    * <p>
059    * This format is primarily used for reflection and JVM internals.
060    */
061   JVM,
062
063   /**
064    * Source code notation - suffix with <c>[]</c> for each dimension.
065    *
066    * <h5 class='section'>Examples:</h5>
067    * <ul class='spaced-list'>
068    *    <li><js>"String[]"</js> - <c>String[]</c>
069    *    <li><js>"String[][]"</js> - <c>String[][]</c>
070    *    <li><js>"int[]"</js> - <c>int[]</c>
071    *    <li><js>"int[][]"</js> - <c>int[][]</c>
072    *    <li><js>"boolean[]"</js> - <c>boolean[]</c>
073    * </ul>
074    *
075    * <p>
076    * This is the format used in Java source code and is the most human-readable.
077    * It's returned by {@link Class#getSimpleName()} and {@link Class#getCanonicalName()}
078    * for array types.
079    *
080    * <p>
081    * This is the most common format for documentation and display purposes.
082    */
083   BRACKETS,
084
085   /**
086    * Word notation - suffix with <js>"Array"</js> for each dimension.
087    *
088    * <h5 class='section'>Examples:</h5>
089    * <ul class='spaced-list'>
090    *    <li><js>"StringArray"</js> - <c>String[]</c>
091    *    <li><js>"StringArrayArray"</js> - <c>String[][]</c>
092    *    <li><js>"intArray"</js> - <c>int[]</c>
093    *    <li><js>"intArrayArray"</js> - <c>int[][]</c>
094    *    <li><js>"booleanArray"</js> - <c>boolean[]</c>
095    * </ul>
096    *
097    * <p>
098    * This format is useful for generating variable names, method names, or other
099    * identifiers where special characters like <c>[]</c> are not allowed.
100    *
101    * <p>
102    * This format is particularly useful in code generation scenarios where you need
103    * valid Java identifiers.
104    */
105   WORD
106}