= TitleBuffer
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Title buffer is a utility class to help produce titles for objects without having to add lots of guard code.

It provides two basic method: one to concatenate a title to the buffer; another to append a title with a joiner string, taking care adding in necessary spaces.

The benefits of using this class is that null references are safely ignored (rather than appearing as 'null'), and joiners (a space by default) are only added when needed.

== API

[source,java]
.TitleBuffer.java
----
class TitleBuffer {
  TitleBuffer()     // <.>
  TitleBuffer(Object object)     // <.>
  TitleBuffer(Object object, String defaultTitle)     // <.>
  TitleBuffer(String text)     // <.>
  boolean isEmpty(Object object)     // <.>
  boolean isEmpty(String text)     // <.>
  TitleBuffer append(int number)     // <.>
  TitleBuffer append(Object object)     // <.>
  TitleBuffer append(Object object, String defaultValue)     // <.>
  TitleBuffer append(String text)     // <.>
  TitleBuffer append(String joiner, Object object)     // <.>
  TitleBuffer append(String joiner, Object object, String defaultTitle)     // <.>
  TitleBuffer append(String joiner, String text)     // <.>
  TitleBuffer appendSpace()     // <.>
  TitleBuffer concat(Object object)     // <.>
  TitleBuffer concat(Object object, String defaultValue)     // <.>
  TitleBuffer concat(String text)     // <.>
  TitleBuffer concat(String joiner, String text)     // <.>
  TitleBuffer concat(String joiner, Object object)     // <.>
  TitleBuffer concat(String joiner, Object object, String defaultValue)     // <.>
  String toString()     // <.>
  TitleBuffer truncate(int noWords)     // <.>
}
----

<.> xref:#TitleBuffer_[TitleBuffer()]
+
--
Creates a new, empty, xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .
--
<.> xref:#TitleBuffer_Object[TitleBuffer(Object)]
+
--
Creates a new xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] , containing the title of the specified object.
--
<.> xref:#TitleBuffer_Object_String[TitleBuffer(Object, String)]
+
--
Creates a new title object, containing the title of the specified object.
--
<.> xref:#TitleBuffer_String[TitleBuffer(String)]
+
--
Creates a new title object, containing the specified text.
--
<.> xref:#isEmpty_Object[isEmpty(Object)]
+
--
Determines if the specified object's title is empty (or null).
--
<.> xref:#isEmpty_String[isEmpty(String)]
+
--
Determines if the specified text is empty. Will return true if either: the specified reference is null; or if the reference is an empty string.
--
<.> xref:#append_int[append(int)]
<.> xref:#append_Object[append(Object)]
+
--
Append the title of the specified object to this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .
--
<.> xref:#append_Object_String[append(Object, String)]
+
--
Appends the title of the specified object, or the specified text if the objects title is null or empty. Prepends a space if there is already some text in this title object.
--
<.> xref:#append_String[append(String)]
+
--
Appends a space (if there is already some text in this title object) and then the specified text.
--
<.> xref:#append_String_Object[append(String, Object)]
+
--
Appends the joining string and the title of the specified object. If the object is empty then nothing will be appended.
--
<.> xref:#append_String_Object_String[append(String, Object, String)]
+
--
Append the `joiner` text, a space, and the title of the specified object to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] . If the title of the specified object is null then use the `defaultValue` text. If both the objects title and the default value are null or equate to a zero-length string then no text will be appended ; not even the joiner text.
--
<.> xref:#append_String_String[append(String, String)]
+
--
Appends the joiner text, a space, and the text to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] . If no text yet exists in the object then the joiner text and space are omitted.
--
<.> xref:#appendSpace_[appendSpace()]
+
--
Append a space to the text of this TitleString object if, and only if, there is some existing text i.e., a space is only added to existing text and will not create a text entry consisting of only one space.
--
<.> xref:#concat_Object[concat(Object)]
+
--
Concatenate the the title value (the result of calling an objects label() method) to this TitleString object. If the value is null the no text is added.
--
<.> xref:#concat_Object_String[concat(Object, String)]
+
--
Concatenate the title of the object value or the specified default value if the title is equal to null or is empty, to this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .
--
<.> xref:#concat_String[concat(String)]
+
--
Concatenate the specified text on to the end of the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .
--
<.> xref:#concat_String_String[concat(String, String)]
+
--
Concatenate the joiner text and the text to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] object. If no text yet exists in the object then the joiner text is omitted.
--
<.> xref:#concat_String_Object[concat(String, Object)]
+
--
Concatenate the joiner text and the title of the object to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] . If no object yet exists in the object then the joiner text is omitted.
--
<.> xref:#concat_String_Object_String[concat(String, Object, String)]
+
--
Concatenate the joiner text and the title of the object to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] object. If no object yet exists in the object then defaultValue is used instead.
--
<.> xref:#toString_[toString()]
+
--
Returns a String that represents the value of this object.
--
<.> xref:#truncate_int[truncate(int)]
+
--
Truncates this title so it has a maximum number of words. Spaces are used to determine words, thus two spaces in a title will cause two words to be mistakenly identified.
--

== Members

[#TitleBuffer_]
=== TitleBuffer()

Creates a new, empty, xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .

[#TitleBuffer_Object]
=== TitleBuffer(Object)

Creates a new xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] , containing the title of the specified object.

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#TitleBuffer_Object_String]
=== TitleBuffer(Object, String)

Creates a new title object, containing the title of the specified object.

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#TitleBuffer_String]
=== TitleBuffer(String)

Creates a new title object, containing the specified text.

[#isEmpty_Object]
=== isEmpty(Object)

Determines if the specified object's title is empty (or null).

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#isEmpty_String]
=== isEmpty(String)

Determines if the specified text is empty. Will return true if either: the specified reference is null; or if the reference is an empty string.

[#append_int]
=== append(int)

[#append_Object]
=== append(Object)

Append the title of the specified object to this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#append_Object_String]
=== append(Object, String)

Appends the title of the specified object, or the specified text if the objects title is null or empty. Prepends a space if there is already some text in this title object.

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#append_String]
=== append(String)

Appends a space (if there is already some text in this title object) and then the specified text.

[#append_String_Object]
=== append(String, Object)

Appends the joining string and the title of the specified object. If the object is empty then nothing will be appended.

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#append_String_Object_String]
=== append(String, Object, String)

Append the `joiner` text, a space, and the title of the specified object to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] . If the title of the specified object is null then use the `defaultValue` text. If both the objects title and the default value are null or equate to a zero-length string then no text will be appended ; not even the joiner text.

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#append_String_String]
=== append(String, String)

Appends the joiner text, a space, and the text to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] . If no text yet exists in the object then the joiner text and space are omitted.

[#appendSpace_]
=== appendSpace()

Append a space to the text of this TitleString object if, and only if, there is some existing text i.e., a space is only added to existing text and will not create a text entry consisting of only one space.

[#concat_Object]
=== concat(Object)

Concatenate the the title value (the result of calling an objects label() method) to this TitleString object. If the value is null the no text is added.

[#concat_Object_String]
=== concat(Object, String)

Concatenate the title of the object value or the specified default value if the title is equal to null or is empty, to this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#concat_String]
=== concat(String)

Concatenate the specified text on to the end of the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] .

[#concat_String_String]
=== concat(String, String)

Concatenate the joiner text and the text to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] object. If no text yet exists in the object then the joiner text is omitted.

[#concat_String_Object]
=== concat(String, Object)

Concatenate the joiner text and the title of the object to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] . If no object yet exists in the object then the joiner text is omitted.

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#concat_String_Object_String]
=== concat(String, Object, String)

Concatenate the joiner text and the title of the object to the text of this xref:refguide:applib:index/util/TitleBuffer.adoc[TitleBuffer] object. If no object yet exists in the object then defaultValue is used instead.

Note: this method only obtains the title using either `title()` or `toString()` ; it doesn't honour other mechanisms for specifying the title, such as _org.apache.isis.applib.annotation.Title_ annotation. If that functionality is required, first call _TitleService#titleOf(Object)_ on the object and pass in the resultant string.

[#toString_]
=== toString()

Returns a String that represents the value of this object.

[#truncate_int]
=== truncate(int)

Truncates this title so it has a maximum number of words. Spaces are used to determine words, thus two spaces in a title will cause two words to be mistakenly identified.
